@tangle-network/browser-agent-driver 0.30.0 → 0.32.0

package/dist/jobs/queue.js

@@ -0,0 +1,114 @@
+/**
+ * Job runner — bounded-concurrency fan-out over the audit pipeline.
+ *
+ * Synchronous in the sense that `runJob()` returns when every target has been
+ * processed (ok, failed, or skipped). Crash safety: every individual result
+ * is persisted to disk as soon as it lands, so killing the process leaves a
+ * resumable record (resume is a future addition; today the partial state
+ * is just observable).
+ *
+ * `auditFn` is injected so tests can run the queue without touching
+ * Playwright/LLMs.
+ */
+import { saveJob, appendIndexEntry } from './store.js';
+import { withRetry, DEFAULT_RETRY_POLICY } from './retry.js';
+const DEFAULT_CONCURRENCY = 2;
+export async function runJob(job, opts) {
+    const concurrency = opts.concurrency ?? job.spec.concurrency ?? DEFAULT_CONCURRENCY;
+    job.status = 'running';
+    job.startedAt = job.startedAt ?? new Date().toISOString();
+    saveJob(job, opts.dir);
+    appendIndexEntry(job, opts.dir);
+    // Resume support: skip targets that already have a non-failed result.
+    const completed = new Set();
+    if (opts.resume) {
+        for (const r of job.results) {
+            if (r.status === 'ok' || r.status === 'skipped')
+                completed.add(targetKey(r));
+        }
+    }
+    const queue = job.targets.filter(t => !completed.has(targetKey(t)));
+    let aborted = false;
+    async function worker() {
+        while (queue.length > 0 && !aborted) {
+            const target = queue.shift();
+            if (!target)
+                break;
+            const entry = await runOne(target, job.spec.audit, opts.auditFn, opts.retryPolicy, opts.onError);
+            if (entry === 'abort') {
+                aborted = true;
+                return;
+            }
+            job.results.push(entry);
+            if (entry.costUSD)
+                job.totalCostUSD = round2(job.totalCostUSD + entry.costUSD);
+            saveJob(job, opts.dir);
+        }
+    }
+    const workers = Array.from({ length: concurrency }, () => worker());
+    await Promise.all(workers);
+    job.completedAt = new Date().toISOString();
+    job.status = aborted ? 'cancelled' : finalStatus(job);
+    saveJob(job, opts.dir);
+    appendIndexEntry(job, opts.dir);
+    return job;
+}
+async function runOne(target, audit, auditFn, retryPolicy, onError) {
+    try {
+        const policy = retryPolicy === null ? undefined : (retryPolicy ?? DEFAULT_RETRY_POLICY);
+        const call = () => auditFn(target, audit);
+        const out = policy ? await withRetry(call, policy) : await call();
+        if (out.blockedReason) {
+            return {
+                ...target,
+                status: 'skipped',
+                runId: out.runId,
+                resultPath: out.resultPath,
+                error: out.blockedReason,
+                costUSD: out.costUSD,
+            };
+        }
+        return {
+            ...target,
+            status: 'ok',
+            runId: out.runId,
+            resultPath: out.resultPath,
+            rollupScore: out.rollupScore,
+            pageType: out.pageType,
+            costUSD: out.costUSD,
+            tokensPath: out.tokensPath,
+        };
+    }
+    catch (err) {
+        const error = err;
+        const decision = onError?.(target, error) ?? 'continue';
+        if (decision === 'abort')
+            return 'abort';
+        return {
+            ...target,
+            status: 'failed',
+            error: error.message,
+        };
+    }
+}
+function targetKey(t) {
+    return t.snapshotUrl ?? t.url;
+}
+function finalStatus(job) {
+    const total = job.results.length;
+    if (total === 0)
+        return 'failed';
+    const ok = job.results.filter(r => r.status === 'ok').length;
+    const failed = job.results.filter(r => r.status === 'failed').length;
+    // 'skipped' is a deterministic non-failure (e.g. anti-bot block detected).
+    // Treat it as a clean outcome — we recorded the reason and moved on.
+    if (ok === 0 && failed > 0)
+        return 'failed';
+    if (failed > 0 || ok < total)
+        return 'partial';
+    return 'completed';
+}
+function round2(n) {
+    return Math.round(n * 100) / 100;
+}
+//# sourceMappingURL=queue.js.map

package/dist/jobs/queue.js.map

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

package/dist/jobs/retry.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Retry-with-backoff helper used by the jobs queue. Deliberately not an LLM
+ * decision — exponential backoff with jitter is a protocol, not a judgment
+ * call. Wrapping it in prose adds latency without adding intelligence.
+ *
+ * Default policy:
+ *   - 3 attempts total (one initial + two retries)
+ *   - Base delay 500ms, doubles each attempt, capped at 5s
+ *   - Adds ±20% jitter so concurrent workers don't synchronize their retries
+ *   - Retries network errors, HTTP 429, HTTP 5xx, and timeouts
+ *   - Does NOT retry HTTP 4xx, anti-bot blocks, or schema-validation errors
+ */
+export interface RetryPolicy {
+    maxAttempts: number;
+    baseDelayMs: number;
+    maxDelayMs: number;
+    /** Returns true if the error is retryable. */
+    isRetryable: (err: Error) => boolean;
+    /** Override default backoff (for tests). */
+    backoffFn?: (attempt: number, base: number, cap: number) => number;
+    /** Hook fired before each retry — useful for telemetry. */
+    onRetry?: (attempt: number, err: Error, delayMs: number) => void;
+}
+/**
+ * Whitelist-only: an error is retryable iff it matches one of the patterns
+ * above. Anything else (4xx, anti-bot, schema-validation, unknown errors) is
+ * deterministic and we don't waste round-trips retrying it.
+ */
+export declare function isRetryableDefault(err: Error): boolean;
+export declare const DEFAULT_RETRY_POLICY: RetryPolicy;
+/**
+ * Run `fn` with retry-on-retryable-failure. Throws the last error after
+ * `maxAttempts` exhausted, or immediately on a non-retryable error.
+ */
+export declare function withRetry<T>(fn: () => Promise<T>, policy?: RetryPolicy): Promise<T>;
+//# sourceMappingURL=retry.d.ts.map

package/dist/jobs/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/jobs/retry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,WAAW;IAC1B,WAAW,EAAE,MAAM,CAAA;IACnB,WAAW,EAAE,MAAM,CAAA;IACnB,UAAU,EAAE,MAAM,CAAA;IAClB,8CAA8C;IAC9C,WAAW,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,OAAO,CAAA;IACpC,4CAA4C;IAC5C,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,MAAM,CAAA;IAClE,2DAA2D;IAC3D,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;CACjE;AAiBD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,KAAK,GAAG,OAAO,CAEtD;AAED,eAAO,MAAM,oBAAoB,EAAE,WAKlC,CAAA;AAQD;;;GAGG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,GAAE,WAAkC,GAAG,OAAO,CAAC,CAAC,CAAC,CAmB/G"}

package/dist/jobs/retry.js

@@ -0,0 +1,77 @@
+/**
+ * Retry-with-backoff helper used by the jobs queue. Deliberately not an LLM
+ * decision — exponential backoff with jitter is a protocol, not a judgment
+ * call. Wrapping it in prose adds latency without adding intelligence.
+ *
+ * Default policy:
+ *   - 3 attempts total (one initial + two retries)
+ *   - Base delay 500ms, doubles each attempt, capped at 5s
+ *   - Adds ±20% jitter so concurrent workers don't synchronize their retries
+ *   - Retries network errors, HTTP 429, HTTP 5xx, and timeouts
+ *   - Does NOT retry HTTP 4xx, anti-bot blocks, or schema-validation errors
+ */
+const RETRYABLE_PATTERNS = [
+    /\b429\b/, // rate limit
+    /\b5\d\d\b/, // 5xx
+    /timeout/i,
+    /timed out/i,
+    /etimedout/i,
+    /econnreset/i,
+    /econnrefused/i,
+    /enotfound/i,
+    /socket hang up/i,
+    /network/i,
+    /fetch failed/i,
+    /CDX returned 5\d\d/i,
+];
+/**
+ * Whitelist-only: an error is retryable iff it matches one of the patterns
+ * above. Anything else (4xx, anti-bot, schema-validation, unknown errors) is
+ * deterministic and we don't waste round-trips retrying it.
+ */
+export function isRetryableDefault(err) {
+    return RETRYABLE_PATTERNS.some(re => re.test(err.message));
+}
+export const DEFAULT_RETRY_POLICY = {
+    maxAttempts: 3,
+    baseDelayMs: 500,
+    maxDelayMs: 5000,
+    isRetryable: isRetryableDefault,
+};
+function defaultBackoff(attempt, base, cap) {
+    const exp = Math.min(base * 2 ** attempt, cap);
+    const jitter = exp * (0.8 + Math.random() * 0.4); // ±20%
+    return Math.round(jitter);
+}
+/**
+ * Run `fn` with retry-on-retryable-failure. Throws the last error after
+ * `maxAttempts` exhausted, or immediately on a non-retryable error.
+ */
+export async function withRetry(fn, policy = DEFAULT_RETRY_POLICY) {
+    const max = Math.max(1, policy.maxAttempts);
+    const backoff = policy.backoffFn ?? defaultBackoff;
+    let lastErr;
+    for (let attempt = 0; attempt < max; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            lastErr = err;
+            if (!policy.isRetryable(lastErr))
+                throw lastErr;
+            if (attempt === max - 1)
+                break;
+            const delay = backoff(attempt, policy.baseDelayMs, policy.maxDelayMs);
+            policy.onRetry?.(attempt + 1, lastErr, delay);
+            await sleep(delay);
+        }
+    }
+    // Tag the final error so callers can tell retried-and-failed apart from never-retried.
+    if (lastErr)
+        lastErr.message = `[after ${max} attempts] ${lastErr.message}`;
+    throw lastErr ?? new Error('withRetry: no error captured but no result returned');
+}
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=retry.js.map

package/dist/jobs/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../src/jobs/retry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAcH,MAAM,kBAAkB,GAAG;IACzB,SAAS,EAAE,aAAa;IACxB,WAAW,EAAE,MAAM;IACnB,UAAU;IACV,YAAY;IACZ,YAAY;IACZ,aAAa;IACb,eAAe;IACf,YAAY;IACZ,iBAAiB;IACjB,UAAU;IACV,eAAe;IACf,qBAAqB;CACtB,CAAA;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAU;IAC3C,OAAO,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAA;AAC5D,CAAC;AAED,MAAM,CAAC,MAAM,oBAAoB,GAAgB;IAC/C,WAAW,EAAE,CAAC;IACd,WAAW,EAAE,GAAG;IAChB,UAAU,EAAE,IAAI;IAChB,WAAW,EAAE,kBAAkB;CAChC,CAAA;AAED,SAAS,cAAc,CAAC,OAAe,EAAE,IAAY,EAAE,GAAW;IAChE,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,IAAI,OAAO,EAAE,GAAG,CAAC,CAAA;IAC9C,MAAM,MAAM,GAAG,GAAG,GAAG,CAAC,GAAG,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,GAAG,CAAC,CAAA,CAAC,OAAO;IACxD,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAA;AAC3B,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAI,EAAoB,EAAE,SAAsB,oBAAoB;IACjG,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,WAAW,CAAC,CAAA;IAC3C,MAAM,OAAO,GAAG,MAAM,CAAC,SAAS,IAAI,cAAc,CAAA;IAClD,IAAI,OAA0B,CAAA;IAC9B,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,GAAG,GAAG,EAAE,OAAO,EAAE,EAAE,CAAC;QAC/C,IAAI,CAAC;YACH,OAAO,MAAM,EAAE,EAAE,CAAA;QACnB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,GAAG,GAAY,CAAA;YACtB,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC;gBAAE,MAAM,OAAO,CAAA;YAC/C,IAAI,OAAO,KAAK,GAAG,GAAG,CAAC;gBAAE,MAAK;YAC9B,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,UAAU,CAAC,CAAA;YACrE,MAAM,CAAC,OAAO,EAAE,CAAC,OAAO,GAAG,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,CAAA;YAC7C,MAAM,KAAK,CAAC,KAAK,CAAC,CAAA;QACpB,CAAC;IACH,CAAC;IACD,uFAAuF;IACvF,IAAI,OAAO;QAAE,OAAO,CAAC,OAAO,GAAG,UAAU,GAAG,cAAc,OAAO,CAAC,OAAO,EAAE,CAAA;IAC3E,MAAM,OAAO,IAAI,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAA;AACnF,CAAC;AAED,SAAS,KAAK,CAAC,EAAU;IACvB,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAA;AACxD,CAAC"}

package/dist/jobs/store.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Job store — whole-file JSON per job + an append-only index for listing.
+ *
+ * Layout:
+ *   ~/.bad/jobs/<jobId>.json      — Job record (atomic write via tmp + rename)
+ *   ~/.bad/jobs/index.jsonl       — append-only one line per job ({jobId, status, createdAt, label})
+ *
+ * Whole-file rewrite is intentional: a job is a single coherent record with
+ * monotonically-extending `results[]`. Append-only at the entry level would
+ * duplicate target rows; append-only at the file level would force readers
+ * to fold N updates into one logical record. Atomic rename gives us crash
+ * safety without that complexity.
+ */
+import type { Job, JobStatus } from './types.js';
+export declare function jobsDir(override?: string): string;
+export declare function jobPath(jobId: string, dir?: string): string;
+export declare function newJobId(now?: Date): string;
+export declare function saveJob(job: Job, dir?: string): void;
+export declare function loadJob(jobId: string, dir?: string): Job | null;
+export declare function appendIndexEntry(job: Job, dir?: string): void;
+export interface JobIndexEntry {
+    jobId: string;
+    status: JobStatus;
+    createdAt: string;
+    label: string | null;
+    targetCount: number;
+}
+/** Reads the index file. Later entries for the same jobId override earlier ones. */
+export declare function listJobs(dir?: string): JobIndexEntry[];
+export declare function updateJobStatus(jobId: string, status: JobStatus, dir?: string): Job | null;
+//# sourceMappingURL=store.d.ts.map

package/dist/jobs/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/jobs/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,OAAO,KAAK,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAIhD,wBAAgB,OAAO,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAEjD;AAMD,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAE3D;AAMD,wBAAgB,QAAQ,CAAC,GAAG,GAAE,IAAiB,GAAG,MAAM,CAIvD;AAED,wBAAgB,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAMpD;AAED,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,GAAG,GAAG,IAAI,CAI/D;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAW7D;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,SAAS,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,oFAAoF;AACpF,wBAAgB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,aAAa,EAAE,CActD;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,GAAG,GAAG,IAAI,CAW1F"}

package/dist/jobs/store.js

@@ -0,0 +1,92 @@
+/**
+ * Job store — whole-file JSON per job + an append-only index for listing.
+ *
+ * Layout:
+ *   ~/.bad/jobs/<jobId>.json      — Job record (atomic write via tmp + rename)
+ *   ~/.bad/jobs/index.jsonl       — append-only one line per job ({jobId, status, createdAt, label})
+ *
+ * Whole-file rewrite is intentional: a job is a single coherent record with
+ * monotonically-extending `results[]`. Append-only at the entry level would
+ * duplicate target rows; append-only at the file level would force readers
+ * to fold N updates into one logical record. Atomic rename gives us crash
+ * safety without that complexity.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+const DEFAULT_DIR = path.join(os.homedir(), '.bad', 'jobs');
+export function jobsDir(override) {
+    return override ?? DEFAULT_DIR;
+}
+function ensureDir(dir) {
+    fs.mkdirSync(dir, { recursive: true });
+}
+export function jobPath(jobId, dir) {
+    return path.join(jobsDir(dir), `${jobId}.json`);
+}
+function indexPath(dir) {
+    return path.join(jobsDir(dir), 'index.jsonl');
+}
+export function newJobId(now = new Date()) {
+    const stamp = now.toISOString().replace(/[-:.]/g, '').slice(0, 15); // YYYYMMDDTHHMMSS
+    const rand = Math.random().toString(36).slice(2, 8);
+    return `job_${stamp}_${rand}`;
+}
+export function saveJob(job, dir) {
+    const target = jobPath(job.jobId, dir);
+    ensureDir(path.dirname(target));
+    const tmp = `${target}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(job, null, 2));
+    fs.renameSync(tmp, target);
+}
+export function loadJob(jobId, dir) {
+    const target = jobPath(jobId, dir);
+    if (!fs.existsSync(target))
+        return null;
+    return JSON.parse(fs.readFileSync(target, 'utf-8'));
+}
+export function appendIndexEntry(job, dir) {
+    const file = indexPath(dir);
+    ensureDir(path.dirname(file));
+    const line = JSON.stringify({
+        jobId: job.jobId,
+        status: job.status,
+        createdAt: job.createdAt,
+        label: job.spec.label ?? null,
+        targetCount: job.targets.length,
+    });
+    fs.appendFileSync(file, line + '\n');
+}
+/** Reads the index file. Later entries for the same jobId override earlier ones. */
+export function listJobs(dir) {
+    const file = indexPath(dir);
+    if (!fs.existsSync(file))
+        return [];
+    const lines = fs.readFileSync(file, 'utf-8').split('\n').filter(Boolean);
+    const map = new Map();
+    for (const line of lines) {
+        try {
+            const entry = JSON.parse(line);
+            map.set(entry.jobId, entry);
+        }
+        catch {
+            // Skip malformed lines — index is best-effort.
+        }
+    }
+    return Array.from(map.values()).sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+}
+export function updateJobStatus(jobId, status, dir) {
+    const job = loadJob(jobId, dir);
+    if (!job)
+        return null;
+    job.status = status;
+    if (status === 'running' && !job.startedAt)
+        job.startedAt = new Date().toISOString();
+    if (status === 'completed' || status === 'failed' || status === 'cancelled' || status === 'partial') {
+        job.completedAt = new Date().toISOString();
+    }
+    saveJob(job, dir);
+    appendIndexEntry(job, dir);
+    return job;
+}
+//# sourceMappingURL=store.js.map

package/dist/jobs/store.js.map

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

package/dist/jobs/types.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Job orchestration types — RFC-003: comparative-audit jobs.
+ *
+ * A job is a declarative spec ("audit these N URLs, optionally with M historical
+ * snapshots each") that fans out to the existing design-audit pipeline and
+ * persists the aggregate result so report generation can run later.
+ *
+ * Persistence: append-only JSONL at `~/.bad/jobs/<jobId>.json` (whole-file
+ * rewrites are fine — jobs are small) plus a one-line index entry at
+ * `~/.bad/jobs/index.jsonl` for fast listing.
+ */
+import type { AudienceTag, ModalityTag, RegulatoryContextTag, AudienceVulnerabilityTag } from '../design/audit/score-types.js';
+export type JobKind = 'comparative-audit';
+export type JobStatus = 'queued' | 'running' | 'partial' | 'completed' | 'failed' | 'cancelled';
+export type DiscoverSource = 'list' | 'wayback';
+/** What targets to audit. `list` = explicit URLs; `wayback` = expand each URL into historical snapshots. */
+export interface DiscoverSpec {
+    source: DiscoverSource;
+    /** Explicit list of URLs (always required — it's the seed even for wayback). */
+    urls: string[];
+    /** wayback only: how many evenly-spaced snapshots to fetch per URL. Default 5. */
+    snapshotsPerUrl?: number;
+    /** wayback only: ISO date lower bound (e.g. "2010-01-01"). */
+    since?: string;
+    /** wayback only: ISO date upper bound (e.g. "2026-01-01"). */
+    until?: string;
+}
+/** Pass-through audit options — mirrors the design-audit CLI flags. */
+export interface AuditOptions {
+    pages?: number;
+    modality?: 'html' | 'ios' | 'android';
+    audience?: AudienceTag[];
+    audienceVulnerability?: AudienceVulnerabilityTag[];
+    modalityTag?: ModalityTag[];
+    regulatoryContext?: RegulatoryContextTag[];
+    headless?: boolean;
+    skipEthics?: boolean;
+    /**
+     * Layer 8 add-on: also run the deterministic brand/design-token extractor at
+     * every target. Adds ~10s/target (no LLM). Output lands at
+     * `<resultPath dir>/tokens.json` and is surfaced via `JobResultEntry.tokensPath`.
+     */
+    extractTokens?: boolean;
+}
+export interface JobSpec {
+    kind: JobKind;
+    discover: DiscoverSpec;
+    audit?: AuditOptions;
+    /** Bounded concurrency for the audit fan-out. Default 2 — Playwright + LLM rate limits cap real-world throughput. */
+    concurrency?: number;
+    /** Hard cost cap. The job aborts pre-flight if estimated cost exceeds this. */
+    maxCostUSD?: number;
+    /** Free-form label for humans (shows up in `bad jobs list`). */
+    label?: string;
+}
+/** One target = one (url, optional snapshot) pair the auditor will run on. */
+export interface JobTarget {
+    /** The original seed URL. For non-wayback discovery, this is also the audit URL. */
+    url: string;
+    /** For wayback targets: the actual snapshot URL passed to the audit. */
+    snapshotUrl?: string;
+    /** For wayback targets: ISO datetime when the snapshot was captured. */
+    capturedAt?: string;
+}
+export type JobResultStatus = 'ok' | 'failed' | 'skipped';
+export interface JobResultEntry extends JobTarget {
+    status: JobResultStatus;
+    /** runId of the design-audit run when status === 'ok'. */
+    runId?: string;
+    /** Path to the run's report.json (relative to cwd or absolute). */
+    resultPath?: string;
+    /** Failure reason when status === 'failed' or 'skipped'. */
+    error?: string;
+    /** Estimated USD cost of this audit (if available from telemetry). */
+    costUSD?: number;
+    /** Roll-up score copied out of the report for fast aggregation queries. */
+    rollupScore?: number;
+    /** Page-type classification. */
+    pageType?: string;
+    /** Path to the tokens.json from the brand-kit extractor (when extractTokens=true). */
+    tokensPath?: string;
+}
+export interface Job {
+    jobId: string;
+    spec: JobSpec;
+    status: JobStatus;
+    createdAt: string;
+    startedAt?: string;
+    completedAt?: string;
+    /** All discovered targets (length = number of audits the job will / did run). */
+    targets: JobTarget[];
+    /** Per-target outcome. Length matches `targets` once the job has progressed past discovery. */
+    results: JobResultEntry[];
+    /** Sum of `results[*].costUSD` for completed entries. */
+    totalCostUSD: number;
+    /** Free-form notes (errors, warnings, telemetry summary). */
+    notes?: string[];
+}
+export interface CostEstimate {
+    targetCount: number;
+    estimatedTotalUSD: number;
+    perAuditUSD: number;
+    /** Whether the estimate is above `spec.maxCostUSD`. */
+    exceedsCap: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/jobs/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/jobs/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,gCAAgC,CAAA;AAE9H,MAAM,MAAM,OAAO,GAAG,mBAAmB,CAAA;AAEzC,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,WAAW,CAAA;AAE/F,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,SAAS,CAAA;AAE/C,4GAA4G;AAC5G,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,cAAc,CAAA;IACtB,gFAAgF;IAChF,IAAI,EAAE,MAAM,EAAE,CAAA;IACd,kFAAkF;IAClF,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,uEAAuE;AACvE,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,CAAA;IACrC,QAAQ,CAAC,EAAE,WAAW,EAAE,CAAA;IACxB,qBAAqB,CAAC,EAAE,wBAAwB,EAAE,CAAA;IAClD,WAAW,CAAC,EAAE,WAAW,EAAE,CAAA;IAC3B,iBAAiB,CAAC,EAAE,oBAAoB,EAAE,CAAA;IAC1C,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB;;;;OAIG;IACH,aAAa,CAAC,EAAE,OAAO,CAAA;CACxB;AAED,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,OAAO,CAAA;IACb,QAAQ,EAAE,YAAY,CAAA;IACtB,KAAK,CAAC,EAAE,YAAY,CAAA;IACpB,qHAAqH;IACrH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,+EAA+E;IAC/E,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,gEAAgE;IAChE,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,8EAA8E;AAC9E,MAAM,WAAW,SAAS;IACxB,oFAAoF;IACpF,GAAG,EAAE,MAAM,CAAA;IACX,wEAAwE;IACxE,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,wEAAwE;IACxE,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,MAAM,eAAe,GAAG,IAAI,GAAG,QAAQ,GAAG,SAAS,CAAA;AAEzD,MAAM,WAAW,cAAe,SAAQ,SAAS;IAC/C,MAAM,EAAE,eAAe,CAAA;IACvB,0DAA0D;IAC1D,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,mEAAmE;IACnE,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,4DAA4D;IAC5D,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,sEAAsE;IACtE,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,2EAA2E;IAC3E,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,gCAAgC;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,sFAAsF;IACtF,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,GAAG;IAClB,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,OAAO,CAAA;IACb,MAAM,EAAE,SAAS,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,iFAAiF;IACjF,OAAO,EAAE,SAAS,EAAE,CAAA;IACpB,+FAA+F;IAC/F,OAAO,EAAE,cAAc,EAAE,CAAA;IACzB,yDAAyD;IACzD,YAAY,EAAE,MAAM,CAAA;IACpB,6DAA6D;IAC7D,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;CACjB;AAED,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,MAAM,CAAA;IACnB,iBAAiB,EAAE,MAAM,CAAA;IACzB,WAAW,EAAE,MAAM,CAAA;IACnB,uDAAuD;IACvD,UAAU,EAAE,OAAO,CAAA;CACpB"}

package/dist/jobs/types.js

@@ -0,0 +1,13 @@
+/**
+ * Job orchestration types — RFC-003: comparative-audit jobs.
+ *
+ * A job is a declarative spec ("audit these N URLs, optionally with M historical
+ * snapshots each") that fans out to the existing design-audit pipeline and
+ * persists the aggregate result so report generation can run later.
+ *
+ * Persistence: append-only JSONL at `~/.bad/jobs/<jobId>.json` (whole-file
+ * rewrites are fine — jobs are small) plus a one-line index entry at
+ * `~/.bad/jobs/index.jsonl` for fast listing.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/jobs/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/jobs/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}

package/dist/reports/aggregate.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Deterministic aggregation over a job's per-target audit results.
+ *
+ * Every number that shows up in a report flows through here — never through
+ * an LLM. The narration layer can describe / contextualize / dramatize, but
+ * counts, scores, deltas, and rankings are all computed here. Same pattern
+ * we use for the audit patches contract: agent narrates, code computes.
+ */
+import type { Job } from '../jobs/types.js';
+import type { AggregateRow, CompareRunsResult, LongitudinalRow } from './types.js';
+/**
+ * Read each ok result's `report.json` from disk and project to AggregateRow.
+ * Skipped/failed entries become rows with `rollupScore: NaN` so callers can
+ * filter them — keeping them in the list preserves index alignment with
+ * `job.results` for tools that want to drill in.
+ */
+export declare function aggregateJob(job: Job): AggregateRow[];
+export interface LeaderboardOptions {
+    /** Filter by page type (e.g. only saas-app rows). */
+    byType?: string;
+    /** Top N entries. Default = no cap. */
+    topN?: number;
+    /** Sort direction. Default 'desc' (highest first). */
+    direction?: 'asc' | 'desc';
+}
+export declare function leaderboard(rows: AggregateRow[], opts?: LeaderboardOptions): AggregateRow[];
+/** Longitudinal view: all snapshots for one URL, sorted by capture time. */
+export declare function longitudinalFor(rows: AggregateRow[], url: string): LongitudinalRow[];
+export declare function compareRuns(a: AggregateRow, b: AggregateRow): CompareRunsResult;
+/** Group rows into tier buckets for "top 10 vs 100-200" style reports. */
+export interface TierBucket {
+    label: string;
+    rows: AggregateRow[];
+    meanScore: number;
+    medianScore: number;
+}
+export declare function tierBuckets(rows: AggregateRow[], boundaries: number[]): TierBucket[];
+//# sourceMappingURL=aggregate.d.ts.map

package/dist/reports/aggregate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aggregate.d.ts","sourceRoot":"","sources":["../../src/reports/aggregate.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,GAAG,EAAkB,MAAM,kBAAkB,CAAA;AAE3D,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAkB,eAAe,EAAE,MAAM,YAAY,CAAA;AAkBlG;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,GAAG,GAAG,YAAY,EAAE,CAMrD;AAwCD,MAAM,WAAW,kBAAkB;IACjC,qDAAqD;IACrD,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,uCAAuC;IACvC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,sDAAsD;IACtD,SAAS,CAAC,EAAE,KAAK,GAAG,MAAM,CAAA;CAC3B;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,YAAY,EAAE,EAAE,IAAI,GAAE,kBAAuB,GAAG,YAAY,EAAE,CAQ/F;AAED,4EAA4E;AAC5E,wBAAgB,eAAe,CAAC,IAAI,EAAE,YAAY,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,eAAe,EAAE,CAUpF;AAED,wBAAgB,WAAW,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,YAAY,GAAG,iBAAiB,CAkB/E;AAED,0EAA0E;AAC1E,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,YAAY,EAAE,CAAA;IACpB,SAAS,EAAE,MAAM,CAAA;IACjB,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,YAAY,EAAE,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,UAAU,EAAE,CAoBpF"}