onadit 0.0.1 → 1.0.0

package/dist/src/jobs/handlers/triage.js

@@ -0,0 +1,95 @@
+/**
+ * Triage job handler — Slice 5.
+ *
+ * Triage is a first-class job type so batches can be queued, retried,
+ * and observed independently of ingest. The handler runs every item in
+ * the payload through a single guarded TriageProvider so a per-batch
+ * cost cap and parallelism limit are enforced at the job boundary.
+ *
+ * Output: a JSON file at `data/triage-results/{jobId}.json` containing
+ * one entry per input item with the triage decision + provenance
+ * (decision, confidence, rationale, model, provider, version). Callers
+ * (e.g. follow-up routing) read this file. We deliberately don't fan
+ * out save/review-queue side effects from inside this handler — Slice 5
+ * is about the runtime, not a redesign of the routing pipeline.
+ *
+ * BatchCostExceededError aborts the job: the failure is surfaced via
+ * the job's error field, which is operator-visible.
+ */
+import path from "node:path";
+import { atomicWrite } from "../../storage/atomic.js";
+import { BatchBudget, Semaphore, withBatchGuards, } from "../../capture/batch-budget.js";
+import { BatchCostExceededError, } from "../../capture/triage-provider.js";
+import { CodexCliTriageProvider } from "../../capture/codex-cli-triage-provider.js";
+import { resolveOperatorOverrideProvider, triageMeteringModeForProvider, } from "../../providers/operator-overrides.js";
+function newDefaultProvider(_deps, _payload) {
+    // OpenAI remains available only via explicit test/providerFactory injection;
+    // the production default is intentionally Codex CLI so live capture uses the
+    // operator's existing CLI auth instead of a separate Keychain secret.
+    return new CodexCliTriageProvider();
+}
+export function createTriageHandler(deps) {
+    return async (job) => {
+        const payload = (job.payload ?? {});
+        const items = Array.isArray(payload.items) ? payload.items : [];
+        const providerOverride = resolveOperatorOverrideProvider(payload.provider_override);
+        if (items.length === 0) {
+            throw new Error("Triage job payload missing items");
+        }
+        const effectivePayload = {
+            items,
+            ...(providerOverride ? { provider_override: providerOverride } : {}),
+        };
+        const provider = (deps.providerFactory ?? newDefaultProvider)(deps, effectivePayload);
+        const meteringMode = triageMeteringModeForProvider(providerOverride ?? (deps.providerFactory ? undefined : "codex-cli"));
+        const budget = new BatchBudget(deps.openai.max_cost_per_batch_usd);
+        const semaphore = new Semaphore(deps.openai.max_parallel_requests);
+        const guarded = withBatchGuards(provider, budget, semaphore);
+        const results = [];
+        let costCapExceeded = false;
+        // Run all items in parallel — the semaphore enforces the in-flight cap.
+        await Promise.all(items.map(async (item) => {
+            try {
+                const triage = await guarded.triage({
+                    content: item.content,
+                    ...(item.source ? { source: item.source } : {}),
+                });
+                results.push({ id: item.id, triage });
+            }
+            catch (err) {
+                if (err instanceof BatchCostExceededError) {
+                    costCapExceeded = true;
+                }
+                results.push({
+                    id: item.id,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }));
+        const output = {
+            job_id: job.id,
+            completed_at: new Date().toISOString(),
+            total: items.length,
+            succeeded: results.filter((r) => r.triage !== undefined).length,
+            failed: results.filter((r) => r.error !== undefined).length,
+            cost_cap_exceeded: costCapExceeded,
+            metering_mode: meteringMode,
+            ...(meteringMode === "unmetered_codex_cli"
+                ? {
+                    spend_note: "Codex CLI historical backfill override is unmetered by OpenAI USD.",
+                }
+                : {}),
+            spent_usd: meteringMode === "openai_usd" ? budget.spent : 0,
+            cost_cap_usd: meteringMode === "openai_usd" ? budget.capUsd : 0,
+            items: results,
+        };
+        const outPath = path.join(deps.dataDir, "triage-results", `${job.id}.json`);
+        await atomicWrite(outPath, JSON.stringify(output, null, 2));
+        if (costCapExceeded) {
+            throw new BatchCostExceededError(`Triage job ${job.id} aborted: batch cost cap of $${budget.capUsd.toFixed(2)} exceeded ` +
+                `(spent $${budget.spent.toFixed(4)}, ${output.succeeded}/${output.total} completed before cap). ` +
+                `Partial results written to ${outPath}.`, budget.spent, budget.capUsd);
+        }
+    };
+}
+//# sourceMappingURL=triage.js.map

package/dist/src/jobs/handlers/triage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"triage.js","sourceRoot":"","sources":["../../../../src/jobs/handlers/triage.ts"],"names":[],"mappings":"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"}

package/dist/src/jobs/maintenance-scheduler.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Enqueues the exclusive `optimize` job when the store needs it.
+ *
+ * Checks hourly, plus once 15 s after boot. The early check matters on the
+ * first start after an upgrade: until the full-text indexes exist, keyword
+ * search falls back to scanning every row (~10 s per request on a 6k-row,
+ * 260 MB corpus; the first optimize finished in under a minute). Nothing is
+ * enqueued when the tables are already
+ * compact and indexed, and a busy exclusive slot just skips the tick, so
+ * maintenance never piles up or runs back to back.
+ */
+import type { JobQueue } from "./queue.js";
+export declare const MAINTENANCE_CHECK_INTERVAL_MS: number;
+export declare const MAINTENANCE_FIRST_CHECK_MS: number;
+export interface MaintenanceSchedulerOptions {
+    queue: Pick<JobQueue, "create">;
+    check?: () => Promise<string[]>;
+    intervalMs?: number;
+    firstCheckMs?: number;
+    now?: () => number;
+    log?: (line: string) => void;
+}
+/**
+ * One maintenance decision. "already_ran" = an optimize job for this interval
+ * already exists (at most one run per interval; later fragments wait for the
+ * next one).
+ */
+export declare function runMaintenanceCheck(opts: MaintenanceSchedulerOptions): Promise<"enqueued" | "not_needed" | "busy" | "already_ran">;
+export declare function startMaintenanceScheduler(opts: MaintenanceSchedulerOptions): () => void;
+//# sourceMappingURL=maintenance-scheduler.d.ts.map

package/dist/src/jobs/maintenance-scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"maintenance-scheduler.d.ts","sourceRoot":"","sources":["../../../src/jobs/maintenance-scheduler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAG3C,eAAO,MAAM,6BAA6B,QAAiB,CAAC;AAC5D,eAAO,MAAM,0BAA0B,QAAY,CAAC;AAEpD,MAAM,WAAW,2BAA2B;IAC1C,KAAK,EAAE,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAChC,KAAK,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAChC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9B;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,2BAA2B,GAChC,OAAO,CAAC,UAAU,GAAG,YAAY,GAAG,MAAM,GAAG,aAAa,CAAC,CAa7D;AAED,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,2BAA2B,GAAG,MAAM,IAAI,CAcvF"}

package/dist/src/jobs/maintenance-scheduler.js

@@ -0,0 +1,41 @@
+import { maintenanceReasons } from "../storage/maintenance.js";
+export const MAINTENANCE_CHECK_INTERVAL_MS = 60 * 60 * 1000;
+export const MAINTENANCE_FIRST_CHECK_MS = 15 * 1000;
+/**
+ * One maintenance decision. "already_ran" = an optimize job for this interval
+ * already exists (at most one run per interval; later fragments wait for the
+ * next one).
+ */
+export async function runMaintenanceCheck(opts) {
+    const reasons = await (opts.check ?? maintenanceReasons)();
+    if (reasons.length === 0)
+        return "not_needed";
+    const interval = opts.intervalMs ?? MAINTENANCE_CHECK_INTERVAL_MS;
+    const bucket = Math.floor((opts.now ?? Date.now)() / interval);
+    const res = await opts.queue.create("optimize", {
+        idempotency_key: `optimize:${bucket}`,
+        payload: { reasons },
+    });
+    if ("conflict" in res)
+        return "busy";
+    if (res.duplicate)
+        return "already_ran";
+    opts.log?.(`maintenance: enqueued optimize (${reasons.join("; ")})\n`);
+    return "enqueued";
+}
+export function startMaintenanceScheduler(opts) {
+    const tick = () => {
+        runMaintenanceCheck(opts).catch((err) => {
+            opts.log?.(`maintenance check failed (non-fatal): ${err instanceof Error ? err.message : String(err)}\n`);
+        });
+    };
+    const first = setTimeout(tick, opts.firstCheckMs ?? MAINTENANCE_FIRST_CHECK_MS);
+    const every = setInterval(tick, opts.intervalMs ?? MAINTENANCE_CHECK_INTERVAL_MS);
+    first.unref?.();
+    every.unref?.();
+    return () => {
+        clearTimeout(first);
+        clearInterval(every);
+    };
+}
+//# sourceMappingURL=maintenance-scheduler.js.map

package/dist/src/jobs/maintenance-scheduler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"maintenance-scheduler.js","sourceRoot":"","sources":["../../../src/jobs/maintenance-scheduler.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAE/D,MAAM,CAAC,MAAM,6BAA6B,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAC5D,MAAM,CAAC,MAAM,0BAA0B,GAAG,EAAE,GAAG,IAAI,CAAC;AAWpD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,IAAiC;IAEjC,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,IAAI,kBAAkB,CAAC,EAAE,CAAC;IAC3D,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,YAAY,CAAC;IAC9C,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,IAAI,6BAA6B,CAAC;IAClE,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,EAAE,GAAG,QAAQ,CAAC,CAAC;IAC/D,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,UAAU,EAAE;QAC9C,eAAe,EAAE,YAAY,MAAM,EAAE;QACrC,OAAO,EAAE,EAAE,OAAO,EAAE;KACrB,CAAC,CAAC;IACH,IAAI,UAAU,IAAI,GAAG;QAAE,OAAO,MAAM,CAAC;IACrC,IAAI,GAAG,CAAC,SAAS;QAAE,OAAO,aAAa,CAAC;IACxC,IAAI,CAAC,GAAG,EAAE,CAAC,mCAAmC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACvE,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,MAAM,UAAU,yBAAyB,CAAC,IAAiC;IACzE,MAAM,IAAI,GAAG,GAAS,EAAE;QACtB,mBAAmB,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;YACtC,IAAI,CAAC,GAAG,EAAE,CAAC,yCAAyC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC5G,CAAC,CAAC,CAAC;IACL,CAAC,CAAC;IACF,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,EAAE,IAAI,CAAC,YAAY,IAAI,0BAA0B,CAAC,CAAC;IAChF,MAAM,KAAK,GAAG,WAAW,CAAC,IAAI,EAAE,IAAI,CAAC,UAAU,IAAI,6BAA6B,CAAC,CAAC;IAClF,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC;IAChB,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC;IAChB,OAAO,GAAG,EAAE;QACV,YAAY,CAAC,KAAK,CAAC,CAAC;QACpB,aAAa,CAAC,KAAK,CAAC,CAAC;IACvB,CAAC,CAAC;AACJ,CAAC"}

package/dist/src/jobs/queue.d.ts

@@ -0,0 +1,157 @@
+import type { Job, JobType, CreateJobResult, JobHandler } from "./types.js";
+/**
+ * In-process job queue with:
+ * - Persistence to `queue.json` (atomic write: temp + rename)
+ * - State machine: queued -> running -> completed | failed, plus cancelled, interrupted
+ * - Idempotency checked before mutual exclusion (PRD 4.1)
+ * - Mutual exclusion for {compact, reindex, reconcile}
+ * - Crash recovery: running -> interrupted -> re-queued on startup
+ */
+export declare class JobQueue {
+    private queuePath;
+    private jobs;
+    private payloadRefs;
+    private handlers;
+    private processing;
+    private held;
+    private persistRetryTimer;
+    private startRetryTimer;
+    private startRetryDelayMs;
+    constructor(queuePath: string);
+    /**
+     * Hold processing — registerHandler and create won't auto-start queued
+     * work until releaseHold() is called. Used at startup to prevent
+     * recovered jobs from executing before the integrity check completes.
+     */
+    hold(): void;
+    /** Release hold and kick processing for any waiting jobs. */
+    releaseHold(): void;
+    /** Register a handler for a job type. Kicks processing for any queued work. */
+    registerHandler(type: JobType, handler: JobHandler): void;
+    /** Check if a handler is registered for a job type. */
+    hasHandler(type: JobType): boolean;
+    /**
+     * Load persisted queue from disk. Mark any `running` jobs as
+     * `interrupted` and re-queue them — timers/progress don't survive restart.
+     *
+     * Only jobs that were `running` at crash time get re-queued. Jobs that
+     * were already `interrupted` (from a previous recovery) are left as-is
+     * so repeated loads don't multiply work.
+     */
+    load(): Promise<void>;
+    /**
+     * Create a job. Returns `{ job, duplicate }`.
+     *
+     * Idempotency is checked first (PRD 4.1):
+     * - If a job with the same `idempotency_key` exists in
+     *   `queued | running | completed` -> return it with `duplicate: true`.
+     * - If it exists in `failed` -> create a new retry job with `retry_of`.
+     *
+     * Mutual exclusion is checked second:
+     * - If the job type is in the exclusive set and another exclusive job
+     *   is `queued | running`, return null (caller should 409).
+     */
+    create(type: JobType, opts?: {
+        idempotency_key?: string;
+        payload?: unknown;
+    }): Promise<CreateJobResult | {
+        conflict: true;
+    }>;
+    /** Get a job by ID, or undefined. */
+    get(id: string): Job | undefined;
+    /**
+     * Return all jobs whose `idempotency_key` starts with `prefix`. Used
+     * by the friend-status projection to surface inbox freshness — jobs
+     * created from the inbox watcher all use keys of the form
+     * `inbox:<hex>`, so a prefix scan answers "what's the inbox lane
+     * doing" without leaking queue internals to the route layer.
+     *
+     * Read-only iteration of the in-memory map; safe to call on a hot
+     * queue. Returns the snapshot in insertion order.
+     */
+    listByIdempotencyPrefix(prefix: string): Job[];
+    /**
+     * Check whether an idempotency key matches an existing active job.
+     * Returns the job if found in queued/running/completed state, undefined otherwise.
+     * Does NOT create or mutate anything — safe for pre-flight checks.
+     */
+    findDuplicate(idempotencyKey: string): Job | undefined;
+    /**
+     * Cancel a job.
+     * - `queued` or `interrupted` -> `cancelled`, returns the job.
+     * - `running` -> returns `{ conflict: true }`.
+     * - Others -> returns undefined (not found or not cancellable).
+     */
+    cancel(id: string): Promise<Job | {
+        conflict: true;
+    } | undefined>;
+    /**
+     * Keep the persisted ledger bounded so `JSON.stringify` can never exceed
+     * V8's max string length (the failure mode that turned every save into a
+     * 500). Two cheap, safe reductions on terminal jobs only:
+     *   1. Drop `payload` — only active jobs need it.
+     *   2. Cap how many terminal jobs we retain (oldest dropped first).
+     * Non-terminal jobs (queued/running/interrupted) are never touched.
+     * Returns true if anything changed.
+     */
+    private compactLedger;
+    /** Atomic write: temp file + rename. Ledger is compacted first so the
+     * serialized form stays well under V8's max string length. */
+    private persist;
+    private createLedgerTooLargeError;
+    private snapshotState;
+    private restoreSnapshot;
+    private payloadDir;
+    private payloadPath;
+    private payloadRefPath;
+    private payloadAbsPath;
+    private isPayloadRef;
+    private hydrateJob;
+    private readPayloadRef;
+    private serializeJobForLedger;
+    private writePayloadFile;
+    private prunePayloadRefCache;
+    private deletePayloadFilesForJob;
+    private cleanupPayloadFiles;
+    private deletePayloadPath;
+    /**
+     * Find the active job for a given idempotency key.
+     * Skip superseded jobs (those with `retried_by` set) so we always
+     * find the leaf of the retry chain, not the old parent.
+     */
+    private findByIdempotencyKey;
+    /**
+     * Create a job that bypasses the mutual exclusion check and is
+     * inserted at the front of the queue (runs before other queued work).
+     *
+     * Used exclusively for startup corruption repair: the mandatory
+     * rebuild must run before any other queued work touches storage,
+     * regardless of what else is in the queue. Other exclusive jobs
+     * naturally wait (one-at-a-time processing) and run after the
+     * rebuild against healthy storage.
+     */
+    createUrgent(type: JobType, opts?: {
+        payload?: unknown;
+    }): Promise<CreateJobResult>;
+    /** Whether any exclusive job is queued or running. */
+    hasActiveExclusiveJob(): boolean;
+    /**
+     * Return the exclusive job that is currently running, or null.
+     * Only returns jobs with status "running" — queued exclusive jobs
+     * have not entered their coordinated maintenance phase.
+     */
+    getRunningExclusiveJob(): Job | null;
+    private createRetryJob;
+    /** Process the next queued job if no job is currently running. */
+    private processNext;
+    private applyPersistedMutation;
+    private applyTerminalMutation;
+    private markPersistDirty;
+    private schedulePersistRetry;
+    private scheduleStartRetry;
+    private clearStartRetry;
+    private clearPersistRetry;
+    private retryDirtyPersist;
+    private findNextQueued;
+}
+//# sourceMappingURL=queue.d.ts.map

package/dist/src/jobs/queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.d.ts","sourceRoot":"","sources":["../../../src/jobs/queue.ts"],"names":[],"mappings":"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"}