velocious 1.0.700 → 1.0.702

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/configuration-types.js

@@ -329,7 +329,7 @@
  * @property {string} [host] - Hostname to bind the HTTP server to.
  * @property {boolean} [inProcess] - Run HTTP handlers in the main thread instead of worker threads.
  * @property {number} [maxBufferedResponseBodyBytes] - Maximum UTF-8/binary byte length accepted by buffered response bodies. Unbounded when absent; streamed file responses are unaffected.
- * @property {number} [maxRequestBodyBytes] - Maximum decoded request-body bytes accepted before routing. Unbounded when absent.
+ * @property {number} [maxRequestBodyBytes] - Maximum decoded request-body bytes accepted before routing. Unbounded when absent, except the built-in MCP endpoint, which defaults to a 1 MiB cap that this option overrides.
  * @property {HttpRequestBodyPolicyResolver} [requestBodyPolicyResolver] - Optional synchronous header-stage resolver for per-request limits and raw-body handling.
  * @property {number} [maxWorkers] - Backward-compatible alias for workers.
  * @property {number} [port] - Port to bind the HTTP server to.
@@ -476,9 +476,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 +598,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 +685,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

@@ -229,6 +229,14 @@ function normalizeHttpCompression(value) {
   }
 }
 
+/**
+ * Default request-body limit for the built-in MCP endpoint. JSON-RPC messages are small,
+ * so the framework caps them instead of making every app that enables `mcp: true` restate
+ * a request-body policy. Explicit `httpServer.maxRequestBodyBytes` or a resolver limit wins.
+ * @type {number}
+ */
+const DEFAULT_MCP_MAX_REQUEST_BODY_BYTES = 1024 * 1024
+
 export default class VelociousConfiguration {
   /**
    * Close database connections promise.
@@ -776,31 +784,58 @@ export default class VelociousConfiguration {
   resolveHttpRequestBodyPolicy(args) {
     const resolver = this.httpServer.requestBodyPolicyResolver
     const configuredPolicy = resolver ? resolver(args) : undefined
+    /** @type {import("./configuration-types.js").ResolvedHttpRequestBodyPolicy} */
+    let resolvedPolicy
 
     if (configuredPolicy === undefined) {
-      return {maxRequestBodyBytes: this.httpServer.maxRequestBodyBytes, mode: "parsed"}
-    }
+      resolvedPolicy = {maxRequestBodyBytes: this.httpServer.maxRequestBodyBytes, mode: "parsed"}
+    } else {
+      if (!configuredPolicy || typeof configuredPolicy !== "object" || Array.isArray(configuredPolicy)) {
+        throw new TypeError("httpServer.requestBodyPolicyResolver must return an object or undefined")
+      }
 
-    if (!configuredPolicy || typeof configuredPolicy !== "object" || Array.isArray(configuredPolicy)) {
-      throw new TypeError("httpServer.requestBodyPolicyResolver must return an object or undefined")
-    }
+      const {maxRequestBodyBytes, mode = "parsed", ...restPolicy} = configuredPolicy
+      const unknownKeys = Object.keys(restPolicy)
 
-    const {maxRequestBodyBytes, mode = "parsed", ...restPolicy} = configuredPolicy
-    const unknownKeys = Object.keys(restPolicy)
+      if (unknownKeys.length > 0) {
+        throw new TypeError(`httpServer.requestBodyPolicyResolver returned unknown keys: ${unknownKeys.join(", ")} (supported: maxRequestBodyBytes, mode)`)
+      }
+      if (mode !== "parsed" && mode !== "raw") {
+        throw new TypeError(`httpServer.requestBodyPolicyResolver mode must be "parsed" or "raw", got: ${String(mode)}`)
+      }
 
-    if (unknownKeys.length > 0) {
-      throw new TypeError(`httpServer.requestBodyPolicyResolver returned unknown keys: ${unknownKeys.join(", ")} (supported: maxRequestBodyBytes, mode)`)
-    }
-    if (mode !== "parsed" && mode !== "raw") {
-      throw new TypeError(`httpServer.requestBodyPolicyResolver mode must be "parsed" or "raw", got: ${String(mode)}`)
+      resolvedPolicy = {
+        maxRequestBodyBytes: maxRequestBodyBytes === undefined
+          ? this.httpServer.maxRequestBodyBytes
+          : optionalPositiveSafeInteger(maxRequestBodyBytes, "httpServer.requestBodyPolicyResolver maxRequestBodyBytes"),
+        mode
+      }
     }
 
-    return {
-      maxRequestBodyBytes: maxRequestBodyBytes === undefined
-        ? this.httpServer.maxRequestBodyBytes
-        : optionalPositiveSafeInteger(maxRequestBodyBytes, "httpServer.requestBodyPolicyResolver maxRequestBodyBytes"),
-      mode
+    return this._applyMcpRequestBodyPolicyDefaults({args, policy: resolvedPolicy})
+  }
+
+  /**
+   * Enforces the built-in MCP endpoint's body contract without per-app plumbing: the
+   * JSON-RPC envelope is read from parsed params, so raw mode is rejected with an
+   * actionable error, and a framework default byte cap applies when the app configured none.
+   * @param {{args: import("./configuration-types.js").HttpRequestBodyPolicyResolverArgs, policy: import("./configuration-types.js").ResolvedHttpRequestBodyPolicy}} options - Resolution inputs.
+   * @returns {import("./configuration-types.js").ResolvedHttpRequestBodyPolicy} - Effective request policy.
+   */
+  _applyMcpRequestBodyPolicyDefaults({args, policy}) {
+    if (!this._mcp.enabled) return policy
+    if (args.httpMethod !== "POST") return policy
+    if (args.path.split("?")[0] !== this._mcp.path) return policy
+
+    if (policy.mode === "raw") {
+      throw new TypeError(
+        `The built-in MCP endpoint at ${this._mcp.path} requires parsed request bodies because its JSON-RPC envelope is read from params. Remove the raw-mode httpServer.requestBodyPolicyResolver entry for this path.`
+      )
     }
+
+    if (policy.maxRequestBodyBytes !== undefined) return policy
+
+    return {maxRequestBodyBytes: DEFAULT_MCP_MAX_REQUEST_BODY_BYTES, mode: policy.mode}
   }
 
   /**
@@ -865,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
@@ -874,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)")
@@ -910,6 +945,7 @@ export default class VelociousConfiguration {
       batchSize,
       isOnline,
       mountPath: (mountPath || "/velocious/sync").replace(/\/+$/u, "") || "/",
+      offline: this._normalizeSyncClientOfflineConfiguration(offline),
       onError,
       realtime,
       transport,
@@ -918,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.

package/build/frontend-model-resource/base-resource.js

@@ -29,6 +29,7 @@ import VelociousError from "../velocious-error.js"
  *   applyFrontendModelPagination: (args: {pagination: FrontendModelResourcePagination, query: import("../database/query/model-class-query.js").default<typeof import("../database/record/index.js").default>}) => void,
  *   applyFrontendModelSearch: (args: {query: import("../database/query/model-class-query.js").default<typeof import("../database/record/index.js").default>, search: FrontendModelResourceSearch}) => void,
  *   applyFrontendModelSort: (args: {query: import("../database/query/model-class-query.js").default<typeof import("../database/record/index.js").default>, sort: FrontendModelResourceSort}) => void,
+ *   ensureFrontendModelJoinPath: (args: {path: string[], query: import("../database/query/model-class-query.js").default<typeof import("../database/record/index.js").default>}) => void,
  *   frontendModelAbilityAction: (action: FrontendModelResourceAction) => string,
  *   frontendModelAbilityAuthorizedQuery: (action: FrontendModelResourceAction, options?: FrontendModelResourceAuthorizedQueryOptions) => import("../database/query/model-class-query.js").default<typeof import("../database/record/index.js").default>,
  *   frontendModelAuthorizedQuery: (action: FrontendModelResourceAction, options?: FrontendModelResourceAuthorizedQueryOptions) => import("../database/query/model-class-query.js").default<typeof import("../database/record/index.js").default>,
@@ -195,6 +196,9 @@ export function frontendModelResourceInternalConstructor(ResourceClass) {
   return /** @type {FrontendModelResourceInternalConstructor<typeof import("../database/record/index.js").default, typeof import("../database/record/index.js").default>} */ (/** @type {unknown} */ (ResourceClass))
 }
 
+const QUICK_SEARCH_COLUMN = "quickSearch"
+
+
 /**
  * Base class for backend frontend-model resources.
  * @template {FrontendModelResourceModelClass} [TModelClass=typeof import("../database/record/index.js").default]
@@ -235,6 +239,23 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
   /** @type {ReturnType<typeof JSON.parse>} */
   static SharedResource = undefined
 
+  /**
+   * Declarative quick-search text columns. When declared, an index search on
+   * the pseudo-column `quickSearch` expands to an OR of LIKE conditions over
+   * these columns instead of hitting the controller default. Each entry is a
+   * root-table column name or a `{path, column}` pair for a joined
+   * relationship path.
+   * @type {Array<import("../configuration-types.js").FrontendModelQuickSearchColumn | string> | null | undefined} */
+  static quickSearchColumns = undefined
+
+  /**
+   * Declarative quick-search numeric columns. When the trimmed quick-search
+   * value is a safe non-negative integer, each declared column also gets an
+   * exact `=` condition ORed into the quick-search predicate. Same entry shape
+   * as {@link FrontendModelBaseResource.quickSearchColumns}.
+   * @type {Array<import("../configuration-types.js").FrontendModelQuickSearchColumn | string> | null | undefined} */
+  static quickSearchNumericColumns = undefined
+
   /**
    * Declarative writable-attribute permit list (camelCase attribute names)
    * used as the default {@link FrontendModelBaseResource#permittedParams} and
@@ -282,7 +303,7 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
   /**
    * Reads a static resource config value from the environment resource first,
    * then from the shared resource.
-   * @param {"abilities" | "attachments" | "attributes" | "builtInCollectionCommands" | "builtInMemberCommands" | "collectionCommands" | "commands" | "memberCommands" | "modelName" | "primaryKey" | "relationships" | "server" | "sync" | "translatedAttributes" | "writableAttributes"} name - Static config property name.
+   * @param {"abilities" | "attachments" | "attributes" | "builtInCollectionCommands" | "builtInMemberCommands" | "collectionCommands" | "commands" | "memberCommands" | "modelName" | "primaryKey" | "quickSearchColumns" | "quickSearchNumericColumns" | "relationships" | "server" | "sync" | "translatedAttributes" | "writableAttributes"} name - Static config property name.
    * @returns {ReturnType<typeof JSON.parse>} - Resolved config value.
    */
   static sharedResourceStaticValue(name) {
@@ -459,6 +480,8 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
     const memberCommands = this.sharedResourceStaticValue("memberCommands")
     const modelName = this.sharedResourceStaticValue("modelName")
     const primaryKey = this.sharedResourceStaticValue("primaryKey")
+    const quickSearchColumns = this.sharedResourceStaticValue("quickSearchColumns")
+    const quickSearchNumericColumns = this.sharedResourceStaticValue("quickSearchNumericColumns")
     const relationships = this.sharedResourceStaticValue("relationships")
     const server = this.sharedResourceStaticValue("server")
     const sync = this.sharedResourceStaticValue("sync")
@@ -476,6 +499,8 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
     if (memberCommands) config.memberCommands = /** @type {string[]} */ (memberCommands)
     if (modelName) config.modelName = /** @type {string} */ (modelName)
     if (primaryKey) config.primaryKey = /** @type {string | string[]} */ (primaryKey)
+    if (quickSearchColumns !== undefined) config.quickSearchColumns = /** @type {Array<import("../configuration-types.js").FrontendModelQuickSearchColumn | string>} */ (quickSearchColumns)
+    if (quickSearchNumericColumns !== undefined) config.quickSearchNumericColumns = /** @type {Array<import("../configuration-types.js").FrontendModelQuickSearchColumn | string>} */ (quickSearchNumericColumns)
     if (relationships) config.relationships = /** @type {string[]} */ (relationships)
     if (server) config.server = /** @type {import("../configuration-types.js").FrontendModelResourceServerConfiguration} */ (server)
     if (sync !== undefined) config.sync = /** @type {import("../configuration-types.js").FrontendModelResourceSyncConfiguration | boolean} */ (sync)
@@ -949,7 +974,8 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
   }
 
   /**
-   * Applies frontend-model index search.
+   * Applies frontend-model index searches, expanding a declared quick search
+   * before falling back to the controller default.
    * @param {object} args - Search args.
    * @param {FrontendModelResourceController} args.controller - Controller handling the query.
    * @param {FrontendModelResourceAnyQuery} args.query - Query instance.
@@ -957,9 +983,118 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
    * @returns {void}
    */
   applyFrontendModelIndexSearch({controller, query, search}) {
+    if (this.applyQuickSearch({controller, query, search})) return
+
     controller.applyFrontendModelSearch({query, search})
   }
 
+  /**
+   * Expands a `quickSearch` pseudo-column search into an OR of LIKE conditions
+   * over the declared {@link FrontendModelBaseResource.quickSearchColumns}, plus
+   * exact `=` conditions over {@link FrontendModelBaseResource.quickSearchNumericColumns}
+   * when the trimmed value is a safe non-negative integer.
+   * @param {object} args - Search args.
+   * @param {FrontendModelResourceController} args.controller - Controller handling the query.
+   * @param {FrontendModelResourceAnyQuery} args.query - Query to filter.
+   * @param {FrontendModelResourceSearch} args.search - Search payload.
+   * @returns {boolean} - Whether the search was handled as a quick search.
+   */
+  applyQuickSearch({controller, query, search}) {
+    const quickSearchColumns = this.quickSearchColumnDefinitions()
+
+    if (!quickSearchColumns || quickSearchColumns.length === 0) return false
+    if (search.path.length > 0 || search.column !== QUICK_SEARCH_COLUMN) return false
+
+    if (search.operator !== "like") {
+      throw VelociousError.safe(`${this.quickSearchErrorLabel()} must use the like operator.`, {code: this.quickSearchErrorCode()})
+    }
+
+    if (typeof search.value !== "string") {
+      throw VelociousError.safe(`${this.quickSearchErrorLabel()} must be a string.`, {code: this.quickSearchErrorCode()})
+    }
+
+    const trimmedValue = search.value.trim()
+
+    if (!trimmedValue) return true
+
+    const conditions = quickSearchColumns.map((column) => (
+      `${this.quickSearchColumnSql({column, controller, query})} LIKE ${query.driver.quote(`%${trimmedValue}%`)}`
+    ))
+    const numericSearchValue = quickSearchNumericValue(trimmedValue)
+
+    if (numericSearchValue !== null) {
+      const quickSearchNumericColumns = this.quickSearchNumericColumnDefinitions() || []
+
+      for (const column of quickSearchNumericColumns) {
+        conditions.push(`${this.quickSearchColumnSql({column, controller, query})} = ${query.driver.quote(numericSearchValue)}`)
+      }
+    }
+
+    query.where(`(${conditions.join(" OR ")})`)
+
+    return true
+  }
+
+  /**
+   * Resolves the declared quick-search text columns through the shared resource.
+   * @returns {Array<import("../configuration-types.js").FrontendModelQuickSearchColumn | string> | null | undefined} - Declared columns.
+   */
+  quickSearchColumnDefinitions() {
+    const ResourceClass = /** @type {typeof FrontendModelBaseResource} */ (this.constructor)
+
+    return /** @type {Array<import("../configuration-types.js").FrontendModelQuickSearchColumn | string> | null | undefined} */ (ResourceClass.sharedResourceStaticValue("quickSearchColumns"))
+  }
+
+  /**
+   * Resolves the declared quick-search numeric columns through the shared resource.
+   * @returns {Array<import("../configuration-types.js").FrontendModelQuickSearchColumn | string> | null | undefined} - Declared columns.
+   */
+  quickSearchNumericColumnDefinitions() {
+    const ResourceClass = /** @type {typeof FrontendModelBaseResource} */ (this.constructor)
+
+    return /** @type {Array<import("../configuration-types.js").FrontendModelQuickSearchColumn | string> | null | undefined} */ (ResourceClass.sharedResourceStaticValue("quickSearchNumericColumns"))
+  }
+
+  /**
+   * Builds the quoted SQL reference for one quick-search column, adding the
+   * relationship join when the column sits on a joined path.
+   * @param {object} args - Column args.
+   * @param {import("../configuration-types.js").FrontendModelQuickSearchColumn | string} args.column - Column declaration.
+   * @param {FrontendModelResourceController} args.controller - Controller handling the query.
+   * @param {FrontendModelResourceAnyQuery} args.query - Query being filtered.
+   * @returns {string} - Quoted SQL column reference.
+   */
+  quickSearchColumnSql({column, controller, query}) {
+    const columnConfig = typeof column === "string" ? {column} : column
+    const path = columnConfig.path || []
+
+    if (path.length > 0) {
+      controller.ensureFrontendModelJoinPath({path, query})
+    }
+
+    const tableReference = query.getTableReferenceForJoin(...path)
+
+    return `${query.driver.quoteTable(tableReference)}.${query.driver.quoteColumn(columnConfig.column)}`
+  }
+
+  /**
+   * Human-readable label used in invalid quick-search payload errors. Owners
+   * with an established public error contract may override this.
+   * @returns {string} - Error label.
+   */
+  quickSearchErrorLabel() {
+    return "Quick search"
+  }
+
+  /**
+   * Error code used for invalid quick-search payload errors. Owners with an
+   * established public error contract may override this.
+   * @returns {string} - Error code.
+   */
+  quickSearchErrorCode() {
+    return "invalid-quick-search"
+  }
+
   /**
    * Applies frontend-model index sort.
    * @param {object} args - Sort args.
@@ -2125,3 +2260,16 @@ function filterWritableFrontendModelAttributes(
 
   return writableAttributes
 }
+
+/**
+ * Parses a trimmed quick-search value as a safe non-negative integer.
+ * @param {string} searchValue - Trimmed quick-search value.
+ * @returns {number | null} - Numeric search value, or null when not numeric.
+ */
+function quickSearchNumericValue(searchValue) {
+  if (!/^[0-9]+$/u.test(searchValue)) return null
+
+  const numericValue = Number.parseInt(searchValue, 10)
+
+  return Number.isSafeInteger(numericValue) ? numericValue : null
+}

package/build/frontend-models/resource-definition.js

@@ -27,6 +27,7 @@ const RESOURCE_STATIC_CONFIG_KEYS = new Set([
   "ModelClass",
   "primaryKey",
   "quickSearchColumns",
+  "quickSearchNumericColumns",
   "relationships",
   "ReplayServiceClass",
   "server",
@@ -168,6 +169,8 @@ function normalizeFrontendModelResourceConfiguration(resourceConfiguration) {
     "memberCommands",
     "modelName",
     "primaryKey",
+    "quickSearchColumns",
+    "quickSearchNumericColumns",
     "relationships",
     "server",
     "sync"
@@ -180,6 +183,8 @@ function normalizeFrontendModelResourceConfiguration(resourceConfiguration) {
 
   const normalizedCommands = normalizeFrontendModelResourceCommands(resourceConfiguration)
   const sync = normalizeFrontendModelResourceSync(resourceConfiguration)
+  const quickSearchColumns = normalizeFrontendModelQuickSearchColumns(resourceConfiguration.quickSearchColumns, "quickSearchColumns")
+  const quickSearchNumericColumns = normalizeFrontendModelQuickSearchColumns(resourceConfiguration.quickSearchNumericColumns, "quickSearchNumericColumns")
 
   return {
     ...resourceConfiguration,
@@ -192,6 +197,8 @@ function normalizeFrontendModelResourceConfiguration(resourceConfiguration) {
     // generator uses it to type each custom command method.
     commandMetadata: normalizedCommands.commandMetadata,
     memberCommands: normalizedCommands.memberCommands,
+    quickSearchColumns,
+    quickSearchNumericColumns,
     sync
   }
 }
@@ -518,6 +525,46 @@ function normalizeSyncOperations(operations) {
   return [...new Set(normalized)].sort()
 }
 
+/**
+ * Normalizes declarative quick-search column entries into a stable list.
+ * Each entry is a plain column-name string or a `{path, column}` object whose
+ * path is a relationship path from the root model.
+ * @param {unknown} columns - Raw quick-search column declarations.
+ * @param {string} label - Config key label for error messages.
+ * @returns {Array<import("../configuration-types.js").FrontendModelQuickSearchColumn> | null} - Normalized columns, or null when undeclared.
+ */
+function normalizeFrontendModelQuickSearchColumns(columns, label) {
+  if (columns === undefined || columns === null) return null
+
+  if (!Array.isArray(columns)) throw new Error(`Resource ${label} must be an array of column names or {path, column} objects.`)
+
+  return columns.map((entry) => {
+    if (typeof entry === "string") {
+      if (entry.length < 1) throw new Error(`Resource ${label} entries must be non-empty column names.`)
+
+      return {column: entry}
+    }
+
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+      throw new Error(`Resource ${label} entries must be column names or {path, column} objects, got: ${JSON.stringify(entry)}`)
+    }
+
+    const entryRecord = /** @type {Record<string, unknown>} */ (entry)
+    const column = entryRecord.column
+    const path = entryRecord.path
+
+    if (typeof column !== "string" || column.length < 1) throw new Error(`Resource ${label} entries require a non-empty column name.`)
+
+    if (path === undefined || path === null) return {column}
+
+    if (!Array.isArray(path) || path.some((pathSegment) => typeof pathSegment !== "string" || pathSegment.length < 1)) {
+      throw new Error(`Resource ${label} entry paths must be arrays of non-empty relationship names.`)
+    }
+
+    return {column, path: [...path]}
+  })
+}
+
 /**
  * Builds a deterministic policy hash.
  * @param {unknown} value - Hash input.