@retinue/agentkit 0.1.0

package/dist/usage/rollups.d.ts

@@ -0,0 +1,121 @@
+/**
+ * The rollup job and the reconciliation report (#139).
+ *
+ * `UsageRollupStore.rebuild` does the arithmetic. What lives here is *which buckets to rebuild and when*, and
+ * the comparison against what the provider says we spent.
+ *
+ * **The work list is derived from the ledger.** `listStaleBuckets` asks which buckets have events newer than
+ * their last computation, so an interrupted job resumes by asking again rather than by remembering where it
+ * was. The same shape #135's re-indexing uses, and for the same reason: a cursor that has to be persisted is a
+ * cursor that can be lost, and a lost rollup cursor is silently wrong totals.
+ *
+ * **Reconciliation reports, it does not correct.** A discrepancy between our ledger and a provider's invoice
+ * has several causes — a rounding difference, an event we never recorded, a charge for a call we did not make,
+ * a provider restatement — and they want different responses. A job that "corrected" the ledger would erase
+ * the evidence needed to tell them apart, and the ledger is append-only precisely so that evidence survives.
+ */
+import type { ExecutionContext } from "../core/context.js";
+import type { TenantId } from "../core/ids.js";
+import type { RollupPeriod, UsageRollup, UsageRollupStore } from "../persistence/index.js";
+export type RollupJobDeps = {
+    readonly rollups: UsageRollupStore;
+    readonly log?: (message: string, detail?: Readonly<Record<string, unknown>>) => void;
+};
+export declare const createRollupJob: (deps: RollupJobDeps) => {
+    /**
+     * Rebuild one page of stale buckets — AC-4.
+     *
+     * A page at a time, so an interruption loses at most a page and no bookkeeping. Rebuilding is a
+     * *recomputation*, so re-running a bucket cannot double count and two workers racing one bucket write the
+     * same value — which is what makes "safe under concurrency" a property of the design rather than a lock.
+     */
+    run(context: {
+        readonly tenantId: TenantId;
+    }, input: {
+        readonly period: RollupPeriod;
+        readonly since: string;
+        readonly limit: number;
+    }): Promise<{
+        readonly rebuilt: number;
+        readonly remaining: number;
+    }>;
+    /** Rebuild a specific range, for a backfill or after a correcting event. */
+    rebuildRange(context: {
+        readonly tenantId: TenantId;
+    }, input: {
+        readonly period: RollupPeriod;
+        readonly from: string;
+        readonly to: string;
+    }): Promise<readonly UsageRollup[]>;
+};
+export type RollupJob = ReturnType<typeof createRollupJob>;
+/**
+ * What the provider says a period cost.
+ *
+ * `costMinorUnits` in the same integer minor units the ledger uses, so a comparison is exact arithmetic rather
+ * than a float difference that is always slightly nonzero.
+ */
+export type ProviderStatement = {
+    readonly provider: string;
+    readonly from: string;
+    readonly to: string;
+    readonly costMinorUnits: number;
+    readonly currency: string;
+};
+/**
+ * The tolerance a discrepancy has to clear to be reported — AC-5.
+ *
+ * **Both a fraction and a floor**, and both are needed. A fraction alone reports every tiny period as broken:
+ * on a €0.02 hour a one-cent rounding difference is 50%. A floor alone stops scaling: on a €10,000 month a
+ * €5 absolute tolerance is noise nobody can act on. A discrepancy must exceed *both* to be worth someone's
+ * attention.
+ */
+export declare const DEFAULT_RECONCILIATION_TOLERANCE: {
+    readonly fraction: 0.02;
+    readonly floorMinorUnits: 100;
+};
+export type ReconciliationTolerance = {
+    readonly fraction: number;
+    readonly floorMinorUnits: number;
+};
+/** Why a period did not reconcile. Separate values because each points at a different investigation. */
+export declare const DISCREPANCY_KINDS: readonly ["under-recorded", "over-recorded", "currency-mismatch"];
+export type DiscrepancyKind = (typeof DISCREPANCY_KINDS)[number];
+/**
+ * Named for usage specifically, because `files/index.ts` has a `ReconciliationReport` of its own — for orphaned
+ * objects, which is a different problem with a different report. The package barrel refused both, which is how
+ * the collision surfaced.
+ */
+export type UsageReconciliationReport = {
+    readonly provider: string;
+    readonly from: string;
+    readonly to: string;
+    readonly ledgerMinorUnits: number;
+    readonly providerMinorUnits: number;
+    readonly deltaMinorUnits: number;
+    readonly withinTolerance: boolean;
+    readonly kind?: DiscrepancyKind;
+    readonly message?: string;
+};
+/**
+ * Compare the ledger's rollups against a provider statement.
+ *
+ * Reads the *rollups*, not the ledger, so reconciliation costs the same whether a tenant has spent a euro or a
+ * million — and so a discrepancy in the rollups themselves is visible rather than hidden by recomputing the
+ * thing being checked.
+ */
+export declare const reconcileUsage: (context: ExecutionContext, deps: {
+    readonly rollups: UsageRollupStore;
+}, input: {
+    readonly statement: ProviderStatement;
+    /**
+     * The currency the ledger records in.
+     *
+     * Passed rather than read from a rollup, because a range with no usage has no rollup to read it from — and
+     * "no usage" is exactly when a statement showing a charge matters most.
+     */
+    readonly ledgerCurrency: string;
+    readonly period?: RollupPeriod;
+    readonly tolerance?: ReconciliationTolerance;
+}) => Promise<UsageReconciliationReport>;
+//# sourceMappingURL=rollups.d.ts.map

package/dist/usage/rollups.js

@@ -0,0 +1,157 @@
+/**
+ * The rollup job and the reconciliation report (#139).
+ *
+ * `UsageRollupStore.rebuild` does the arithmetic. What lives here is *which buckets to rebuild and when*, and
+ * the comparison against what the provider says we spent.
+ *
+ * **The work list is derived from the ledger.** `listStaleBuckets` asks which buckets have events newer than
+ * their last computation, so an interrupted job resumes by asking again rather than by remembering where it
+ * was. The same shape #135's re-indexing uses, and for the same reason: a cursor that has to be persisted is a
+ * cursor that can be lost, and a lost rollup cursor is silently wrong totals.
+ *
+ * **Reconciliation reports, it does not correct.** A discrepancy between our ledger and a provider's invoice
+ * has several causes — a rounding difference, an event we never recorded, a charge for a call we did not make,
+ * a provider restatement — and they want different responses. A job that "corrected" the ledger would erase
+ * the evidence needed to tell them apart, and the ledger is append-only precisely so that evidence survives.
+ */
+import { bucketStartFor, bucketsBetween, nextBucket } from "./quota.js";
+export const createRollupJob = (deps) => {
+    const log = deps.log ?? (() => { });
+    return {
+        /**
+         * Rebuild one page of stale buckets — AC-4.
+         *
+         * A page at a time, so an interruption loses at most a page and no bookkeeping. Rebuilding is a
+         * *recomputation*, so re-running a bucket cannot double count and two workers racing one bucket write the
+         * same value — which is what makes "safe under concurrency" a property of the design rather than a lock.
+         */
+        async run(context, input) {
+            const stale = await deps.rollups.listStaleBuckets({
+                tenantId: context.tenantId,
+                period: input.period,
+                since: input.since,
+                limit: input.limit,
+            });
+            for (const bucket of stale.items) {
+                // No `computedAt`: the store stamps it from its own clock, because staleness compares that stamp
+                // against when events were recorded and both must come from one source.
+                await deps.rollups.rebuild({
+                    tenantId: context.tenantId,
+                    period: bucket.period,
+                    bucketStart: bucket.bucketStart,
+                    /**
+                     * The grain the store reported — #175.
+                     *
+                     * Dropping it would rebuild the tenant row twice and never build a principal's at all, so every
+                     * per-person figure would read zero and every per-person quota would be unenforceable. The store
+                     * reports both grains from one ledger pass precisely so the job does not have to know which
+                     * principals were active.
+                     */
+                    ...(bucket.principalId === undefined ? {} : { principalId: bucket.principalId }),
+                });
+            }
+            // Asked again rather than computed, because events may have landed while this page ran — and a stale
+            // "remaining" is how a loop stops early or never stops.
+            const after = await deps.rollups.listStaleBuckets({
+                tenantId: context.tenantId,
+                period: input.period,
+                since: input.since,
+                limit: 1,
+            });
+            if (stale.items.length > 0)
+                log("rebuilt usage buckets", { period: input.period, count: stale.items.length });
+            return { rebuilt: stale.items.length, remaining: after.items.length };
+        },
+        /** Rebuild a specific range, for a backfill or after a correcting event. */
+        async rebuildRange(context, input) {
+            const written = [];
+            for (const bucketStart of bucketsBetween(input.period, input.from, input.to)) {
+                written.push(await deps.rollups.rebuild({
+                    tenantId: context.tenantId,
+                    period: input.period,
+                    bucketStart,
+                }));
+            }
+            return written;
+        },
+    };
+};
+/**
+ * The tolerance a discrepancy has to clear to be reported — AC-5.
+ *
+ * **Both a fraction and a floor**, and both are needed. A fraction alone reports every tiny period as broken:
+ * on a €0.02 hour a one-cent rounding difference is 50%. A floor alone stops scaling: on a €10,000 month a
+ * €5 absolute tolerance is noise nobody can act on. A discrepancy must exceed *both* to be worth someone's
+ * attention.
+ */
+export const DEFAULT_RECONCILIATION_TOLERANCE = { fraction: 0.02, floorMinorUnits: 100 };
+/** Why a period did not reconcile. Separate values because each points at a different investigation. */
+export const DISCREPANCY_KINDS = ["under-recorded", "over-recorded", "currency-mismatch"];
+/**
+ * Compare the ledger's rollups against a provider statement.
+ *
+ * Reads the *rollups*, not the ledger, so reconciliation costs the same whether a tenant has spent a euro or a
+ * million — and so a discrepancy in the rollups themselves is visible rather than hidden by recomputing the
+ * thing being checked.
+ */
+export const reconcileUsage = async (context, deps, input) => {
+    const period = input.period ?? "day";
+    const tolerance = input.tolerance ?? DEFAULT_RECONCILIATION_TOLERANCE;
+    const ledger = await deps.rollups.sum({
+        tenantId: context.tenantId,
+        period,
+        from: bucketStartFor(period, input.statement.from),
+        // Exclusive upper bound, extended to the end of the bucket containing `to` — a statement ending mid-day
+        // still covers that day's spend, and truncating would report every statement as under-recorded.
+        to: nextBucket(period, bucketStartFor(period, input.statement.to)),
+    });
+    // Currency first, because comparing two numbers in different currencies is not a discrepancy — it is a
+    // meaningless subtraction that would report a plausible figure. Checked before the arithmetic rather than
+    // after, so no number is ever computed across currencies.
+    if (input.ledgerCurrency !== input.statement.currency)
+        return {
+            provider: input.statement.provider,
+            from: input.statement.from,
+            to: input.statement.to,
+            ledgerMinorUnits: ledger.costMinorUnits,
+            providerMinorUnits: input.statement.costMinorUnits,
+            // Deliberately zero rather than a difference: there is no difference between amounts in different
+            // currencies, and a number here would be quoted as one.
+            deltaMinorUnits: 0,
+            withinTolerance: false,
+            kind: "currency-mismatch",
+            message: `The ledger records ${input.ledgerCurrency} and ${input.statement.provider} billed in ${input.statement.currency}; the totals cannot be compared.`,
+        };
+    const delta = ledger.costMinorUnits - input.statement.costMinorUnits;
+    const magnitude = Math.abs(delta);
+    const base = Math.max(input.statement.costMinorUnits, 1);
+    // Both thresholds, not either: a fraction alone flags every tiny period, a floor alone stops scaling.
+    const withinTolerance = magnitude <= tolerance.floorMinorUnits || magnitude / base <= tolerance.fraction;
+    if (withinTolerance)
+        return {
+            provider: input.statement.provider,
+            from: input.statement.from,
+            to: input.statement.to,
+            ledgerMinorUnits: ledger.costMinorUnits,
+            providerMinorUnits: input.statement.costMinorUnits,
+            deltaMinorUnits: delta,
+            withinTolerance: true,
+        };
+    const kind = delta < 0 ? "under-recorded" : "over-recorded";
+    return {
+        provider: input.statement.provider,
+        from: input.statement.from,
+        to: input.statement.to,
+        ledgerMinorUnits: ledger.costMinorUnits,
+        providerMinorUnits: input.statement.costMinorUnits,
+        deltaMinorUnits: delta,
+        withinTolerance: false,
+        kind,
+        // Both figures and the direction, because "under-recorded" and "over-recorded" point at different
+        // investigations: the first is usage we are not billing for, the second is a charge we cannot account for.
+        message: kind === "under-recorded"
+            ? `${input.statement.provider} billed ${input.statement.costMinorUnits} but the ledger records ${ledger.costMinorUnits} — ${magnitude} minor units of usage were not recorded.`
+            : `The ledger records ${ledger.costMinorUnits} but ${input.statement.provider} billed ${input.statement.costMinorUnits} — ${magnitude} minor units were recorded that the provider did not bill.`,
+    };
+};
+//# sourceMappingURL=rollups.js.map

package/dist/worker/export.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The export worker (#134).
+ *
+ * Composition only, like the extraction worker — every bound and every failure decision lives in
+ * `export/index.ts`. What this owns is the loop.
+ *
+ * **A failed render completes the job.** The service records a typed failure and returns; retrying a
+ * document that cannot be rendered produces the same answer at the same cost forever. Only an infrastructure
+ * failure throws, and only that is worth retrying.
+ *
+ * The job carries a tenant but not a *principal*, so the host supplies the `ExecutionContext` the render runs
+ * as. That is deliberate: an export must be rendered with the entitlement of the person who asked for it, and
+ * a worker inventing an all-powerful context would make AC-5 decorative.
+ */
+import type { ExecutionContext } from "../core/context.js";
+import type { ArtifactExport } from "../persistence/index.js";
+import type { ExportJob, ExportService } from "../export/index.js";
+export interface ExportConsumer {
+    start(handler: (job: ExportJob) => Promise<void>): Promise<void> | void;
+    stop(graceMs: number): Promise<void>;
+}
+export type ExportWorkerConfig = {
+    /** Low, like extraction's: rendering is CPU-bound and four concurrent renders on one loop is four slow ones. */
+    readonly concurrency: number;
+    readonly shutdownGraceMs: number;
+};
+export declare const DEFAULT_EXPORT_WORKER_CONFIG: ExportWorkerConfig;
+export type ExportWorkerDeps = {
+    readonly exports: ExportService;
+    readonly consumer: ExportConsumer;
+    /**
+     * The context a job renders as.
+     *
+     * Required, and required to be per-job: the render re-reads the artifact through `ArtifactService`, so this
+     * is what makes an export carry the requester's entitlement rather than the worker's.
+     */
+    readonly contextFor: (job: ExportJob) => Promise<ExecutionContext> | ExecutionContext;
+    readonly config?: Partial<ExportWorkerConfig>;
+    readonly log?: (message: string, detail?: Readonly<Record<string, unknown>>) => void;
+    readonly onOutcome?: (job: ExportJob, result: ArtifactExport) => void;
+    readonly onError?: (job: ExportJob, error: unknown) => void;
+};
+export declare const createExportWorker: (deps: ExportWorkerDeps) => {
+    start(): Promise<void>;
+    shutdown(reason: string): Promise<{
+        readonly graceful: boolean;
+    }>;
+    status(): {
+        running: boolean;
+        inFlight: number;
+        processed: number;
+        failed: number;
+    };
+    concurrency: number;
+};
+export type ExportWorker = ReturnType<typeof createExportWorker>;
+//# sourceMappingURL=export.d.ts.map

package/dist/worker/export.js

@@ -0,0 +1,81 @@
+/**
+ * The export worker (#134).
+ *
+ * Composition only, like the extraction worker — every bound and every failure decision lives in
+ * `export/index.ts`. What this owns is the loop.
+ *
+ * **A failed render completes the job.** The service records a typed failure and returns; retrying a
+ * document that cannot be rendered produces the same answer at the same cost forever. Only an infrastructure
+ * failure throws, and only that is worth retrying.
+ *
+ * The job carries a tenant but not a *principal*, so the host supplies the `ExecutionContext` the render runs
+ * as. That is deliberate: an export must be rendered with the entitlement of the person who asked for it, and
+ * a worker inventing an all-powerful context would make AC-5 decorative.
+ */
+export const DEFAULT_EXPORT_WORKER_CONFIG = { concurrency: 2, shutdownGraceMs: 20_000 };
+export const createExportWorker = (deps) => {
+    const config = { ...DEFAULT_EXPORT_WORKER_CONFIG, ...deps.config };
+    const log = deps.log ?? (() => { });
+    let running = false;
+    let inFlight = 0;
+    let processed = 0;
+    let failed = 0;
+    const settled = new Set();
+    const handle = async (job) => {
+        inFlight += 1;
+        try {
+            const context = await deps.contextFor(job);
+            const result = await deps.exports.render(job, context);
+            processed += 1;
+            // Counted, not thrown: a document that cannot be rendered is an outcome, and the queue must not retry it.
+            if (result.state === "failed")
+                failed += 1;
+            deps.onOutcome?.(job, result);
+        }
+        catch (error) {
+            // Only infrastructure reaches here — the service turns every render problem into a record. Rethrown so
+            // the queue does retry, which is right for a store that was briefly unreachable.
+            log("export job failed", { job, error });
+            deps.onError?.(job, error);
+            throw error;
+        }
+        finally {
+            inFlight -= 1;
+        }
+    };
+    return {
+        async start() {
+            running = true;
+            await deps.consumer.start(async (job) => {
+                const promise = handle(job);
+                settled.add(promise);
+                try {
+                    await promise;
+                }
+                finally {
+                    settled.delete(promise);
+                }
+            });
+        },
+        async shutdown(reason) {
+            log("export worker shutting down", { reason, inFlight });
+            running = false;
+            // Stop accepting first, then wait. Draining first would accept a job it has no intention of finishing.
+            await deps.consumer.stop(config.shutdownGraceMs);
+            const graceful = await Promise.race([
+                Promise.allSettled([...settled]).then(() => true),
+                new Promise((resolve) => {
+                    const timer = setTimeout(() => resolve(false), config.shutdownGraceMs);
+                    // Unref so a clean shutdown is not held open by its own deadline.
+                    timer.unref?.();
+                }),
+            ]);
+            return { graceful };
+        },
+        status() {
+            return { running, inFlight, processed, failed };
+        },
+        concurrency: config.concurrency,
+    };
+};
+//# sourceMappingURL=export.js.map

package/dist/worker/extraction.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The extraction worker (#131, AC-2 and AC-3).
+ *
+ * Composition only, like `worker/main.ts` — every bound and every failure decision lives in
+ * `documents/extraction.ts`, and duplicating any of them here would mean two places to look when a document
+ * misbehaves. What this file owns is the loop: claim, extract, report, and stop cleanly.
+ *
+ * Written against the same `JobConsumer`-shaped seam as the run worker so the ordering decisions — the part
+ * that can actually be wrong — are testable without Redis.
+ *
+ * **A failed extraction is not a failed job.** The pipeline records a typed failure and returns; the job
+ * completes. That is deliberate: a job that failed would be retried by the queue, and retrying a scan with no
+ * text layer produces the same answer at the same cost forever. Only an *infrastructure* failure — the store
+ * unreachable — throws, and only that is worth retrying.
+ */
+import type { FileExtraction } from "../persistence/index.js";
+import type { ExtractionJob } from "../documents/index.js";
+import type { ExtractionService } from "../documents/extraction.js";
+/** The consumer side. Mirrors `JobConsumer` for runs; `stop` must stop accepting before it waits. */
+export interface ExtractionConsumer {
+    start(handler: (job: ExtractionJob) => Promise<void>): Promise<void> | void;
+    stop(graceMs: number): Promise<void>;
+}
+export type ExtractionWorkerConfig = {
+    /**
+     * Jobs at once. Low by default, and lower than the run worker's on purpose: extraction is CPU-bound, and
+     * four concurrent PDF parses on one event loop is four slow parses rather than four fast ones.
+     */
+    readonly concurrency: number;
+    readonly shutdownGraceMs: number;
+};
+export declare const DEFAULT_EXTRACTION_WORKER_CONFIG: ExtractionWorkerConfig;
+export type ExtractionWorkerDeps = {
+    readonly extraction: ExtractionService;
+    readonly consumer: ExtractionConsumer;
+    readonly config?: Partial<ExtractionWorkerConfig>;
+    readonly log?: (message: string, detail?: Readonly<Record<string, unknown>>) => void;
+    /** Observability hook, and what the tests assert on. */
+    readonly onOutcome?: (job: ExtractionJob, extraction: FileExtraction) => void;
+    readonly onError?: (job: ExtractionJob, error: unknown) => void;
+};
+export type ExtractionWorkerStatus = {
+    readonly running: boolean;
+    readonly inFlight: number;
+    readonly processed: number;
+    readonly failed: number;
+};
+export declare const createExtractionWorker: (deps: ExtractionWorkerDeps) => {
+    start(): Promise<void>;
+    shutdown(reason: string): Promise<{
+        readonly graceful: boolean;
+    }>;
+    status(): ExtractionWorkerStatus;
+    concurrency: number;
+};
+export type ExtractionWorker = ReturnType<typeof createExtractionWorker>;
+//# sourceMappingURL=extraction.d.ts.map

package/dist/worker/extraction.js

@@ -0,0 +1,84 @@
+/**
+ * The extraction worker (#131, AC-2 and AC-3).
+ *
+ * Composition only, like `worker/main.ts` — every bound and every failure decision lives in
+ * `documents/extraction.ts`, and duplicating any of them here would mean two places to look when a document
+ * misbehaves. What this file owns is the loop: claim, extract, report, and stop cleanly.
+ *
+ * Written against the same `JobConsumer`-shaped seam as the run worker so the ordering decisions — the part
+ * that can actually be wrong — are testable without Redis.
+ *
+ * **A failed extraction is not a failed job.** The pipeline records a typed failure and returns; the job
+ * completes. That is deliberate: a job that failed would be retried by the queue, and retrying a scan with no
+ * text layer produces the same answer at the same cost forever. Only an *infrastructure* failure — the store
+ * unreachable — throws, and only that is worth retrying.
+ */
+export const DEFAULT_EXTRACTION_WORKER_CONFIG = {
+    concurrency: 2,
+    shutdownGraceMs: 20_000,
+};
+export const createExtractionWorker = (deps) => {
+    const config = { ...DEFAULT_EXTRACTION_WORKER_CONFIG, ...deps.config };
+    const log = deps.log ?? (() => { });
+    let running = false;
+    let inFlight = 0;
+    let processed = 0;
+    let failed = 0;
+    const settled = new Set();
+    const handle = async (job) => {
+        inFlight += 1;
+        try {
+            const extraction = await deps.extraction.extract(job);
+            processed += 1;
+            // Counted, not thrown. A document that cannot be read is an outcome; the queue must not retry it.
+            if (extraction.state === "failed")
+                failed += 1;
+            deps.onOutcome?.(job, extraction);
+        }
+        catch (error) {
+            // Only infrastructure reaches here — the pipeline turns every document problem into a record. Rethrown
+            // so the queue *does* retry, which is right for a store that was briefly unreachable.
+            log("extraction job failed", { job, error });
+            deps.onError?.(job, error);
+            throw error;
+        }
+        finally {
+            inFlight -= 1;
+        }
+    };
+    return {
+        async start() {
+            running = true;
+            await deps.consumer.start(async (job) => {
+                const promise = handle(job);
+                settled.add(promise);
+                try {
+                    await promise;
+                }
+                finally {
+                    settled.delete(promise);
+                }
+            });
+        },
+        async shutdown(reason) {
+            log("extraction worker shutting down", { reason, inFlight });
+            running = false;
+            // Stop accepting first, then wait. Draining first would accept a job with no intention of finishing it.
+            await deps.consumer.stop(config.shutdownGraceMs);
+            const graceful = await Promise.race([
+                Promise.allSettled([...settled]).then(() => true),
+                new Promise((resolve) => {
+                    const timer = setTimeout(() => resolve(false), config.shutdownGraceMs);
+                    // Unref so a clean shutdown is not held open by its own deadline.
+                    timer.unref?.();
+                }),
+            ]);
+            return { graceful };
+        },
+        status() {
+            return { running, inFlight, processed, failed };
+        },
+        concurrency: config.concurrency,
+    };
+};
+//# sourceMappingURL=extraction.js.map

package/dist/worker/main.d.ts

@@ -0,0 +1,103 @@
+/**
+ * The worker process entrypoint (#107).
+ *
+ * `runtime/worker.ts` has had the claim, heartbeat, checkpoint and recovery logic all along and
+ * nothing ran it. This is that missing process, and it is **composition only** — every recovery and
+ * heartbeat behaviour it relies on already exists and is already tested. Adding execution logic here
+ * would mean two places to look when a run misbehaves.
+ *
+ * Written against a `JobConsumer` seam rather than BullMQ directly, so the entrypoint's ordering
+ * decisions — which are the part that can actually be wrong — are testable without Redis.
+ */
+import type { JobDispatcher, Run } from "../runtime/index.js";
+import type { DurableWorker, ProcessResult } from "../runtime/worker.js";
+import type { RunId, TenantId } from "../core/ids.js";
+/**
+ * A unit of work off the queue. Mirrors the dispatcher's `enqueueRun` input.
+ *
+ * The trace fields (#143) are optional and unused by the runtime itself — `instrumentConsumer` reads them. They
+ * live on this type rather than on a parallel one so the consumer seam stays a single shape; a second type would
+ * mean an adapter deciding which to produce.
+ */
+export type RunJob = {
+    readonly tenantId: TenantId;
+    readonly runId: RunId;
+    readonly traceparent?: string;
+    readonly enqueuedAt?: string;
+};
+/**
+ * The queue's consumer side.
+ *
+ * `stop` must **stop accepting new jobs immediately** and only then wait for in-flight handlers. An
+ * implementation that drains first would accept a job it has no intention of finishing.
+ */
+export interface JobConsumer {
+    start(handler: (job: RunJob) => Promise<void>): Promise<void> | void;
+    stop(graceMs: number): Promise<void>;
+}
+export type WorkerConfig = {
+    /** Jobs handled at once. Above the store's connection pool this queues on the pool instead. */
+    readonly concurrency: number;
+    /**
+     * How long a claim survives without a keepalive. The worker heartbeats at a third of this, so a
+     * single slow round trip does not drop a live claim.
+     */
+    readonly leaseMs: number;
+    /** How often to sweep for runs whose lease expired. */
+    readonly reapEveryMs: number;
+    /** Candidates per sweep. Bounded so a large backlog cannot turn one sweep into a long transaction. */
+    readonly reapLimit: number;
+    /**
+     * How long shutdown waits for in-flight runs.
+     *
+     * Deliberately shorter than a run's `maxWallClockMs` can be: a long run will be **checkpointed**
+     * rather than finished, which is correct — the alternative is a deploy that never completes. See the
+     * open question on #107.
+     */
+    readonly shutdownGraceMs: number;
+};
+export declare const DEFAULT_WORKER_CONFIG: WorkerConfig;
+export type WorkerRuntimeDeps = {
+    readonly worker: DurableWorker;
+    readonly consumer: JobConsumer;
+    /** Reaped runs are re-enqueued rather than executed inline, so recovery goes through the same path. */
+    readonly dispatcher: JobDispatcher;
+    readonly config?: Partial<WorkerConfig>;
+    readonly log?: (message: string, detail?: Readonly<Record<string, unknown>>) => void;
+    /** Observability hook; also what the tests assert on. */
+    readonly onOutcome?: (job: RunJob, result: ProcessResult) => void;
+    readonly onError?: (job: RunJob, error: unknown) => void;
+    /** Injectable so a test can drive the reaper without waiting on wall clock. */
+    readonly setInterval?: (fn: () => void, ms: number) => {
+        readonly clear: () => void;
+    };
+};
+export type WorkerStatus = {
+    readonly running: boolean;
+    readonly inFlight: number;
+    readonly processed: number;
+    readonly reaped: number;
+};
+export type WorkerRuntime = {
+    start(): Promise<void>;
+    /** Resolves once consumption has stopped and in-flight work has finished or the grace elapsed. */
+    shutdown(reason: string): Promise<{
+        readonly graceful: boolean;
+        readonly exitCode: number;
+    }>;
+    status(): WorkerStatus;
+    /** Runs one reap sweep now. Exposed so a host can trigger recovery on demand. */
+    reapOnce(): Promise<readonly Run[]>;
+};
+export declare const createWorkerRuntime: (deps: WorkerRuntimeDeps) => WorkerRuntime;
+/**
+ * Attach OS signal handlers. Separate from `createWorkerRuntime` on purpose: a library that binds to
+ * `process` merely by being constructed is hostile to embed and to test, and every test here would
+ * otherwise need real signals.
+ */
+export declare const installSignalHandlers: (runtime: WorkerRuntime, options?: {
+    readonly signals?: readonly NodeJS.Signals[];
+    readonly onExit?: (code: number) => void;
+    readonly process?: Pick<NodeJS.Process, "on">;
+}) => (() => void);
+//# sourceMappingURL=main.d.ts.map