ravenflow 0.3.0 → 0.4.0

package/dist/index.d.ts

@@ -1,673 +1,363 @@
-import { z } from 'zod';
-import { Job, Queue, QueueEvents, ConnectionOptions, Worker, WorkerOptions } from 'bullmq';
+import { Job, ConnectionOptions, Queue } from 'bullmq';
 import pino from 'pino';
-import { IndexSpecification, CreateIndexesOptions, Document, Collection, Db, AnyBulkWriteOperation } from 'mongodb';
+import { Db } from 'mongodb';
 
-interface BaseJobConfig {
-    queue?: string;
-    cron?: string;
-    attempts?: number;
-    backoff?: {
-        type: "fixed" | "exponential";
-        delay: number;
-    };
-}
-declare const zRateLimitConfig: z.ZodUnion<readonly [z.ZodObject<{
-    perSecond: z.ZodNumber;
-}, z.core.$strip>, z.ZodObject<{
-    perMinute: z.ZodNumber;
-}, z.core.$strip>]>;
-type RateLimitConfig = z.infer<typeof zRateLimitConfig>;
-interface MemoryEtlStepConfig {
-    rateLimit?: RateLimitConfig;
-}
-interface StepConfig extends MemoryEtlStepConfig {
-    attempts?: number;
-    backoff?: {
-        type: "fixed" | "exponential";
-        delay: number;
-    };
-    queue?: string;
+declare const CONTINUATION: unique symbol;
+interface Continuation<TPayload> {
+    readonly [CONTINUATION]: true;
+    readonly params: TPayload;
+    readonly delayMs?: number;
+    readonly deduplicationId?: string;
 }
-interface EtlExtractResult<TRaw, TCursor> {
-    data: TRaw[];
-    cursor: TCursor | null;
-    hasMore: boolean;
-}
-declare const zJobStatus: z.ZodEnum<{
-    pending: "pending";
-    in_progress: "in_progress";
-    completed: "completed";
-    failed: "failed";
-    stalled: "stalled";
-}>;
-type JobStatus = z.infer<typeof zJobStatus>;
-
-interface SimpleJobConfig<TData, TReturn> extends BaseJobConfig {
-    type: "simple";
-    handler: (job: Job, params: TData) => Promise<TReturn>;
+interface ContinueOptions {
+    delayMs?: number;
+    deduplicationId?: string;
 }
-declare function defineSimpleJob<TData, TReturn>(config: Omit<SimpleJobConfig<TData, TReturn>, "type">): SimpleJobConfig<TData, TReturn>;
 
-interface MemoryEtlJobConfig<TRaw, TProcessed, TCursor = number> extends BaseJobConfig {
-    type: "memory-etl";
-    extract: (cursor: TCursor | null) => Promise<EtlExtractResult<TRaw, TCursor>>;
-    transform: (data: TRaw) => Promise<TProcessed>;
-    load: (data: TProcessed[]) => Promise<void>;
-    steps?: {
-        extract?: MemoryEtlStepConfig;
-        transform?: MemoryEtlStepConfig;
-        load?: MemoryEtlStepConfig;
-    };
-}
-declare function defineMemoryEtlJob<TRaw, TProcessed, TCursor = number>(config: Omit<MemoryEtlJobConfig<TRaw, TProcessed, TCursor>, "type">): MemoryEtlJobConfig<TRaw, TProcessed, TCursor>;
+type Logger = pino.Logger;
+interface LoggerOptions {
+    level?: "trace" | "debug" | "info" | "warn" | "error" | "fatal";
+    pretty?: boolean;
+}
 
-interface DistributedEtlJobConfig<TRaw, TProcessed, TCursor = number> extends BaseJobConfig {
-    type: "distributed-etl";
-    extract: (cursor: TCursor | null) => Promise<EtlExtractResult<TRaw, TCursor>>;
-    transform: (data: TRaw) => Promise<TProcessed>;
-    load: (data: TProcessed[]) => Promise<void>;
-    steps?: {
-        extract?: StepConfig;
-        transform?: StepConfig;
-        load?: StepConfig;
-    };
-}
-declare function defineDistributedEtlJob<TRaw, TProcessed, TCursor = number>(config: Omit<DistributedEtlJobConfig<TRaw, TProcessed, TCursor>, "type">): DistributedEtlJobConfig<TRaw, TProcessed, TCursor>;
+interface JobContext<TParams> {
+    params: TParams;
+    deduplicationId?: string;
+    continueWith(params: TParams, options?: ContinueOptions): Continuation<TParams>;
+    job: Job;
+    logger: Logger;
+    signal: AbortSignal;
+}
 
-interface StatefulEtlJobConfig<TRaw, TProcessed, TCursor = string> extends BaseJobConfig {
-    type: "stateful-etl";
-    extract: (cursor: TCursor | null) => Promise<EtlExtractResult<TRaw, TCursor>>;
-    transform: (data: TRaw) => Promise<TProcessed>;
-    load: (data: TProcessed[]) => Promise<void>;
-    /**
-     * When true, only one run of this job can be active at a time.
-     * If a run is already pending or in_progress (with a live heartbeat), the new trigger is skipped.
-     * Defaults to false — each trigger creates an independent run.
-     */
-    singletonRun?: boolean;
-    stallTimeoutMs?: number;
-    maxStallRetries?: number;
-    steps?: {
-        extract?: StepConfig;
-        transform?: StepConfig;
-        load?: StepConfig;
-    };
-}
-declare function defineStatefulEtlJob<TRaw, TProcessed, TCursor = string>(config: Omit<StatefulEtlJobConfig<TRaw, TProcessed, TCursor>, "type">): StatefulEtlJobConfig<TRaw, TProcessed, TCursor>;
+interface BackoffPolicy {
+    type: "fixed" | "exponential";
+    delayMs: number;
+    jitter?: number;
+}
+type DeduplicatePolicy<TPayload> = true | ((params: TPayload) => string);
+type PacePolicy = {
+    perSecond: number;
+    perMinute?: never;
+    perHour?: never;
+} | {
+    perMinute: number;
+    perSecond?: never;
+    perHour?: never;
+} | {
+    perHour: number;
+    perSecond?: never;
+    perMinute?: never;
+};
 
-type TokenBucketInterval = "second" | "minute" | "hour" | "day" | "week";
-interface TokenBucketJobConfig extends BaseJobConfig {
-    type: "token-bucket";
+type JobTrigger = CronTrigger | SpoolTriggerDeclaration;
+interface CronTrigger {
     cron: string;
-    rate?: {
-        amount: number;
-        interval: TokenBucketInterval;
-    };
-    getBudget?: () => Promise<number> | number;
-    maxCarryOver?: number;
-    consumeTimeout?: number;
-    consume: (tokens: number) => Promise<number | void> | number | void;
-}
-declare function defineTokenBucketJob(config: Omit<TokenBucketJobConfig, "type">): TokenBucketJobConfig;
+    spool?: never;
+}
+interface SpoolTriggerDeclaration {
+    spool: SpoolTrigger;
+    cron?: never;
+}
+interface SpoolTrigger {
+    name: string;
+    tickMs?: number;
+    canPull?: () => boolean | Promise<boolean>;
+    expireUnclaimedAfterMs?: number;
+}
+interface DeclaredTrigger {
+    cron?: string;
+    spool?: SpoolTrigger;
+}
 
-type JobConfig = SimpleJobConfig<any, any> | MemoryEtlJobConfig<any, any, any> | DistributedEtlJobConfig<any, any, any> | StatefulEtlJobConfig<any, any, any> | TokenBucketJobConfig;
+type TriggerFor<TPayload> = SatisfiableByNothing<TPayload> extends true ? JobTrigger : SpoolTriggerDeclaration | CronRefused;
+type CronTriggerFor<TPayload> = SatisfiableByNothing<TPayload> extends true ? CronTrigger : CronRefused;
+type SatisfiableByNothing<TPayload> = AcceptsUndefined<TPayload> extends true ? true : AcceptsEmptyObject<TPayload>;
+type AcceptsUndefined<TPayload> = undefined extends TPayload ? true : false;
+type AcceptsEmptyObject<TPayload> = {} extends TPayload ? true : false;
+interface CronRefused {
+    cron?: CronNeedsAPayloadNothingHasToProvide;
+    spool?: never;
+}
+type CronNeedsAPayloadNothingHasToProvide = "a cron trigger has nothing to pass this job: make every field of its payload optional, or declare the payload as void";
 
-interface RetentionConfig {
-    /** Number of completed jobs to keep per queue. Set to 0 to remove immediately. */
-    completed?: number;
-    /** Number of failed jobs to keep per queue. Set to 0 to remove immediately. */
-    failed?: number;
+interface JobDefinition<TPayload, TResult> {
+    queue?: string;
+    attempts?: number;
+    backoff?: BackoffPolicy;
+    trigger?: TriggerFor<TPayload>;
+    deduplicate?: DeduplicatePolicy<TPayload>;
+    pace?: PacePolicy;
+    handler: JobHandler<TPayload, TResult>;
+}
+type JobHandler<TPayload, TResult> = (ctx: JobContext<TPayload>) => Promise<TResult | Continuation<TPayload>>;
+type SpoolFedJob<TPayload, TResult> = JobDefinition<TPayload, TResult> & {
+    trigger: SpoolTriggerDeclaration;
+    pace: PacePolicy;
+};
+type ClockFedJob<TPayload, TResult> = JobDefinition<TPayload, TResult> & {
+    trigger: CronTrigger;
+};
+declare function defineJob<TPayload, TResult>(definition: JobDefinitionWith<SpoolTriggerDeclaration, TPayload, TResult> & {
+    pace: PacePolicy;
+}): SpoolFedJob<TPayload, TResult>;
+declare function defineJob<TPayload, TResult>(definition: JobDefinitionWith<CronTriggerFor<TPayload>, TPayload, TResult>): ClockFedJob<TPayload, TResult>;
+declare function defineJob<TPayload, TResult>(definition: UnspooledJobDefinition<TPayload, TResult>): JobDefinition<TPayload, TResult>;
+type JobDefinitionWith<TTrigger, TPayload, TResult> = Omit<JobDefinition<TPayload, TResult>, "trigger"> & {
+    trigger: TTrigger;
+};
+type UnspooledJobDefinition<TPayload, TResult> = Omit<JobDefinition<TPayload, TResult>, "trigger"> & {
+    trigger?: CronTriggerFor<TPayload>;
+};
+
+interface AnyJob {
+    queue?: string;
+    attempts?: number;
+    backoff?: BackoffPolicy;
+    trigger?: DeclaredTrigger;
+    deduplicate?: DeduplicatePolicy<never>;
+    pace?: PacePolicy;
+    handler: (ctx: JobContext<never>) => Promise<unknown>;
 }
+
 interface RavenflowConfig<TJobs extends string = string> {
     defaultQueue: string;
-    jobs: Record<TJobs, JobConfig>;
+    jobs: Record<TJobs, AnyJob>;
+    logger?: LoggerOptions;
+    queuesRetention?: QueuesRetentionConfig;
+    jobResultsRetentionHours?: number;
+    aggregatedResultsRetentionHours?: number;
+}
+interface QueuesRetentionConfig {
+    completedCount?: number;
+    failedCount?: number;
 }
-type JobNames<T extends RavenflowConfig> = T extends RavenflowConfig<infer TJobs> ? TJobs : never;
 declare function defineConfig<const T extends RavenflowConfig>(config: T): T;
 
-interface EtlResult {
-    extractedCount: number;
-    transformedCount: number;
-    loadedCount: number;
-}
-type JobProxy<T extends JobConfig> = T extends SimpleJobConfig<infer TData, infer TReturn> ? {
-    send: (params: TData) => Promise<Job<TData, TReturn>>;
-    sendAndWait: (params: TData) => Promise<TReturn>;
-} : T extends MemoryEtlJobConfig<any, any, any> ? {
-    send: () => Promise<void>;
-    sendAndWait: () => Promise<EtlResult>;
-} : T extends DistributedEtlJobConfig<any, any> ? {
-    send: () => Promise<void>;
-    sendAndWait: () => Promise<EtlResult>;
-} : T extends StatefulEtlJobConfig<any, any, any> ? {
-    send: () => Promise<void>;
-    sendAndWait: () => Promise<void>;
-} : T extends TokenBucketJobConfig ? {
-    send: () => Promise<void>;
-    sendAndWait: () => Promise<void>;
-} : never;
-type JobsProxy<TJobs extends Record<string, JobConfig>> = {
-    [K in keyof TJobs]: JobProxy<TJobs[K]>;
-};
-
-type Logger = pino.Logger;
-interface LoggerOptions {
-    level?: "trace" | "debug" | "info" | "warn" | "error" | "fatal";
-    pretty?: boolean;
+declare class MongoConnection {
+    private readonly uri;
+    private client;
+    private database;
+    private connecting;
+    constructor(uri: string);
+    connect(): Promise<Db>;
+    close(): Promise<void>;
+    private openTheDatabase;
+    private forgetTheAttempt;
 }
-declare function initLogger(options?: LoggerOptions): Logger;
-declare function getLogger(): Logger;
 
-type QueueStore = Record<string, {
-    queue: Queue;
-    events: QueueEvents;
-}>;
+type ControlKey = `job:${string}`;
 
-declare class StallWatcher {
-    private readonly workerQueue;
-    private readonly statefulEtlConfigs;
-    private readonly userQueues;
-    constructor(jobConfigs: Record<string, JobConfig>, userQueues: Record<string, {
-        queue: Queue;
-    }>, defaultQueue: string, workerQueue: Queue);
-    canProcess(jobName: string): boolean;
-    start(): Promise<void>;
-    stop(): Promise<void>;
-    process(job: Job): Promise<void>;
+interface ControlPublisher {
+    publish(key: ControlKey): Promise<void>;
+}
+declare class ControlChannel implements ControlPublisher {
+    private readonly connection;
+    private readonly logger;
+    private publisher;
+    private subscriber;
+    constructor(connection: ConnectionOptions, logger: Logger);
+    publish(key: ControlKey): Promise<void>;
+    subscribe(onInvalidate: (key: ControlKey) => void): Promise<void>;
+    close(): Promise<void>;
+    private deliver;
+    private listenOn;
+    private open;
 }
 
-interface IndexDescriptor {
-    keys: IndexSpecification;
-    options?: CreateIndexesOptions;
-}
-type BucketGranularity = "hour" | "day";
-interface IncrementStatsInput {
-    success: boolean;
-    durationMs?: number;
-}
-interface JobStatsDoc {
-    jobType: string;
-    bucketStart: Date;
-    granularity: BucketGranularity;
-    count: number;
-    success: number;
-    failed: number;
-    totalDurationMs: number;
-    createdAt: Date;
-    updatedAt: Date;
-}
-interface JobErrorDoc {
-    signature: string;
-    jobType: string;
-    message: string;
-    stack: string;
-    count: number;
-    firstSeenAt: Date;
-    lastSeenAt: Date;
-    createdAt: Date;
-    updatedAt: Date;
-    /** Normalized `Error.cause` chain beyond the top-level error. OMITTED when empty. */
-    causeChain?: Array<{
-        message: string;
-        name: string;
-    }>;
-}
-interface RecordOccurrenceInput {
-    jobType: string;
-    error: unknown;
-}
-interface TopErrorsOptions {
-    limit: number;
-    jobType?: string;
-    /**
-     * When set, restricts results to errors whose `lastSeenAt >= since`.
-     * Dashboard health views pass the range start (e.g. 7 days ago, UTC midnight)
-     * so "top errors" matches the displayed range; omitting returns all errors
-     * back to the collection's 90-day TTL boundary.
-     */
-    since?: Date;
-}
-interface JobFailureDoc {
-    jobId: string;
-    jobType: string;
-    input: string;
-    errorMessage: string;
-    errorStack: string;
-    logs: string;
-    failedAt: Date;
-    createdAt: Date;
-    /** Normalized `Error.cause` chain beyond the top-level error. OMITTED when empty. */
-    causeChain?: Array<{
-        message: string;
-        name: string;
-    }>;
-}
-interface RecordFailureInput {
-    jobId: string;
-    jobType: string;
-    input: unknown;
-    error: unknown;
-    failedAt: Date;
-    logs?: string;
-}
-interface ListFailuresOptions {
-    jobType?: string;
-    fromDate?: Date | null;
-    toDate?: Date | null;
-    skip?: number;
-    limit?: number;
-}
-declare const JOB_FAILURES_INPUT_MAX_CHARS = 100000;
-declare const JOB_FAILURES_MESSAGE_MAX_CHARS = 2000;
-declare const JOB_FAILURES_STACK_MAX_CHARS = 8000;
-declare const JOB_FAILURES_LOGS_MAX_CHARS = 500000;
-interface WorkerQueueEntry {
-    name: string;
-    concurrency: number;
-}
-interface WorkerDoc {
-    workerId: string;
-    hostname: string;
-    pid: number;
-    queues: WorkerQueueEntry[];
-    startedAt: Date;
-    lastHeartbeatAt: Date;
-    createdAt: Date;
-    updatedAt: Date;
+declare const LEVERS: readonly ["executionPaused", "triggerPaused", "ingestPaused"];
+type Lever = (typeof LEVERS)[number];
+type JobControls = Record<Lever, boolean>;
+
+interface ControlReads {
+    read(jobName: string): Promise<JobControls>;
 }
-interface RegisterWorkerInput {
-    workerId: string;
-    hostname: string;
-    pid: number;
-    queues: WorkerQueueEntry[];
-    startedAt: Date;
-}
-interface UpsertWorkerQueueInput {
-    workerId: string;
-    queue: WorkerQueueEntry;
-}
-/**
- * Read shape for the `job_configs` collection — what `JobConfigsRepo.getConfig`
- * returns (with persistence timestamps stripped, or synthesized for absent records).
- *
- * Distinct from `JobConfig` (in `src/types/job/unions.ts`), which is the discriminated
- * union of job-definition types (simple / memory-etl / distributed-etl / etc.) used
- * at app-registration time. `JobConfigEntry` is the runtime persistence shape for
- * dashboard-managed per-job-type settings (enabled flag + free-form metadata).
- */
-interface JobConfigEntry {
-    jobType: string;
-    enabled: boolean;
-    metadata: Record<string, unknown>;
-}
-/**
- * Persisted shape for the `job_configs` collection — the read shape plus
- * MongoDB-managed timestamps. Returned by `JobConfigsRepo.listAll` (every row
- * there is, by definition, persisted, so the timestamps are always real).
- */
-interface JobConfigDoc extends JobConfigEntry {
-    createdAt: Date;
-    updatedAt: Date;
+interface JobControlPlane extends ControlReads {
+    write(jobName: string, patch: Partial<JobControls>): Promise<void>;
 }
 
-declare abstract class Repository<T extends Document> {
-    readonly collection: Collection<T>;
-    constructor(db: Db, rawCollectionName: string);
-    protected abstract indexes(): IndexDescriptor[];
-    init(): Promise<void>;
+interface LeverEntry {
+    key: ControlKey;
+    lever: Lever;
+    value: string;
+}
+interface StoredLever {
+    jobName: string;
+    lever: Lever;
+    value: string;
+}
+declare class ControlHash {
+    private readonly options;
+    private readonly logger;
+    private connection;
+    constructor(options: ConnectionOptions, logger: Logger);
+    readLevers(key: ControlKey): Promise<Map<Lever, string>>;
+    readEveryLever(): Promise<StoredLever[]>;
+    write(entry: LeverEntry): Promise<void>;
+    writeIfAbsent(entry: LeverEntry): Promise<boolean>;
+    close(): Promise<void>;
+    private get redis();
 }
 
-declare class WorkersRepo extends Repository<WorkerDoc> {
-    constructor(db: Db);
-    protected indexes(): IndexDescriptor[];
-    registerWorker(input: RegisterWorkerInput): Promise<void>;
-    updateHeartbeat(workerId: string): Promise<void>;
-    /**
-     * Appends or replaces a queue entry on the worker's record.
-     *
-     * Single-writer invariant: this method is NOT atomic under concurrent writers to the
-     * SAME `workerId`. WorkerRegistry is a process-local singleton, and `workerId` is
-     * unique per process by contract (default: `<hostname>:<pid>:<uuid>`). Sharing a
-     * stable `workerId` across processes violates AC #6 and will race last-writer-wins.
-     */
-    addQueue(input: UpsertWorkerQueueInput): Promise<void>;
-    deregisterWorker(workerId: string): Promise<void>;
-    findAlive(maxHeartbeatAgeMs: number): Promise<WorkerDoc[]>;
-    cleanupStale(maxHeartbeatAgeMs: number): Promise<number>;
-    private validateRegisterInput;
-    private validateQueueEntry;
-    private validateMaxHeartbeatAgeMs;
+interface MirroredControls extends Partial<JobControls> {
+    _id: string;
+    updatedAt: Date;
 }
-
-declare class JobStatsRepo extends Repository<JobStatsDoc> {
-    constructor(db: Db);
-    protected indexes(): IndexDescriptor[];
-    /**
-     * Builds the bulk write operations for a stats increment WITHOUT executing them.
-     * Returns TWO ops — one for the hour bucket, one for the day bucket — matching
-     * `incrementStats`'s direct-call shape bit-for-bit. Intended to be pushed through
-     * a `BatchWriter` by the event-hooks layer (Story 1.7). Throws synchronously on
-     * invalid `durationMs`; otherwise no side effects.
-     *
-     * NOTE: `now` is captured at builder invocation time, NOT at BatchWriter flush
-     * time — `createdAt`, `updatedAt`, and `bucketStart` all reflect the event's
-     * wall-clock, not the flush wall-clock. Aggregations are therefore correctly
-     * attributed to the hour/day the event occurred, even if the batch flush is
-     * delayed by the buffer timer.
-     */
-    toIncrementStatsOps(jobType: string, input: IncrementStatsInput): AnyBulkWriteOperation<JobStatsDoc>[];
-    incrementStats(jobType: string, input: IncrementStatsInput): Promise<void>;
-    getStats(jobType: string, fromDate: Date, toDate: Date, granularity: BucketGranularity): Promise<JobStatsDoc[]>;
-    /**
-     * Fetches every stats document in the given range + granularity, across ALL
-     * jobTypes. Intended for dashboard views that need a cross-jobType overview
-     * (e.g., "7-day health per job type") without a prior enumeration step.
-     *
-     * Result order: `bucketStart` ascending, then `jobType` ascending. Caller is
-     * responsible for grouping by jobType client-side if desired.
-     *
-     * Applies the same `MAX_GET_STATS_RESULTS` cap as `getStats` — a single query
-     * across all jobTypes × buckets × granularity is bounded, but the cap keeps
-     * the method safe under accidental wide-range queries.
-     */
-    getStatsAllJobTypes(fromDate: Date, toDate: Date, granularity: BucketGranularity): Promise<JobStatsDoc[]>;
-    private upsertBucket;
-    private buildBucketOp;
-    private buildBucketPayload;
-    private validateDurationMs;
+interface ControlMirror {
+    mirrorJobControls(jobName: string, patch: Partial<JobControls>): Promise<void>;
+    listAll(): Promise<MirroredControls[]>;
 }
 
-declare class JobErrorsRepo extends Repository<JobErrorDoc> {
-    constructor(db: Db);
-    protected indexes(): IndexDescriptor[];
-    /**
-     * Records one occurrence of an error, deduplicated by its stable signature.
-     *
-     * Invariant: `jobType` is set **only on insert** (`$setOnInsert`). Once a signature
-     * is first observed under jobType A, subsequent occurrences under jobType B do NOT
-     * overwrite the stored value. The signature is the identity of the error; a signature
-     * appearing across multiple job types indicates shared infrastructure failure (e.g.
-     * ECONNRESET from the shared DB) and is worth surfacing on the first-observed job.
-     */
-    recordOccurrence(input: RecordOccurrenceInput): Promise<void>;
-    /**
-     * Builds the bulk write operation for `recordOccurrence` WITHOUT executing it.
-     * Returns a single upsert op matching the direct-call shape bit-for-bit.
-     *
-     * NOTE: `now` is captured at builder invocation time, NOT at BatchWriter flush
-     * time — firstSeenAt / lastSeenAt reflect the event's wall-clock, not the
-     * flush wall-clock. This preserves the semantic that these timestamps track
-     * the error's occurrence, not the observability pipeline's delay.
-     */
-    toRecordOccurrenceOp(input: RecordOccurrenceInput): AnyBulkWriteOperation<JobErrorDoc>;
-    private buildRecordOccurrencePayload;
-    topErrors(options: TopErrorsOptions): Promise<JobErrorDoc[]>;
-}
+type LiveControls = Map<string, JobControls>;
 
-declare class JobFailuresRepo extends Repository<JobFailureDoc> {
-    constructor(db: Db);
-    protected indexes(): IndexDescriptor[];
-    recordFailure(input: RecordFailureInput): Promise<void>;
-    /**
-     * Builds the bulk write operation for `recordFailure` WITHOUT executing it.
-     * Returns a single insertOne op matching the direct-call document shape
-     * bit-for-bit. Intended for the event-hooks layer (Story 1.7) to push through
-     * a `BatchWriter`. Throws synchronously on invalid input using the same error
-     * messages as `recordFailure`.
-     */
-    toRecordFailureOp(input: RecordFailureInput): AnyBulkWriteOperation<JobFailureDoc>;
-    private buildFailureDoc;
-    private validateFailureInput;
-    listFailures(options: ListFailuresOptions): Promise<{
-        items: JobFailureDoc[];
-        total: number;
-    }>;
-    getFailure(jobId: string): Promise<JobFailureDoc | null>;
-    private serializeInputValue;
-    private capLogs;
+interface RehydrationReport {
+    restored: number;
+    alreadyLive: number;
+    truncated: boolean;
 }
 
-declare class JobConfigsRepo extends Repository<JobConfigDoc> {
-    constructor(db: Db);
-    protected indexes(): IndexDescriptor[];
-    getConfig(jobType: string): Promise<JobConfigEntry>;
-    setEnabled(jobType: string, enabled: boolean): Promise<void>;
-    listAll(): Promise<JobConfigDoc[]>;
-    isEnabled(jobType: string): Promise<boolean>;
-    /**
-     * Idempotent bulk upsert of every registered jobType + its metadata
-     * projection (Story 5.1 D5.1-a). Called once per `RavenflowApp` instance
-     * inside `initializeMonitoring()`.
-     *
-     * Semantics:
-     *   - `$setOnInsert { enabled: true, createdAt }` — the enabled flag is
-     *     set to the default ONLY on initial insert. An operator-toggled
-     *     `enabled: false` is NEVER overwritten by a subsequent boot.
-     *   - `$set { metadata }` — metadata is always refreshed from code config
-     *     (code is source of truth for non-user-writable fields).
-     *   - `$currentDate { updatedAt }` — timestamp bumps every call.
-     *
-     * Metadata projection (narrow + stable — see D5.1-h):
-     *   - `type`: jobConfig.type (always present in the discriminated union).
-     *   - `queue`: jobConfig.queue ?? null (null = inherits defaultQueue).
-     *   - `cron`: jobConfig.cron if present (token-bucket only today), else null.
-     *
-     * Additional type-specific fields (token-bucket's `rate`, distributed-etl's
-     * `steps`) are NOT extracted — BSON can't serialize the function references
-     * they contain, and the dashboard surface consumes only `type`/`queue`/`cron`
-     * in V1. Future stories can widen this projection without a schema change.
-     *
-     * Failure mode: `bulkWrite` is the only I/O. Empty input short-circuits
-     * because the driver rejects empty ops arrays.
-     */
-    ensureEntries(jobs: Record<string, JobConfig>): Promise<void>;
-    private validateJobType;
+interface ControlStoreParts {
+    hash: ControlHash;
+    publisher: ControlPublisher;
+    mirror: ControlMirror;
+    logger: Logger;
+}
+declare class ControlStore implements JobControlPlane {
+    private readonly parts;
+    constructor(parts: ControlStoreParts);
+    read(jobName: string): Promise<JobControls>;
+    write(jobName: string, patch: Partial<JobControls>): Promise<void>;
+    readAll(): Promise<LiveControls>;
+    rehydrate(): Promise<RehydrationReport>;
+    close(): Promise<void>;
+    private isPulled;
+    private writeLevers;
+    private announce;
+    private writeMirror;
 }
 
-interface WorkerRegistryOptions {
-    heartbeatIntervalMs?: number;
-    /** @internal Injected for testability; real callers should rely on the default. */
-    hostnameProvider?: () => string;
-    /** @internal Injected for testability; real callers should rely on the default. */
-    pidProvider?: () => number;
-    /** @internal Injected for testability; real callers should rely on the default. */
-    workerIdProvider?: () => string;
-    /** @internal Injected for testability; real callers should rely on the default. */
-    clock?: () => Date;
-}
-declare class WorkerRegistry {
-    private readonly repo;
-    private readonly heartbeatIntervalMs;
-    private readonly hostname;
-    private readonly pid;
-    private readonly _workerId;
-    private readonly startedAt;
-    private readonly clock;
-    private timer;
-    private started;
-    private registered;
-    constructor(repo: WorkersRepo, options?: WorkerRegistryOptions);
-    get workerId(): string;
-    registerQueue(queue: WorkerQueueEntry): Promise<void>;
-    start(): Promise<void>;
-    stop(): Promise<void>;
-    private doHeartbeat;
-    private static validateHeartbeatInterval;
-    private static validateQueueEntry;
+declare class ControlPlane implements JobControlPlane {
+    private readonly parts;
+    private readonly cache;
+    constructor(parts: {
+        store: ControlStore;
+        channel: ControlChannel;
+        logger: Logger;
+    });
+    read(jobName: string): Promise<JobControls>;
+    write(jobName: string, patch: Partial<JobControls>): Promise<void>;
+    rehydrate(): Promise<void>;
+    close(): Promise<void>;
+    private closeQuietly;
 }
 
-interface BatchWriterConfig {
-    /** Max ops buffered before a size-triggered flush. Must be in [1000, 5000]. */
-    maxBufferSize: number;
-    /** Interval between time-triggered flushes in ms. Default 30000. Also used as `maxTimeMS` on bulkWrite. */
-    flushIntervalMs?: number;
+type QueuesByName = Record<string, Queue>;
+
+interface SpoolPurgeReport {
+    dropped: number;
+    inFlight: number;
 }
 
-declare class BatchWriter<T extends Document = Document> {
-    private readonly collection;
-    private readonly maxBufferSize;
-    private readonly hardCapSize;
-    private readonly flushIntervalMs;
-    private buffer;
-    private timer;
-    private flushing;
-    private drained;
-    constructor(collection: Collection<T>, config: BatchWriterConfig);
-    push(operation: AnyBulkWriteOperation<T>): void;
-    drain(): Promise<void>;
-    private flush;
-    private doFlush;
-    private enforceHardCap;
-    private startTimer;
-    private stopTimer;
-    private resetTimer;
-    private validateConfig;
+type JobsProxy<TJobs extends Record<string, AnyJob>> = {
+    [K in keyof TJobs]: JobProxy<TJobs[K]>;
+};
+type JobProxy<T extends AnyJob> = T extends JobDefinition<infer TPayload, infer TResult> ? SendOrIngest<T, TPayload, TResult> & {
+    controls: ControlsOf<T>;
+} : never;
+type SendOrIngest<T extends AnyJob, TPayload, TResult> = T extends {
+    trigger: SpoolTriggerDeclaration;
+} ? SpoolIngest<TPayload> : JobSend<TPayload, TResult>;
+interface JobSend<TPayload, TResult> {
+    send(params: TPayload, options?: SendOptions): Promise<Job<TPayload, TResult>>;
+}
+interface SendOptions {
+    delayMs?: number;
+    priority?: number;
+    deduplicationId?: string;
+}
+interface SpoolIngest<TItem> {
+    push(item: TItem): Promise<string>;
+    pushMany(items: TItem[]): Promise<string[]>;
+}
+type ControlsOf<T extends AnyJob> = T extends {
+    trigger: SpoolTriggerDeclaration;
+} ? SpoolFedControls : T extends {
+    trigger: CronTrigger;
+} ? ClockFedControls : ExecutionControls;
+interface ExecutionControls {
+    pauseExecution(): Promise<void>;
+    resumeExecution(): Promise<void>;
+}
+interface TriggerControls {
+    pauseTrigger(): Promise<void>;
+    resumeTrigger(): Promise<void>;
+}
+interface IngestControls {
+    pauseIngest(): Promise<void>;
+    resumeIngest(): Promise<void>;
+}
+interface ClockFedControls extends ExecutionControls, TriggerControls {
+}
+interface SpoolFedControls extends ExecutionControls, TriggerControls, IngestControls {
+    purgeBacklog(): Promise<SpoolPurgeReport>;
 }
 
-interface MongoConnectionObject {
-    host: string;
-    port?: number;
-    username?: string;
-    password?: string;
-    database?: string;
-}
-interface RavenflowAppOptions {
-    redis: ConnectionOptions;
-    mongo?: string | MongoConnectionObject;
-    retention?: RetentionConfig;
-    logger?: LoggerOptions;
-    monitoring?: {
-        enabled?: boolean;
-        heartbeatIntervalMs?: number;
-        batchWriter?: {
-            maxBufferSize?: number;
-            flushIntervalMs?: number;
-        };
-    };
-}
-declare class RavenflowApp<TConfig extends RavenflowConfig = RavenflowConfig> {
-    protected redisConnection: ConnectionOptions;
-    protected defaultConcurrency: number;
-    protected config: TConfig;
-    protected mongoUri: string | null;
-    jobs: JobsProxy<TConfig["jobs"]>;
-    protected jobConfigs: Record<JobNames<TConfig>, JobConfig>;
-    protected queues: QueueStore;
-    protected workers: Worker[];
-    protected stallWatcher: StallWatcher | null;
-    protected workersRepo: WorkersRepo | null;
-    protected workerRegistry: WorkerRegistry | null;
-    protected jobStatsRepo: JobStatsRepo | null;
-    protected jobErrorsRepo: JobErrorsRepo | null;
-    protected jobFailuresRepo: JobFailuresRepo | null;
-    protected jobConfigsRepo: JobConfigsRepo | null;
-    protected jobStatsBatchWriter: BatchWriter<JobStatsDoc> | null;
-    protected jobErrorsBatchWriter: BatchWriter<JobErrorDoc> | null;
-    protected jobFailuresBatchWriter: BatchWriter<JobFailureDoc> | null;
-    protected monitoringInitPromise: Promise<void> | null;
-    protected readonly monitoringOptions: {
-        enabled: boolean;
-        heartbeatIntervalMs: number | undefined;
-        batchWriter: BatchWriterConfig;
-    };
-    constructor(config: TConfig, options: RavenflowAppOptions);
-    startWorker(queueName: string, options?: {
-        concurrency?: number;
-    }): Promise<void>;
-    protected initializeMonitoring(queueName: string, concurrency: number): Promise<void>;
+declare class RavenflowClient<TConfig extends RavenflowConfig = RavenflowConfig> {
+    readonly jobs: JobsProxy<TConfig["jobs"]>;
+    protected readonly redisConnectionOptions: ConnectionOptions;
+    protected readonly mongoUri: string;
+    protected readonly mongo: MongoConnection;
+    protected readonly config: TConfig;
+    protected readonly controlPlane: ControlPlane;
+    protected readonly queues: QueuesByName;
+    protected readonly logger: Logger;
+    constructor(config: TConfig, options: {
+        redis: ConnectionOptions;
+        mongo: string;
+    });
     close(): Promise<void>;
 }
 
-declare function errorSignature(err: unknown): string;
-
-declare function captureJobLogs(queue: Queue, jobId: string, maxChars: number): Promise<string>;
+declare function createRavenflowClient<TConfig extends RavenflowConfig>(config: TConfig, options: ConstructorParameters<typeof RavenflowClient>[1]): RavenflowClient<TConfig>;
 
-interface EventHooksOptions {
-    queue: Queue;
-    jobConfigs: Record<string, JobConfig>;
-    jobStatsRepo: JobStatsRepo;
-    jobErrorsRepo: JobErrorsRepo;
-    jobFailuresRepo: JobFailuresRepo;
-    jobStatsBatchWriter: BatchWriter<JobStatsDoc>;
-    jobErrorsBatchWriter: BatchWriter<JobErrorDoc>;
-    jobFailuresBatchWriter: BatchWriter<JobFailureDoc>;
-    logsMaxChars?: number;
-}
-declare function attachEventHooks(worker: Worker, options: EventHooksOptions): void;
-
-/**
- * Inlined minute-count constants. Mirrors BullMQ's `MetricsTime` enum
- * (bullmq@5.63.1) but severs the import edge so consumers of this constant
- * don't pull BullMQ into their bundle. Values are pure math (minutes in
- * the named window) and therefore stable across BullMQ versions. Lives
- * here instead of `index.ts` to avoid an import cycle
- * (`index.ts` → `./app/index` → `./app/app` → `worker-manager`).
- */
-declare const METRICS_TIME: {
-    readonly ONE_MINUTE: 1;
-    readonly FIVE_MINUTES: 5;
-    readonly FIFTEEN_MINUTES: 15;
-    readonly THIRTY_MINUTES: 30;
-    readonly ONE_HOUR: 60;
-    readonly ONE_DAY: 1440;
-    readonly ONE_WEEK: 10080;
-    readonly TWO_WEEKS: 20160;
-    readonly ONE_MONTH: 80640;
-};
-/**
- * Default BullMQ metrics configuration applied to every ravenflow-managed
- * Worker. Enables the per-minute data-point collection read by the
- * ravenflow-dashboard Jobs-per-Second indicator (Epic 4 Story 4.2).
- *
- * Without this default, BullMQ's `collectMetrics` Lua function is a no-op on
- * every `moveToFinished` — `queue.getMetrics('completed')` would return
- * `{ meta: { count: 0 }, data: [] }` indefinitely for Ravenflow-managed
- * queues (silent false-negative under real throughput).
- *
- * `ONE_WEEK = 10_080` minutes ≈ 7 days of minute-resolution history at a
- * Redis footprint of ~10 KB/queue/week. Callers may override via the
- * `workerOpts.metrics` parameter on `createWorker` (e.g. to disable
- * collection or pick a shorter window).
- *
- * Frozen so the exported reference cannot be mutated by a caller (shared
- * default would otherwise bleed globally across `createWorker` calls).
- */
-declare const DEFAULT_WORKER_METRICS: NonNullable<WorkerOptions["metrics"]>;
-
-/**
- * Delay (ms) applied to jobs whose jobType is `enabled: false`. After this
- * window BullMQ returns the job to the `waiting` set and a worker picks it
- * up again; the gate re-evaluates. When the jobType re-enables the next
- * attempt passes the check and dispatches normally.
- *
- * 60 seconds strikes the balance between "pause takes effect quickly" and
- * "don't hammer Redis / Mongo with redefer churn" (D5.1-b).
- */
-declare const DISABLED_JOB_DEFER_DELAY_MS = 60000;
-/**
- * Worker-side defer gate for disabled jobTypes (Story 5.1 D5.1-b).
- *
- * When the jobType's `enabled` flag is `false` in `job_configs`, this
- * helper moves the job to `delayed` with a +60s timestamp, increments
- * the cumulative `disabledDeferCount` on `job.progress`, and throws
- * `DelayedError` — the BullMQ-canonical signal for "I moved this job to
- * delayed, don't mark completed/failed" (verified against
- * node_modules/bullmq/dist/esm/classes/errors/delayed-error.d.ts:9
- * bullmq@5.63.1).
- *
- * When the jobType is enabled (or no row exists — default is `true`),
- * this is a no-op and the caller proceeds to normal dispatch.
- *
- * The `token` argument is the processor lambda's 2nd BullMQ argument
- * (verified against node_modules/bullmq/dist/esm/classes/job.d.ts:444
- * bullmq@5.63.1 — moveToDelayed(timestamp, token?) — passing undefined
- * is accepted but may fail under lock contention with renewLock).
- */
-declare function deferIfDisabled(job: Job, jobConfigs: Record<string, JobConfig>, jobConfigsRepo: JobConfigsRepo, token: string | undefined): Promise<void>;
+interface RavenflowWorkerOptions {
+    redis: ConnectionOptions;
+    mongo: string;
+    queue: string;
+    concurrency?: number;
+    withdrawal?: WithdrawalOptions;
+}
+interface WithdrawalOptions {
+    afterMs?: number;
+    onWithdraw?: (reason: string) => void | Promise<void>;
+}
 
-declare function computeBucketStart(ts: Date, granularity: BucketGranularity): Date;
+declare class RavenflowWorker {
+    private readonly config;
+    private readonly options;
+    private readonly jobs;
+    private readonly logger;
+    private serving;
+    private starting;
+    private closing;
+    constructor(config: RavenflowConfig, options: RavenflowWorkerOptions);
+    start(): Promise<void>;
+    close(): Promise<void>;
+    private serveOrStop;
+    private stopServing;
+    private refuseASecondStart;
+    private openServing;
+    private buildControlPlaneReader;
+    private buildJobResultsRecorder;
+    private buildJobResultsAggregator;
+    private buildSpoolFeeder;
+    private buildMongoWatch;
+    private beginAWithdrawal;
+    private serve;
+    private openRecorder;
+    private sayJobResultsAreNotRecorded;
+    private takeJobs;
+}
 
-declare function createRavenflowApp<TConfig extends RavenflowConfig>(config: TConfig, options: RavenflowAppOptions): RavenflowApp<TConfig>;
+declare function createRavenflowWorker(config: RavenflowConfig, options: RavenflowWorkerOptions): RavenflowWorker;
 
-export { BatchWriter, type BatchWriterConfig, type BucketGranularity, DEFAULT_WORKER_METRICS, DISABLED_JOB_DEFER_DELAY_MS, type DistributedEtlJobConfig, type EtlExtractResult, type EtlResult, type EventHooksOptions, type IncrementStatsInput, type IndexDescriptor, JOB_FAILURES_INPUT_MAX_CHARS, JOB_FAILURES_LOGS_MAX_CHARS, JOB_FAILURES_MESSAGE_MAX_CHARS, JOB_FAILURES_STACK_MAX_CHARS, type JobConfig, type JobConfigDoc, type JobConfigEntry, JobConfigsRepo, type JobErrorDoc, JobErrorsRepo, type JobFailureDoc, JobFailuresRepo, type JobStatsDoc, JobStatsRepo, type JobStatus, type ListFailuresOptions, type Logger, type LoggerOptions, METRICS_TIME, type MemoryEtlJobConfig, type MemoryEtlStepConfig, type MongoConnectionObject, type RateLimitConfig, RavenflowApp, type RavenflowAppOptions, type RavenflowConfig, type RecordFailureInput, type RecordOccurrenceInput, type RegisterWorkerInput, Repository, type RetentionConfig, type SimpleJobConfig, type StatefulEtlJobConfig, type StepConfig, type TokenBucketInterval, type TokenBucketJobConfig, type TopErrorsOptions, type UpsertWorkerQueueInput, type WorkerDoc, type WorkerQueueEntry, WorkerRegistry, type WorkerRegistryOptions, WorkersRepo, attachEventHooks, captureJobLogs, computeBucketStart, createRavenflowApp, deferIfDisabled, defineConfig, defineDistributedEtlJob, defineMemoryEtlJob, defineSimpleJob, defineStatefulEtlJob, defineTokenBucketJob, errorSignature, getLogger, initLogger };
+export { type JobDefinition, RavenflowClient, type RavenflowConfig, RavenflowWorker, type RavenflowWorkerOptions, createRavenflowClient, createRavenflowWorker, defineConfig, defineJob };