velocious 1.0.606 → 1.0.607

package/build/src/background-jobs/local-job-registry.d.ts

@@ -0,0 +1,26 @@
+import VelociousJob from "./platform-job.js";
+/** Static, bundler-safe local background-job registry. */
+export default class LocalBackgroundJobRegistry {
+    jobClasses: (typeof VelociousJob)[];
+    /** @type {Map<string, typeof VelociousJob> | undefined} */
+    jobsByName: Map<string, typeof VelociousJob> | undefined;
+    /**
+     * Creates a registry from the configuration's statically imported job classes.
+     * @param {{jobClasses: Array<typeof VelociousJob>}} args - Registry options.
+     */
+    constructor({ jobClasses }: {
+        jobClasses: Array<typeof VelociousJob>;
+    });
+    /**
+     * Validates and indexes the configured job classes.
+     * @returns {void} - No return value.
+     */
+    ensureReady(): void;
+    /**
+     * Resolves a registered class.
+     * @param {string} jobName - Persisted job name.
+     * @returns {typeof VelociousJob} - Registered class.
+     */
+    resolve(jobName: string): typeof VelociousJob;
+}
+//# sourceMappingURL=local-job-registry.d.ts.map

package/build/src/background-jobs/local-job-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-job-registry.d.ts","sourceRoot":"","sources":["../../../src/background-jobs/local-job-registry.js"],"names":[],"mappings":"AAEA,OAAO,YAAY,MAAM,mBAAmB,CAAA;AAE5C,0DAA0D;AAC1D,MAAM,CAAC,OAAO,OAAO,0BAA0B;IAMtC,UAAU;IACf,2DAA2D;IACtD,UAAU,EADJ,GAAG,CAAC,MAAM,EAAE,OAAO,YAAY,CAAC,GAAG,SAAS;IANzD;;;OAGG;IACH,YAAY,EAAC,UAAU,EAAC,EAFb;QAAC,UAAU,EAAE,KAAK,CAAC,OAAO,YAAY,CAAC,CAAA;KAE1B,EAIvB;IAED;;;OAGG;IACH,WAAW,IAFE,IAAI,CAwBhB;IAED;;;;OAIG;IACH,OAAO,CAAC,OAAO,EAHJ,MAGI,GAFF,OAAO,YAAY,CAU/B;CACF"}

package/build/src/background-jobs/local-job-registry.js

@@ -0,0 +1,51 @@
+// @ts-check
+import VelociousJob from "./platform-job.js";
+/** Static, bundler-safe local background-job registry. */
+export default class LocalBackgroundJobRegistry {
+    /**
+     * Creates a registry from the configuration's statically imported job classes.
+     * @param {{jobClasses: Array<typeof VelociousJob>}} args - Registry options.
+     */
+    constructor({ jobClasses }) {
+        this.jobClasses = jobClasses;
+        /** @type {Map<string, typeof VelociousJob> | undefined} */
+        this.jobsByName = undefined;
+    }
+    /**
+     * Validates and indexes the configured job classes.
+     * @returns {void} - No return value.
+     */
+    ensureReady() {
+        if (this.jobsByName)
+            return;
+        if (!Array.isArray(this.jobClasses))
+            throw new TypeError("backgroundJobs.jobClasses must be an array");
+        const jobsByName = new Map();
+        for (const JobClass of this.jobClasses) {
+            if (typeof JobClass !== "function" || JobClass === VelociousJob || !(JobClass.prototype instanceof VelociousJob)) {
+                throw new TypeError("backgroundJobs.jobClasses must contain VelociousJob subclasses");
+            }
+            const jobName = JobClass.jobName();
+            if (typeof jobName !== "string" || jobName.trim().length === 0) {
+                throw new TypeError("backgroundJobs.jobClasses must declare non-empty job names");
+            }
+            if (jobsByName.has(jobName))
+                throw new Error(`Duplicate local background job name: ${jobName}`);
+            jobsByName.set(jobName, JobClass);
+        }
+        this.jobsByName = jobsByName;
+    }
+    /**
+     * Resolves a registered class.
+     * @param {string} jobName - Persisted job name.
+     * @returns {typeof VelociousJob} - Registered class.
+     */
+    resolve(jobName) {
+        this.ensureReady();
+        const JobClass = this.jobsByName?.get(jobName);
+        if (!JobClass)
+            throw new Error(`Local background job is not registered in backgroundJobs.jobClasses: ${jobName}`);
+        return JobClass;
+    }
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibG9jYWwtam9iLXJlZ2lzdHJ5LmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vc3JjL2JhY2tncm91bmQtam9icy9sb2NhbC1qb2ItcmVnaXN0cnkuanMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsWUFBWTtBQUVaLE9BQU8sWUFBWSxNQUFNLG1CQUFtQixDQUFBO0FBRTVDLDBEQUEwRDtBQUMxRCxNQUFNLENBQUMsT0FBTyxPQUFPLDBCQUEwQjtJQUM3Qzs7O09BR0c7SUFDSCxZQUFZLEVBQUMsVUFBVSxFQUFDO1FBQ3RCLElBQUksQ0FBQyxVQUFVLEdBQUcsVUFBVSxDQUFBO1FBQzVCLDJEQUEyRDtRQUMzRCxJQUFJLENBQUMsVUFBVSxHQUFHLFNBQVMsQ0FBQTtJQUM3QixDQUFDO0lBRUQ7OztPQUdHO0lBQ0gsV0FBVztRQUNULElBQUksSUFBSSxDQUFDLFVBQVU7WUFBRSxPQUFNO1FBQzNCLElBQUksQ0FBQyxLQUFLLENBQUMsT0FBTyxDQUFDLElBQUksQ0FBQyxVQUFVLENBQUM7WUFBRSxNQUFNLElBQUksU0FBUyxDQUFDLDRDQUE0QyxDQUFDLENBQUE7UUFFdEcsTUFBTSxVQUFVLEdBQUcsSUFBSSxHQUFHLEVBQUUsQ0FBQTtRQUU1QixLQUFLLE1BQU0sUUFBUSxJQUFJLElBQUksQ0FBQyxVQUFVLEVBQUUsQ0FBQztZQUN2QyxJQUFJLE9BQU8sUUFBUSxLQUFLLFVBQVUsSUFBSSxRQUFRLEtBQUssWUFBWSxJQUFJLENBQUMsQ0FBQyxRQUFRLENBQUMsU0FBUyxZQUFZLFlBQVksQ0FBQyxFQUFFLENBQUM7Z0JBQ2pILE1BQU0sSUFBSSxTQUFTLENBQUMsZ0VBQWdFLENBQUMsQ0FBQTtZQUN2RixDQUFDO1lBRUQsTUFBTSxPQUFPLEdBQUcsUUFBUSxDQUFDLE9BQU8sRUFBRSxDQUFBO1lBRWxDLElBQUksT0FBTyxPQUFPLEtBQUssUUFBUSxJQUFJLE9BQU8sQ0FBQyxJQUFJLEVBQUUsQ0FBQyxNQUFNLEtBQUssQ0FBQyxFQUFFLENBQUM7Z0JBQy9ELE1BQU0sSUFBSSxTQUFTLENBQUMsNERBQTRELENBQUMsQ0FBQTtZQUNuRixDQUFDO1lBQ0QsSUFBSSxVQUFVLENBQUMsR0FBRyxDQUFDLE9BQU8sQ0FBQztnQkFBRSxNQUFNLElBQUksS0FBSyxDQUFDLHdDQUF3QyxPQUFPLEVBQUUsQ0FBQyxDQUFBO1lBRS9GLFVBQVUsQ0FBQyxHQUFHLENBQUMsT0FBTyxFQUFFLFFBQVEsQ0FBQyxDQUFBO1FBQ25DLENBQUM7UUFFRCxJQUFJLENBQUMsVUFBVSxHQUFHLFVBQVUsQ0FBQTtJQUM5QixDQUFDO0lBRUQ7Ozs7T0FJRztJQUNILE9BQU8sQ0FBQyxPQUFPO1FBQ2IsSUFBSSxDQUFDLFdBQVcsRUFBRSxDQUFBO1FBRWxCLE1BQU0sUUFBUSxHQUFHLElBQUksQ0FBQyxVQUFVLEVBQUUsR0FBRyxDQUFDLE9BQU8sQ0FBQyxDQUFBO1FBRTlDLElBQUksQ0FBQyxRQUFRO1lBQUUsTUFBTSxJQUFJLEtBQUssQ0FBQyx3RUFBd0UsT0FBTyxFQUFFLENBQUMsQ0FBQTtRQUVqSCxPQUFPLFFBQVEsQ0FBQTtJQUNqQixDQUFDO0NBQ0YiLCJzb3VyY2VzQ29udGVudCI6WyIvLyBAdHMtY2hlY2tcblxuaW1wb3J0IFZlbG9jaW91c0pvYiBmcm9tIFwiLi9wbGF0Zm9ybS1qb2IuanNcIlxuXG4vKiogU3RhdGljLCBidW5kbGVyLXNhZmUgbG9jYWwgYmFja2dyb3VuZC1qb2IgcmVnaXN0cnkuICovXG5leHBvcnQgZGVmYXVsdCBjbGFzcyBMb2NhbEJhY2tncm91bmRKb2JSZWdpc3RyeSB7XG4gIC8qKlxuICAgKiBDcmVhdGVzIGEgcmVnaXN0cnkgZnJvbSB0aGUgY29uZmlndXJhdGlvbidzIHN0YXRpY2FsbHkgaW1wb3J0ZWQgam9iIGNsYXNzZXMuXG4gICAqIEBwYXJhbSB7e2pvYkNsYXNzZXM6IEFycmF5PHR5cGVvZiBWZWxvY2lvdXNKb2I+fX0gYXJncyAtIFJlZ2lzdHJ5IG9wdGlvbnMuXG4gICAqL1xuICBjb25zdHJ1Y3Rvcih7am9iQ2xhc3Nlc30pIHtcbiAgICB0aGlzLmpvYkNsYXNzZXMgPSBqb2JDbGFzc2VzXG4gICAgLyoqIEB0eXBlIHtNYXA8c3RyaW5nLCB0eXBlb2YgVmVsb2Npb3VzSm9iPiB8IHVuZGVmaW5lZH0gKi9cbiAgICB0aGlzLmpvYnNCeU5hbWUgPSB1bmRlZmluZWRcbiAgfVxuXG4gIC8qKlxuICAgKiBWYWxpZGF0ZXMgYW5kIGluZGV4ZXMgdGhlIGNvbmZpZ3VyZWQgam9iIGNsYXNzZXMuXG4gICAqIEByZXR1cm5zIHt2b2lkfSAtIE5vIHJldHVybiB2YWx1ZS5cbiAgICovXG4gIGVuc3VyZVJlYWR5KCkge1xuICAgIGlmICh0aGlzLmpvYnNCeU5hbWUpIHJldHVyblxuICAgIGlmICghQXJyYXkuaXNBcnJheSh0aGlzLmpvYkNsYXNzZXMpKSB0aHJvdyBuZXcgVHlwZUVycm9yKFwiYmFja2dyb3VuZEpvYnMuam9iQ2xhc3NlcyBtdXN0IGJlIGFuIGFycmF5XCIpXG5cbiAgICBjb25zdCBqb2JzQnlOYW1lID0gbmV3IE1hcCgpXG5cbiAgICBmb3IgKGNvbnN0IEpvYkNsYXNzIG9mIHRoaXMuam9iQ2xhc3Nlcykge1xuICAgICAgaWYgKHR5cGVvZiBKb2JDbGFzcyAhPT0gXCJmdW5jdGlvblwiIHx8IEpvYkNsYXNzID09PSBWZWxvY2lvdXNKb2IgfHwgIShKb2JDbGFzcy5wcm90b3R5cGUgaW5zdGFuY2VvZiBWZWxvY2lvdXNKb2IpKSB7XG4gICAgICAgIHRocm93IG5ldyBUeXBlRXJyb3IoXCJiYWNrZ3JvdW5kSm9icy5qb2JDbGFzc2VzIG11c3QgY29udGFpbiBWZWxvY2lvdXNKb2Igc3ViY2xhc3Nlc1wiKVxuICAgICAgfVxuXG4gICAgICBjb25zdCBqb2JOYW1lID0gSm9iQ2xhc3Muam9iTmFtZSgpXG5cbiAgICAgIGlmICh0eXBlb2Ygam9iTmFtZSAhPT0gXCJzdHJpbmdcIiB8fCBqb2JOYW1lLnRyaW0oKS5sZW5ndGggPT09IDApIHtcbiAgICAgICAgdGhyb3cgbmV3IFR5cGVFcnJvcihcImJhY2tncm91bmRKb2JzLmpvYkNsYXNzZXMgbXVzdCBkZWNsYXJlIG5vbi1lbXB0eSBqb2IgbmFtZXNcIilcbiAgICAgIH1cbiAgICAgIGlmIChqb2JzQnlOYW1lLmhhcyhqb2JOYW1lKSkgdGhyb3cgbmV3IEVycm9yKGBEdXBsaWNhdGUgbG9jYWwgYmFja2dyb3VuZCBqb2IgbmFtZTogJHtqb2JOYW1lfWApXG5cbiAgICAgIGpvYnNCeU5hbWUuc2V0KGpvYk5hbWUsIEpvYkNsYXNzKVxuICAgIH1cblxuICAgIHRoaXMuam9ic0J5TmFtZSA9IGpvYnNCeU5hbWVcbiAgfVxuXG4gIC8qKlxuICAgKiBSZXNvbHZlcyBhIHJlZ2lzdGVyZWQgY2xhc3MuXG4gICAqIEBwYXJhbSB7c3RyaW5nfSBqb2JOYW1lIC0gUGVyc2lzdGVkIGpvYiBuYW1lLlxuICAgKiBAcmV0dXJucyB7dHlwZW9mIFZlbG9jaW91c0pvYn0gLSBSZWdpc3RlcmVkIGNsYXNzLlxuICAgKi9cbiAgcmVzb2x2ZShqb2JOYW1lKSB7XG4gICAgdGhpcy5lbnN1cmVSZWFkeSgpXG5cbiAgICBjb25zdCBKb2JDbGFzcyA9IHRoaXMuam9ic0J5TmFtZT8uZ2V0KGpvYk5hbWUpXG5cbiAgICBpZiAoIUpvYkNsYXNzKSB0aHJvdyBuZXcgRXJyb3IoYExvY2FsIGJhY2tncm91bmQgam9iIGlzIG5vdCByZWdpc3RlcmVkIGluIGJhY2tncm91bmRKb2JzLmpvYkNsYXNzZXM6ICR7am9iTmFtZX1gKVxuXG4gICAgcmV0dXJuIEpvYkNsYXNzXG4gIH1cbn1cbiJdfQ==

package/build/src/background-jobs/local-store.d.ts

@@ -0,0 +1,364 @@
+import TableData from "../database/table-data/index.js";
+export declare const LOCAL_BACKGROUND_JOBS_TABLE = "velocious_local_background_jobs";
+export declare const LOCAL_BACKGROUND_JOB_CONCURRENCY_TABLE = "velocious_local_background_job_concurrency";
+export declare const LOCAL_BACKGROUND_JOBS_INDEX_NAMES: string[];
+/**
+ * Creates the production clock used by local dispatch.
+ * @returns {import("./types.js").LocalBackgroundJobsClock} - Production clock.
+ */
+export declare function localBackgroundJobsClock(): import("./types.js").LocalBackgroundJobsClock;
+/** Namespaced portable SQLite persistence for local background jobs. */
+export default class LocalBackgroundJobsStore {
+    clock: import("./types.js").LocalBackgroundJobsClock;
+    configuration: import("../configuration.js").default;
+    databaseIdentifier: string | undefined;
+    onCommittedEnqueue: (() => void) | undefined;
+    _isReady: boolean;
+    /** @type {Promise<void> | null} */
+    _readyPromise: Promise<void> | null;
+    /** @type {WeakMap<import("../database/drivers/base.js").default, {completion: Promise<void>, promise: Promise<void>}>} */
+    _transactionReadyPromises: WeakMap<import("../database/drivers/base.js").default, {
+        completion: Promise<void>;
+        promise: Promise<void>;
+    }>;
+    /**
+     * Creates a store for one configuration and local database.
+     * @param {object} args - Store options.
+     * @param {import("../configuration.js").default} args.configuration - Owning configuration.
+     * @param {import("./types.js").LocalBackgroundJobsClock} [args.clock] - Persistence clock.
+     * @param {string} [args.databaseIdentifier] - Configured local database identifier.
+     * @param {() => void} [args.onCommittedEnqueue] - Commit-aware dispatcher wake.
+     */
+    constructor({ configuration, clock, databaseIdentifier, onCommittedEnqueue }: {
+        configuration: import("../configuration.js").default;
+        clock?: import("./types.js").LocalBackgroundJobsClock;
+        databaseIdentifier?: string;
+        onCommittedEnqueue?: () => void;
+    });
+    /**
+     * Resolves the configured local database identifier.
+     * @returns {string} - Database identifier.
+     */
+    getDatabaseIdentifier(): string;
+    /**
+     * Ensures the versioned physical schema exists.
+     * @returns {Promise<void>} - Resolves when ready.
+     */
+    ensureReady(): Promise<void>;
+    /**
+     * Clears the per-instance readiness latch for a deliberate adapter reopen.
+     * @returns {void} - No return value.
+     */
+    resetReadiness(): void;
+    /**
+     * Coordinates physical and transaction-local schema readiness.
+     * @param {import("../database/drivers/base.js").default} db - Local SQLite connection.
+     * @returns {Promise<void>} - Resolves when this caller can use the schema.
+     */
+    _ensureReadyWithDb(db: import("../database/drivers/base.js").default): Promise<void>;
+    /**
+     * Creates or repairs version-one tables and indexes.
+     * @param {import("../database/drivers/base.js").default} db - Local SQLite connection.
+     * @returns {Promise<boolean>} - Whether schema state changed.
+     */
+    _applySchema(db: import("../database/drivers/base.js").default): Promise<boolean>;
+    /**
+     * Builds the migration ledger table definition.
+     * @returns {TableData} - Migration ledger table.
+     */
+    _migrationsTableData(): TableData;
+    /**
+     * Builds the local jobs table definition.
+     * @returns {TableData} - Local jobs table definition.
+     */
+    _jobsTableData(): TableData;
+    /**
+     * Builds the local concurrency counter table definition.
+     * @returns {TableData} - Concurrency counter table definition.
+     */
+    _concurrencyTableData(): TableData;
+    /**
+     * Rejects an incompatible current-version table rather than rebuilding data.
+     * @param {import("../database/drivers/base.js").default} db - Local SQLite connection.
+     * @param {string} tableName - Table name.
+     * @param {string[]} expectedColumns - Required columns.
+     * @returns {Promise<void>} - Resolves when compatible.
+     */
+    _assertColumns(db: import("../database/drivers/base.js").default, tableName: string, expectedColumns: string[]): Promise<void>;
+    /**
+     * Recreates missing indexes declared by the current schema.
+     * @param {import("../database/drivers/base.js").default} db - Local SQLite connection.
+     * @returns {Promise<boolean>} - Whether an index was created.
+     */
+    _ensureIndexes(db: import("../database/drivers/base.js").default): Promise<boolean>;
+    /**
+     * Checks whether the current local schema version is recorded.
+     * @param {import("../database/drivers/base.js").default} db - Connection.
+     * @returns {Promise<boolean>} - Whether version one is recorded.
+     */
+    _hasMigration(db: import("../database/drivers/base.js").default): Promise<boolean>;
+    /**
+     * Builds the scoped migration key.
+     * @returns {string} - Scoped migration key.
+     */
+    _migrationKey(): string;
+    /**
+     * Enqueues a local job in the caller's active transaction when present.
+     * @param {object} args - Enqueue request.
+     * @param {string} args.jobName - Registered job name.
+     * @param {Array<ReturnType<typeof JSON.parse>>} args.args - Serialized job arguments.
+     * @param {import("./types.js").BackgroundJobOptions} [args.options] - Job options.
+     * @returns {Promise<string>} - Durable job id.
+     */
+    enqueue({ jobName, args, options }: {
+        jobName: string;
+        args: Array<ReturnType<typeof JSON.parse>>;
+        options?: import("./types.js").BackgroundJobOptions;
+    }): Promise<string>;
+    /**
+     * Serializes matching in-process deduplication checks through commit while
+     * leaving unrelated job identities independent.
+     * @template T
+     * @param {import("./types.js").PreparedLocalBackgroundJob} preparedJob - Prepared job identity.
+     * @param {(holdUntil: (completion: Promise<void>) => void) => Promise<T>} callback - Deduplication mutation.
+     * @returns {Promise<T>} - Mutation result.
+     */
+    _serializeDeduplicatedEnqueue<T>(preparedJob: import("./types.js").PreparedLocalBackgroundJob, callback: (holdUntil: (completion: Promise<void>) => void) => Promise<T>): Promise<T>;
+    /**
+     * Prepares validated local job data for insertion.
+     * @param {{args: Array<ReturnType<typeof JSON.parse>>, jobName: string, options: import("./types.js").BackgroundJobOptions}} args - Job request.
+     * @returns {import("./types.js").PreparedLocalBackgroundJob} - Prepared row data.
+     */
+    _prepareJob({ args, jobName, options }: {
+        args: Array<ReturnType<typeof JSON.parse>>;
+        jobName: string;
+        options: import("./types.js").BackgroundJobOptions;
+    }): import("./types.js").PreparedLocalBackgroundJob;
+    /**
+     * Inserts one prepared local job row and its concurrency metadata.
+     * @param {import("../database/drivers/base.js").default} db - Local SQLite connection.
+     * @param {import("./types.js").PreparedLocalBackgroundJob} preparedJob - Prepared row data.
+     * @returns {Promise<void>} - Resolves after insertion.
+     */
+    _insertPreparedJob(db: import("../database/drivers/base.js").default, preparedJob: import("./types.js").PreparedLocalBackgroundJob): Promise<void>;
+    /**
+     * Reconciles configured queue-derived caps and durable counters.
+     * @returns {Promise<void>} - Resolves after reconciliation.
+     */
+    reconcileQueueConcurrency(): Promise<void>;
+    /**
+     * Applies current queue-derived concurrency policy to one queued row.
+     * Explicit concurrency keys remain owned by the enqueue contract.
+     * @param {import("../database/drivers/base.js").default} db - Local SQLite connection.
+     * @param {import("./types.js").BackgroundJobRow} job - Queued job snapshot.
+     * @param {Record<string, {maxConcurrent?: number, priority?: number}>} queues - Current queue policy snapshot.
+     * @returns {Promise<import("./types.js").BackgroundJobRow>} - Reconciled snapshot.
+     */
+    _reconcileQueuedJobConcurrency(db: import("../database/drivers/base.js").default, job: import("./types.js").BackgroundJobRow, queues: Record<string, {
+        maxConcurrent?: number;
+        priority?: number;
+    }>): Promise<import("./types.js").BackgroundJobRow>;
+    /**
+     * Finds the next eligible local job.
+     * @returns {Promise<import("./types.js").BackgroundJobRow | null>} - Next eligible local job.
+     */
+    nextAvailableJob(): Promise<import("./types.js").BackgroundJobRow | null>;
+    /**
+     * Finds the soonest future queued job.
+     * @returns {Promise<import("./types.js").BackgroundJobRow | null>} - Soonest future queued job.
+     */
+    nextScheduledJob(): Promise<import("./types.js").BackgroundJobRow | null>;
+    /**
+     * Finds a persisted local job by id.
+     * @param {string} jobId - Job id.
+     * @returns {Promise<import("./types.js").BackgroundJobRow | null>} - Persisted job.
+     */
+    getJob(jobId: string): Promise<import("./types.js").BackgroundJobRow | null>;
+    /**
+     * Lists local jobs in creation order.
+     * @returns {Promise<import("./types.js").BackgroundJobRow[]>} - All local jobs in creation order.
+     */
+    listJobs(): Promise<import("./types.js").BackgroundJobRow[]>;
+    /**
+     * Atomically reserves concurrency and claims one queued job.
+     * @param {{jobId: string, workerId?: string}} args - Claim request.
+     * @returns {Promise<import("./types.js").BackgroundJobHandoff | null>} - Fenced claim.
+     */
+    markHandedOff({ jobId, workerId }: {
+        jobId: string;
+        workerId?: string;
+    }): Promise<import("./types.js").BackgroundJobHandoff | null>;
+    /**
+     * Finds active local handoffs owned by one worker.
+     * @param {{workerId: string}} args - Worker identity.
+     * @returns {Promise<Array<{jobId: string, handoffId: string}>>} - Active worker handoffs.
+     */
+    handedOffJobsForWorker({ workerId }: {
+        workerId: string;
+    }): Promise<Array<{
+        jobId: string;
+        handoffId: string;
+    }>>;
+    /**
+     * Returns an exact active handoff to the queue.
+     * @param {{jobId: string, handoffId: string}} args - Handoff release.
+     * @returns {Promise<void>} - Resolves after the fenced release.
+     */
+    markReturnedToQueue({ jobId, handoffId }: {
+        jobId: string;
+        handoffId: string;
+    }): Promise<void>;
+    /**
+     * Applies a fenced successful acknowledgement.
+     * @param {{jobId: string, handoffId?: string}} args - Completion report.
+     * @returns {Promise<boolean>} - Whether the lease won.
+     */
+    markCompleted({ jobId, handoffId }: {
+        jobId: string;
+        handoffId?: string;
+    }): Promise<boolean>;
+    /**
+     * Applies a fenced reschedule without consuming an attempt.
+     * @param {{jobId: string, handoffId?: string, delayMs: number}} args - Reschedule report.
+     * @returns {Promise<boolean>} - Whether the lease won.
+     */
+    markRescheduled({ jobId, handoffId, delayMs }: {
+        jobId: string;
+        handoffId?: string;
+        delayMs: number;
+    }): Promise<boolean>;
+    /**
+     * Applies a fenced failure, retry, or terminal transition.
+     * @param {{jobId: string, handoffId?: string, error: ReturnType<typeof JSON.parse>}} args - Failure report.
+     * @returns {Promise<import("./types.js").BackgroundJobRow | null>} - Accepted transition snapshot.
+     */
+    markFailed({ jobId, handoffId, error }: {
+        jobId: string;
+        handoffId?: string;
+        error: ReturnType<typeof JSON.parse>;
+    }): Promise<import("./types.js").BackgroundJobRow | null>;
+    /**
+     * Turns every abandoned local handoff into the normal failure/retry path.
+     * @returns {Promise<import("./types.js").BackgroundJobRow[]>} - Recovered transitions.
+     */
+    recoverHandedOffJobs(): Promise<import("./types.js").BackgroundJobRow[]>;
+    /**
+     * Deletes local queue state for focused tests.
+     * @returns {Promise<void>} - Resolves after deletion.
+     */
+    clearAll(): Promise<void>;
+    /**
+     * Applies the common retry or exhausted failure transition.
+     * @param {import("../database/drivers/base.js").default} db - Local SQLite connection.
+     * @param {import("./types.js").BackgroundJobRow} job - Active handoff.
+     * @param {ReturnType<typeof JSON.parse>} error - Performance error.
+     * @returns {Promise<import("./types.js").BackgroundJobRow | null>} - Transition snapshot.
+     */
+    _applyFailure(db: import("../database/drivers/base.js").default, job: import("./types.js").BackgroundJobRow, error: ReturnType<typeof JSON.parse>): Promise<import("./types.js").BackgroundJobRow | null>;
+    /**
+     * Ensures that a durable concurrency counter exists with the required cap.
+     * @param {import("../database/drivers/base.js").default} db - Local SQLite connection.
+     * @param {import("./types.js").ResolvedBackgroundJobConcurrency} concurrency - Desired counter.
+     * @returns {Promise<void>} - Resolves when ensured.
+     */
+    _ensureConcurrency(db: import("../database/drivers/base.js").default, concurrency: import("./types.js").ResolvedBackgroundJobConcurrency): Promise<void>;
+    /**
+     * Atomically reserves one slot for a concurrency key.
+     * @param {import("../database/drivers/base.js").default} db - Connection.
+     * @param {string} concurrencyKey - Concurrency key.
+     * @returns {Promise<boolean>} - Whether a slot was reserved.
+     */
+    _reserveConcurrency(db: import("../database/drivers/base.js").default, concurrencyKey: string): Promise<boolean>;
+    /**
+     * Releases one slot for a concurrency key.
+     * @param {import("../database/drivers/base.js").default} db - Connection.
+     * @param {string | null} concurrencyKey - Concurrency key.
+     * @returns {Promise<void>} - Resolves after release.
+     */
+    _releaseConcurrency(db: import("../database/drivers/base.js").default, concurrencyKey: string | null): Promise<void>;
+    /**
+     * Acquires the transaction's write lock for a concurrency counter row.
+     * @param {import("../database/drivers/base.js").default} db - Connection.
+     * @param {string | null} concurrencyKey - Concurrency key.
+     * @returns {Promise<void>} - Resolves after locking.
+     */
+    _lockConcurrencyRow(db: import("../database/drivers/base.js").default, concurrencyKey: string | null): Promise<void>;
+    /**
+     * Rebuilds active counters from durable handed-off jobs.
+     * @param {import("../database/drivers/base.js").default} db - Connection.
+     * @returns {Promise<void>} - Resolves after counter rebuild.
+     */
+    _rebuildConcurrencyCounts(db: import("../database/drivers/base.js").default): Promise<void>;
+    /**
+     * Builds the configured queue-priority ordering expression.
+     * @param {import("../database/drivers/base.js").default} db - Connection.
+     * @returns {string | null} - Queue priority expression.
+     */
+    _queuePriorityOrderSql(db: import("../database/drivers/base.js").default): string | null;
+    /**
+     * Checks whether a persisted handoff owns the supplied acknowledgement fence.
+     * @param {import("./types.js").BackgroundJobRow | null} job - Persisted job.
+     * @param {string | undefined} handoffId - Handoff fence.
+     * @returns {job is import("./types.js").BackgroundJobRow} - Whether accepted.
+     */
+    _acceptsHandoff(job: import("./types.js").BackgroundJobRow | null, handoffId: string | undefined): job is import("./types.js").BackgroundJobRow;
+    /**
+     * Finds a persisted local job using the current connection.
+     * @param {import("../database/drivers/base.js").default} db - Connection.
+     * @param {string} jobId - Job id.
+     * @returns {Promise<import("./types.js").BackgroundJobRow | null>} - Persisted row.
+     */
+    _getJob(db: import("../database/drivers/base.js").default, jobId: string): Promise<import("./types.js").BackgroundJobRow | null>;
+    /**
+     * Normalizes one raw local database row.
+     * @param {Record<string, ReturnType<typeof JSON.parse>>} row - Raw row.
+     * @returns {import("./types.js").BackgroundJobRow} - Normalized row.
+     */
+    _normalizeRow(row: Record<string, ReturnType<typeof JSON.parse>>): import("./types.js").BackgroundJobRow;
+    /**
+     * Normalizes one nullable database number.
+     * @param {ReturnType<typeof JSON.parse>} value - Database number.
+     * @returns {number | null} - Normalized number.
+     */
+    _numberOrNull(value: ReturnType<typeof JSON.parse>): number | null;
+    /**
+     * Executes a structured update and reports its affected-row count.
+     * @param {import("../database/drivers/base.js").default} db - Connection.
+     * @param {import("../database/drivers/base.js").UpdateSqlArgsType} args - Update arguments.
+     * @returns {Promise<number>} - Affected rows.
+     */
+    _updateAffectedRows(db: import("../database/drivers/base.js").default, args: import("../database/drivers/base.js").UpdateSqlArgsType): Promise<number>;
+    /**
+     * Joins an ambient app transaction or uses the database's scoped operation lease.
+     * @template T
+     * @param {import("../database/drivers/base.js").default} db - Connection.
+     * @param {(db: import("../database/drivers/base.js").default) => Promise<T>} callback - Mutation.
+     * @returns {Promise<T>} - Mutation result.
+     */
+    _mutate<T>(db: import("../database/drivers/base.js").default, callback: (db: import("../database/drivers/base.js").default) => Promise<T>): Promise<T>;
+    /**
+     * Runs a callback in a transaction and returns its captured result.
+     * @template T
+     * @param {import("../database/drivers/base.js").default} db - Connection.
+     * @param {() => Promise<T>} callback - Transaction callback.
+     * @returns {Promise<T>} - Callback result.
+     */
+    _transactionResult<T>(db: import("../database/drivers/base.js").default, callback: () => Promise<T>): Promise<T>;
+    /**
+     * Runs a callback with the configured local database connection.
+     * @template T
+     * @param {(db: import("../database/drivers/base.js").default) => Promise<T>} callback - Connection callback.
+     * @returns {Promise<T>} - Callback result.
+     */
+    _withDb<T>(callback: (db: import("../database/drivers/base.js").default) => Promise<T>): Promise<T>;
+    /**
+     * Reports an unexpected local-store failure through framework channels.
+     * @param {{error: Error, stage: string}} args - Error report.
+     * @returns {void} - No return value.
+     */
+    _reportFrameworkError({ error, stage }: {
+        error: Error;
+        stage: string;
+    }): void;
+}
+//# sourceMappingURL=local-store.d.ts.map

package/build/src/background-jobs/local-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-store.d.ts","sourceRoot":"","sources":["../../../src/background-jobs/local-store.js"],"names":[],"mappings":"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"}