@cleocode/core 2026.9.7 → 2026.9.9

package/dist/store/background-jobs.d.ts

@@ -1,171 +1,492 @@
-/**
- * Background Job Manager for Long-Running Operations
- *
- * Operations that may take >30s support async execution. This module
- * provides a job manager backed by a SQLite DurableJobStore so that job
- * state survives process restart.  Any job recorded as `running` in the
- * database at construction time is immediately transitioned to `orphaned`
- * so that humans/agents can triage it — no silent retry.
- *
- * @remarks
- * Relocated from `packages/cleo/src/dispatch/lib/background-jobs.ts` into
- * `@cleocode/core/store` (R3-K1 · T11455 · SG-RUNTIME-UNIFICATION). This is
- * Drizzle DB-access logic, so it belongs in `@cleocode/core` — the package that
- * owns the consolidated SQLite schema, the single Drizzle instance, and the DB
- * handle types. Hosting it here means there is exactly ONE `drizzle-orm`
- * instance backing the query builders (no dual peer-hashed instance / `tsc -b`
- * `SQL<unknown>` nominal mismatch). `@cleocode/runtime/gateway` imports the
- * accessor from here and declares no `drizzle-orm` dependency of its own.
- *
- * @task T641
- * @task T11455
- */
+import type { AtomicJobBookkeeping, AtomicJobMutation, AtomicJobRetryBookkeeping, BackgroundJobCandidatePage, BackgroundJobExecutionContext, BackgroundJobFailureCode, BackgroundJobLease, BackgroundJobPageQuery, BackgroundJobStoreOptions, BackgroundJobSubmission, JobAttemptOutcome, JobFinalizationResult, OperationExecutionContext } from '@cleocode/contracts/jobs';
 import type { NodeSQLiteDatabase } from './sqlite.js';
 import { type BackgroundJobStatus } from './tasks-schema.js';
 export type { BackgroundJobStatus };
-/**
- * Background job representation returned by public API methods.
- *
- * Timestamps are ISO-8601 strings so callers do not need to know that the
- * database stores them as integer milliseconds.
- */
+/** Inspectable durable job, including unresolved legacy scope and ownership. */
 export interface BackgroundJob {
-    /** Unique job identifier (UUID v4). */
+    /** Unique persisted job ID. */
     id: string;
-    /** Operation name, e.g. "nexus.analyze". */
+    /** Supported operation name. */
     operation: string;
-    /** Current lifecycle status. */
+    /** Persisted lifecycle status; cancellation requests are separate. */
     status: BackgroundJobStatus;
-    /** ISO-8601 timestamp of when the job started. */
+    /** ISO-8601 creation time. */
     startedAt: string;
-    /** ISO-8601 timestamp of when the job finished; undefined while running. */
+    /** ISO-8601 terminal time, if committed. */
     completedAt?: string;
-    /** JSON-serialised result; undefined on failure or while running. */
+    /** Existing executor result surface. */
     result?: unknown;
-    /** Error message; undefined on success or while running. */
+    /** Persisted executor error, when failed. */
     error?: string;
-    /** Progress 0-100; undefined until reported. */
+    /** Last reported percentage. */
     progress?: number;
-    /** Agent or session that claimed this job; undefined if unclaimed. */
+    /** Actor display identity, distinct from the unique lease owner. */
     claimedBy?: string;
+    /** Explicit project identity; null discloses unresolved legacy scope. */
+    projectId: string | null;
+    /** Unique owner of the current claim; null on legacy unowned rows. */
+    ownerId: string | null;
+    /** Current lease expiration in epoch milliseconds. */
+    leaseExpiresAt: number | null;
+    /** Last heartbeat in epoch milliseconds. */
+    heartbeatAt: number;
+    /** Monotonic claim fence. */
+    fencingEpoch: number;
+    /** Number of issued execution claims. */
+    attempts: number;
+    /** Persisted cancellation request; does not assert executor termination. */
+    cancellationRequestedAt: number | null;
+    /** Last fenced JSON checkpoint bytes. */
+    checkpointJson: string | null;
+    /** Last checkpoint timestamp in epoch milliseconds. */
+    checkpointAt: number | null;
+    /** Project/operation-scoped retry key. */
+    idempotencyKey: string | null;
+    /** SHA-256 of immutable proposal bytes. */
+    proposalHash: string | null;
+    /** Authentic immutable input bytes; null means the original payload is unavailable. */
+    proposalJson: string | null;
+    /** Ownership assessment at read time, independent of lifecycle status. */
+    ownership: 'current' | 'expired' | 'unclaimed' | 'legacy-unknown' | 'terminal';
+    /** Explicit diagnostic failure, when result decoding or local persistence failed. */
+    diagnosticError?: string;
 }
-/**
- * Configuration for {@link BackgroundJobManager}.
- */
-export interface BackgroundJobManagerConfig {
-    /** Maximum number of concurrently *running* jobs. Default: 10. */
+/** Configuration for the existing executor facade. */
+export interface BackgroundJobManagerConfig extends BackgroundJobStoreOptions {
+    /** Maximum running jobs observed in this client's project scope. */
     maxJobs?: number;
-    /** How long (ms) to retain completed/failed/cancelled jobs. Default: 3 600 000 (1 h). */
+    /** Former retention window. @deprecated Job evidence is retained regardless of age. */
     retentionMs?: number;
 }
-type TasksDb = NodeSQLiteDatabase;
 /**
- * Drizzle-backed persistence layer for background jobs.
- *
- * On construction the store scans for `running` rows left by a prior
- * process and marks them `orphaned`.  All reads and writes go through
- * Drizzle — no raw SQL strings.
- *
- * @task T641
+ * Stable refusal of an unsafe ownership, retry, or transaction operation.
+ * @remarks A refusal preserves the current owner's work and reports no committed transition.
+ */
+export declare class BackgroundJobError extends Error {
+    /** Machine-readable refusal reason. */
+    readonly code: BackgroundJobFailureCode;
+    /**
+     * Construct an explicit job-store refusal.
+     * @param code - Stable failure category.
+     * @param message - Human-readable reason and required correction.
+     * @remarks This error never establishes successful job execution.
+     * @example
+     * ```ts
+     * throw new BackgroundJobError('E_JOB_LEASE_LOST', 'Reclaim expired work first');
+     * ```
+     */
+    constructor(code: BackgroundJobFailureCode, message: string);
+}
+/**
+ * Revalidate captured job ownership inside the domain's existing write transaction.
+ * @param db - The same transaction handle that will perform the domain mutation.
+ * @param execution - Captured lifetime and optional immutable job fence.
+ * @throws BackgroundJobError when ownership, scope, proposal, cancellation or file identity changed.
+ * @remarks This read does not start a transaction or authorize arbitrary work. Callers
+ * must own the surrounding write transaction and independently validate their domain
+ * preconditions. Keeping this check inside that transaction fences concurrent claims
+ * and permits domain mutations and receipts to compose in one atomic unit.
+ * @example
+ * ```ts
+ * db.transaction(tx => { assertOperationWriteFence(tx, execution); writePreparedRows(tx); });
+ * ```
+ */
+export declare function assertOperationWriteFence(db: Pick<NodeSQLiteDatabase, 'select'>, execution: OperationExecutionContext): void;
+/**
+ * Drizzle-backed ownership of the established active job table.
+ * @remarks Sync methods refuse an already-owned native transaction before writing.
+ * No method infers a missing legacy lease to be expired. Rows are never age-pruned.
+ * @example
+ * ```ts
+ * const jobs = new DurableJobStore(db, { projectId: 'project-uuid' });
+ * const lease = jobs.insert('job-uuid', 'doctor.knowledge', Date.now());
+ * if (lease) jobs.complete(lease.jobId, { verified: true }, Date.now());
+ * ```
  */
 export declare class DurableJobStore {
     #private;
-    constructor(db: TasksDb);
+    /** Positive lease duration used for claims and heartbeats. */
+    readonly leaseMs: number;
+    /**
+     * Open a client without changing persisted work.
+     * @param db - Existing canonical database handle; no new connection is opened.
+     * @param options - Explicit scope, actor, and lease duration.
+     * @remarks Unscoped legacy callers retain visible null project identity.
+     * @example
+     * ```ts
+     * const store = new DurableJobStore(db, { projectId: 'project-uuid', leaseMs: 30000 });
+     * ```
+     */
+    constructor(db: NodeSQLiteDatabase, options?: BackgroundJobStoreOptions);
+    /**
+     * Create a leased job, or return the existing immutable scoped submission.
+     * @param id - Proposed UUID for a new job.
+     * @param operation - Supported operation identifier.
+     * @param now - Event timestamp in epoch milliseconds.
+     * @param submission - Optional scoped immutable retry contract.
+     * @param maxRunning - Optional running-job limit checked atomically with creation.
+     * @returns Grant for new work, or null when an identical submission already exists.
+     * @remarks A repeated submission never acquires ownership or re-executes by itself.
+     * @example
+     * ```ts
+     * const grant = store.insert(id, 'doctor.knowledge', Date.now(), submission);
+     * ```
+     */
+    insert(id: string, operation: string, now: number, submission?: BackgroundJobSubmission, maxRunning?: number): BackgroundJobLease | null;
+    /**
+     * Find an existing immutable submission without claiming it.
+     * @param operation - Exact supported operation.
+     * @param submission - Project and retry identity.
+     * @returns Persisted job, or undefined.
+     * @remarks Input conflict validation is performed by insert before coalescing.
+     * @example
+     * ```ts
+     * const prior = store.findSubmission('doctor.knowledge', submission);
+     * ```
+     */
+    findSubmission(operation: string, submission: BackgroundJobSubmission): BackgroundJob | undefined;
     /**
-     * Insert a new job row with `running` status.
-     *
-     * @param id        - UUID for the job
-     * @param operation - Operation name
-     * @param now       - Current timestamp in ms
+     * Persist authentic pending work without claiming or starting an executor.
+     * @param id - Proposed job identity; matching retries retain the original identity.
+     * @param operation - Exact operation whose supported inputs the domain service validates.
+     * @param now - Submission timestamp in epoch milliseconds.
+     * @param submission - Required project-scoped immutable serialized proposal.
+     * @param execution - Optional original invocation budget; omitted legacy callers retain existing behavior.
+     * @returns Persisted pending job, or unchanged prior matching submission.
+     * @remarks Input and its hash commit in one native transaction. Existing history
+     * without payload is retained, never reconstructed from a hash or overwritten.
+     * @example
+     * ```ts
+     * const pending = store.defer(id, 'docs.projection', Date.now(), submission);
+     * ```
      */
-    insert(id: string, operation: string, now: number): void;
+    defer(id: string, operation: string, now: number, submission: BackgroundJobSubmission, execution?: OperationExecutionContext): BackgroundJob;
     /**
-     * Retrieve a single job by ID.  Returns `undefined` if not found.
+     * Read a job with scope and ownership disclosed.
+     * @param id - Job identity.
+     * @returns Job or undefined.
+     * @remarks A missing or expired lease is never represented as current ownership.
+     * @example
+     * ```ts
+     * const job = store.get(id);
+     * ```
      */
     get(id: string): BackgroundJob | undefined;
     /**
-     * Retrieve all jobs, optionally filtered by status.
+     * List visible jobs.
+     * @param status - Optional lifecycle filter.
+     * @returns Matching scoped jobs.
+     * @remarks Project-scoped clients exclude other projects and unscoped legacy rows.
+     * @example
+     * ```ts
+     * const jobs = store.list('running');
+     * ```
      */
     list(status?: string): BackgroundJob[];
     /**
-     * Mark a job as `complete` with an optional result payload.
+     * Read a bounded candidate page without a runtime manager or ownership mutation.
+     * @param query - Exact operation, optional status, payload cap and bound cursor.
+     * @param execution - Original captured caller and deadline; never renewed by this read.
+     * @returns Candidate rows and a last-scanned cursor; the domain must validate principals.
+     * @throws BackgroundJobError for ambiguous scope, mismatched cursors, oversized rows or borrowed transactions.
+     * @remarks SQL limits candidates before payload materialization or JSON parsing. Mutable
+     * claimedBy is not used as principal authority. Existing transaction cleanup bounds lock waits;
+     * synchronous SQLite work is cooperative and cannot be preempted by a JavaScript timer.
+     * @example
+     * ```ts
+     * const page = store.listPage({ operation: 'doctor.knowledge', limit: 20 }, execution);
+     * ```
+     */
+    listPage(query: BackgroundJobPageQuery, execution: OperationExecutionContext): BackgroundJobCandidatePage<BackgroundJob>;
+    /**
+     * Claim authentic unstarted work or reclaim an explicitly expired lease.
+     * @param id - Existing job identity.
+     * @param now - Claim timestamp.
+     * @param maxRunning - Optional capacity limit enforced atomically with the claim.
+     * @param execution - Optional original invocation budget; supplying it adds scoped cancellation and deadline checks.
+     * @returns New attempt's lease.
+     * @remarks Preserves checkpoint and cancellation request. Pending work must have
+     * authentic hash-matching inputs and no prior execution; ambiguous legacy rows refuse.
+     * @example
+     * ```ts
+     * const lease = store.claim(expiredJob.id, Date.now());
+     * ```
+     */
+    claim(id: string, now: number, maxRunning?: number, execution?: OperationExecutionContext): BackgroundJobLease;
+    /**
+     * Start an explicit new attempt after retaining terminal or expired owned work atomically.
+     * @param id - Authentic failed, cancelled or explicitly expired owned job with the same immutable proposal.
+     * @param now - New attempt timestamp.
+     * @param execution - Fresh bounded invocation; expired contexts or old fences cannot be renewed.
+     * @param retainOutcome - Trusted synchronous core callback that rechecks domain preconditions,
+     * appends the complete previous row image, and verifies its receipt before returning.
+     * @param maxRunning - Optional capacity limit enforced inside the same transaction.
+     * @returns New owned lease, without reapplying any domain operation.
+     * @throws BackgroundJobError when scope, terminal status, authentic input, counters, or receipt is invalid.
+     * @remarks Complete jobs are never reopened. Expired running rows retain their authentic
+     * uncertain outcome; expiry does not invent failure. Explicit resume acknowledges a retained
+     * previous cancellation request and clears it only with the new claim. Callback failure, cancellation, or claim failure
+     * rolls back both historical bookkeeping and the new claim. The caller must independently
+     * preserve its append-only history in the same database; this is not an arbitrary callback sandbox.
+     * @example
+     * ```ts
+     * const lease = store.retryAtomically(id, Date.now(), context, retainPreviousAttempt);
+     * ```
+     */
+    retryAtomically(id: string, now: number, execution: OperationExecutionContext, retainOutcome: AtomicJobRetryBookkeeping, maxRunning?: number): BackgroundJobLease;
+    /**
+     * Renew an owned lease and observe persisted cancellation.
+     * @param id - Owned job identity.
+     * @param now - Heartbeat timestamp.
+     * @returns Current job including cancellation request.
+     * @remarks Expired attempts cannot revive themselves through heartbeat.
+     * @example
+     * ```ts
+     * const job = store.heartbeat(id, Date.now());
+     * ```
+     */
+    heartbeat(id: string, now: number): BackgroundJob;
+    /**
+     * Persist a checkpoint under the current attempt fence.
+     * @param id - Owned job identity.
+     * @param valueJson - Valid serialized checkpoint bytes.
+     * @param now - Checkpoint timestamp.
+     * @remarks Writes atomically with ownership verification; does not authorize domain writes.
+     * @example
+     * ```ts
+     * store.checkpoint(id, JSON.stringify({ nextFile: 8 }), Date.now());
+     * ```
+     */
+    checkpoint(id: string, valueJson: string, now: number): void;
+    /**
+     * Request cancellation without claiming that execution has stopped.
+     * @param id - Visible job identity.
+     * @param now - Request timestamp.
+     * @param execution - Optional original invocation context; never renews its deadline.
+     * @returns Whether pending work was cancelled or running work has a persisted request.
+     * @remarks Terminal results are preserved when cancellation arrives after commit.
+     * @example
+     * ```ts
+     * const requested = store.requestCancel(id, Date.now());
+     * ```
+     */
+    requestCancel(id: string, now: number, execution?: OperationExecutionContext): boolean;
+    /**
+     * Commit actual executor success under ownership.
+     * @param id - Job identity.
+     * @param result - Actual outcome.
+     * @param now - Completion timestamp.
+     * @remarks An earlier cancellation request does not erase work already committed.
+     * @example
+     * ```ts
+     * store.complete(id, { verified: true }, Date.now());
+     * ```
      */
     complete(id: string, result: unknown, now: number): void;
     /**
-     * Mark a job as `failed` with an error message.
+     * Commit a synchronous domain mutation, its receipt and job completion atomically.
+     * @param execution - Captured context carrying this client's current claimed fence.
+     * @param mutation - Trusted synchronous domain operation returning JSON receipt bytes.
+     * @returns Exact receipt bytes committed with the domain changes and terminal job row.
+     * @throws BackgroundJobError when the transaction is borrowed, authority changed,
+     * cancellation was observed before commit, or receipt bytes are invalid.
+     * @remarks The store acquires its own write transaction; an ambient BEGIN confers
+     * no authority. Domain code must independently validate its proposal and operate
+     * only on the same SQLite database without transaction control or external effects.
+     * Guards are cooperative boundaries, not preemption. Cancellation observed after
+     * COMMIT cannot erase the committed result. Arbitrary async callbacks are unsupported.
+     * @example
+     * ```ts
+     * const receiptJson = store.completeAtomically(execution, () => applyPreparedRepair());
+     * ```
+     */
+    completeAtomically(execution: OperationExecutionContext, mutation: AtomicJobMutation): string;
+    /**
+     * Finalize trusted receipt/event metadata and a failed or cancelled attempt atomically.
+     * @param execution - Original bounded attempt identity and current ownership fence.
+     * @param outcome - Sourced observed outcome; expiry alone cannot supply this fact.
+     * @param bookkeeping - Synchronous metadata-only service callback returning JSON receipt bytes.
+     * @returns Committed receipt or explicit pending finalization with actual elapsed time.
+     * @remarks Cancellation allows bookkeeping only; domain repair remains forbidden.
+     * An exhausted deadline never acquires a lock. Failed finalization preserves the
+     * lease/checkpoint for inspection and a later explicit recovery attempt. No budget
+     * is renewed, and synchronous SQLite completion is not preempted by a timer.
+     * @example
+     * ```ts
+     * const result = store.finalizeAtomically(context, outcome, () => appendAttemptReceipt());
+     * ```
+     */
+    finalizeAtomically(execution: OperationExecutionContext, outcome: JobAttemptOutcome, bookkeeping: AtomicJobBookkeeping): JobFinalizationResult;
+    /**
+     * Commit actual executor failure under ownership.
+     * @param id - Job identity.
+     * @param error - Failure message.
+     * @param now - Failure timestamp.
+     * @remarks Stale owners cannot replace a newer attempt's outcome.
+     * @example
+     * ```ts
+     * store.fail(id, 'Verification failed', Date.now());
+     * ```
      */
     fail(id: string, error: string, now: number): void;
     /**
-     * Mark a job as `cancelled`.
+     * Acknowledge an executor's cancellation.
+     * @param id - Owned job identity.
+     * @param now - Acknowledgement timestamp.
+     * @remarks Requires a persisted cancellation request and current ownership.
+     * @example
+     * ```ts
+     * store.cancel(id, Date.now());
+     * ```
      */
     cancel(id: string, now: number): void;
     /**
-     * Update the progress (0-100) and heartbeat of a running job.
+     * Update an owned attempt's progress.
+     * @param id - Job identity.
+     * @param progress - Finite percentage, clamped to zero through one hundred.
+     * @param now - Observation timestamp.
+     * @remarks Progress does not renew an expired lease or overwrite another owner.
+     * @example
+     * ```ts
+     * store.progress(id, 50, Date.now());
+     * ```
      */
     progress(id: string, progress: number, now: number): void;
     /**
-     * Delete terminal (complete/failed/cancelled/orphaned) jobs whose
-     * `completedAt` is older than `cutoffMs`.
-     *
-     * @returns Number of rows deleted.
+     * Retain historical job evidence regardless of age.
+     * @param _cutoffMs - Former deletion threshold, retained for API compatibility.
+     * @returns Zero; any future deletion requires explicit evidence-aware recovery policy.
+     * @remarks No automatic or age-only pruning is performed.
+     * @example
+     * ```ts
+     * const removed = store.purgeOlderThan(Date.now()); // 0
+     * ```
      */
-    purgeOlderThan(cutoffMs: number): number;
+    purgeOlderThan(_cutoffMs: number): number;
 }
 /**
- * Manages background jobs for long-running operations.
- *
- * Backed by a {@link DurableJobStore} so job state persists across process
- * restarts.  The public interface is identical to the previous in-memory
- * implementation so the job-manager accessor does not change.
- *
- * @task T641
+ * Existing executor facade with persisted ownership and cooperative cancellation.
+ * @remarks Executors must use a separately authorized transactional service for
+ * domain changes and receipts; this class fences only job metadata/checkpoints.
+ * @example
+ * ```ts
+ * const manager = new BackgroundJobManager(db, { projectId: 'project-uuid' });
+ * const id = await manager.startJob('inspect', async ({ signal }) => ({ cancelled: signal.aborted }));
+ * ```
  */
 export declare class BackgroundJobManager {
     #private;
-    constructor(db: TasksDb, config?: BackgroundJobManagerConfig);
     /**
-     * Start a new background job.
-     *
-     * @param operation - The operation identifier (e.g. "nexus.analyze")
-     * @param executor  - Async function to execute in the background
-     * @returns The job ID
-     * @throws Error if the maximum number of concurrent running jobs is reached
+     * Open the existing facade.
+     * @param db - Canonical store.
+     * @param config - Scope and lease configuration.
+     * @remarks Construction does not orphan or execute persisted work.
+     * @example
+     * ```ts
+     * const manager = new BackgroundJobManager(db, { projectId: 'project-uuid' });
+     * ```
+     */
+    constructor(db: NodeSQLiteDatabase, config?: BackgroundJobManagerConfig);
+    /**
+     * Start new work or coalesce an identical immutable submission.
+     * @param operation - Supported operation.
+     * @param executor - Existing executor, now given cancellation and checkpoint capabilities.
+     * @param submission - Optional scoped retry identity.
+     * @returns New or already persisted job identity.
+     * @remarks Repeated submissions never invoke a second executor.
+     * @example
+     * ```ts
+     * const id = await manager.startJob('inspect', async () => ({ verified: true }), submission);
+     * ```
+     */
+    startJob(operation: string, executor: (context: BackgroundJobExecutionContext) => Promise<unknown>, submission?: BackgroundJobSubmission): Promise<string>;
+    /**
+     * Record optional work durably without scheduling an executor or model.
+     * @param operation - Supported action validated by the calling domain service.
+     * @param submission - Authentic scoped proposal bytes for explicit later resume.
+     * @returns Existing or newly persisted job identity.
+     * @remarks This does not establish completion of the optional projection or a
+     * domain repair receipt. Explicit resume must validate current prerequisites.
+     * @example
+     * ```ts
+     * const id = manager.deferJob('docs.projection', submission);
+     * ```
+     */
+    deferJob(operation: string, submission: BackgroundJobSubmission): string;
+    /**
+     * Explicitly start pending work or resume expired ownership using the existing facade.
+     * @param id - Expired job identity.
+     * @param executor - Executor capable of resuming its persisted checkpoint.
+     * @returns Identity of the resumed job.
+     * @remarks The earlier owner is fenced before a replacement executor can run.
+     * @example
+     * ```ts
+     * await manager.resumeJob(id, async ({ checkpoint }) => { checkpoint('{}'); });
+     * ```
      */
-    startJob(operation: string, executor: () => Promise<unknown>): Promise<string>;
+    resumeJob(id: string, executor: (context: BackgroundJobExecutionContext) => Promise<unknown>): Promise<string>;
     /**
-     * Get a specific job by ID.
-     *
-     * @returns The job or `undefined` if not found.
+     * Read persisted state and local diagnostic failures.
+     * @param id - Job identity.
+     * @returns Job or undefined.
+     * @remarks Persistence errors are disclosed separately from a committed outcome.
+     * @example
+     * ```ts
+     * const job = manager.getJob(id);
+     * ```
      */
-    getJob(jobId: string): BackgroundJob | undefined;
+    getJob(id: string): BackgroundJob | undefined;
     /**
-     * List all jobs, optionally filtered by status.
-     *
-     * @param status - Optional status filter string.
-     * @returns Array of matching jobs.
+     * List persisted scoped jobs.
+     * @param status - Optional lifecycle filter.
+     * @returns Matching jobs.
+     * @remarks Includes cancellation requests and local diagnostic failures.
+     * @example
+     * ```ts
+     * const jobs = manager.listJobs('running');
+     * ```
      */
     listJobs(status?: string): BackgroundJob[];
     /**
-     * Cancel a running job.
-     *
-     * @returns `true` if the job was cancelled; `false` if not found or not running.
+     * Request cancellation of visible running work.
+     * @param id - Job identity.
+     * @returns Whether the request was recorded, not proof of termination.
+     * @remarks Other owners observe the durable request on heartbeat.
+     * @example
+     * ```ts
+     * const requested = manager.cancelJob(id);
+     * ```
      */
-    cancelJob(jobId: string): boolean;
+    cancelJob(id: string): boolean;
     /**
-     * Update the progress of a running job (0-100).
-     *
-     * @returns `true` if updated; `false` if the job is not found or not running.
+     * Report progress from an owned executor.
+     * @param id - Job identity.
+     * @param progress - Finite percentage.
+     * @returns Whether the job exists and is running.
+     * @remarks A visible job owned by another attempt is explicitly refused.
+     * @example
+     * ```ts
+     * manager.updateProgress(id, 50);
+     * ```
      */
-    updateProgress(jobId: string, progress: number): boolean;
+    updateProgress(id: string, progress: number): boolean;
     /**
-     * Delete completed/failed/cancelled/orphaned jobs past the retention window.
-     *
-     * @returns Number of jobs removed.
+     * Preserve historical evidence.
+     * @returns Zero rows removed.
+     * @remarks Age alone never authorizes deletion of job evidence.
+     * @example
+     * ```ts
+     * const removed = manager.cleanup(); // 0
+     * ```
      */
     cleanup(): number;
     /**
-     * Destroy the manager: cancel all in-process running jobs and stop the
-     * cleanup timer.  Does NOT purge DB rows — orphaned jobs must be reviewed.
+     * Request cancellation only for this manager's executors and stop its timers.
+     * @remarks Does not claim non-cooperative executors stopped or alter another owner.
+     * @example
+     * ```ts
+     * manager.destroy(); // inspect persisted cancellation/completion separately
+     * ```
      */
     destroy(): void;
 }

package/dist/store/background-jobs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"background-jobs.d.ts","sourceRoot":"","sources":["../../src/store/background-jobs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAEL,KAAK,mBAAmB,EAGzB,MAAM,mBAAmB,CAAC;AAG3B,YAAY,EAAE,mBAAmB,EAAE,CAAC;AAEpC;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,uCAAuC;IACvC,EAAE,EAAE,MAAM,CAAC;IACX,4CAA4C;IAC5C,SAAS,EAAE,MAAM,CAAC;IAClB,gCAAgC;IAChC,MAAM,EAAE,mBAAmB,CAAC;IAC5B,kDAAkD;IAClD,SAAS,EAAE,MAAM,CAAC;IAClB,4EAA4E;IAC5E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qEAAqE;IACrE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,4DAA4D;IAC5D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gDAAgD;IAChD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sEAAsE;IACtE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC,kEAAkE;IAClE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yFAAyF;IACzF,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AA8CD,KAAK,OAAO,GAAG,kBAAkB,CAAC;AAElC;;;;;;;;GAQG;AACH,qBAAa,eAAe;;gBAGd,EAAE,EAAE,OAAO;IAwBvB;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAWxD;;OAEG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;IAM1C;;OAEG;IACH,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,aAAa,EAAE;IAWtC;;OAEG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAcxD;;OAEG;IACH,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAalD;;OAEG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAYrC;;OAEG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAWzD;;;;;OAKG;IACH,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;CAqBzC;AAMD;;;;;;;;GAQG;AACH,qBAAa,oBAAoB;;gBAOnB,EAAE,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,0BAA0B;IAe5D;;;;;;;OAOG;IACG,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;IAsBpF;;;;OAIG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;IAIhD;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,aAAa,EAAE;IAI1C;;;;OAIG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAgBjC;;;;OAIG;IACH,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO;IASxD;;;;OAIG;IACH,OAAO,IAAI,MAAM;IAKjB;;;OAGG;IACH,OAAO,IAAI,IAAI;CAqDhB"}
+{"version":3,"file":"background-jobs.d.ts","sourceRoot":"","sources":["../../src/store/background-jobs.ts"],"names":[],"mappings":"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"}