velocious 1.0.701 → 1.0.703

package/README.md

@@ -15,6 +15,7 @@
 * Frontend-model transport for creating, updating, querying, and subscribing to query-filtered lifecycle events over HTTP/WebSocket, including committed counter-cache parent updates, structured per-attribute validation error responses, immutable per-operation remote request context, registration-local tenant subscription partitioning, and one-budget WebSocket startup controls (see [docs/frontend-models.md](docs/frontend-models.md), [docs/remote-request-context.md](docs/remote-request-context.md), and [docs/websocket-channels.md](docs/websocket-channels.md))
 * Client-side offline sync mutation logs and frontend-model optimistic queueing primitives (see the [shared-resource sync developer guide](docs/shared-resource-sync-guide.md) and [offline sync architecture](docs/offline-sync.md))
 * Declarative client sync scopes with per-scope cursors, a reusable observable single-flight coordinator with bounded retry and deterministic teardown, generation-fenced identity replacement and selected-scope cache reset, automatic mutation tracking, opt-in durable base-version conflict replay, realtime delivery and reconnect gap closure, computed server-publish scope metadata with atomic null-safe publisher row identities, a shared public maintenance upsert helper and legacy-duplicate reconciliation, and immutable-handle project clients whose local database state plus remote pull/replay/realtime request context stay tenant-bound through reconnect (see [docs/sync-client.md](docs/sync-client.md), [docs/sync-coordinator.md](docs/sync-coordinator.md), [docs/remote-request-context.md](docs/remote-request-context.md), and [docs/offline-sync.md](docs/offline-sync.md))
+* SyncClient long-offline sessions: framework-owned device-identity enrollment, backend-issued offline grants with per-grant retention, signing at queue time, signed batch replay with synced/conflict/rejected mapping, and signed peer bundle export/import through `sync.client.offline` (see [docs/sync-client.md](docs/sync-client.md#long-offline-sessions-grant-lifecycle-signed-queue-signed-replay-peer-api) and [docs/offline-sync.md](docs/offline-sync.md#implemented-slice-syncclient-offline-session-grant-lifecycle-signed-queue-signed-replay-peer-api))
 * Reactive `useLiveQuery(Model.where(...))` queries for default databases plus immutable-handle tenant live-query sources whose committed events and refreshes stay on the captured physical tenant (see [docs/live-queries.md](docs/live-queries.md))
 * Server-side sync envelope replay orchestration for app-owned sync receivers, including allowlisted authoritative conflict snapshots that retain submitted aliases in conflict metadata while keying `serverModel` by canonical model attributes (see [docs/sync-envelope-replay-service.md](docs/sync-envelope-replay-service.md))
 * Self-sustaining sync feeds: upstream imports triggered by the changes pull itself, with framework-owned coalescing and throttling (see [docs/sync-upstream-imports.md](docs/sync-upstream-imports.md))

package/build/background-jobs/pooled-runner-shutdown.js

@@ -10,6 +10,7 @@ export const POOLED_CHILD_SHUTDOWN_REASONS = Object.freeze([
   "parent_retire_drained",
   "job_timeout",
   "worker_stop",
+  "child_silence",
   "signal_sigterm",
   "signal_sigint",
   "signal_sigkill",

package/build/background-jobs/types.js

@@ -9,9 +9,9 @@
 /** @typedef {"queued" | "handed_off"} BackgroundJobActiveStatus */
 /** @typedef {"cancelled" | "completed" | "failed" | "orphaned"} BackgroundJobTerminalStatus */
 /** @typedef {BackgroundJobActiveStatus | BackgroundJobTerminalStatus} BackgroundJobStatus */
-/** @typedef {"exit" | "process-error" | "ipc-send"} PooledRunnerFailureOrigin */
+/** @typedef {"exit" | "process-error" | "ipc-send" | "child-silence"} PooledRunnerFailureOrigin */
 /** @typedef {"starting" | "running" | "retiring"} PooledRunnerLifecycleState */
-/** @typedef {"parent_retire_drained" | "job_timeout" | "worker_stop" | "signal_sigterm" | "signal_sigint" | "signal_sigkill" | "signal_other" | "ipc_disconnect" | "process_error" | "unexpected_exit"} PooledChildShutdownReason */
+/** @typedef {"parent_retire_drained" | "job_timeout" | "worker_stop" | "child_silence" | "signal_sigterm" | "signal_sigint" | "signal_sigkill" | "signal_other" | "ipc_disconnect" | "process_error" | "unexpected_exit"} PooledChildShutdownReason */
 /**
  * @deprecated Use PooledChildShutdownReason for exact shutdown provenance.
  * @typedef {"unexpected" | "job-timeout" | "worker-shutdown-timeout"} PooledRunnerTerminationReason

package/build/background-jobs/worker.js

@@ -50,11 +50,23 @@ import { POOLED_RUNNER_INFLIGHT_JOB_ID_LIMIT, boundedPooledRunnerInflightJobIds,
  * @property {ReturnType<typeof setTimeout>} [shutdownSignalTimer] - Drained-retirement fallback signal timer.
  * @property {ReturnType<typeof setTimeout> | null} [timeoutSigkillTimer] - Pending timeout SIGKILL timer.
  * @property {string} [timeoutJobId] - Job whose timeout initiated termination.
+ * @property {number} lastActivityAtMs - Last time the worker saw any IPC message from this child, or dispatched to it.
+ * @property {ReturnType<typeof setTimeout>} [silenceTimer] - Armed per-child IPC-silence watchdog timer.
+ * @property {ReturnType<typeof setTimeout>} [silenceSigkillTimer] - Pending SIGKILL for a child the silence watchdog declared wedged.
  */
 /** Grace period after SIGTERM before a lingering process runner is SIGKILLed. */
 const FORKED_CHILD_SIGKILL_GRACE_MS = 5000
 /** Time a drained retirement gives the child IPC request to begin teardown before SIGTERM fallback. */
 const POOLED_RUNNER_SHUTDOWN_REQUEST_GRACE_MS = 250
+/**
+ * Default bound on how long a pooled child with in-flight jobs may stay silent on
+ * its IPC channel before the worker declares it wedged. A healthy child samples its
+ * memory every 10 seconds while jobs run, so silence past this bound means its event
+ * loop cannot run its own timers — the signature of the silent transport wedge. The
+ * bound is deliberately far above a healthy long job's quiet window: it only fires on
+ * a child that cannot prove it is alive, never on a genuinely busy runner.
+ */
+const POOLED_CHILD_SILENCE_TIMEOUT_MS = 120000
 /**
  * Largest delay Node's `setTimeout` accepts without overflowing to a 1ms delay
  * (a 32-bit signed int of ms, ~24.8 days). A `jobTimeoutMs` above this — or a
@@ -198,13 +210,14 @@ export default class BackgroundJobsWorker {
    * @param {number} [args.generationHandshakeTimeoutMs] - Maximum time to wait for generation acknowledgement (default: 4000).
    * @param {number} [args.reconnectDelayMs] - Delay before reconnecting an established worker connection (default: 1000).
    * @param {number} [args.jobTimeoutMs] - Override the wall-clock timeout for forked and pooled jobs from `configuration.getBackgroundJobsConfig()`. `0` disables it.
+   * @param {number} [args.pooledRunnerSilenceTimeoutMs] - Override the per-child IPC-silence bound for pooled children with in-flight jobs from `configuration.getBackgroundJobsConfig()` (default 120000ms). `0` disables the watchdog.
    * @param {boolean} [args.closeDatabaseConnectionsOnStop] - Whether stop owns closing the configuration's database pools (default true).
    * @param {() => void | Promise<void>} [args.onStopped] - Lifecycle hook invoked after the worker finishes stopping.
    * @param {() => void} [args.onGenerationAccepted] - Explicit generation-acceptance observation hook.
    * @param {() => void} [args.onRetireMessage] - Explicit retire-message observation hook.
    * @param {(observation: import("./types.js").PooledChildMemoryObservation) => void | Promise<void>} [args.onPooledRunnerMemoryObservation] - Explicit pooled-child memory observation hook. Every validated observation (periodic while a child has in-flight jobs, plus on demand) is forwarded here, in addition to the worker's compact stderr log line, so an application can route memory diagnostics (e.g. to a bug reporter) without parsing logs.
    */
-  constructor({configuration, host, port, generationId, workerInstanceId, maxConcurrentForkedJobs, maxConcurrentInlineJobs, pooledRunnerCount, pooledRunnerConcurrency, pooledRunnerMaxJobs, pooledRunnerMaxRssBytes, pooledRunnerMaxLifetimeMs, runnerMaxOldSpaceSizeMb, runnerMallocArenaMax, forkedChildSigkillGraceMs, heartbeatIntervalMs, generationHandshakeTimeoutMs = DEFAULT_GENERATION_HANDSHAKE_TIMEOUT_MS, reconnectDelayMs = 1000, jobTimeoutMs, closeDatabaseConnectionsOnStop = true, onStopped, onGenerationAccepted, onRetireMessage, onPooledRunnerMemoryObservation} = {}) {
+  constructor({configuration, host, port, generationId, workerInstanceId, maxConcurrentForkedJobs, maxConcurrentInlineJobs, pooledRunnerCount, pooledRunnerConcurrency, pooledRunnerMaxJobs, pooledRunnerMaxRssBytes, pooledRunnerMaxLifetimeMs, runnerMaxOldSpaceSizeMb, runnerMallocArenaMax, forkedChildSigkillGraceMs, heartbeatIntervalMs, generationHandshakeTimeoutMs = DEFAULT_GENERATION_HANDSHAKE_TIMEOUT_MS, reconnectDelayMs = 1000, jobTimeoutMs, pooledRunnerSilenceTimeoutMs, closeDatabaseConnectionsOnStop = true, onStopped, onGenerationAccepted, onRetireMessage, onPooledRunnerMemoryObservation} = {}) {
     /**
      * Narrows the runtime value to the documented type.
      * @type {Promise<import("../configuration.js").default>} */
@@ -261,6 +274,8 @@ export default class BackgroundJobsWorker {
     this.pooledRunnerMaxJobs = this.pooledRunnerMaxJobsOverride || 100
     this.pooledRunnerMaxRssBytes = this.pooledRunnerMaxRssBytesOverride || 512 * 1024 * 1024
     this.pooledRunnerMaxLifetimeMs = this.pooledRunnerMaxLifetimeMsOverride || 60 * 60 * 1000
+    this.pooledRunnerSilenceTimeoutMsOverride = typeof pooledRunnerSilenceTimeoutMs === "number" ? pooledRunnerSilenceTimeoutMs : undefined
+    this.pooledRunnerSilenceTimeoutMs = this.pooledRunnerSilenceTimeoutMsOverride ?? POOLED_CHILD_SILENCE_TIMEOUT_MS
     this.runnerMaxOldSpaceSizeMb = this.runnerMaxOldSpaceSizeMbOverride || 2048
     this.runnerMallocArenaMax = this.runnerMallocArenaMaxOverride || 4
     /**
@@ -429,6 +444,7 @@ export default class BackgroundJobsWorker {
     if (typeof this.pooledRunnerMaxJobsOverride !== "number") this.pooledRunnerMaxJobs = poolConfig.pooledRunnerMaxJobs
     if (typeof this.pooledRunnerMaxRssBytesOverride !== "number") this.pooledRunnerMaxRssBytes = poolConfig.pooledRunnerMaxRssBytes
     if (typeof this.pooledRunnerMaxLifetimeMsOverride !== "number") this.pooledRunnerMaxLifetimeMs = poolConfig.pooledRunnerMaxLifetimeMs
+    if (typeof this.pooledRunnerSilenceTimeoutMsOverride !== "number" && typeof poolConfig.pooledRunnerSilenceTimeoutMs === "number") this.pooledRunnerSilenceTimeoutMs = poolConfig.pooledRunnerSilenceTimeoutMs
     if (typeof this.runnerMaxOldSpaceSizeMbOverride !== "number" && typeof poolConfig.runnerMaxOldSpaceSizeMb === "number") this.runnerMaxOldSpaceSizeMb = poolConfig.runnerMaxOldSpaceSizeMb
     if (typeof this.runnerMallocArenaMaxOverride !== "number" && typeof poolConfig.runnerMallocArenaMax === "number") this.runnerMallocArenaMax = poolConfig.runnerMallocArenaMax
 
@@ -1279,6 +1295,7 @@ export default class BackgroundJobsWorker {
     const timeoutTimer = this._armPooledJobTimeout({child, payload})
 
     state.inflight.set(payload.id, {payload, resolve: resolvePooledJob, pooledJob, timeoutTimer})
+    this._notePooledChildActivity({child, state})
     try {
       child.send({type: "job", payload, sharedTransactionBroker: this._pooledJobSharedTransactionBrokerConfig()})
     } catch (error) {
@@ -1403,7 +1420,7 @@ export default class BackgroundJobsWorker {
     })
     this.pooledChildren.add(child)
     this.inflightProcessChildren.add(child)
-    this.pooledChildStates.set(child, {createdAtMs: Date.now(), jobsRun: 0, inflight: new Map(), lastDispatchSeq: 0, retiring: false, started: false})
+    this.pooledChildStates.set(child, {createdAtMs: Date.now(), jobsRun: 0, inflight: new Map(), lastDispatchSeq: 0, retiring: false, started: false, lastActivityAtMs: Date.now()})
     child.on("message", (message) => this._handlePooledChildMessage({child, message}))
     child.once("exit", (exitCode, signal) => this._handlePooledChildFailure({
       child,
@@ -1438,6 +1455,7 @@ export default class BackgroundJobsWorker {
     if (!message || typeof message !== "object") return
     const record = /** @type {{type?: ReturnType<typeof JSON.parse>, childInstanceId?: ReturnType<typeof JSON.parse>, jobId?: ReturnType<typeof JSON.parse>, acknowledged?: ReturnType<typeof JSON.parse>, rssBytes?: ReturnType<typeof JSON.parse>, peakRssBytes?: ReturnType<typeof JSON.parse>, error?: ReturnType<typeof JSON.parse>}} */ (message)
     const state = this.pooledChildStates.get(child)
+    this._notePooledChildActivity({child, state})
     if (record.type === "ready") {
       if (state) {
         state.started = true
@@ -1700,6 +1718,112 @@ export default class BackgroundJobsWorker {
     return false
   }
 
+  /**
+   * Records one pooled child's IPC activity and re-arms its silence watchdog while
+   * that child still owns in-flight jobs. Every message the child sends — readiness,
+   * acceptance, memory observation, shutdown observation, or job outcome — proves its
+   * event loop is running, because a healthy child samples itself every 10 seconds
+   * while jobs are in flight. Silence past the bound therefore means a wedged child
+   * that can no longer prove it is alive, not a busy one.
+   * @param {object} args - Activity details.
+   * @param {import("node:child_process").ChildProcess} args.child - Pooled child.
+   * @param {PooledChildState | undefined} args.state - Child state.
+   * @returns {void}
+   */
+  _notePooledChildActivity({child, state}) {
+    if (!state) return
+    state.lastActivityAtMs = Date.now()
+    if (state.inflight.size > 0 && !state.settling) this._armPooledChildSilenceTimer({child, state})
+  }
+
+  /**
+   * Resolves the effective pooled-child silence bound in ms, or null when disabled.
+   * A non-positive or non-finite value disables the watchdog at whichever level
+   * supplied it, matching the job-timeout contract.
+   * @returns {number | null} - Bound in ms, or null when disabled.
+   */
+  _resolvePooledChildSilenceTimeoutMs() {
+    const raw = this.pooledRunnerSilenceTimeoutMs
+
+    if (typeof raw !== "number" || !Number.isFinite(raw) || raw <= 0) return null
+
+    return Math.min(raw, MAX_FORKED_JOB_TIMEOUT_MS)
+  }
+
+  /**
+   * Re-arms one child's silence watchdog from its last observed activity. Only
+   * children with in-flight jobs are watched: a child with nothing in flight cannot
+   * strand work, and its periodic sampler is inactive then, so silence is not
+   * evidence of a wedge.
+   * @param {object} args - Watchdog details.
+   * @param {import("node:child_process").ChildProcess} args.child - Pooled child.
+   * @param {PooledChildState} args.state - Child state.
+   * @returns {void}
+   */
+  _armPooledChildSilenceTimer({child, state}) {
+    const timeoutMs = this._resolvePooledChildSilenceTimeoutMs()
+    if (!(typeof timeoutMs === "number" && timeoutMs > 0)) return
+
+    if (state.silenceTimer) clearTimeout(state.silenceTimer)
+    state.silenceTimer = setTimeout(() => this._onPooledChildSilence({child, state}), timeoutMs)
+    if (typeof state.silenceTimer.unref === "function") state.silenceTimer.unref()
+  }
+
+  /**
+   * Fired when a pooled child with in-flight jobs stays silent past the bound. A
+   * wedged child keeps its IPC channel open but stops running its own timers, so the
+   * disconnect/exit path never fires and its jobs stay stranded until a human
+   * notices. The worker declares the child dead: it requests shutdown under the exact
+   * `child_silence` reason, reports the whole in-flight set as failed through the
+   * established failure path (so the jobs requeue and capacity is re-advertised), and
+   * signals the wedged process — SIGTERM, then SIGKILL after the existing grace — so
+   * it actually goes away instead of blocking the event loop forever.
+   * @param {object} args - Watchdog details.
+   * @param {import("node:child_process").ChildProcess} args.child - Pooled child.
+   * @param {PooledChildState} args.state - Child state.
+   * @returns {void}
+   */
+  _onPooledChildSilence({child, state}) {
+    state.silenceTimer = undefined
+    if (state.settling || state.shutdownReason) return
+    const silentMs = Date.now() - state.lastActivityAtMs
+    const boundMs = this._resolvePooledChildSilenceTimeoutMs()
+    if (!(typeof boundMs === "number" && silentMs >= boundMs)) return
+
+    const error = new Error(`Pooled background job runner went silent for ${silentMs}ms past the ${boundMs}ms bound — treated as wedged`)
+    this._logPooledSilenceEvent({child, state, silentMs, boundMs})
+    this._requestPooledChildShutdown({child, reason: "child_silence", signal: "SIGTERM"})
+    void this._handlePooledChildFailure({child, error, origin: "child-silence", signal: null})
+    state.silenceSigkillTimer = setTimeout(() => {
+      state.silenceSigkillTimer = undefined
+      this._signalPooledChild({child, signal: "SIGKILL"})
+    }, this.forkedChildSigkillGraceMs)
+    if (typeof state.silenceSigkillTimer.unref === "function") state.silenceSigkillTimer.unref()
+  }
+
+  /**
+   * Logs one compact JSON line naming a child the silence watchdog declared wedged
+   * (the same stderr surface the memory observations use, which reaches the production
+   * log), so the recovery is attributable after the fact instead of looking like a
+   * random runner exit.
+   * @param {object} args - Event details.
+   * @param {import("node:child_process").ChildProcess} args.child - Pooled child.
+   * @param {PooledChildState} args.state - Child state.
+   * @param {number} args.silentMs - Observed silence in ms.
+   * @param {number} args.boundMs - Configured bound in ms.
+   * @returns {void}
+   */
+  _logPooledSilenceEvent({child, state, silentMs, boundMs}) {
+    console.error(JSON.stringify({
+      event: "pooled-child-silence",
+      childInstanceId: state.childInstanceId ?? null,
+      childPid: child.pid ?? null,
+      silentMs,
+      boundMs,
+      jobs: state.inflight.size
+    }))
+  }
+
   /**
    * Logs one compact pooled-capacity event to the worker's own stderr (the
    * surface that reaches the production log). Used by the bounded liveness
@@ -1848,6 +1972,8 @@ export default class BackgroundJobsWorker {
       // the SIGKILL grace from a timeout kill, and every armed per-job backstop.
       if (state.timeoutSigkillTimer) clearTimeout(state.timeoutSigkillTimer)
       if (state.shutdownSignalTimer) clearTimeout(state.shutdownSignalTimer)
+      if (state.silenceTimer) clearTimeout(state.silenceTimer)
+      if (state.silenceSigkillTimer) clearTimeout(state.silenceSigkillTimer)
       for (const inflightEntry of state.inflight.values()) {
         if (inflightEntry.timeoutTimer) clearTimeout(inflightEntry.timeoutTimer)
       }

package/build/configuration-types.js

@@ -199,6 +199,7 @@
  * @property {number} [pooledRunnerMaxJobs] - Number of sequential jobs a pooled child runs before it is replaced, bounding process-level resource accumulation. Default: `100`.
  * @property {number} [pooledRunnerMaxRssBytes] - Peak RSS (the kernel `VmHWM` high-water mark reported by the child) at which a pooled child is replaced after an acknowledged job. The child's peak, not its settled RSS at job-outcome time, is the trigger, so a burst working-set that reclaims before the outcome still retires the child. Default: `536870912` (512 MiB).
  * @property {number} [pooledRunnerMaxLifetimeMs] - Age after an acknowledged job at which a pooled child is replaced. Default: `3600000` (one hour).
+ * @property {number} [pooledRunnerSilenceTimeoutMs] - IPC-silence bound for a pooled child with in-flight jobs. A child that sends nothing (readiness, acceptance, memory observation, or job outcome) for longer than this is declared wedged: its in-flight jobs are reported failed for requeue, its capacity is re-advertised, and the wedged process is terminated. A healthy child samples itself every 10 seconds while jobs run, so the bound only fires on a child that cannot prove it is alive. Default: `120000`.
  * @property {number} [runnerMaxOldSpaceSizeMb] - V8 heap cap (`--max-old-space-size`, MiB) applied to every background-jobs runner child process (pooled, forked, and spawned) so a single child can never commit multiple GBs of heap. Default: `2048`.
  * @property {number} [runnerMallocArenaMax] - `MALLOC_ARENA_MAX` exported to every background-jobs runner child process, bounding glibc per-thread arenas. Defaults to an inherited `MALLOC_ARENA_MAX`, else `4`.
  * @property {Record<string, {maxConcurrent?: number, priority?: number}>} [queues] - Per-queue
@@ -476,9 +477,19 @@
  * @property {"hasOne" | "hasMany"} type - Attachment cardinality.
  */
 
+/**
+ * One declarative quick-search column. A plain string is a root-table column;
+ * `{path, column}` searches a column on a joined relationship path.
+ * @typedef {object} FrontendModelQuickSearchColumn
+ * @property {string[]} [path] - Relationship path from the root model to the column's table.
+ * @property {string} column - Database column name to search.
+ */
+
 /**
  * @typedef {object} FrontendModelResourceConfiguration
  * @property {Array<string | FrontendModelAttributeConfiguration> | Record<string, FrontendModelAttributeConfiguration | import("./database/drivers/base-column.js").default | boolean>} attributes - Attributes to expose on the frontend model.
+ * @property {Array<FrontendModelQuickSearchColumn | string>} [quickSearchColumns] - Declarative quick-search text columns; an index search on the pseudo-column `quickSearch` expands to an OR of LIKE conditions over these columns.
+ * @property {Array<FrontendModelQuickSearchColumn | string>} [quickSearchNumericColumns] - Declarative quick-search numeric columns; an integer quick-search value also matches these columns exactly.
  * @property {string[]} [abilities] - Additional camelCase ability action names to expose for per-record `record.can(action)` reads. Base CRUD actions (`read`, `create`, `update`, `destroy`) are always included and must not be listed here.
  * @property {Record<string, FrontendModelAttachmentConfiguration>} [attachments] - Attachment helpers keyed by attachment name.
  * @property {string[]} [commands] - Legacy built-in command names (`index`, `find`, `create`, `update`, `destroy`, `attach`, `download`, `url`).
@@ -588,17 +599,75 @@
  * @property {() => boolean | Promise<boolean>} [isOnline] - Connectivity gate for pulls and replays. Defaults to always online.
  * @property {string} [mountPath] - Mount path the server serves the sync endpoints under (match the server's `sync.api.mountPath`). Defaults to "/velocious/sync"; normalization strips trailing slashes and always fills in the default.
  * @property {(error: Error) => void} [onError] - Reports background replay/pull failures. Defaults to rethrowing.
+ * @property {VelociousSyncClientOfflineConfiguration} [offline] - Long-offline session configuration consumed by `startOfflineSession()`: device identity, enrollment, grant scopes, signed-replay path, and the backend public key for peer import.
  * @property {VelociousSyncClientRealtimeConfiguration} [realtime] - Realtime push configuration consumed by `subscribeRealtime(...)`.
  * @property {VelociousSyncClientTransport} transport - Transport posting to the framework sync endpoints (e.g. the frontend-model websocket client).
  * @property {VelociousSyncRealtimeWebsocketClient} [websocketClient] - Shared app-lifetime websocket client (the low-level form) that all sync traffic rides. Provide the same instance the frontend-model transport uses so one connection carries everything. When set, the realtime bridge subscribes channels on it and never owns its lifecycle: unsubscribing closes only channel subscriptions, leaving the socket connected.
  * @property {string | (() => string | null | undefined)} [websocketUrl] - Shared app-lifetime websocket URL. When set (and no `websocketClient` is given), the framework builds and owns one reconnecting `VelociousWebsocketClient` for all sync traffic, connected on first use.
  */
 
+/**
+ * App-owned durable storage for the device signing identity (the backend-signed
+ * device certificate plus the device private key). Native apps back this with
+ * secure storage; the framework never embeds a storage technology.
+ * @typedef {object} VelociousSyncClientDeviceIdentityStorage
+ * @property {() => import("./sync/sync-offline-session.js").SyncOfflineDeviceIdentity | null | undefined | Promise<import("./sync/sync-offline-session.js").SyncOfflineDeviceIdentity | null | undefined>} load - Reads the stored identity (null when the device has none yet).
+ * @property {(identity: import("./sync/sync-offline-session.js").SyncOfflineDeviceIdentity) => Promise<void> | void} save - Persists the identity.
+ */
+
+/**
+ * App-owned durable storage for retained offline grants. Pending mutations must
+ * always replay with the grant they were signed under, so a device that
+ * restarts while offline needs its issued grants back.
+ * @typedef {object} VelociousSyncClientGrantStorage
+ * @property {() => Array<import("./sync/offline-grant.js").SignedOfflineGrant> | Promise<Array<import("./sync/offline-grant.js").SignedOfflineGrant>>} load - Reads the retained grants.
+ * @property {(grants: Array<import("./sync/offline-grant.js").SignedOfflineGrant>) => Promise<void> | void} save - Persists the retained grants.
+ */
+
+/**
+ * Client-side long-offline session configuration consumed by
+ * `SyncClient.startOfflineSession()`. The framework owns the session lifecycle
+ * (identity, grant bootstrap/refresh, signing, signed replay, peer bundles) over
+ * the built-in `/frontend-models/sync/bootstrap` and
+ * `/frontend-models/sync/replay` endpoints; the app only owns durable storage,
+ * the enrollment hook, and the grant scopes.
+ * @typedef {object} VelociousSyncClientOfflineConfiguration
+ * @property {VelociousSyncClientDeviceIdentityStorage} deviceIdentityStorage - App-owned durable device-identity storage adapter.
+ * @property {(args: {configuration: import("./configuration.js").default, publicKey: import("./sync/device-identity.js").SyncJsonWebKey}) => import("./sync/device-identity.js").DeviceCertificate | Promise<import("./sync/device-identity.js").DeviceCertificate>} enrollDevice - App-owned enrollment hook: asks the backend to register the device public key and returns the backend-signed certificate.
+ * @property {(args: {configuration: import("./configuration.js").default}) => Record<string, import("./configuration-types.js").FrontendModelSyncJsonValue> | Promise<Record<string, import("./configuration-types.js").FrontendModelSyncJsonValue>>} grantScopes - Resolves the scopes the bootstrap request asks the backend to materialize into the grant.
+ * @property {string} [bootstrapPath] - Signed-bootstrap endpoint path. Defaults to "/frontend-models/sync/bootstrap".
+ * @property {string} [replayPath] - Signed-replay endpoint path. Defaults to "/frontend-models/sync/replay".
+ * @property {import("./sync/device-identity.js").SyncJsonWebKey} [backendPublicKey] - Backend public key used to verify device certificates and imported peer mutations.
+ * @property {VelociousSyncClientGrantStorage} [grantStorage] - Optional durable grant retention adapter.
+ * @property {import("./sync/local-mutation-log.js").default} [mutationLog] - Durable local mutation log the offline session replays and exports. Defaults to the conflict-tracking log declared by the synced models.
+ * @property {() => Date} [now] - Session clock. Defaults to the current time.
+ */
+
+/**
+ * Normalized client-side long-offline session configuration. Same shape as
+ * {@link VelociousSyncClientOfflineConfiguration} with the defaults filled in.
+ * @typedef {VelociousSyncClientOfflineConfiguration & {
+ *   bootstrapPath: string,
+ *   configuration: import("./configuration.js").default,
+ *   now: () => Date,
+ *   replayPath: string
+ * }} NormalizedVelociousSyncClientOfflineConfiguration
+ */
+
+/**
+ * Normalized client-side sync configuration. Same shape as
+ * {@link VelociousSyncClientConfiguration} with the defaults filled in.
+ * @typedef {VelociousSyncClientConfiguration & {
+ *   mountPath: string,
+ *   offline: NormalizedVelociousSyncClientOfflineConfiguration | undefined
+ * }} NormalizedVelociousSyncClientConfiguration
+ */
+
 /**
  * Velocious sync configuration.
  * @typedef {object} VelociousSyncConfiguration
  * @property {VelociousSyncApiConfiguration} [api] - Auto-mounts the Velocious sync changes/replay endpoints for this resource class.
- * @property {VelociousSyncClientConfiguration} [client] - Client-side sync configuration consumed by `SyncClient.fromConfiguration(...)`.
+ * @property {NormalizedVelociousSyncClientConfiguration | undefined} client - Normalized client-side sync configuration consumed by `SyncClient.fromConfiguration(...)`.
  * @property {import("./sync/device-identity.js").SyncJsonWebKey | null} [deviceCertificateBackendPublicKey] - Public backend key used to verify offline device certificates for sync replay.
  * @property {number} [changeFeedRetentionSize] - Number of accepted server changes retained before clients must refresh from snapshot.
  * @property {Array<import("./sync/offline-grant.js").OfflineGrantSigningKey>} offlineGrantSigningKeys - Signing keys used to issue and verify offline grants. Secrets must never be exposed to clients.
@@ -617,13 +686,15 @@
  */
 
 /**
- * @typedef {Omit<FrontendModelResourceConfiguration, "abilities" | "builtInCollectionCommands" | "builtInMemberCommands" | "collectionCommands" | "commands" | "memberCommands" | "sync"> & {
+ * @typedef {Omit<FrontendModelResourceConfiguration, "abilities" | "builtInCollectionCommands" | "builtInMemberCommands" | "collectionCommands" | "commands" | "memberCommands" | "quickSearchColumns" | "quickSearchNumericColumns" | "sync"> & {
  *   abilities: FrontendModelResourceAbilitiesConfiguration
  *   builtInCollectionCommands: Record<string, string>
  *   builtInMemberCommands: Record<string, string>
  *   collectionCommands: Record<string, string>
  *   commandMetadata: Record<string, {args: Array<{name: string, type: string}>, returnType: string | null}>
  *   memberCommands: Record<string, string>
+ *   quickSearchColumns: FrontendModelQuickSearchColumn[] | null
+ *   quickSearchNumericColumns: FrontendModelQuickSearchColumn[] | null
  *   sync?: NormalizedFrontendModelResourceSyncConfiguration
  * }} NormalizedFrontendModelResourceConfiguration
  */

package/build/configuration.js

@@ -900,7 +900,7 @@ export default class VelociousConfiguration {
   /**
    * Normalizes client-side sync configuration consumed by `SyncClient.fromConfiguration(...)`.
    * @param {import("./configuration-types.js").VelociousSyncClientConfiguration | undefined} client - Client-side sync configuration.
-   * @returns {import("./configuration-types.js").VelociousSyncClientConfiguration | undefined} - Normalized client-side sync configuration.
+   * @returns {import("./configuration-types.js").NormalizedVelociousSyncClientConfiguration | undefined} - Normalized client-side sync configuration.
    */
   _normalizeSyncClientConfiguration(client) {
     if (client === undefined || client === null) return undefined
@@ -909,11 +909,11 @@ export default class VelociousConfiguration {
       throw new Error("sync.client must be an object with transport and authenticationToken")
     }
 
-    const {authenticationToken, batchSize, isOnline, mountPath, onError, realtime, transport, websocketClient, websocketUrl, ...restClient} = client
+    const {authenticationToken, batchSize, isOnline, mountPath, onError, offline, realtime, transport, websocketClient, websocketUrl, ...restClient} = client
     const restClientKeys = Object.keys(restClient)
 
     if (restClientKeys.length > 0) {
-      throw new Error(`sync.client received unknown keys: ${restClientKeys.join(", ")} (supported: authenticationToken, batchSize, isOnline, mountPath, onError, realtime, transport, websocketClient, websocketUrl)`)
+      throw new Error(`sync.client received unknown keys: ${restClientKeys.join(", ")} (supported: authenticationToken, batchSize, isOnline, mountPath, onError, offline, realtime, transport, websocketClient, websocketUrl)`)
     }
     if (!transport || typeof transport !== "object" || typeof transport.post !== "function") {
       throw new Error("sync.client.transport must be an object with a post(path, body) method (like the frontend-model websocket client)")
@@ -945,6 +945,7 @@ export default class VelociousConfiguration {
       batchSize,
       isOnline,
       mountPath: (mountPath || "/velocious/sync").replace(/\/+$/u, "") || "/",
+      offline: this._normalizeSyncClientOfflineConfiguration(offline),
       onError,
       realtime,
       transport,
@@ -953,6 +954,63 @@ export default class VelociousConfiguration {
     }
   }
 
+  /**
+   * Normalizes the client-side long-offline session configuration consumed by
+   * `SyncClient.startOfflineSession()`. The framework owns the session
+   * lifecycle; the app provides durable identity storage, the enrollment hook,
+   * and the grant scopes callback.
+   * @param {import("./configuration-types.js").VelociousSyncClientOfflineConfiguration | undefined} offline - Offline configuration block.
+   * @returns {import("./configuration-types.js").NormalizedVelociousSyncClientOfflineConfiguration | undefined} - Normalized offline configuration.
+   */
+  _normalizeSyncClientOfflineConfiguration(offline) {
+    if (offline === undefined || offline === null) return undefined
+
+    if (typeof offline !== "object" || Array.isArray(offline)) {
+      throw new Error("sync.client.offline must be an object with deviceIdentityStorage, enrollDevice, and grantScopes")
+    }
+
+    const {backendPublicKey, bootstrapPath, deviceIdentityStorage, enrollDevice, grantScopes, grantStorage, mutationLog, now, replayPath, ...restOffline} = offline
+    const restOfflineKeys = Object.keys(restOffline)
+
+    if (restOfflineKeys.length > 0) {
+      throw new Error(`sync.client.offline received unknown keys: ${restOfflineKeys.join(", ")} (supported: backendPublicKey, bootstrapPath, deviceIdentityStorage, enrollDevice, grantScopes, grantStorage, mutationLog, now, replayPath)`)
+    }
+    if (!deviceIdentityStorage || typeof deviceIdentityStorage !== "object" || Array.isArray(deviceIdentityStorage) || typeof deviceIdentityStorage.load !== "function" || typeof deviceIdentityStorage.save !== "function") {
+      throw new Error("sync.client.offline.deviceIdentityStorage must be an object with load() and save(identity) methods")
+    }
+    if (typeof enrollDevice !== "function") throw new Error("sync.client.offline.enrollDevice must be a function resolving the backend-signed device certificate")
+    if (typeof grantScopes !== "function") throw new Error("sync.client.offline.grantScopes must be a function resolving the bootstrap grant scopes")
+    if (backendPublicKey !== undefined && (typeof backendPublicKey !== "object" || backendPublicKey === null || Array.isArray(backendPublicKey))) {
+      throw new Error("sync.client.offline.backendPublicKey must be a public JSON Web Key object")
+    }
+    if (bootstrapPath !== undefined && (typeof bootstrapPath !== "string" || !bootstrapPath.startsWith("/"))) {
+      throw new Error(`sync.client.offline.bootstrapPath must start with '/', got: ${String(bootstrapPath)}`)
+    }
+    if (replayPath !== undefined && (typeof replayPath !== "string" || !replayPath.startsWith("/"))) {
+      throw new Error(`sync.client.offline.replayPath must start with '/', got: ${String(replayPath)}`)
+    }
+    if (grantStorage !== undefined && (typeof grantStorage !== "object" || grantStorage === null || Array.isArray(grantStorage) || typeof grantStorage.load !== "function" || typeof grantStorage.save !== "function")) {
+      throw new Error("sync.client.offline.grantStorage must be an object with load() and save(grants) methods")
+    }
+    if (mutationLog !== undefined && (typeof mutationLog !== "object" || mutationLog === null || typeof mutationLog.append !== "function")) {
+      throw new Error("sync.client.offline.mutationLog must be a LocalMutationLog")
+    }
+    if (now !== undefined && typeof now !== "function") throw new Error("sync.client.offline.now must be a function resolving the session clock")
+
+    return {
+      backendPublicKey,
+      bootstrapPath: (bootstrapPath || "/frontend-models/sync/bootstrap").replace(/\/+$/u, "") || "/",
+      configuration: this,
+      deviceIdentityStorage,
+      enrollDevice,
+      grantScopes,
+      grantStorage,
+      mutationLog,
+      now: now || (() => new Date()),
+      replayPath: (replayPath || "/frontend-models/sync/replay").replace(/\/+$/u, "") || "/"
+    }
+  }
+
   /**
    * Normalizes sync API endpoint configuration.
    * @param {import("./configuration-types.js").VelociousSyncApiConfiguration | undefined} api - Sync API configuration.
@@ -1762,6 +1820,7 @@ export default class VelociousConfiguration {
     const envPooledRunnerMaxJobsRaw = processEnvironment?.VELOCIOUS_BACKGROUND_JOBS_POOLED_RUNNER_MAX_JOBS
     const envPooledRunnerMaxRssBytesRaw = processEnvironment?.VELOCIOUS_BACKGROUND_JOBS_POOLED_RUNNER_MAX_RSS_BYTES
     const envPooledRunnerMaxLifetimeMsRaw = processEnvironment?.VELOCIOUS_BACKGROUND_JOBS_POOLED_RUNNER_MAX_LIFETIME_MS
+    const envPooledRunnerSilenceTimeoutMsRaw = processEnvironment?.VELOCIOUS_BACKGROUND_JOBS_POOLED_RUNNER_SILENCE_TIMEOUT_MS
     const envRunnerMaxOldSpaceSizeMbRaw = processEnvironment?.VELOCIOUS_BACKGROUND_JOBS_RUNNER_MAX_OLD_SPACE_SIZE_MB
     const envRunnerMallocArenaMaxRaw = processEnvironment?.VELOCIOUS_BACKGROUND_JOBS_RUNNER_MALLOC_ARENA_MAX
     const envDispatchStrategy = processEnvironment?.VELOCIOUS_BACKGROUND_JOBS_DISPATCH_STRATEGY
@@ -1775,6 +1834,7 @@ export default class VelociousConfiguration {
     const envPooledRunnerMaxJobs = envPooledRunnerMaxJobsRaw ? Number(envPooledRunnerMaxJobsRaw) : undefined
     const envPooledRunnerMaxRssBytes = envPooledRunnerMaxRssBytesRaw ? Number(envPooledRunnerMaxRssBytesRaw) : undefined
     const envPooledRunnerMaxLifetimeMs = envPooledRunnerMaxLifetimeMsRaw ? Number(envPooledRunnerMaxLifetimeMsRaw) : undefined
+    const envPooledRunnerSilenceTimeoutMs = envPooledRunnerSilenceTimeoutMsRaw ? Number(envPooledRunnerSilenceTimeoutMsRaw) : undefined
     const envRunnerMaxOldSpaceSizeMb = envRunnerMaxOldSpaceSizeMbRaw ? Number(envRunnerMaxOldSpaceSizeMbRaw) : undefined
     const envRunnerMallocArenaMax = envRunnerMallocArenaMaxRaw ? Number(envRunnerMallocArenaMaxRaw) : undefined
     const envPollInterval = envPollIntervalRaw ? Number(envPollIntervalRaw) : undefined
@@ -1812,6 +1872,9 @@ export default class VelociousConfiguration {
     const pooledRunnerMaxLifetimeMs = typeof configured.pooledRunnerMaxLifetimeMs === "number" && Number.isFinite(configured.pooledRunnerMaxLifetimeMs) && configured.pooledRunnerMaxLifetimeMs >= 1
       ? configured.pooledRunnerMaxLifetimeMs
       : (!("pooledRunnerMaxLifetimeMs" in configured) && typeof envPooledRunnerMaxLifetimeMs === "number" && Number.isFinite(envPooledRunnerMaxLifetimeMs) && envPooledRunnerMaxLifetimeMs >= 1 ? envPooledRunnerMaxLifetimeMs : 60 * 60 * 1000)
+    const pooledRunnerSilenceTimeoutMs = typeof configured.pooledRunnerSilenceTimeoutMs === "number" && Number.isFinite(configured.pooledRunnerSilenceTimeoutMs) && configured.pooledRunnerSilenceTimeoutMs >= 1
+      ? configured.pooledRunnerSilenceTimeoutMs
+      : (!("pooledRunnerSilenceTimeoutMs" in configured) && typeof envPooledRunnerSilenceTimeoutMs === "number" && Number.isFinite(envPooledRunnerSilenceTimeoutMs) && envPooledRunnerSilenceTimeoutMs >= 1 ? envPooledRunnerSilenceTimeoutMs : 120000)
     // Runner children get a hard V8 heap cap and a bounded glibc arena count
     // so one child can never commit multiple GBs of heap or unbounded
     // allocator arenas. The cap stays far above observed runner usage; an
@@ -1872,7 +1935,7 @@ export default class VelociousConfiguration {
 
     const jobClasses = this.getBackgroundJobClasses()
 
-    return {host, port, databaseIdentifier, maxConcurrentForkedJobs, maxConcurrentInlineJobs, mode, pooledRunnerCount, pooledRunnerConcurrency, pooledRunnerMaxJobs, pooledRunnerMaxRssBytes, pooledRunnerMaxLifetimeMs, runnerMaxOldSpaceSizeMb, runnerMallocArenaMax, dispatchStrategy, pollIntervalMs, drainStoreOperationTimeoutMs, scheduledEnqueueTimeoutMs, queues, jobClasses, jobTimeoutMs, retention, generationId, initialGenerationState, lifecycleSocketPath}
+    return {host, port, databaseIdentifier, maxConcurrentForkedJobs, maxConcurrentInlineJobs, mode, pooledRunnerCount, pooledRunnerConcurrency, pooledRunnerMaxJobs, pooledRunnerMaxRssBytes, pooledRunnerMaxLifetimeMs, pooledRunnerSilenceTimeoutMs, runnerMaxOldSpaceSizeMb, runnerMallocArenaMax, dispatchStrategy, pollIntervalMs, drainStoreOperationTimeoutMs, scheduledEnqueueTimeoutMs, queues, jobClasses, jobTimeoutMs, retention, generationId, initialGenerationState, lifecycleSocketPath}
   }
 
   /**