velocious 1.0.692 → 1.0.694

package/build/mcp/manifest-tools.js

@@ -0,0 +1,310 @@
+// @ts-check
+
+/**
+ * @typedef {object} ManifestCommandEntry
+ * @property {Array<{name: string, type: string}>} [args] - Declared typed command arguments.
+ * @property {string} methodName - Command method name.
+ * @property {string} [path] - Manifest command path (member paths carry `<id>`).
+ * @property {string | null} [returnType] - Declared JSDoc return type.
+ * @property {"collection" | "member"} scope - Command scope.
+ */
+
+/**
+ * @typedef {object} ManifestResourceEntry
+ * @property {Record<string, ManifestCommandEntry[]>} [commands] - Scope-keyed custom command entries.
+ * @property {Record<string, Record<string, string>>} [builtInCommands] - Scope-keyed built-in command maps (methodName → slug).
+ * @property {string} modelName - Backend model name.
+ * @property {string | string[]} [primaryKey] - Primary key attribute name(s).
+ */
+
+/**
+ * @typedef {Record<string, unknown> & {formatVersion?: number, resources?: Record<string, unknown>}} ApiManifest
+ */
+
+import inflection from "inflection"
+
+const MCP_TOOL_NAME_PATTERN = /^[a-z0-9_]+$/
+
+/** @type {Record<string, string>} */
+const BUILT_IN_COMMAND_DESCRIPTIONS = {
+  attach: "Attach a file attachment to one record.",
+  attachmentList: "List the attachments of one record.",
+  create: "Create one record with `attributes` (and optional `nestedAttributes`).",
+  destroy: "Destroy one record by primary key `id`.",
+  download: "Download one attachment of one record.",
+  find: "Find one record by primary key `id`.",
+  index: "List records with optional `where`, `searches`, `sort`, `limit`, `offset`, `page`, `perPage`, `preload`, `select`, `count`, `pluck`, `distinct`, `group`, `joins`, and `queryData`.",
+  update: "Update one record by primary key `id` with `attributes` (and optional `nestedAttributes`).",
+  url: "Resolve the download URL of one attachment of one record."
+}
+
+const META_TOOL_NAME = "frontend_model_api_manifest"
+const META_TOOL_DESCRIPTION = "Return the full frontend-model API manifest (all resources, attributes, abilities, and commands) so callers can discover the available model commands."
+
+/**
+ * Maps one JSDoc type string from command metadata to a JSON Schema fragment.
+ * @param {string} type - JSDoc type string (for example `string`, `number`, `{id: number}`).
+ * @returns {{items?: {type: string}, type: string}} - JSON Schema type fragment.
+ */
+function jsonSchemaTypeForJSDocType(type) {
+  const normalizedType = type.trim()
+
+  if (normalizedType === "number" || normalizedType === "integer") return {type: "number"}
+  if (normalizedType === "boolean") return {type: "boolean"}
+  if (normalizedType.startsWith("Array<") || normalizedType.endsWith("[]")) return {items: {type: "string"}, type: "array"}
+
+  return {type: "string"}
+}
+
+/**
+ * Builds the MCP tool name for one model command.
+ * @param {object} args - Arguments.
+ * @param {string} args.modelKey - Manifest resource key (configured model name).
+ * @param {string} args.commandName - Command method name.
+ * @param {"collection" | "member"} args.scope - Command scope.
+ * @returns {string} - MCP tool name.
+ */
+function mcpToolName({commandName, modelKey, scope}) {
+  const modelPart = inflection.underscore(modelKey).toLowerCase()
+  const commandPart = inflection.underscore(commandName).toLowerCase()
+  const scopePart = scope === "member" ? "_by_id" : ""
+
+  return `${modelPart}_${commandPart}${scopePart}`
+}
+
+/**
+ * Builds the primary key input properties for one manifest resource.
+ * @param {string | string[] | undefined} primaryKey - Resource primary key attribute name(s).
+ * @returns {Record<string, {description: string, type: string}>} - Primary key JSON Schema properties.
+ */
+function primaryKeyProperties(primaryKey) {
+  const keyAttributes = Array.isArray(primaryKey) ? primaryKey : [primaryKey || "id"]
+  /** @type {Record<string, {description: string, type: string}>} */
+  const properties = {}
+
+  for (const keyAttribute of keyAttributes) {
+    properties[keyAttribute] = {description: `Primary key attribute \`${keyAttribute}\` of the record.`, type: "string"}
+  }
+
+  return properties
+}
+
+/**
+ * Builds the fixed input schema for one built-in command.
+ * @param {object} args - Arguments.
+ * @param {string} args.commandName - Built-in command name.
+ * @param {string | string[] | undefined} args.primaryKey - Resource primary key attribute name(s).
+ * @returns {Record<string, unknown>} - JSON Schema object for the tool input.
+ */
+function builtInCommandInputSchema({commandName, primaryKey}) {
+  if (commandName === "index") {
+    return {
+      additionalProperties: false,
+      properties: {
+        count: {description: "Return only the count of matching records.", type: "boolean"},
+        distinct: {description: "Apply DISTINCT to the index query.", type: "boolean"},
+        group: {description: "Group the index query by attribute names or relationship-path descriptors.", type: "object"},
+        joins: {description: "Relationship-path join descriptors.", type: "object"},
+        limit: {description: "Maximum number of records to return.", type: "number"},
+        offset: {description: "Number of records to skip.", type: "number"},
+        page: {description: "1-based page number (combine with `perPage`).", type: "number"},
+        perPage: {description: "Records per page.", type: "number"},
+        pluck: {description: "Attribute names or relationship-path descriptors to pluck instead of full records.", type: "array"},
+        preload: {description: "Relationship preload descriptors.", type: "object"},
+        queryData: {description: "Structured query-data descriptor.", type: "object"},
+        searches: {description: "Search descriptors (path/column/operator/value).", type: "array"},
+        select: {description: "Selected attribute names per model.", type: "object"},
+        selectsExtra: {description: "Extra selected attributes.", type: "object"},
+        sort: {description: "Sort definitions (column or relationship-path descriptors).", type: "array"},
+        where: {description: "Attribute filter hash.", type: "object"},
+        withCount: {description: "Include the total count alongside records.", type: "boolean"}
+      },
+      type: "object"
+    }
+  }
+
+  if (commandName === "create") {
+    return {
+      additionalProperties: false,
+      properties: {
+        attributes: {description: "Writable attribute values for the new record.", type: "object"},
+        nestedAttributes: {description: "Nested relationship attribute payloads.", type: "object"}
+      },
+      required: ["attributes"],
+      type: "object"
+    }
+  }
+
+  if (commandName === "update") {
+    const idProperties = primaryKeyProperties(primaryKey)
+
+    return {
+      additionalProperties: false,
+      properties: {
+        attributes: {description: "Writable attribute values to apply.", type: "object"},
+        ...idProperties,
+        nestedAttributes: {description: "Nested relationship attribute payloads.", type: "object"}
+      },
+      required: [...Object.keys(idProperties), "attributes"],
+      type: "object"
+    }
+  }
+
+  // find / destroy / attach / download / url / attachmentList are id-addressed
+  const idProperties = primaryKeyProperties(primaryKey)
+
+  return {
+    additionalProperties: false,
+    properties: {...idProperties},
+    required: [...Object.keys(idProperties)],
+    type: "object"
+  }
+}
+
+/**
+ * Builds the input schema for one custom command from its manifest argument metadata.
+ * @param {object} args - Arguments.
+ * @param {ManifestCommandEntry} args.entry - Manifest command entry.
+ * @param {string | string[] | undefined} args.primaryKey - Resource primary key attribute name(s).
+ * @returns {Record<string, unknown>} - JSON Schema object for the tool input.
+ */
+function customCommandInputSchema({entry, primaryKey}) {
+  const commandArgs = entry.args || []
+  /** @type {Record<string, {description?: string, items?: {items?: {type: string}, type: string}, type: string}>} */
+  const properties = {}
+
+  for (const commandArg of commandArgs) {
+    properties[commandArg.name] = jsonSchemaTypeForJSDocType(commandArg.type)
+  }
+
+  if (entry.scope === "member") {
+    for (const [keyAttribute, keySchema] of Object.entries(primaryKeyProperties(primaryKey))) {
+      if (!properties[keyAttribute]) properties[keyAttribute] = keySchema
+    }
+  }
+
+  return {
+    additionalProperties: true,
+    properties,
+    type: "object"
+  }
+}
+
+/**
+ * Generates MCP tool definitions from a frontend-model API manifest.
+ * Every built-in and custom command of every manifest resource becomes one tool;
+ * one meta tool exposes the raw manifest for discovery.
+ * @param {ApiManifest} manifest - Manifest from `configuration.getApiManifest()`.
+ * @returns {Record<string, unknown>[]} - MCP `tools/list` tool definitions.
+ */
+export function generateMcpTools(manifest) {
+  const resources = manifest.resources
+  const tools = []
+
+  if (!resources) return [buildMetaTool()]
+
+  for (const modelKey of Object.keys(resources).sort()) {
+    const resource = /** @type {ManifestResourceEntry} */ (resources[modelKey])
+    const commands = resource.commands || {}
+    const builtInCommands = resource.builtInCommands || {}
+
+    for (const scope of /** @type {Array<"collection" | "member">} */ (["collection", "member"])) {
+      for (const entry of scopeCommandEntries({builtInCommands, commands, scope})) {
+        const commandName = entry.methodName
+        const isBuiltIn = entry.isBuiltIn
+        const name = mcpToolName({commandName, modelKey, scope})
+
+        if (!MCP_TOOL_NAME_PATTERN.test(name)) continue
+
+        tools.push({
+          description: isBuiltIn
+            ? `${BUILT_IN_COMMAND_DESCRIPTIONS[commandName] || `Run the built-in \`${commandName}\` command on \`${resource.modelName}\`.`} Model: \`${resource.modelName}\`.`
+            : `Custom command \`${commandName}\` on model \`${resource.modelName}\`${entry.returnType ? ` (returns ${entry.returnType})` : ""}.`,
+          inputSchema: isBuiltIn
+            ? builtInCommandInputSchema({commandName, primaryKey: resource.primaryKey})
+            : customCommandInputSchema({entry, primaryKey: resource.primaryKey}),
+          name
+        })
+      }
+    }
+  }
+
+  tools.push(buildMetaTool())
+
+  return tools
+}
+
+/**
+ * Merges the manifest's built-in command names and custom command entries for
+ * one scope into a single deterministic command-entry list.
+ * @param {object} args - Arguments.
+ * @param {Record<string, Record<string, string>>} args.builtInCommands - Scope-keyed built-in command maps.
+ * @param {Record<string, ManifestCommandEntry[]>} args.commands - Scope-keyed custom command entries.
+ * @param {"collection" | "member"} args.scope - Command scope.
+ * @returns {Array<ManifestCommandEntry & {isBuiltIn: boolean}>} - Combined command entries.
+ */
+function scopeCommandEntries({builtInCommands, commands, scope}) {
+  /** @type {Array<ManifestCommandEntry & {isBuiltIn: boolean}>} */
+  const entries = []
+
+  for (const commandName of Object.keys(builtInCommands[scope] || {})) {
+    entries.push({isBuiltIn: true, methodName: commandName, scope})
+  }
+
+  for (const entry of commands[scope] || []) {
+    entries.push({...entry, isBuiltIn: false})
+  }
+
+  return entries.sort((a, b) => a.methodName.localeCompare(b.methodName))
+}
+
+/**
+ * Builds the manifest discovery meta tool.
+ * @returns {Record<string, unknown>} - MCP tool definition.
+ */
+function buildMetaTool() {
+  return {
+    description: META_TOOL_DESCRIPTION,
+    inputSchema: {additionalProperties: false, properties: {}, type: "object"},
+    name: META_TOOL_NAME
+  }
+}
+
+/**
+ * Parses one MCP tool name back into its manifest model key and command method name.
+ * @param {object} args - Arguments.
+ * @param {string} args.toolName - MCP tool name.
+ * @param {ApiManifest} args.manifest - Manifest from `configuration.getApiManifest()`.
+ * @returns {{commandName: string, modelKey: string, scope: "collection" | "member"} | null} - Command identity, or null when unknown.
+ */
+export function parseMcpToolName({manifest, toolName}) {
+  if (toolName === META_TOOL_NAME) return null
+
+  const resources = manifest.resources
+
+  if (!resources) return null
+
+  for (const modelKey of Object.keys(resources)) {
+    const resource = /** @type {ManifestResourceEntry} */ (resources[modelKey])
+    const commands = resource.commands || {}
+    const builtInCommands = resource.builtInCommands || {}
+
+    for (const scope of /** @type {Array<"collection" | "member">} */ (["collection", "member"])) {
+      const commandNames = [...Object.keys(builtInCommands[scope] || {}), ...(commands[scope] || []).map((entry) => entry.methodName)]
+
+      for (const commandName of commandNames) {
+        if (mcpToolName({commandName, modelKey, scope}) === toolName) {
+          return {commandName, modelKey, scope}
+        }
+      }
+    }
+  }
+
+  return null
+}
+
+/**
+ * Runs the metaToolName helper.
+ * @returns {string} - The meta tool name.
+ */
+export function metaToolName() { return META_TOOL_NAME }

package/build/routes/built-in/mcp/controller.js

@@ -0,0 +1,63 @@
+import Controller from "../../../controller.js"
+import {handleMcpRequest} from "../../../mcp/json-rpc-server.js"
+
+export default class BuiltInMcpController extends Controller {
+  /**
+   * Runs one JSON-RPC message of the MCP protocol over the HTTP transport.
+   * The request body is parsed into params by the HTTP request parser; the
+   * JSON-RPC envelope is extracted from it and answered exactly like the stdio
+   * transport. The request's `Authorization` header is forwarded as the
+   * request-context `authorization` key, so tool calls authenticate through the
+   * app's own tenant/ability resolvers just like regular frontend-model calls.
+   * @returns {Promise<void>} - Resolves when the JSON-RPC response has been rendered.
+   */
+  async handle() {
+    const params = this.params()
+    const requestContext = buildRequestContextFromHeaders({request: this.request()})
+    const response = await handleMcpRequest({
+      configuration: this.getConfiguration(),
+      request: {
+        id: params.id ?? null,
+        jsonrpc: params.jsonrpc,
+        method: params.method,
+        params: typeof params.params === "object" && params.params !== null && !Array.isArray(params.params) ? params.params : undefined
+      },
+      requestContext
+    })
+
+    this._response.setHeader("Content-Type", "application/json; charset=UTF-8")
+
+    if (response === null) {
+      // Notifications never carry a JSON-RPC response id; 202 Accepted with an
+      // empty body keeps the HTTP transport honest about that.
+      this._response.setStatus(202)
+      this._response.setBody("")
+
+      return
+    }
+
+    this._response.setBody(`${JSON.stringify(response)}\n`)
+  }
+}
+
+/**
+ * Builds the remote request context forwarded to every tool call from the
+ * incoming HTTP request headers. The `Authorization` header becomes the
+ * request-context `authorization` key, which the MCP dispatcher forwards as
+ * the Authorization header of the synthetic in-process frontend-model request.
+ * @param {object} args - Arguments.
+ * @param {import("../../../http-server/client/request.js").default} args.request - Incoming HTTP request.
+ * @returns {Record<string, string | number | boolean> | undefined} - Request context, or undefined when no headers carry context.
+ */
+function buildRequestContextFromHeaders({request}) {
+  /** @type {Record<string, string | number | boolean>} */
+  const context = {}
+
+  const authorization = request.header("authorization")
+
+  if (typeof authorization === "string" && authorization.trim().length > 0) {
+    context.authorization = authorization.trim()
+  }
+
+  return Object.keys(context).length > 0 ? context : undefined
+}

package/build/routes/catch-all-route.js

@@ -0,0 +1,58 @@
+// @ts-check
+
+import restArgsError from "../utils/rest-args-error.js"
+
+/**
+ * Catch-all route options.
+ * @typedef {object} CatchAllRouteOptions
+ * @property {string} [controller] - Controller name unmatched requests resolve to.
+ * @property {string} [action] - Action name unmatched requests resolve to.
+ */
+
+/**
+ * Application-declared catch-all route created with `route.catchAll(...)` in
+ * the routes file. It is not a path matcher: the resolver applies it only
+ * when no other route in the tree matched, replacing the built-in errors
+ * not-found response with the application's own controller/action (for
+ * example a JSON error envelope) without hand-wiring a route resolver hook.
+ */
+export default class VelociousRouteCatchAllRoute {
+  /**
+   * Controller name unmatched requests resolve to.
+   * @type {string} */
+  controller
+
+  /**
+   * Action name unmatched requests resolve to.
+   * @type {string} */
+  action
+
+  /**
+   * Runs constructor.
+   * @param {CatchAllRouteOptions} [options] - Catch-all options.
+   */
+  constructor({controller = "_root", action = "notFound", ...restArgs} = {}) {
+    restArgsError(restArgs)
+
+    if (typeof controller !== "string" || controller.length < 1) {
+      throw new Error(`Expected catch-all 'controller' to be a non-empty string, got: ${String(controller)}`)
+    }
+
+    if (typeof action !== "string" || action.length < 1) {
+      throw new Error(`Expected catch-all 'action' to be a non-empty string, got: ${String(action)}`)
+    }
+
+    this.controller = controller
+    this.action = action
+  }
+
+  /**
+   * Runs get human paths.
+   * @returns {Array<{action: string | null, method: string, path: string}>} - Route definitions for this route.
+   */
+  getHumanPaths() {
+    return [
+      {method: "ANY", action: this.action, path: "*"}
+    ]
+  }
+}

package/build/routes/resolver.js

@@ -126,7 +126,10 @@ export default class VelociousRoutesResolver {
       const __filename = fileURLToPath(import.meta.url)
       const __dirname = dirname(__filename)
       const requestedPath = currentPath.replace(/^\//, "") || "_root"
-      const attemptedControllerPath = `${this.configuration.getDirectory()}/src/routes/${requestedPath}/controller.js`
+      const catchAllRoute = currentRoute?.catchAllRoute
+      const attemptedControllerPath = catchAllRoute
+        ? `${this.configuration.getDirectory()}/src/routes/${catchAllRoute.controller}/controller.js`
+        : `${this.configuration.getDirectory()}/src/routes/${requestedPath}/controller.js`
 
       const logger = this.logger
 
@@ -136,13 +139,23 @@ export default class VelociousRoutesResolver {
 
       await logger.warn(`No route matched for ${loggedPath}. Tried controller at ${attemptedControllerPath}`)
 
-      controller = "errors"
-      controllerPath = "./built-in/errors/controller.js"
-      action = "notFound"
-      skipAbilityResolution = true
-      skipControllerConnections = true
-      skipTenantResolution = true
-      viewPath = await fs.realpath(`${__dirname}/built-in/errors`)
+      if (catchAllRoute) {
+        controller = catchAllRoute.controller
+        action = normalizeActionName(catchAllRoute.action)
+        controllerPath = `${this.configuration.getDirectory()}/src/routes/${controller}/controller.js`
+        viewPath = `${this.configuration.getDirectory()}/src/routes/${controller}`
+        skipAbilityResolution = true
+        skipControllerConnections = true
+        skipTenantResolution = true
+      } else {
+        controller = "errors"
+        controllerPath = "./built-in/errors/controller.js"
+        action = "notFound"
+        skipAbilityResolution = true
+        skipControllerConnections = true
+        skipTenantResolution = true
+        viewPath = await fs.realpath(`${__dirname}/built-in/errors`)
+      }
     } else if (action) {
       if (!controller) controller = "_root"
 

package/build/routes/root-route.js

@@ -1,11 +1,36 @@
 // @ts-check
 
 import BasicRoute from "./basic-route.js"
+import CatchAllRoute from "./catch-all-route.js"
 
 export default class VelociousRootRoute extends BasicRoute {
+  /**
+   * Application catch-all route declared with `route.catchAll(...)`, or null
+   * when the application did not declare one.
+   * @type {CatchAllRoute | null} */
+  catchAllRoute = null
+
+  /**
+   * Runs catch all. Declares the application's catch-all route: unmatched
+   * requests resolve to the given controller/action instead of the built-in
+   * errors not-found response.
+   * @param {import("./catch-all-route.js").CatchAllRouteOptions} [options] - Catch-all options.
+   * @returns {void} - No return value.
+   */
+  catchAll(options = {}) {
+    if (this.catchAllRoute) throw new Error("Only one catchAll route can be declared")
+
+    this.catchAllRoute = new CatchAllRoute(options)
+  }
+
   getHumanPaths() {
-    return [
+    /** @type {Array<{action: string | null, method: string, path: string}>} */
+    const humanPaths = [
       {method: "GET", action: "index", path: "/"}
     ]
+
+    if (this.catchAllRoute) humanPaths.push(...this.catchAllRoute.getHumanPaths())
+
+    return humanPaths
   }
 }

package/build/src/background-jobs/scheduled-enqueue-bound.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Default bound for one scheduled background-job enqueue attempt.
+ *
+ * A durable enqueue that never settles (wedged DB connection, advisory lock held by a dead process)
+ * used to poison its schedule key forever: `BackgroundJobsScheduler` kept the in-flight promise in
+ * `pendingEnqueuesByJobKey`, every later tick returned early, and shutdown could never drain. The
+ * bound makes that stall observable and self-healing instead of silent.
+ *
+ * It is deliberately larger than the advisory-lock acquisition bound, because a scheduled enqueue
+ * waits for a lock *and then* inserts. Keeping the enqueue watchdog outside the lock bound lets the
+ * precise `AdvisoryLockTimeoutError` surface first — naming the lock that is actually stuck —
+ * instead of a generic enqueue timeout that hides which lock caused the stall.
+ * @type {number} */
+export declare const DEFAULT_SCHEDULED_ENQUEUE_TIMEOUT_MS: number;
+//# sourceMappingURL=scheduled-enqueue-bound.d.ts.map

package/build/src/background-jobs/scheduled-enqueue-bound.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduled-enqueue-bound.d.ts","sourceRoot":"","sources":["../../../src/background-jobs/scheduled-enqueue-bound.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;oBAYoB;AACpB,eAAO,MAAM,oCAAoC,EADvC,MACkG,CAAA"}

package/build/src/background-jobs/scheduled-enqueue-bound.js

@@ -0,0 +1,17 @@
+// @ts-check
+import { DEFAULT_ADVISORY_LOCK_ACQUIRE_TIMEOUT_MS } from "../database/advisory-lock-bound.js";
+/**
+ * Default bound for one scheduled background-job enqueue attempt.
+ *
+ * A durable enqueue that never settles (wedged DB connection, advisory lock held by a dead process)
+ * used to poison its schedule key forever: `BackgroundJobsScheduler` kept the in-flight promise in
+ * `pendingEnqueuesByJobKey`, every later tick returned early, and shutdown could never drain. The
+ * bound makes that stall observable and self-healing instead of silent.
+ *
+ * It is deliberately larger than the advisory-lock acquisition bound, because a scheduled enqueue
+ * waits for a lock *and then* inserts. Keeping the enqueue watchdog outside the lock bound lets the
+ * precise `AdvisoryLockTimeoutError` surface first — naming the lock that is actually stuck —
+ * instead of a generic enqueue timeout that hides which lock caused the stall.
+ * @type {number} */
+export const DEFAULT_SCHEDULED_ENQUEUE_TIMEOUT_MS = DEFAULT_ADVISORY_LOCK_ACQUIRE_TIMEOUT_MS + 5 * 60 * 1000;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic2NoZWR1bGVkLWVucXVldWUtYm91bmQuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi9zcmMvYmFja2dyb3VuZC1qb2JzL3NjaGVkdWxlZC1lbnF1ZXVlLWJvdW5kLmpzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLFlBQVk7QUFFWixPQUFPLEVBQUMsd0NBQXdDLEVBQUMsTUFBTSxvQ0FBb0MsQ0FBQTtBQUUzRjs7Ozs7Ozs7Ozs7O29CQVlvQjtBQUNwQixNQUFNLENBQUMsTUFBTSxvQ0FBb0MsR0FBRyx3Q0FBd0MsR0FBRyxDQUFDLEdBQUcsRUFBRSxHQUFHLElBQUksQ0FBQSIsInNvdXJjZXNDb250ZW50IjpbIi8vIEB0cy1jaGVja1xuXG5pbXBvcnQge0RFRkFVTFRfQURWSVNPUllfTE9DS19BQ1FVSVJFX1RJTUVPVVRfTVN9IGZyb20gXCIuLi9kYXRhYmFzZS9hZHZpc29yeS1sb2NrLWJvdW5kLmpzXCJcblxuLyoqXG4gKiBEZWZhdWx0IGJvdW5kIGZvciBvbmUgc2NoZWR1bGVkIGJhY2tncm91bmQtam9iIGVucXVldWUgYXR0ZW1wdC5cbiAqXG4gKiBBIGR1cmFibGUgZW5xdWV1ZSB0aGF0IG5ldmVyIHNldHRsZXMgKHdlZGdlZCBEQiBjb25uZWN0aW9uLCBhZHZpc29yeSBsb2NrIGhlbGQgYnkgYSBkZWFkIHByb2Nlc3MpXG4gKiB1c2VkIHRvIHBvaXNvbiBpdHMgc2NoZWR1bGUga2V5IGZvcmV2ZXI6IGBCYWNrZ3JvdW5kSm9ic1NjaGVkdWxlcmAga2VwdCB0aGUgaW4tZmxpZ2h0IHByb21pc2UgaW5cbiAqIGBwZW5kaW5nRW5xdWV1ZXNCeUpvYktleWAsIGV2ZXJ5IGxhdGVyIHRpY2sgcmV0dXJuZWQgZWFybHksIGFuZCBzaHV0ZG93biBjb3VsZCBuZXZlciBkcmFpbi4gVGhlXG4gKiBib3VuZCBtYWtlcyB0aGF0IHN0YWxsIG9ic2VydmFibGUgYW5kIHNlbGYtaGVhbGluZyBpbnN0ZWFkIG9mIHNpbGVudC5cbiAqXG4gKiBJdCBpcyBkZWxpYmVyYXRlbHkgbGFyZ2VyIHRoYW4gdGhlIGFkdmlzb3J5LWxvY2sgYWNxdWlzaXRpb24gYm91bmQsIGJlY2F1c2UgYSBzY2hlZHVsZWQgZW5xdWV1ZVxuICogd2FpdHMgZm9yIGEgbG9jayAqYW5kIHRoZW4qIGluc2VydHMuIEtlZXBpbmcgdGhlIGVucXVldWUgd2F0Y2hkb2cgb3V0c2lkZSB0aGUgbG9jayBib3VuZCBsZXRzIHRoZVxuICogcHJlY2lzZSBgQWR2aXNvcnlMb2NrVGltZW91dEVycm9yYCBzdXJmYWNlIGZpcnN0IOKAlCBuYW1pbmcgdGhlIGxvY2sgdGhhdCBpcyBhY3R1YWxseSBzdHVjayDigJRcbiAqIGluc3RlYWQgb2YgYSBnZW5lcmljIGVucXVldWUgdGltZW91dCB0aGF0IGhpZGVzIHdoaWNoIGxvY2sgY2F1c2VkIHRoZSBzdGFsbC5cbiAqIEB0eXBlIHtudW1iZXJ9ICovXG5leHBvcnQgY29uc3QgREVGQVVMVF9TQ0hFRFVMRURfRU5RVUVVRV9USU1FT1VUX01TID0gREVGQVVMVF9BRFZJU09SWV9MT0NLX0FDUVVJUkVfVElNRU9VVF9NUyArIDUgKiA2MCAqIDEwMDBcbiJdfQ==

package/build/src/background-jobs/scheduled-enqueue-timeout-error.d.ts

@@ -0,0 +1,24 @@
+import { TimeoutError } from "awaitery/build/timeout.js";
+/** Typed failure for a scheduled background-job enqueue that never settled within its bound. */
+export default class ScheduledBackgroundJobEnqueueTimeoutError extends TimeoutError {
+    /** @type {"BACKGROUND_JOB_SCHEDULED_ENQUEUE_TIMEOUT"} */
+    code: "BACKGROUND_JOB_SCHEDULED_ENQUEUE_TIMEOUT";
+    jobKey: string;
+    jobName: string;
+    scheduledEnqueueTimeoutMs: number;
+    /**
+     * Builds a scheduled-enqueue timeout error without job arguments or connection details.
+     * @param {object} args - Safe timeout context.
+     * @param {string} args.jobKey - Schedule key whose enqueue stalled.
+     * @param {string} args.jobName - Resolved job class name.
+     * @param {number} args.scheduledEnqueueTimeoutMs - Configured bound that expired.
+     * @param {TimeoutError} [args.cause] - Original watchdog timeout.
+     */
+    constructor({ jobKey, jobName, scheduledEnqueueTimeoutMs, cause }: {
+        jobKey: string;
+        jobName: string;
+        scheduledEnqueueTimeoutMs: number;
+        cause?: TimeoutError;
+    });
+}
+//# sourceMappingURL=scheduled-enqueue-timeout-error.d.ts.map

package/build/src/background-jobs/scheduled-enqueue-timeout-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduled-enqueue-timeout-error.d.ts","sourceRoot":"","sources":["../../../src/background-jobs/scheduled-enqueue-timeout-error.js"],"names":[],"mappings":"AAEA,OAAO,EAAC,YAAY,EAAC,MAAM,2BAA2B,CAAA;AAEtD,gGAAgG;AAChG,MAAM,CAAC,OAAO,OAAO,yCAA0C,SAAQ,YAAY;IAa/E,yDAAyD;IACpD,IAAI,EADE,0CAA0C;IAEhD,MAAM;IACN,OAAO;IACP,yBAAyB;IAhBhC;;;;;;;OAOG;IACH,YAAY,EAAC,MAAM,EAAE,OAAO,EAAE,yBAAyB,EAAE,KAAK,EAAC,EAL5D;QAAqB,MAAM,EAAnB,MAAM,CACd;QAAqB,OAAO,EAApB,MAAM,CACd;QAAqB,yBAAyB,EAAtC,MAAM,CACd;QAA4B,KAAK,AAAjC,CACF,EADU,YAAY,CACtB;KAC8D,EAS9D;CACF"}

package/build/src/background-jobs/scheduled-enqueue-timeout-error.js

@@ -0,0 +1,23 @@
+// @ts-check
+import { TimeoutError } from "awaitery/build/timeout.js";
+/** Typed failure for a scheduled background-job enqueue that never settled within its bound. */
+export default class ScheduledBackgroundJobEnqueueTimeoutError extends TimeoutError {
+    /**
+     * Builds a scheduled-enqueue timeout error without job arguments or connection details.
+     * @param {object} args - Safe timeout context.
+     * @param {string} args.jobKey - Schedule key whose enqueue stalled.
+     * @param {string} args.jobName - Resolved job class name.
+     * @param {number} args.scheduledEnqueueTimeoutMs - Configured bound that expired.
+     * @param {TimeoutError} [args.cause] - Original watchdog timeout.
+     */
+    constructor({ jobKey, jobName, scheduledEnqueueTimeoutMs, cause }) {
+        super(`Scheduled background job enqueue did not settle within ${scheduledEnqueueTimeoutMs}ms`, cause ? { cause } : undefined);
+        this.name = "ScheduledBackgroundJobEnqueueTimeoutError";
+        /** @type {"BACKGROUND_JOB_SCHEDULED_ENQUEUE_TIMEOUT"} */
+        this.code = "BACKGROUND_JOB_SCHEDULED_ENQUEUE_TIMEOUT";
+        this.jobKey = jobKey;
+        this.jobName = jobName;
+        this.scheduledEnqueueTimeoutMs = scheduledEnqueueTimeoutMs;
+    }
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic2NoZWR1bGVkLWVucXVldWUtdGltZW91dC1lcnJvci5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uLy4uL3NyYy9iYWNrZ3JvdW5kLWpvYnMvc2NoZWR1bGVkLWVucXVldWUtdGltZW91dC1lcnJvci5qcyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxZQUFZO0FBRVosT0FBTyxFQUFDLFlBQVksRUFBQyxNQUFNLDJCQUEyQixDQUFBO0FBRXRELGdHQUFnRztBQUNoRyxNQUFNLENBQUMsT0FBTyxPQUFPLHlDQUEwQyxTQUFRLFlBQVk7SUFDakY7Ozs7Ozs7T0FPRztJQUNILFlBQVksRUFBQyxNQUFNLEVBQUUsT0FBTyxFQUFFLHlCQUF5QixFQUFFLEtBQUssRUFBQztRQUM3RCxLQUFLLENBQUMsMERBQTBELHlCQUF5QixJQUFJLEVBQUUsS0FBSyxDQUFDLENBQUMsQ0FBQyxFQUFDLEtBQUssRUFBQyxDQUFDLENBQUMsQ0FBQyxTQUFTLENBQUMsQ0FBQTtRQUUzSCxJQUFJLENBQUMsSUFBSSxHQUFHLDJDQUEyQyxDQUFBO1FBQ3ZELHlEQUF5RDtRQUN6RCxJQUFJLENBQUMsSUFBSSxHQUFHLDBDQUEwQyxDQUFBO1FBQ3RELElBQUksQ0FBQyxNQUFNLEdBQUcsTUFBTSxDQUFBO1FBQ3BCLElBQUksQ0FBQyxPQUFPLEdBQUcsT0FBTyxDQUFBO1FBQ3RCLElBQUksQ0FBQyx5QkFBeUIsR0FBRyx5QkFBeUIsQ0FBQTtJQUM1RCxDQUFDO0NBQ0YiLCJzb3VyY2VzQ29udGVudCI6WyIvLyBAdHMtY2hlY2tcblxuaW1wb3J0IHtUaW1lb3V0RXJyb3J9IGZyb20gXCJhd2FpdGVyeS9idWlsZC90aW1lb3V0LmpzXCJcblxuLyoqIFR5cGVkIGZhaWx1cmUgZm9yIGEgc2NoZWR1bGVkIGJhY2tncm91bmQtam9iIGVucXVldWUgdGhhdCBuZXZlciBzZXR0bGVkIHdpdGhpbiBpdHMgYm91bmQuICovXG5leHBvcnQgZGVmYXVsdCBjbGFzcyBTY2hlZHVsZWRCYWNrZ3JvdW5kSm9iRW5xdWV1ZVRpbWVvdXRFcnJvciBleHRlbmRzIFRpbWVvdXRFcnJvciB7XG4gIC8qKlxuICAgKiBCdWlsZHMgYSBzY2hlZHVsZWQtZW5xdWV1ZSB0aW1lb3V0IGVycm9yIHdpdGhvdXQgam9iIGFyZ3VtZW50cyBvciBjb25uZWN0aW9uIGRldGFpbHMuXG4gICAqIEBwYXJhbSB7b2JqZWN0fSBhcmdzIC0gU2FmZSB0aW1lb3V0IGNvbnRleHQuXG4gICAqIEBwYXJhbSB7c3RyaW5nfSBhcmdzLmpvYktleSAtIFNjaGVkdWxlIGtleSB3aG9zZSBlbnF1ZXVlIHN0YWxsZWQuXG4gICAqIEBwYXJhbSB7c3RyaW5nfSBhcmdzLmpvYk5hbWUgLSBSZXNvbHZlZCBqb2IgY2xhc3MgbmFtZS5cbiAgICogQHBhcmFtIHtudW1iZXJ9IGFyZ3Muc2NoZWR1bGVkRW5xdWV1ZVRpbWVvdXRNcyAtIENvbmZpZ3VyZWQgYm91bmQgdGhhdCBleHBpcmVkLlxuICAgKiBAcGFyYW0ge1RpbWVvdXRFcnJvcn0gW2FyZ3MuY2F1c2VdIC0gT3JpZ2luYWwgd2F0Y2hkb2cgdGltZW91dC5cbiAgICovXG4gIGNvbnN0cnVjdG9yKHtqb2JLZXksIGpvYk5hbWUsIHNjaGVkdWxlZEVucXVldWVUaW1lb3V0TXMsIGNhdXNlfSkge1xuICAgIHN1cGVyKGBTY2hlZHVsZWQgYmFja2dyb3VuZCBqb2IgZW5xdWV1ZSBkaWQgbm90IHNldHRsZSB3aXRoaW4gJHtzY2hlZHVsZWRFbnF1ZXVlVGltZW91dE1zfW1zYCwgY2F1c2UgPyB7Y2F1c2V9IDogdW5kZWZpbmVkKVxuXG4gICAgdGhpcy5uYW1lID0gXCJTY2hlZHVsZWRCYWNrZ3JvdW5kSm9iRW5xdWV1ZVRpbWVvdXRFcnJvclwiXG4gICAgLyoqIEB0eXBlIHtcIkJBQ0tHUk9VTkRfSk9CX1NDSEVEVUxFRF9FTlFVRVVFX1RJTUVPVVRcIn0gKi9cbiAgICB0aGlzLmNvZGUgPSBcIkJBQ0tHUk9VTkRfSk9CX1NDSEVEVUxFRF9FTlFVRVVFX1RJTUVPVVRcIlxuICAgIHRoaXMuam9iS2V5ID0gam9iS2V5XG4gICAgdGhpcy5qb2JOYW1lID0gam9iTmFtZVxuICAgIHRoaXMuc2NoZWR1bGVkRW5xdWV1ZVRpbWVvdXRNcyA9IHNjaGVkdWxlZEVucXVldWVUaW1lb3V0TXNcbiAgfVxufVxuIl19

package/build/src/background-jobs/scheduler.d.ts

@@ -38,6 +38,8 @@ export default class BackgroundJobsScheduler {
         options: import("./types.js").BackgroundJobOptions;
     }) => Promise<void>;
     logger: Logger;
+    /** @type {number | null} - Bound (ms) for one scheduled enqueue attempt; `null` disables the bound. */
+    scheduledEnqueueTimeoutMs: number | null;
     /**
      * Narrows the runtime value to the documented type.
      * @type {Array<ReturnType<typeof setInterval>>} */
@@ -135,6 +137,44 @@ export default class BackgroundJobsScheduler {
         jobConfiguration: import("../configuration-types.js").ScheduledBackgroundJobConfiguration;
         jobKey: string;
     }): Promise<void>;
+    /**
+     * Runs one durable enqueue attempt under the scheduled-enqueue bound.
+     *
+     * The bound is applied with a local race rather than `awaitery`'s `timeout()`:
+     * that helper starts its callback through `Promise.resolve().then(...)`, which
+     * would defer every scheduled enqueue by a microtask and change the tick
+     * semantics callers rely on. Here the attempt starts synchronously, and the
+     * watchdog uses the module-captured timers so it is never observable as a
+     * schedule timer. Only the watchdog raises the typed timeout error, so a
+     * timeout raised inside the enqueue itself keeps its own error path.
+     * @param {object} args - Options.
+     * @param {string} args.jobKey - Schedule key.
+     * @param {string} args.jobName - Resolved job class name.
+     * @param {() => Promise<void>} args.run - Enqueue attempt.
+     * @returns {Promise<void>} - Resolves when the attempt settles within the bound.
+     */
+    _withScheduledEnqueueTimeout({ jobKey, jobName, run }: {
+        jobKey: string;
+        jobName: string;
+        run: () => Promise<void>;
+    }): Promise<void>;
+    /**
+     * Surfaces a scheduled enqueue whose store call never settled. Without this report the only
+     * symptom is a schedule that silently stops enqueueing after one wedged call.
+     * @param {object} args - Options.
+     * @param {Error} args.error - Timeout error.
+     * @param {string} args.jobKey - Schedule key.
+     * @returns {void}
+     */
+    _reportScheduledEnqueueStall({ error, jobKey }: {
+        error: Error;
+        jobKey: string;
+    }): void;
+    /**
+     * Resolves the scheduled-enqueue bound from configuration.
+     * @returns {number | null} - Bound in milliseconds, or `null` for an unbounded wait.
+     */
+    _resolveScheduledEnqueueTimeoutMs(): number | null;
     /**
      * Runs normalize every.
      * @param {NonNullable<import("../configuration-types.js").ScheduledBackgroundJobConfiguration["every"]>} every - Every config (caller must guarantee not undefined).