tina4-nodejs 3.13.92 → 3.13.95

package/types/core/src/plan.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Project plan management — persistent, human-readable task state.
+ *
+ * Ported from tina4_python/dev_admin/plan.py (master reference).
+ * A plan is a markdown file under plan/ at the project root with sections
+ * for title, goal, steps (checkboxes), and notes. Exactly one plan is
+ * "current" at a time, recorded in plan/.current.
+ *
+ * Byte-for-byte compatible with Python's plan/*.md storage.
+ */
+export interface PlanStep {
+    text: string;
+    done: boolean;
+    index?: number;
+}
+export interface ParsedPlan {
+    title: string;
+    goal: string;
+    steps: PlanStep[];
+    notes: string;
+}
+export interface PlanSummary {
+    name: string;
+    title: string;
+    steps_total: number;
+    steps_done: number;
+    is_current: boolean;
+    /** Path relative to project root — lets the SPA open the right file
+     *  regardless of which dir the plan came from (plan/ vs .tina4/plans/). */
+    path: string;
+}
+export interface ExecutionSummary {
+    created: string[];
+    patched: string[];
+    migrations: string[];
+    total: number;
+}
+export interface CurrentPlan {
+    current: string | null;
+    title?: string;
+    goal?: string;
+    steps?: PlanStep[];
+    next_step?: PlanStep | null;
+    notes?: string;
+    progress?: {
+        done: number;
+        total: number;
+    };
+    execution?: ExecutionSummary;
+    warning?: string;
+}
+export declare const Plan: {
+    /**
+     * All plan files — merged from `plan/` (user-curated canonical) and
+     * `.tina4/plans/` (where the Rust supervisor's planner writes).
+     *
+     * Two directories exist because of a historic split: the framework
+     * treats `plan/` as the canonical project location, but the Rust agent's
+     * planner writes to `.tina4/plans/` (alongside other AI-state artefacts
+     * like chat history). Until those are unified we read both so plans
+     * created either way are discoverable. Dedup by filename when a plan
+     * exists in both — `plan/` wins on collision.
+     *
+     * Newest-first by filename (Rust planner uses unix-timestamp prefixes).
+     */
+    listPlans(): PlanSummary[];
+    currentName(): string;
+    setCurrent(name: string): {
+        ok: boolean;
+        current?: string;
+        error?: string;
+    };
+    clearCurrent(): {
+        ok: boolean;
+    };
+    current(): CurrentPlan;
+    read(name: string): ParsedPlan & {
+        name?: string;
+        error?: string;
+    };
+    create(title: string, goal?: string, steps?: string[], makeCurrent?: boolean): {
+        ok: boolean;
+        name?: string;
+        title?: string;
+        is_current?: boolean;
+        error?: string;
+    };
+    completeStep(index: number, name?: string): Record<string, unknown>;
+    uncompleteStep(index: number, name?: string): Record<string, unknown>;
+    addStep(text: string, name?: string): Record<string, unknown>;
+    appendNote(text: string, name?: string): Record<string, unknown>;
+    recordAction(action: string, filePath: string, note?: string): void;
+    summariseExecution(name?: string): ExecutionSummary;
+    flesh(name?: string, prompt?: string): Promise<Record<string, unknown>>;
+    archive(name?: string): Record<string, unknown>;
+};

package/types/core/src/projectIndex.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Project index — lightweight, persistent "where is what" map.
+ *
+ * Ported from tina4_python/dev_admin/project_index.py (master reference).
+ *
+ * Storage: .tina4/project_index.json at the project root.
+ * Freshness: lazy-refreshes on read via mtime compare — no watchers.
+ * Extractors: per-language symbol extraction (TS/JS, Twig/HTML, SQL, Markdown,
+ * Python) using regex. No LLM involvement — pure static analysis.
+ */
+export interface FileRoute {
+    method: string;
+    path: string;
+    handler: string;
+}
+export interface FileEntry {
+    path?: string;
+    size?: number;
+    mtime?: number;
+    language?: string;
+    sha256?: string;
+    skipped?: string;
+    extraction_error?: string;
+    summary?: string;
+    symbols?: string[];
+    imports?: string[];
+    routes?: FileRoute[];
+    docstring?: string;
+    exports?: string[];
+    extends?: string[];
+    blocks?: string[];
+    includes?: string[];
+    creates?: string[];
+    alters?: string[];
+    title?: string;
+    sections?: string[];
+    first_line?: string;
+    error?: string;
+}
+export declare const ProjectIndex: {
+    refresh(): {
+        added: number;
+        updated: number;
+        removed: number;
+        total: number;
+        path: string;
+    };
+    search(query: string, limit?: number): Array<{
+        path: string;
+        summary: string;
+        score: number;
+        language: string;
+    }>;
+    fileEntry(relPath: string): FileEntry;
+    overview(): Record<string, unknown>;
+};

package/types/core/src/queue.d.ts

@@ -0,0 +1,268 @@
+import { type QueueJob } from "./job.js";
+export { LiteBackend } from "./queueBackends/liteBackend.js";
+export { type QueueJob } from "./job.js";
+export interface QueueConfig {
+    backend?: string;
+    path?: string;
+    topic?: string;
+    maxRetries?: number;
+    /**
+     * Seconds to delay a failed job's automatic re-enqueue. 0 (the default)
+     * means retry immediately — the next pop()/consume() iteration picks it up
+     * straight away. Parity with Python's retry_backoff.
+     */
+    retryBackoff?: number;
+    /**
+     * Reservation/visibility timeout (seconds). A popped job is reserved for this
+     * long; if the consumer dies before complete()/fail() (crash, OOM, k8s
+     * eviction) the next pop() reclaims it — incrementing attempts and
+     * re-enqueuing, or dead-lettering past maxRetries (at-least-once delivery).
+     * Falls back to TINA4_QUEUE_VISIBILITY_TIMEOUT, else 300 (5 min). <= 0
+     * disables the reclaim (a reservation then lasts until the consumer acks —
+     * the old at-most-once behaviour). File + MongoDB backends, which are the
+     * only backends Node offers (ADR-0022). Parity with Python's
+     * visibility_timeout.
+     */
+    visibilityTimeout?: number;
+}
+/**
+ * Where the file-backed queue stores its jobs — `TINA4_QUEUE_PATH`, else
+ * `data/queue` (relative to the working directory).
+ *
+ * Exported because it is the ONE answer to "where do the queue files live",
+ * and anything that reads the store directly (the dev-admin queue panel) must
+ * ask here rather than re-deriving it. The dev admin hardcoded
+ * `cwd/data/queue/<topic>` and so listed a DIFFERENT directory from the one
+ * `Queue.size()` counted the moment `TINA4_QUEUE_PATH` was set.
+ */
+export declare function queueBasePath(): string;
+export interface ProcessOptions {
+    pollInterval?: number;
+    maxJobs?: number;
+    maxRetries?: number;
+    batchSize?: number;
+    /**
+     * Override the queue's topic for this drain (parity with Python's
+     * process(handler, topic=...)). When set, process() retargets the queue so
+     * pop() reads the requested topic instead of the construction-time one.
+     */
+    topic?: string;
+}
+export interface ConsumeOptions {
+    /** Topic to consume (defaults to the constructor topic). */
+    topic?: string;
+    batchSize?: number;
+    pollInterval?: number;
+    iterations?: number;
+    id?: string;
+}
+export interface QueueBackendInterface {
+    push(queue: string, payload: unknown, delay?: number, priority?: number): string;
+    pop(queue: string): QueueJob | null;
+    size(queue: string): number;
+    clear(queue: string): void;
+    /**
+     * Release whatever connection the backend holds, and be safe to call twice.
+     *
+     * REQUIRED, not optional, and deliberately so: it mirrors PHP's
+     * Tina4\Queue\QueueBackend, where close() has always been part of the
+     * interface. Optional would reintroduce exactly the bug this closes — a
+     * caller feature-detecting `backend.close?.()` silently skips the backend
+     * that forgot to implement it, which is how tina4-ruby's lite backend went
+     * un-closed by every `respond_to?(:close)` guard in its tree.
+     */
+    close(): void;
+    complete?(queue: string, id: string): void;
+    fail?(queue: string, id: string, error: string, maxRetries: number, retryBackoff: number): void;
+    retry?(queue: string, id: string, delaySeconds?: number): void;
+    deadLetters?(queue: string, maxRetries?: number): QueueJob[];
+    failed?(queue: string, maxRetries?: number): QueueJob[];
+    retryFailed?(queue: string, maxRetries?: number): number;
+    purge?(queue: string, status?: string): number;
+}
+export declare class Queue {
+    private backendName;
+    private basePath;
+    private topic;
+    private _maxRetries;
+    private _retryBackoff;
+    private _visibilityTimeout;
+    private externalBackend;
+    private liteBackend;
+    /**
+     * Unified Queue constructor.
+     *
+     * Accepts either:
+     *   - new Queue({ topic: "tasks", backend: "mongodb" })
+     *   - new Queue("mongodb", { path: "data/queue" })  // legacy
+     *   - new Queue()  // file backend, default topic
+     *
+     * Throws on backend "rabbitmq" or "kafka" (ADR-0022).
+     */
+    constructor(backendOrConfig?: string | QueueConfig, config?: QueueConfig);
+    /**
+     * Point this queue at ``topic`` in place.
+     *
+     * produce()/consume()/process() call this so a topic argument actually
+     * changes which topic is read or written. Without it the argument was
+     * accepted but ignored on the read path — pop() always used the
+     * construction-time topic, so consume("other") silently drained the wrong
+     * queue. The lite + external backends are topic-per-call (every push/pop/size
+     * takes the queue name), so changing this.topic retargets all of them; the
+     * job lifecycle (complete()/fail()/retry()) routes by the job's own .topic, so
+     * it is unaffected. Mirrors Python's Queue._retarget().
+     */
+    private retarget;
+    /**
+     * Add a job to the queue. Returns job ID.
+     *
+     * Can be called as:
+     *   queue.push(payload)                — uses constructor topic
+     *   queue.push(payload, delay)         — uses constructor topic with delay
+     *   queue.push(payload, delay, priority) — with delay and priority
+     *
+     * @param priority — Higher value = higher priority. Default 0.
+     */
+    push(payload: unknown, delay?: number, priority?: number): string;
+    /**
+     * Atomically claim the next available job from this queue's topic. Returns null if empty.
+     */
+    pop(): QueueJob | null;
+    /**
+     * Pop up to count jobs at once. Returns a partial batch if fewer available.
+     */
+    popBatch(count: number): QueueJob[];
+    /**
+     * Process jobs from a queue with a handler function.
+     */
+    process(handler: (job: QueueJob | QueueJob[]) => Promise<void> | void, options?: ProcessOptions): void;
+    /**
+     * Count jobs filtered by status. Defaults to "pending".
+     */
+    size(status?: string): number;
+    /**
+     * Remove all jobs from this queue's topic. Returns the number cleared.
+     */
+    clear(): number;
+    /**
+     * Release the backend's connection and free its resources.
+     *
+     * MEASURED 2026-08-04: close() was absent on the top-level Queue in ALL FOUR
+     * frameworks, and in Node it was absent on every backend class too — so an
+     * application had no way at all to hand a queue's client back. Same class of
+     * leak as ADR-0025 corollary 4 (client-lifecycle-is-bounded).
+     *
+     * Safe on EVERY backend: the file backend holds no connection and closes as a
+     * documented no-op, so a TINA4_QUEUE_BACKEND change never turns a working
+     * shutdown path into an error. Idempotent — each backend drops its handles on
+     * the first call, so a second call finds nothing to close and returns.
+     *
+     * HONEST CAVEAT specific to Node: neither backend it can reach holds a
+     * connection between calls today. The Mongo backend runs each operation in
+     * its own child process (ADR-0022), which closes its own client before it
+     * exits, and rabbitmq/kafka are refused outright at construction. So this
+     * releases nothing YET — it is here for the contract, and because the day the
+     * persistent-connection rewrite lands the client is released here with no
+     * change at any call site. Python, PHP and Ruby release a REAL client through
+     * the identically-named method.
+     *
+     * Treat the queue as spent afterwards and build a new one to keep working.
+     */
+    close(): void;
+    /**
+     * Get jobs that failed at least once but are still being retried
+     * (0 < attempts < maxRetries). These live in the pending queue under the
+     * auto-retry lifecycle; dead-lettered jobs are returned by deadLetters().
+     */
+    failed(): QueueJob[];
+    /**
+     * Retry all dead letter jobs for this queue's topic.
+     * Moves failed jobs that exceeded max retries back to pending.
+     *
+     * @param delaySeconds - Optional delay before jobs become available
+     * @returns true if at least one job was re-queued, false if none found
+     */
+    retry(jobId?: string, delaySeconds?: number): boolean;
+    /**
+     * Get dead letter jobs — failed jobs that exceeded max retries.
+     */
+    deadLetters(maxRetries?: number): QueueJob[];
+    /**
+     * Delete messages by status (e.g. "completed", "failed", "dead").
+     */
+    purge(status: string, maxRetries?: number): number;
+    /**
+     * Re-queue failed jobs that haven't exceeded max retries back to pending.
+     */
+    retryFailed(maxRetries?: number): number;
+    /**
+     * Produce a message onto a topic. Convenience wrapper around push().
+     *
+     * Retargets to the requested topic (restoring the prior one afterwards) so it
+     * shares the same retarget path consume()/process() use — keeping produce and
+     * consume symmetric on the same topic argument.
+     */
+    produce(topic: string, payload: unknown, priority?: number, delay?: number): string;
+    /**
+     * Consume jobs from a topic using a generator (yield pattern).
+     *
+     * Usage:
+     *   for (const job of queue.consume("emails")) {
+     *       processEmail(job);
+     *   }
+     *
+     *   // Consume a specific job by ID:
+     *   for (const job of queue.consume("emails", "job-id-123")) {
+     *       processEmail(job);
+     *   }
+     */
+    /**
+     * Long-running async generator that polls the queue continuously.
+     * When empty, sleeps for pollInterval ms before polling again.
+     * No external while-loop or sleep needed.
+     *
+     * @param topic Queue topic (defaults to constructor topic)
+     * @param id Optional job ID — single yield, no polling
+     * @param pollInterval Milliseconds to sleep when queue is empty (default 1000)
+     *
+     * Usage:
+     *   for await (const job of queue.consume("emails")) { ... }
+     *   for await (const job of queue.consume("emails", undefined, 5000)) { ... }
+     */
+    consume(topicOrOptions?: string | ConsumeOptions, id?: string, pollInterval?: number, iterations?: number, batchSize?: number): AsyncGenerator<QueueJob | QueueJob[]>;
+    /**
+     * Pop a specific job by ID from this queue's topic.
+     */
+    popById(id: string): QueueJob | null;
+    /**
+     * Get the configured topic name.
+     */
+    getTopic(): string;
+    getMaxRetries(): number;
+    getRetryBackoff(): number;
+    /**
+     * Resolved reservation/visibility timeout (seconds). <= 0 means the reclaim
+     * is disabled. File + MongoDB backends honour it; RabbitMQ/Kafka delegate to
+     * the broker.
+     */
+    getVisibilityTimeout(): number;
+    /**
+     * Record a failed attempt for a job. The backend increments `attempts`
+     * exactly once and decides whether to re-enqueue (attempts < maxRetries,
+     * after retryBackoff seconds) or dead-letter (attempts >= maxRetries).
+     */
+    _failJob(queue: string, job: QueueJob, error: string, maxRetries: number): void;
+    /**
+     * Re-queue a job back to the main queue directory with incremented attempts.
+     */
+    _retryJob(queue: string, job: QueueJob, delaySeconds?: number): void;
+    /**
+     * Acknowledge a completed job — drop its reservation so the visibility reclaim
+     * never re-delivers it. Routes to the active backend: a reservation-based
+     * external backend (MongoDB) acks there (without this its reserved doc would
+     * be re-delivered after the visibility window); RabbitMQ (no-ack on get) and
+     * Kafka (offset-based) expose no complete(), so the lite path is used and is a
+     * harmless no-op for them since they already acked/own redelivery.
+     */
+    _completeJob(queue: string, job: QueueJob): void;
+}

package/types/core/src/queueBackends/kafkaBackend.d.ts

@@ -0,0 +1,117 @@
+import type { QueueJob } from "../queue.js";
+export interface KafkaConfig {
+    brokers?: string;
+    groupId?: string;
+    /**
+     * Accepted for API parity with the file/MongoDB backends and IGNORED —
+     * consumer-group offsets own redelivery, so the framework-level visibility
+     * timeout does not apply here.
+     */
+    visibilityTimeout?: number;
+}
+/**
+ * librdkafka-style SSL/SASL client config (a TLS broker/proxy). Mirrors the
+ * keys produced by Python's `KafkaConnector._security_config`. Every key is
+ * optional — an unset env var leaves the key OUT (librdkafka defaults to the
+ * PLAINTEXT protocol with no SASL).
+ */
+export interface KafkaSecurityConfig {
+    "security.protocol"?: string;
+    "ssl.ca.location"?: string;
+    "sasl.mechanism"?: string;
+    "sasl.username"?: string;
+    "sasl.password"?: string;
+}
+/** Resolved producer/consumer config — brokers, client id, and security keys. */
+export interface KafkaClientConfig extends KafkaSecurityConfig {
+    "bootstrap.servers": string;
+    "client.id": string;
+    "group.id"?: string;
+    "auto.offset.reset"?: string;
+    "enable.auto.commit"?: boolean;
+}
+/**
+ * Build the SSL/SASL client config from the environment (for a TLS broker or
+ * proxy in front of Kafka). Each setting is read from the Tina4-namespaced env
+ * var FIRST (`TINA4_KAFKA_SECURITY_PROTOCOL` …) and falls back to the bare
+ * librdkafka-convention name (`KAFKA_SECURITY_PROTOCOL` …) that many Kafka
+ * deployments already set. Honours security.protocol (e.g. SSL, SASL_SSL),
+ * ssl.ca.location, and optional SASL (mechanism / username / password). Unset
+ * keys are omitted so librdkafka keeps its PLAINTEXT defaults.
+ *
+ * Exported for testing/introspection — and exact parity with Python's
+ * `_security_config` (same key set, same precedence, same omit-when-unset).
+ */
+export declare function kafkaSecurityConfig(env?: NodeJS.ProcessEnv): KafkaSecurityConfig;
+export interface QueueBackend {
+    push(queue: string, payload: unknown, delay?: number, priority?: number): string;
+    pop(queue: string): QueueJob | null;
+    size(queue: string): number;
+    clear(queue: string): void;
+}
+/**
+ * Kafka queue backend using raw Kafka protocol over TCP.
+ *
+ * Uses synchronous-style communication by spawning a child process
+ * for each operation, similar to the Redis session handler pattern.
+ */
+export declare class KafkaBackend implements QueueBackend {
+    private brokers;
+    private groupId;
+    constructor(config?: KafkaConfig);
+    /**
+     * Resolved connection config — exposed for testing/introspection.
+     */
+    getConfig(): Required<Omit<KafkaConfig, "visibilityTimeout">>;
+    /**
+     * Resolved SSL/SASL client config from the environment (PLAINTEXT default).
+     * Mirrors Python's `KafkaConnector._security_config`.
+     */
+    securityConfig(): KafkaSecurityConfig;
+    /**
+     * Full producer config — brokers + client id + the resolved security block.
+     * The security keys are applied to BOTH producer and consumer (matching
+     * Python's `_connect_confluent`).
+     */
+    producerConfig(): KafkaClientConfig;
+    /**
+     * Full consumer config — brokers + client id + group id + the SAME resolved
+     * security block applied to the producer.
+     */
+    consumerConfig(): KafkaClientConfig;
+    /**
+     * Parse broker string into host:port.
+     */
+    private parseBroker;
+    /**
+     * Execute a Kafka operation synchronously via a child process.
+     *
+     * The wire protocol is hand-rolled (Tina4 is zero-dependency — no npm Kafka
+     * library). Produce uses Produce **v3** carrying a Kafka **v2 RecordBatch**
+     * (magic byte 2) with a **CRC-32C** (Castagnoli) checksum; Fetch uses Fetch
+     * **v4** and parses the v2 RecordBatch out of the response. Both formats are
+     * what a modern KRaft broker (apache/kafka 3.7.0) requires — the old
+     * Produce-v0 / message-format-v0 / CRC=0 batch is rejected by such brokers.
+     */
+    private execSync;
+    /**
+     * Sleep synchronously between produce retries.
+     *
+     * `push()` is synchronous (the whole backend drives its socket through a child
+     * process), so there is no event loop to await on. `Atomics.wait` on a
+     * SharedArrayBuffer is the stdlib way to block a thread for a fixed time --
+     * no dependency, no busy-wait burning CPU.
+     */
+    private static sleepSync;
+    /**
+     * Turn a sentinel from the protocol child into a thrown error, or return.
+     *
+     * The wording matches the Python and PHP backends exactly -- the parity rule
+     * covers user-visible error messages, not just behaviour.
+     */
+    private static assertNoError;
+    push(queue: string, payload: unknown, _delay?: number): string;
+    pop(queue: string): QueueJob | null;
+    size(_queue: string): number;
+    clear(_queue: string): void;
+}

package/types/core/src/queueBackends/liteBackend.d.ts

@@ -0,0 +1,128 @@
+import { type QueueJob } from "../job.js";
+import { type JobQueueBridge } from "../job.js";
+export declare class LiteBackend {
+    private basePath;
+    private seq;
+    /**
+     * Reservation/visibility timeout (seconds). A popped job is held in reserved/
+     * with availableAt = now + visibilityTimeout. If the consumer dies before
+     * complete()/fail() (crash, OOM, k8s eviction) the next pop() reclaims it once
+     * the window expires — incrementing attempts and re-enqueuing, or
+     * dead-lettering past maxRetries. <= 0 disables the reclaim (a reservation
+     * then lasts until the consumer acks — the old at-most-once behaviour).
+     */
+    private visibilityTimeout;
+    constructor(basePath?: string, visibilityTimeout?: number);
+    private ensureDir;
+    private ensureFailedDir;
+    private ensureReservedDir;
+    private reservedPath;
+    private nowIso;
+    private futureIso;
+    private nextPrefix;
+    /**
+     * No-op: the file backend holds no connection to release.
+     *
+     * It exists so `Queue.close()` can call ONE method on every backend instead
+     * of testing for it, and so switching TINA4_QUEUE_BACKEND to "file" never
+     * turns a working close() into "backend.close is not a function". Idempotent
+     * by construction — there is nothing to drop.
+     */
+    close(): void;
+    push(queue: string, payload: unknown, delay?: number, priority?: number): string;
+    /**
+     * Return [filename, jobData] for every pending, non-delayed job, ordered by
+     * the dequeue policy: highest priority first, ties broken oldest-first by
+     * createdAt. createdAt is an ISO-8601 string, so lexicographic comparison ==
+     * chronological order.
+     */
+    private availableCandidates;
+    /**
+     * Persist a reservation record so a dead consumer's job is reclaimable.
+     *
+     * Stores reservedAt + availableAt = now + visibilityTimeout. The next pop()
+     * reclaims this job once availableAt has passed (see reclaimExpired).
+     * complete()/fail()/retry() delete the record.
+     */
+    private writeReserved;
+    /**
+     * Return expired reservations to the queue (at-least-once delivery).
+     *
+     * A reserved job whose availableAt <= now means its consumer never
+     * acknowledged in time (crash / OOM / pod eviction). Atomically claim it
+     * (delete the reservation file), increment attempts, and either re-enqueue it
+     * (so the next pop picks it up) or dead-letter it once it has hit maxRetries.
+     * Disabled when visibilityTimeout <= 0.
+     */
+    private reclaimExpired;
+    pop(queue: string, bridge: JobQueueBridge): QueueJob | null;
+    popBatch(queue: string, bridge: JobQueueBridge, count: number): QueueJob[];
+    /**
+     * Delete a job's reservation record (best-effort).
+     */
+    private clearReservation;
+    /**
+     * Acknowledge a completed job — drop its reservation record so the visibility
+     * reclaim never re-delivers an already-acked job.
+     */
+    completeJob(queue: string, job: QueueJob): void;
+    private static readonly DEAD_STATES;
+    size(queue: string, status?: string): number;
+    clear(queue: string): number;
+    /**
+     * Jobs that have failed at least once but are still being retried.
+     *
+     * Under the auto-retry lifecycle a failed-but-retryable job lives in the
+     * pending queue (not the dead-letter dir), so this scans the queue dir for
+     * pending jobs with attempts > 0 that have not yet exhausted their retries.
+     * Dead-lettered jobs are returned by deadLetters().
+     */
+    failed(queue: string, maxRetries?: number): QueueJob[];
+    /**
+     * Revive a specific dead-letter job by id back to the pending queue.
+     *
+     * Manual override (Queue.retry(jobId) / job.retry()) — always revives a
+     * dead-letter regardless of attempt count. Returns false only if no
+     * dead-letter with that id exists.
+     */
+    retry(queue: string, jobId: string, delaySeconds?: number): boolean;
+    deadLetters(queue: string, maxRetries?: number): QueueJob[];
+    purge(queue: string, status: string, maxRetries?: number): number;
+    /**
+     * Re-queue dead-letter jobs that are under the (possibly raised) limit back
+     * to pending. Mirrors Python retry_failed(): a job dead-lettered at the
+     * original maxRetries needs a raised limit to qualify again.
+     */
+    retryFailed(queue: string, maxRetries?: number): number;
+    popById(queue: string, id: string): QueueJob | null;
+    /**
+     * Write the job back to the pending queue (queue dir).
+     *
+     * Re-enqueued jobs get a fresh createdAt so that within a priority tier they
+     * sort behind jobs that have not yet been attempted. `attempts` already
+     * reflects the latest failure count. The job carries its prior error.
+     */
+    private requeue;
+    /**
+     * Move the job to the dead-letter (failed/) directory. Terminal until a
+     * manual retryFailed()/retry() revives it.
+     */
+    private deadLetter;
+    /**
+     * Record a failed attempt.
+     *
+     * Increments `attempts` exactly once (the increment lives here, NOT in
+     * job.ts — see the double-increment fix). If the job still has retries left
+     * (attempts < maxRetries) it is automatically re-enqueued to pending, after
+     * an optional retryBackoff delay. Once it has been attempted maxRetries times
+     * (attempts >= maxRetries) it is moved to the dead-letter store.
+     */
+    failJob(queue: string, job: QueueJob, error: string, maxRetries: number, retryBackoff?: number): void;
+    /**
+     * Explicit re-queue requested by the caller (job.retry()).
+     *
+     * Always re-enqueues regardless of the retry limit — manual override,
+     * distinct from the automatic failJob() path.
+     */
+    retryJob(queue: string, job: QueueJob, delaySeconds?: number): void;
+}