@db3.ai/app 0.1.0-beta.1

package/src/queue/contracts/QueueEvents.ts

@@ -0,0 +1,77 @@
+import type { QueueJobId, QueueJobOrigin } from './QueuePayload';
+import type { QueueFailedJobRetryReference } from './QueueRetry';
+
+/**
+ * Lifecycle actions emitted as a durable queue job moves through the queue.
+ */
+export type QueueLifecycleAction =
+	| 'dispatched'
+	| 'claimed'
+	| 'released'
+	| 'deferred'
+	| 'succeeded'
+	| 'lease_lost'
+	| 'failed';
+
+/**
+ * Immutable lifecycle event emitted after the corresponding queue transition.
+ */
+export interface QueueLifecycleEvent {
+	/** Lifecycle transition represented by this event. */
+	action: QueueLifecycleAction;
+	/** UTC timestamp captured when the queue published the event. */
+	timestamp: string;
+	/** Named queue or channel containing the job. */
+	queue: string;
+	/** Durable job name used to resolve its handler. */
+	jobName: string;
+	/** Driver-owned queue record identifier. */
+	jobId: QueueJobId;
+	/** Stable UUID retained across every attempt for this queued job. */
+	jobUuid: string;
+	/** Number of processing attempts consumed at this transition. */
+	attempts: number;
+	/** Maximum processing attempts before terminal failure. */
+	maxTries: number;
+	/** Seconds before the next attempt is available, when applicable. */
+	delaySeconds?: number;
+	/** Handler duration for processing transitions, when measured. */
+	durationMs?: number;
+	/** Error that caused a release, deferral, or terminal failure. */
+	error?: unknown;
+	/** Framework-owned correlation metadata persisted with the queue envelope. */
+	origin?: QueueJobOrigin;
+	/** Terminal failure that was replayed to create this job, when applicable. */
+	retryOf?: QueueFailedJobRetryReference;
+	/** Application-owned job payload for opt-in diagnostic consumers. */
+	payloadData: Record<string, unknown>;
+}
+
+/**
+ * Synchronous or asynchronous consumer of queue lifecycle events.
+ * Thrown errors and rejected promises are reported without rejecting queue work.
+ */
+export type QueueLifecycleListener = (
+	event: QueueLifecycleEvent,
+) => void | Promise<void>;
+
+/**
+ * Failure raised by a lifecycle listener or optional job hook.
+ */
+export interface QueueLifecycleFailure {
+	/** Component that failed while observing an already-decided queue transition. */
+	source: 'listener' | 'hook';
+	/** Lifecycle event being observed when the failure occurred. */
+	event: QueueLifecycleEvent;
+	/** Optional QueueableJob hook that raised the failure. */
+	hook?: 'onRetry' | 'onFinalFailure';
+	/** Error raised by the listener or hook. */
+	error: unknown;
+}
+
+/**
+ * Reports non-fatal lifecycle listener and job-hook errors.
+ */
+export type QueueLifecycleErrorHandler = (
+	failure: QueueLifecycleFailure,
+) => void;

package/src/queue/contracts/QueuePayload.ts

@@ -0,0 +1,150 @@
+import type { QueueFailedJobRetryReference, QueueRetryBackoff, QueueRetryBackoffOptions } from './QueueRetry';
+
+/**
+ * Serialized form of a queueable job before it is wrapped in a durable queue envelope.
+ *
+ * Queueable jobs use this shape for object serialization and chained follow-up work.
+ */
+export interface SerializedQueuedJob<TData extends Record<string, unknown> = Record<string, unknown>> {
+	/** Durable job name used to resolve the handler when a worker processes the payload. */
+	job: string;
+	/** Human-readable label shown in logs and queue monitors. */
+	displayName?: string;
+	/** JSON-safe payload data owned by the queued job. */
+	data: TData;
+	/** Remaining jobs that should run after this job succeeds. */
+	chained?: SerializedQueuedJob[];
+}
+
+/**
+ * Framework-owned correlation metadata attached to one root queue job.
+ *
+ * Origins let orchestration layers observe a queue job without adding their
+ * identifiers to application-owned job payloads.
+ */
+export interface QueueJobOrigin {
+	/** Framework subsystem that owns the correlated record. */
+	type: string;
+	/** Stable identifier understood by the originating subsystem. */
+	id: string;
+}
+
+/**
+ * Durable payload stored by queue drivers.
+ *
+ * Drivers persist this envelope as the canonical queue record payload. Application jobs
+ * should treat `data` as their own payload and the other fields as framework metadata.
+ */
+export interface JobEnvelope<TData = Record<string, unknown>> {
+	/** Stable UUID for this queued job attempt chain. */
+	uuid: string;
+	/** Human-readable label shown in logs and queue monitors. */
+	displayName: string;
+	/** Durable job name used to resolve the handler. */
+	job: string;
+	/** Maximum number of attempts before the job is moved to failed storage. */
+	maxTries: number;
+	/** Durable delay policy used when an ordinary failed attempt is released. */
+	backoff?: QueueRetryBackoff;
+	/** Absolute Unix timestamp after which another ordinary retry must not be scheduled. */
+	retryUntil?: number;
+	/** Application-owned JSON-safe payload data. */
+	data: TData;
+	/** Optional framework-owned record that originated this root queue job. */
+	origin?: QueueJobOrigin;
+	/** Terminal failed-job record that was replayed to create this job. */
+	retryOf?: QueueFailedJobRetryReference;
+	/** Remaining jobs that should be dispatched after this job succeeds. */
+	chained?: SerializedQueuedJob[];
+}
+
+/**
+ * Identifier returned by a queue driver when a job is persisted.
+ */
+export type QueueJobId = number | string;
+
+/**
+ * Built-in queue driver names understood by the framework.
+ */
+export type QueueDriverName = 'database' | 'redis';
+
+/**
+ * Claimed queue job passed to handlers and lifecycle hooks.
+ */
+export interface QueueJob<TData = Record<string, unknown>> {
+	/** Driver-owned queue record id. */
+	id: QueueJobId;
+	/** Named queue/channel this job was claimed from. */
+	queue: string;
+	/** Number of processing attempts already consumed by this job. */
+	attempts: number;
+	/** Durable queue payload envelope. */
+	payload: JobEnvelope<TData>;
+}
+
+/**
+ * Per-dispatch overrides for queueing one job.
+ */
+export interface DispatchOptions {
+	/**
+	 * Named queue/channel the job should be pushed onto.
+	 *
+	 * Workers process one named queue at a time, so this lets callers route
+	 * different classes of work to different worker pools. When omitted, the
+	 * queue service uses its configured default queue name.
+	 */
+	queue?: string;
+
+	/**
+	 * Number of seconds to wait before the job becomes available to workers.
+	 */
+	delaySeconds?: number;
+
+	/**
+	 * Maximum number of processing attempts before the job is failed.
+	 */
+	maxTries?: number;
+
+	/**
+	 * Durable delay policy for ordinary failed attempts.
+	 */
+	backoff?: QueueRetryBackoffOptions;
+
+	/**
+	 * Maximum number of seconds ordinary retries may remain active after dispatch.
+	 *
+	 * Explicit QueueRetryLaterError deferrals own their own retry horizon and do
+	 * not consume this ordinary-attempt window.
+	 */
+	retryUntilSeconds?: number;
+
+	/**
+	 * Framework-owned correlation metadata for this root queued job.
+	 *
+	 * Chained jobs do not inherit this value automatically because their
+	 * lifecycle is distinct from the root dispatch.
+	 */
+	origin?: QueueJobOrigin;
+}
+
+/**
+ * Result status for one queue processing attempt.
+ *
+ * `lease_lost` means the handler settled but the worker could not prove that its
+ * exact attempt still owned the durable job, so no outcome transition was made.
+ */
+export type QueueProcessStatus = 'succeeded' | 'released' | 'deferred' | 'failed' | 'lease_lost';
+
+/**
+ * Detailed outcome returned after processing one claimed queue job.
+ */
+export interface QueueProcessResult {
+	/** Claimed queue job that was processed. */
+	job: QueueJob;
+	/** Final status for this processing attempt. */
+	status: QueueProcessStatus;
+	/** Delay before a released or deferred job becomes available again. */
+	delaySeconds?: number;
+	/** Handler or lease error explaining why the attempt did not succeed. */
+	error?: unknown;
+}

package/src/queue/contracts/QueueRetry.ts

@@ -0,0 +1,47 @@
+import type { QueueJobId } from './QueuePayload';
+
+/**
+ * Supported delay-growth strategies for ordinary queue retries.
+ */
+export type QueueRetryBackoffStrategy = 'linear' | 'exponential';
+
+/**
+ * Durable retry backoff stored with a queued job.
+ *
+ * Persisting this policy ensures every worker calculates the same retry schedule,
+ * even when queue configuration changes after the job was dispatched.
+ */
+export interface QueueRetryBackoff {
+	/** Delay-growth strategy applied after each consumed attempt. */
+	strategy: QueueRetryBackoffStrategy;
+	/** Base delay in seconds before the first retry. */
+	initialSeconds: number;
+	/** Maximum delay in seconds after applying the selected growth strategy. */
+	maxSeconds: number;
+	/** Whether equal jitter should be applied to reduce coordinated retry spikes. */
+	jitter: boolean;
+}
+
+/**
+ * Per-dispatch overrides used to build a durable retry backoff policy.
+ */
+export interface QueueRetryBackoffOptions {
+	/** Delay-growth strategy applied after each consumed attempt. */
+	strategy?: QueueRetryBackoffStrategy;
+	/** Base delay in seconds before the first retry. */
+	initialSeconds?: number;
+	/** Maximum delay in seconds after applying the selected growth strategy. */
+	maxSeconds?: number;
+	/** Whether equal jitter should be applied to reduce coordinated retry spikes. */
+	jitter?: boolean;
+}
+
+/**
+ * Links a replayed queue job to the terminal failure that produced it.
+ */
+export interface QueueFailedJobRetryReference {
+	/** Driver-owned failed-job record that was replayed. */
+	failedJobId: QueueJobId;
+	/** Stable UUID of the original terminally failed job. */
+	jobUuid: string;
+}

package/src/queue/contracts/QueueService.ts

@@ -0,0 +1,219 @@
+import type { QueueMonitor, QueueMonitorOptions } from '../queueMonitor';
+import type { QueueEvents } from '../QueueEvents';
+import type { QueueableJob } from '../QueueableJob';
+import type { QueueLifecycleErrorHandler } from './QueueEvents';
+import type { DispatchOptions, QueueDriverName, QueueJob, QueueJobId, QueueProcessResult } from './QueuePayload';
+import type { QueueRetryBackoffStrategy } from './QueueRetry';
+import type { QueueDriver, QueueFailedJob } from './QueueDriver';
+import type { QueueableJobClass } from './QueueableJob';
+import type { QueueWorkerLifecycle, QueueWorkerOptions } from './QueueWorkerLifecycle';
+import type { RedisQueueDriverOptions } from './RedisQueueDriver';
+
+/**
+ * Function-style handler registered for a durable queued job name.
+ */
+export type JobHandler<TData = Record<string, unknown>> = (job: QueueJob<TData>) => Promise<void>;
+
+/**
+ * Input passed to a lazy job resolver when a worker sees an unknown job name.
+ */
+export interface QueueJobResolverContext {
+	/** Durable queued job name from the persisted payload. */
+	jobName: string;
+}
+
+/**
+ * Resolves a queueable job class just in time for worker processing.
+ */
+export type QueueJobResolver = (
+	context: QueueJobResolverContext,
+) => QueueableJobClass | null | Promise<QueueableJobClass | null>;
+
+/**
+ * Queue service configuration shared by dispatching, processing, and worker startup.
+ */
+export interface QueueOptions {
+	/**
+	 * Default queue name used when dispatching or processing jobs without an explicit queue.
+	 */
+	queue?: string;
+	/**
+	 * Concrete queue driver instance, or the registered driver name to resolve lazily.
+	 */
+	driver?: QueueDriver | QueueDriverName;
+	/**
+	 * Named queue driver to resolve when no concrete driver instance is provided.
+	 */
+	driverName?: QueueDriverName;
+	/**
+	 * Redis driver options used when driver or driverName resolves to `redis`.
+	 */
+	redis?: RedisQueueDriverOptions;
+	/**
+	 * Number of seconds before an in-progress job is considered expired and claimable again.
+	 */
+	retryAfterSeconds?: number;
+	/**
+	 * Base delay, in seconds, used when releasing failed jobs for another attempt.
+	 */
+	retryDelaySeconds?: number;
+	/**
+	 * Default delay-growth strategy persisted on newly dispatched jobs.
+	 */
+	retryBackoffStrategy?: QueueRetryBackoffStrategy;
+	/**
+	 * Maximum delay, in seconds, persisted on newly dispatched jobs.
+	 */
+	retryMaxDelaySeconds?: number;
+	/**
+	 * Whether newly dispatched jobs apply equal jitter to ordinary retry delays.
+	 */
+	retryJitter?: boolean;
+	/**
+	 * Default polling interval, in milliseconds, for long-running workers.
+	 */
+	workerIntervalMs?: number;
+	/**
+	 * Maximum number of jobs a worker should process during one polling tick.
+	 */
+	maxJobsPerTick?: number;
+	/**
+	 * Enables or disables worker startup unless startWorker() is called with force.
+	 */
+	workerEnabled?: boolean;
+	/**
+	 * Configures queue lifecycle telemetry for development panels and tests.
+	 */
+	queueMonitor?: false | QueueMonitorOptions;
+	/**
+	 * Reports isolated lifecycle listener and QueueableJob hook failures.
+	 */
+	onLifecycleError?: QueueLifecycleErrorHandler;
+	/**
+	 * Lazily resolves a QueueableJob class when a worker sees an unknown job name.
+	 */
+	jobResolver?: QueueJobResolver;
+}
+
+/**
+ * Hooks for observing a single job processing attempt.
+ */
+export interface QueueWorkOptions {
+	/**
+	 * Called after a driver claims a job and before the registered handler runs.
+	 */
+	onClaimed?(job: QueueJob): void;
+}
+
+/**
+ * Public queue service API used by application code and queueable jobs.
+ */
+export interface QueueService {
+	/**
+	 * Always-on asynchronous queue lifecycle event dispatcher.
+	 */
+	readonly events: QueueEvents;
+
+	/**
+	 * Queue lifecycle monitor attached to this service, when enabled.
+	 */
+	readonly queueMonitor: QueueMonitor | null;
+
+	/**
+	 * Returns recent terminal failures from driver-owned persistence.
+	 *
+	 * @param limit - Maximum number of recent failed jobs to return.
+	 * @returns Recent failed jobs ordered from newest to oldest.
+	 */
+	failedJobs(limit?: number): Promise<QueueFailedJob[]>;
+
+	/**
+	 * Replays one persisted terminal failure as a new active queue job.
+	 *
+	 * The original failure remains available for audit and the replacement job
+	 * receives a new UUID linked back to that failed record.
+	 *
+	 * @param id - Driver-owned failed-job record id.
+	 * @param options - Optional queue, attempts, backoff, and delay overrides.
+	 * @returns Queue driver id for the replacement job.
+	 */
+	retryFailed(id: QueueJobId, options?: DispatchOptions): Promise<QueueJobId>;
+
+	/**
+	 * Registers an async handler for a named job payload.
+	 *
+	 * @param name - Durable queued job name.
+	 * @param handler - Handler invoked when a worker processes that job name.
+	 */
+	registerHandler<TData = Record<string, unknown>>(name: string, handler: JobHandler<TData>): void;
+
+	/**
+	 * Registers a queueable job class for worker rehydration.
+	 *
+	 * @param Job - Job class with JSON rehydration inherited from QueueableJob.
+	 */
+	registerJob<TJob extends QueueableJobClass>(Job: TJob): void;
+
+	/**
+	 * Dispatches a named job payload.
+	 *
+	 * @param job - Durable job name.
+	 * @param data - JSON-safe payload data.
+	 * @param options - Per-dispatch queue options.
+	 * @returns Queue driver id for the queued job.
+	 */
+	dispatch<TData extends Record<string, unknown>>(job: string, data: TData, options?: DispatchOptions): Promise<QueueJobId>;
+
+	/**
+	 * Dispatches a queueable job instance.
+	 *
+	 * @param job - Queueable job instance to serialize and dispatch.
+	 * @param options - Per-dispatch queue options.
+	 * @returns Queue driver id for the queued job.
+	 */
+	dispatch<TJob extends QueueableJob>(job: TJob, options?: DispatchOptions): Promise<QueueJobId>;
+
+	/**
+	 * Dispatches queueable jobs in order, one after each successful predecessor.
+	 *
+	 * @param jobs - Serializable jobs to chain.
+	 * @param options - Per-dispatch options for the first queued job.
+	 * @returns Queue driver id for the first queued job.
+	 */
+	chain(jobs: QueueableJob[], options?: DispatchOptions): Promise<QueueJobId>;
+
+	/**
+	 * Dispatches queueable jobs independently.
+	 *
+	 * @param jobs - Serializable jobs to dispatch.
+	 * @param options - Per-dispatch options applied to each job.
+	 * @returns Queue driver ids for the queued jobs.
+	 */
+	batch(jobs: QueueableJob[], options?: DispatchOptions): Promise<QueueJobId[]>;
+
+	/**
+	 * Processes at most one available job from a named queue.
+	 *
+	 * @param queue - Named queue/channel to process.
+	 * @returns True when a job was claimed and processed.
+	 */
+	processNextJob(queue?: string): Promise<boolean>;
+
+	/**
+	 * Processes at most one job and returns the detailed outcome.
+	 *
+	 * @param queue - Named queue/channel to process.
+	 * @param options - Per-work hooks for the processing attempt.
+	 * @returns Detailed result, or null when the queue was idle.
+	 */
+	workNextJob(queue?: string, options?: QueueWorkOptions): Promise<QueueProcessResult | null>;
+
+	/**
+	 * Starts a polling worker for a named queue.
+	 *
+	 * @param queue - Named queue/channel the worker should poll.
+	 * @param options - Worker lifecycle and polling options.
+	 * @returns Worker lifecycle controls, or null when worker startup is disabled.
+	 */
+	startWorker(queue?: string, options?: QueueWorkerOptions): QueueWorkerLifecycle | null;
+}

package/src/queue/contracts/QueueWorkerLifecycle.ts

@@ -0,0 +1,71 @@
+/**
+ * Minimal logger contract used by queue workers.
+ */
+export interface QueueLogger {
+	/**
+	 * Writes an informational queue worker message.
+	 *
+	 * @param message - Message ready for terminal or log output.
+	 */
+	info(message: string): void;
+
+	/**
+	 * Writes a warning queue worker message.
+	 *
+	 * @param message - Message ready for terminal or log output.
+	 */
+	warn?(message: string): void;
+
+	/**
+	 * Writes an error queue worker message.
+	 *
+	 * @param message - Message ready for terminal or log output.
+	 */
+	error?(message: string): void;
+}
+
+/**
+ * Runtime controls for a polling queue worker.
+ */
+export interface QueueWorkerOptions {
+	/**
+	 * Number of milliseconds between worker ticks.
+	 */
+	intervalMs?: number;
+	/**
+	 * Maximum number of jobs to process during each tick.
+	 */
+	maxJobsPerTick?: number;
+	/**
+	 * Logger used for lifecycle and job processing messages.
+	 */
+	logger?: QueueLogger;
+	/**
+	 * Enables detailed lifecycle logging for idle ticks and queued follow-up work.
+	 */
+	verbose?: boolean;
+	/**
+	 * Starts the worker even when QUEUE_WORKER=false or workerEnabled is false.
+	 */
+	force?: boolean;
+}
+
+/**
+ * Public lifecycle controls for a long-running queue worker.
+ */
+export interface QueueWorkerLifecycle {
+	/**
+	 * Starts polling the configured queue.
+	 */
+	start(): void;
+
+	/**
+	 * Stops future polling ticks without aborting an active tick.
+	 */
+	stop(): void;
+
+	/**
+	 * Stops future polling and resolves after the active tick has completed.
+	 */
+	stopAndDrain(): Promise<void>;
+}

package/src/queue/contracts/QueueableJob.ts

@@ -0,0 +1,56 @@
+import type { Queue } from '../Queue';
+import type { QueueableJob } from '../QueueableJob';
+import type { QueueJob, SerializedQueuedJob } from './QueuePayload';
+
+/**
+ * Serialized queueable job payload stored before a driver wraps it in an envelope.
+ */
+export type SerializedQueueableJob<TData extends Record<string, unknown> = Record<string, unknown>> = SerializedQueuedJob<TData>;
+
+/**
+ * Queue runtime metadata passed to a rehydrated job.
+ */
+export interface QueueableJobContext {
+	/** Claimed queue job being handled. */
+	job: QueueJob;
+	/** Queue service that is processing this job. */
+	queue: Queue;
+}
+
+/**
+ * Context passed after a failed attempt has safely been released for retry.
+ */
+export interface QueueableJobRetryContext extends QueueableJobContext {
+	/** Error raised by the failed handler attempt. */
+	error: unknown;
+	/** Seconds before the released job becomes available again. */
+	delaySeconds: number;
+}
+
+/**
+ * Context passed after a job exhausts its attempts and is durably failed.
+ */
+export interface QueueableJobFailureContext extends QueueableJobContext {
+	/** Terminal error persisted by the queue driver. */
+	error: unknown;
+}
+
+/**
+ * Constructor contract for serializable queueable job classes.
+ */
+export interface QueueableJobClass<TJob extends QueueableJob = QueueableJob> {
+	/** Runtime class name used as the default durable job name. */
+	readonly name: string;
+	/** Optional durable job name override. */
+	readonly jobName?: string;
+	/** Creates a job from its application-facing runtime data. */
+	new(data: any): TJob;
+
+	/**
+	 * Rehydrates a queueable job instance from persisted payload data.
+	 *
+	 * @param data - JSON-safe data stored in the queue payload.
+	 * @returns Queueable job instance ready to handle.
+	 */
+	fromJSON(data: Record<string, unknown>): TJob;
+}

package/src/queue/contracts/RedisQueueDriver.ts

@@ -0,0 +1,37 @@
+/**
+ * Connection and key options for the Redis queue driver.
+ */
+export interface RedisQueueDriverOptions {
+	/**
+	 * Redis connection URL. When omitted, the driver reads QUEUE_REDIS_URL or REDIS_URL.
+	 */
+	url?: string;
+	/**
+	 * Redis host used when no URL is supplied.
+	 */
+	host?: string;
+	/**
+	 * Redis port used when no URL is supplied.
+	 */
+	port?: number;
+	/**
+	 * Redis username for ACL authentication.
+	 */
+	username?: string;
+	/**
+	 * Redis password for authentication.
+	 */
+	password?: string;
+	/**
+	 * Redis database index selected after connecting.
+	 */
+	database?: number;
+	/**
+	 * Prefix applied to every key owned by this queue driver.
+	 */
+	keyPrefix?: string;
+	/**
+	 * Milliseconds to wait before failing the Redis connection attempt.
+	 */
+	connectionTimeoutMs?: number;
+}

package/src/queue/contracts/index.ts

@@ -0,0 +1,9 @@
+export * from './QueueDriver';
+export * from './QueueEvents';
+export * from './QueuePayload';
+export * from './QueueRetry';
+export * from './QueueableJob';
+export * from './QueueService';
+export * from './QueueWorkerLifecycle';
+export * from './RedisQueueDriver';
+export * from './CreateJob';