agent-bober 0.17.1 → 0.19.0

package/dist/research/runner.d.ts

@@ -0,0 +1,80 @@
+/**
+ * runResearchJob — deterministic multi-model research runner.
+ *
+ * Flow:
+ *   1. Resolve >=2 distinct provider/model blocks via model-diversity.
+ *   2. Query each block via the injected queryModel dep (no SDK imports here).
+ *   3. Collect labelled contributions.
+ *   4. Serialize into a markdown vault note and write it to disk.
+ *   5. Build one Finding and emit it via the injected findingSink EXACTLY once.
+ *   6. Return { notePath, models, finding }.
+ *
+ * PURE deps-injection contract:
+ *   - queryModel  — provider-agnostic; CLI binds to createClient().chat()
+ *   - findingSink — hub writer; CLI binds to ingestFinding(store, f, {now})
+ *   - now         — injected ISO timestamp; never call new Date() in this module
+ *   - vaultRoot   — target vault dir; must be writable by the caller
+ *
+ * Clock discipline: `now` is always stamped at the CLI .action() boundary.
+ * This module never calls new Date() or Date.now().
+ */
+import type { Finding } from "../hub/finding.js";
+import type { RoleProviderBlock } from "../fleet/tier-policy.js";
+import type { ResearchJob } from "./types.js";
+import { type ModelContribution } from "./note-writer.js";
+import { type RetrievalClient } from "./online-retrieval.js";
+import type { ResearchEgressGuard } from "./egress.js";
+/** Provider-agnostic query function — wraps a single LLM chat call. */
+export type QueryModel = (block: RoleProviderBlock, prompt: string) => Promise<string>;
+/** Hub Finding emitter — called exactly once after the note is written. */
+export type FindingSink = (finding: Finding) => Promise<void>;
+/** Injected dependencies for runResearchJob. */
+export interface RunDeps {
+    /** Provider-agnostic query fn — NO SDK import; CLI binds to createClient(). */
+    queryModel: QueryModel;
+    /** Finding sink — CLI binds to ingestFinding(store, f, { now }). */
+    findingSink: FindingSink;
+    /** Injected ISO timestamp — stamped at the CLI boundary; never read the clock here. */
+    now: string;
+    /** Writable vault root directory. */
+    vaultRoot: string;
+    /** Research egress guard — when absent, retrieval is skipped entirely (zero outbound). */
+    egress?: ResearchEgressGuard;
+    /** Injected retrieval client — when absent, retrieval is skipped entirely. */
+    retrievalClient?: RetrievalClient;
+}
+/** Result returned by runResearchJob. */
+export interface RunResult {
+    /** Absolute path of the written vault note. */
+    notePath: string;
+    /** Canonical model labels queried (e.g. ["openai-compat/deepseek", "openai-compat/grok"]). */
+    models: string[];
+    /** The Finding emitted to the hub. */
+    finding: Finding;
+}
+/**
+ * A domain-specific analyzer can post-process contributions to produce a
+ * custom Finding. If no analyzer is registered for a domain, the generic
+ * default is used (multi-model synthesis with neutral defaults).
+ *
+ * bober: registry is a simple Map; swap for a plugin loader if the number of
+ *        domains grows beyond ~5 (the current set is research/medical/coding).
+ *        Do NOT register src/medical/ analyzers here — that is a future sprint.
+ */
+export type DomainAnalyzer = (job: ResearchJob, contributions: ModelContribution[], now: string) => Finding;
+/**
+ * Register a domain-specific analyzer. The key is the domain string
+ * (e.g. "medical"). Overwrites any existing registration for that domain.
+ * Called by domain modules (never by src/medical/ in this sprint).
+ */
+export declare function registerAnalyzer(domain: string, analyzer: DomainAnalyzer): void;
+/**
+ * Execute one research job: query >=2 distinct model blocks, write a vault
+ * note, and emit exactly ONE Finding to the injected sink.
+ *
+ * @param job  - The stored ResearchJob definition.
+ * @param deps - Injected dependencies (queryModel, findingSink, now, vaultRoot).
+ * @returns    RunResult with the note path, model labels, and the emitted Finding.
+ */
+export declare function runResearchJob(job: ResearchJob, deps: RunDeps): Promise<RunResult>;
+//# sourceMappingURL=runner.d.ts.map

package/dist/research/runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../src/research/runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAMH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AACjE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,OAAO,EAGL,KAAK,iBAAiB,EACvB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAY,KAAK,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACvE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAIvD,uEAAuE;AACvE,MAAM,MAAM,UAAU,GAAG,CAAC,KAAK,EAAE,iBAAiB,EAAE,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAEvF,2EAA2E;AAC3E,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAE9D,gDAAgD;AAChD,MAAM,WAAW,OAAO;IACtB,+EAA+E;IAC/E,UAAU,EAAE,UAAU,CAAC;IACvB,oEAAoE;IACpE,WAAW,EAAE,WAAW,CAAC;IACzB,uFAAuF;IACvF,GAAG,EAAE,MAAM,CAAC;IACZ,qCAAqC;IACrC,SAAS,EAAE,MAAM,CAAC;IAElB,0FAA0F;IAC1F,MAAM,CAAC,EAAE,mBAAmB,CAAC;IAC7B,8EAA8E;IAC9E,eAAe,CAAC,EAAE,eAAe,CAAC;CACnC;AAED,yCAAyC;AACzC,MAAM,WAAW,SAAS;IACxB,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAC;IACjB,8FAA8F;IAC9F,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,sCAAsC;IACtC,OAAO,EAAE,OAAO,CAAC;CAClB;AAID;;;;;;;;GAQG;AACH,MAAM,MAAM,cAAc,GAAG,CAC3B,GAAG,EAAE,WAAW,EAChB,aAAa,EAAE,iBAAiB,EAAE,EAClC,GAAG,EAAE,MAAM,KACR,OAAO,CAAC;AAIb;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,GAAG,IAAI,CAE/E;AA0CD;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,WAAW,EAChB,IAAI,EAAE,OAAO,GACZ,OAAO,CAAC,SAAS,CAAC,CAmDpB"}

package/dist/research/runner.js

@@ -0,0 +1,115 @@
+/**
+ * runResearchJob — deterministic multi-model research runner.
+ *
+ * Flow:
+ *   1. Resolve >=2 distinct provider/model blocks via model-diversity.
+ *   2. Query each block via the injected queryModel dep (no SDK imports here).
+ *   3. Collect labelled contributions.
+ *   4. Serialize into a markdown vault note and write it to disk.
+ *   5. Build one Finding and emit it via the injected findingSink EXACTLY once.
+ *   6. Return { notePath, models, finding }.
+ *
+ * PURE deps-injection contract:
+ *   - queryModel  — provider-agnostic; CLI binds to createClient().chat()
+ *   - findingSink — hub writer; CLI binds to ingestFinding(store, f, {now})
+ *   - now         — injected ISO timestamp; never call new Date() in this module
+ *   - vaultRoot   — target vault dir; must be writable by the caller
+ *
+ * Clock discipline: `now` is always stamped at the CLI .action() boundary.
+ * This module never calls new Date() or Date.now().
+ */
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { createHash } from "node:crypto";
+import { diverseBlocks, modelLabel } from "./model-diversity.js";
+import { researchNotePath, serializeResearchNote, } from "./note-writer.js";
+import { retrieve } from "./online-retrieval.js";
+const analyzerRegistry = new Map();
+/**
+ * Register a domain-specific analyzer. The key is the domain string
+ * (e.g. "medical"). Overwrites any existing registration for that domain.
+ * Called by domain modules (never by src/medical/ in this sprint).
+ */
+export function registerAnalyzer(domain, analyzer) {
+    analyzerRegistry.set(domain, analyzer);
+}
+// ── Helpers ───────────────────────────────────────────────────────────
+/** Derive a content-stable Finding id from domain|title|kind. */
+function deriveFindingId(domain, title, kind) {
+    return createHash("sha256")
+        .update(`${domain}|${title}|${kind}`)
+        .digest("hex")
+        .slice(0, 16);
+}
+/** Build the generic Finding for a completed research run. */
+function buildFinding(job, contributions, now) {
+    const domain = job.domain ?? "research";
+    const title = `Research: ${job.question}`;
+    const kind = "watch";
+    const id = deriveFindingId(domain, title, kind);
+    // evidence = per-model contribution labels (cited sources)
+    const evidence = contributions.map((c) => `${c.label}: ${c.text.slice(0, 120)}`);
+    return {
+        id,
+        domain,
+        title,
+        kind,
+        urgency: 2,
+        severity: 2,
+        evidence,
+        surfacedAt: now,
+        tags: ["research", ...(job.domain !== undefined ? [`domain:${job.domain}`] : [])],
+        status: "open",
+    };
+}
+// ── Runner ────────────────────────────────────────────────────────────
+/**
+ * Execute one research job: query >=2 distinct model blocks, write a vault
+ * note, and emit exactly ONE Finding to the injected sink.
+ *
+ * @param job  - The stored ResearchJob definition.
+ * @param deps - Injected dependencies (queryModel, findingSink, now, vaultRoot).
+ * @returns    RunResult with the note path, model labels, and the emitted Finding.
+ */
+export async function runResearchJob(job, deps) {
+    const { queryModel, findingSink, now, vaultRoot } = deps;
+    // 1. Resolve >=2 distinct provider/model blocks (sc-2-1)
+    const blocks = diverseBlocks(job.tier);
+    // Guard: need at least 2 distinct blocks to satisfy sc-2-1
+    if (blocks.length < 2) {
+        throw new Error(`model-diversity returned ${blocks.length} block(s); need >=2 for a multi-model run`);
+    }
+    // 2. Query each block with a research prompt
+    const prompt = `Answer the following research question concisely and accurately:\n\n${job.question}`;
+    const contributions = [];
+    for (const block of blocks) {
+        const text = await queryModel(block, prompt);
+        contributions.push({ label: modelLabel(block), text });
+    }
+    // ── Sprint 3: gated online-research retrieval (axis OFF default => skipped entirely) ──
+    // When egress is absent or axis is off: sourceUrls stays [] and the retrieval client
+    // is NEVER constructed or invoked — zero outbound requests (sc-3-3 off-path proof).
+    let sourceUrls = [];
+    if (deps.egress?.isAllowed("online-research") === true && deps.retrievalClient !== undefined) {
+        const sources = await retrieve(job.question, deps.retrievalClient);
+        sourceUrls = sources.map((s) => s.url);
+    }
+    // 3. Build the note content (PURE — no fs)
+    const labels = contributions.map((c) => c.label);
+    const noteContent = serializeResearchNote(job, labels, contributions, now, sourceUrls);
+    // 4. Write the note to disk (sc-2-2)
+    // Marker = first 12 chars of job id (stable slug for the filename)
+    const marker = job.id.slice(0, 12);
+    const notePath = researchNotePath(vaultRoot, marker, now);
+    await mkdir(dirname(notePath), { recursive: true });
+    await writeFile(notePath, noteContent, "utf-8");
+    // 5. Build and emit exactly ONE Finding (sc-2-3)
+    const domain = job.domain ?? "research";
+    const analyzer = analyzerRegistry.get(domain);
+    const finding = analyzer !== undefined
+        ? analyzer(job, contributions, now)
+        : buildFinding(job, contributions, now);
+    await findingSink(finding);
+    return { notePath, models: labels, finding };
+}
+//# sourceMappingURL=runner.js.map

package/dist/research/runner.js.map

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

package/dist/research/scheduler.d.ts

@@ -0,0 +1,61 @@
+/**
+ * tick — idempotent recurring research scheduler (Sprint 4).
+ *
+ * Clock discipline: `now` is always injected — never call new Date() or Date.now()
+ * inside this module. The wall clock is read ONLY at the CLI .action() boundary
+ * (mirrors src/research/runner.ts:18-19 and src/state/facts.ts:18-21).
+ *
+ * Idempotency: after a job runs, its nextDueAt is advanced to
+ * computeNextDue(cadence, now) which is strictly > now, so a second tick at
+ * the same now evaluates due === false for that job (sc-4-3).
+ *
+ * Concurrency: single-process, no lock needed (two-person personal use case;
+ * contract assumption L50).
+ */
+import type { ResearchJob } from "./types.js";
+/**
+ * Injected dependencies for tick.
+ * All I/O and the clock are injected so unit tests can bypass real providers
+ * and SQLite (mirrors RunDeps in src/research/runner.ts:46-61).
+ */
+export interface TickDeps {
+    /** Injected ISO-8601 instant — stamped at the CLI boundary; never read the clock here. */
+    now: string;
+    /** Load all stored jobs. CLI binds to () => listJobs(projectRoot). */
+    listJobs: () => Promise<ResearchJob[]>;
+    /**
+     * Persist an advanced job.
+     * CLI binds to (j) => addJob(projectRoot, j) which is an in-place upsert by id
+     * (briefing Finding B — jobId hashes only question|createdAt, so id is stable
+     * even after nextDueAt/lastRunAt are set).
+     */
+    saveJob: (job: ResearchJob) => Promise<void>;
+    /**
+     * Execute one due job.
+     * CLI binds runResearchJob with queryModel/findingSink/now/vaultRoot already
+     * bound (Sprint 2 runner, invoked UNCHANGED).
+     */
+    runJob: (job: ResearchJob) => Promise<void>;
+}
+/** Summary of a tick invocation — which jobs ran and which were skipped. */
+export interface TickResult {
+    /** ids of jobs that were due and ran. */
+    ran: string[];
+    /** ids of jobs skipped because nextDueAt > now. */
+    skipped: string[];
+}
+/**
+ * Run every due job once, advance its nextDueAt, record lastRunAt, and persist.
+ *
+ * Selection rule: a job is due when
+ *   - nextDueAt is undefined (never scheduled → due on first tick), OR
+ *   - Date.parse(nextDueAt) <= Date.parse(now)
+ *
+ * Order: run FIRST, then advance + persist. If runJob throws, the job is NOT
+ * persisted so it remains due on the next tick.
+ *
+ * Idempotency: on a second tick at the same now, all previously-run jobs have
+ * nextDueAt > now (computeNextDue always advances by >= 1 day), so they are skipped.
+ */
+export declare function tick(deps: TickDeps): Promise<TickResult>;
+//# sourceMappingURL=scheduler.d.ts.map

package/dist/research/scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["../../src/research/scheduler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAI9C;;;;GAIG;AACH,MAAM,WAAW,QAAQ;IACvB,0FAA0F;IAC1F,GAAG,EAAE,MAAM,CAAC;IACZ,sEAAsE;IACtE,QAAQ,EAAE,MAAM,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IACvC;;;;;OAKG;IACH,OAAO,EAAE,CAAC,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C;;;;OAIG;IACH,MAAM,EAAE,CAAC,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7C;AAED,4EAA4E;AAC5E,MAAM,WAAW,UAAU;IACzB,yCAAyC;IACzC,GAAG,EAAE,MAAM,EAAE,CAAC;IACd,mDAAmD;IACnD,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAID;;;;;;;;;;;;GAYG;AACH,wBAAsB,IAAI,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,UAAU,CAAC,CAqC9D"}

package/dist/research/scheduler.js

@@ -0,0 +1,58 @@
+/**
+ * tick — idempotent recurring research scheduler (Sprint 4).
+ *
+ * Clock discipline: `now` is always injected — never call new Date() or Date.now()
+ * inside this module. The wall clock is read ONLY at the CLI .action() boundary
+ * (mirrors src/research/runner.ts:18-19 and src/state/facts.ts:18-21).
+ *
+ * Idempotency: after a job runs, its nextDueAt is advanced to
+ * computeNextDue(cadence, now) which is strictly > now, so a second tick at
+ * the same now evaluates due === false for that job (sc-4-3).
+ *
+ * Concurrency: single-process, no lock needed (two-person personal use case;
+ * contract assumption L50).
+ */
+import { computeNextDue } from "./cadence.js";
+// ── tick ──────────────────────────────────────────────────────────────
+/**
+ * Run every due job once, advance its nextDueAt, record lastRunAt, and persist.
+ *
+ * Selection rule: a job is due when
+ *   - nextDueAt is undefined (never scheduled → due on first tick), OR
+ *   - Date.parse(nextDueAt) <= Date.parse(now)
+ *
+ * Order: run FIRST, then advance + persist. If runJob throws, the job is NOT
+ * persisted so it remains due on the next tick.
+ *
+ * Idempotency: on a second tick at the same now, all previously-run jobs have
+ * nextDueAt > now (computeNextDue always advances by >= 1 day), so they are skipped.
+ */
+export async function tick(deps) {
+    const { now, listJobs, saveJob, runJob } = deps;
+    const jobs = await listJobs();
+    const ran = [];
+    const skipped = [];
+    const nowMs = Date.parse(now);
+    for (const job of jobs) {
+        // A job with no nextDueAt is due immediately on first tick.
+        const isDue = job.nextDueAt === undefined ||
+            Date.parse(job.nextDueAt) <= nowMs;
+        if (!isDue) {
+            skipped.push(job.id);
+            continue;
+        }
+        // Run first — if runJob throws, we do not advance or persist.
+        await runJob(job);
+        // Advance scheduling fields using the injected now (no wall clock).
+        const advanced = {
+            ...job,
+            lastRunAt: now,
+            nextDueAt: computeNextDue(job.cadence, now),
+        };
+        // Persist via the injected saveJob (= addJob upsert; same id → same file).
+        await saveJob(advanced);
+        ran.push(job.id);
+    }
+    return { ran, skipped };
+}
+//# sourceMappingURL=scheduler.js.map

package/dist/research/scheduler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.js","sourceRoot":"","sources":["../../src/research/scheduler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAsC9C,yEAAyE;AAEzE;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,IAAI,CAAC,IAAc;IACvC,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAEhD,MAAM,IAAI,GAAG,MAAM,QAAQ,EAAE,CAAC;IAC9B,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,MAAM,OAAO,GAAa,EAAE,CAAC;IAE7B,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAE9B,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,4DAA4D;QAC5D,MAAM,KAAK,GACT,GAAG,CAAC,SAAS,KAAK,SAAS;YAC3B,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,KAAK,CAAC;QAErC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACrB,SAAS;QACX,CAAC;QAED,8DAA8D;QAC9D,MAAM,MAAM,CAAC,GAAG,CAAC,CAAC;QAElB,oEAAoE;QACpE,MAAM,QAAQ,GAAgB;YAC5B,GAAG,GAAG;YACN,SAAS,EAAE,GAAG;YACd,SAAS,EAAE,cAAc,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC;SAC5C,CAAC;QAEF,2EAA2E;QAC3E,MAAM,OAAO,CAAC,QAAQ,CAAC,CAAC;QAExB,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACnB,CAAC;IAED,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC;AAC1B,CAAC"}

package/dist/research/types.d.ts

@@ -0,0 +1,81 @@
+import { z } from "zod";
+/**
+ * Recurrence cadence for a research job.
+ *
+ * Representation choice: a closed string-literal enum (`"daily" | "weekly" | "monthly"`).
+ * This is simpler and safer than a free-form cron string for the current use-cases;
+ * next-due computation (Sprint 4) will map these to concrete intervals without
+ * requiring a cron parser. Do NOT compute next-due dates in this module — that is
+ * Sprint 4 (contract outOfScope L55).
+ */
+export declare const CadenceSchema: z.ZodEnum<["daily", "weekly", "monthly"]>;
+export type Cadence = z.infer<typeof CadenceSchema>;
+/**
+ * A recurring research job definition stored as a JSON file under
+ * `.bober/research/jobs/<jobId>.json`.
+ *
+ * All timestamps are ISO-8601 strings; this module never reads the clock
+ * (mirrors src/state/facts.ts:18-21 — clock is stamped at the CLI boundary).
+ *
+ * tier vs modelSet: both are optional; the executor (Sprint 2) resolves
+ * which to use at runtime. Storing both allows flexible scheduling without
+ * commitment to either axis in Sprint 1.
+ *
+ * onlineResearch defaults to false — the online-research egress axis is not
+ * enabled until Sprint 3. The field is stored verbatim for forward-compatibility.
+ */
+export declare const ResearchJobSchema: z.ZodObject<{
+    id: z.ZodString;
+    /** The research question to answer. Must be non-empty (sc-1-1). */
+    question: z.ZodString;
+    /** How often the job runs. See CadenceSchema for allowed values. */
+    cadence: z.ZodEnum<["daily", "weekly", "monthly"]>;
+    /** Difficulty tier hint (e.g. "hard") — optional, resolved at execution time. */
+    tier: z.ZodOptional<z.ZodString>;
+    /** Explicit model set override — optional, resolved at execution time. */
+    modelSet: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    /** Repository slug to scope the research against, if any. */
+    targetRepo: z.ZodOptional<z.ZodString>;
+    /** Domain tag (e.g. "medical", "coding") for priority-hub routing. */
+    domain: z.ZodOptional<z.ZodString>;
+    /**
+     * Whether online retrieval is enabled for this job.
+     * Defaults to false — online-research egress is not active until Sprint 3.
+     */
+    onlineResearch: z.ZodDefault<z.ZodBoolean>;
+    /** ISO-8601 creation timestamp — set once at CLI boundary, never mutated. */
+    createdAt: z.ZodString;
+    /**
+     * ISO-8601 next-due instant (Sprint 4). Unset => due immediately on first tick.
+     * Advanced by computeNextDue(cadence, now) after each run. Never read from the wall clock.
+     */
+    nextDueAt: z.ZodOptional<z.ZodString>;
+    /** ISO-8601 timestamp of the most recent successful run (Sprint 4). Unset until first run. */
+    lastRunAt: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    question: string;
+    cadence: "daily" | "weekly" | "monthly";
+    onlineResearch: boolean;
+    createdAt: string;
+    tier?: string | undefined;
+    modelSet?: string[] | undefined;
+    targetRepo?: string | undefined;
+    domain?: string | undefined;
+    nextDueAt?: string | undefined;
+    lastRunAt?: string | undefined;
+}, {
+    id: string;
+    question: string;
+    cadence: "daily" | "weekly" | "monthly";
+    createdAt: string;
+    tier?: string | undefined;
+    modelSet?: string[] | undefined;
+    targetRepo?: string | undefined;
+    domain?: string | undefined;
+    onlineResearch?: boolean | undefined;
+    nextDueAt?: string | undefined;
+    lastRunAt?: string | undefined;
+}>;
+export type ResearchJob = z.infer<typeof ResearchJobSchema>;
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/research/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa,2CAAyC,CAAC;AACpE,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAIpD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,iBAAiB;;IAE5B,mEAAmE;;IAEnE,oEAAoE;;IAEpE,iFAAiF;;IAEjF,0EAA0E;;IAE1E,6DAA6D;;IAE7D,sEAAsE;;IAEtE;;;OAGG;;IAEH,6EAA6E;;IAE7E;;;OAGG;;IAEH,8FAA8F;;;;;;;;;;;;;;;;;;;;;;;;;;EAE9F,CAAC;AAEH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC"}

package/dist/research/types.js

@@ -0,0 +1,57 @@
+import { z } from "zod";
+// ── Cadence ───────────────────────────────────────────────────────────
+/**
+ * Recurrence cadence for a research job.
+ *
+ * Representation choice: a closed string-literal enum (`"daily" | "weekly" | "monthly"`).
+ * This is simpler and safer than a free-form cron string for the current use-cases;
+ * next-due computation (Sprint 4) will map these to concrete intervals without
+ * requiring a cron parser. Do NOT compute next-due dates in this module — that is
+ * Sprint 4 (contract outOfScope L55).
+ */
+export const CadenceSchema = z.enum(["daily", "weekly", "monthly"]);
+// ── ResearchJob ───────────────────────────────────────────────────────
+/**
+ * A recurring research job definition stored as a JSON file under
+ * `.bober/research/jobs/<jobId>.json`.
+ *
+ * All timestamps are ISO-8601 strings; this module never reads the clock
+ * (mirrors src/state/facts.ts:18-21 — clock is stamped at the CLI boundary).
+ *
+ * tier vs modelSet: both are optional; the executor (Sprint 2) resolves
+ * which to use at runtime. Storing both allows flexible scheduling without
+ * commitment to either axis in Sprint 1.
+ *
+ * onlineResearch defaults to false — the online-research egress axis is not
+ * enabled until Sprint 3. The field is stored verbatim for forward-compatibility.
+ */
+export const ResearchJobSchema = z.object({
+    id: z.string().min(1),
+    /** The research question to answer. Must be non-empty (sc-1-1). */
+    question: z.string().min(1),
+    /** How often the job runs. See CadenceSchema for allowed values. */
+    cadence: CadenceSchema,
+    /** Difficulty tier hint (e.g. "hard") — optional, resolved at execution time. */
+    tier: z.string().optional(),
+    /** Explicit model set override — optional, resolved at execution time. */
+    modelSet: z.array(z.string()).optional(),
+    /** Repository slug to scope the research against, if any. */
+    targetRepo: z.string().optional(),
+    /** Domain tag (e.g. "medical", "coding") for priority-hub routing. */
+    domain: z.string().optional(),
+    /**
+     * Whether online retrieval is enabled for this job.
+     * Defaults to false — online-research egress is not active until Sprint 3.
+     */
+    onlineResearch: z.boolean().default(false),
+    /** ISO-8601 creation timestamp — set once at CLI boundary, never mutated. */
+    createdAt: z.string().datetime(),
+    /**
+     * ISO-8601 next-due instant (Sprint 4). Unset => due immediately on first tick.
+     * Advanced by computeNextDue(cadence, now) after each run. Never read from the wall clock.
+     */
+    nextDueAt: z.string().datetime().optional(),
+    /** ISO-8601 timestamp of the most recent successful run (Sprint 4). Unset until first run. */
+    lastRunAt: z.string().datetime().optional(),
+});
+//# sourceMappingURL=types.js.map

package/dist/research/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/research/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,yEAAyE;AAEzE;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC,CAAC;AAGpE,yEAAyE;AAEzE;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC;IACxC,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACrB,mEAAmE;IACnE,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3B,oEAAoE;IACpE,OAAO,EAAE,aAAa;IACtB,iFAAiF;IACjF,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC3B,0EAA0E;IAC1E,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;IACxC,6DAA6D;IAC7D,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACjC,sEAAsE;IACtE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC7B;;;OAGG;IACH,cAAc,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;IAC1C,6EAA6E;IAC7E,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAChC;;;OAGG;IACH,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IAC3C,8FAA8F;IAC9F,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;CAC5C,CAAC,CAAC"}

package/dist/seo/adapters/http.d.ts

@@ -0,0 +1,43 @@
+/**
+ * HttpClient — the SOLE provider-agnostic HTTP transport seam under
+ * `src/seo/` (spec-20260715-ultimate-seo-suite, Sprint 8; ADR-5).
+ *
+ * `src/seo/adapters/http.ts` is the ONLY file under `src/seo/` allowed to
+ * reference the global `fetch`. Every live adapter (`GscAdapter` this
+ * sprint, `DataForSeoAdapter` in Sprint 9) takes an injectable `HttpClient`
+ * constructor param defaulting to `defaultHttpClient`; tests inject a fake
+ * so no socket ever opens in CI. Mirrors the injectable-transport pattern
+ * in `src/medical/retrieval/medline-source.ts:37-39` and
+ * `src/medical/whoop/whoop-client.ts:40-52`, generalised to a
+ * `{method, headers, body}` request shape shared by both GSC and
+ * DataForSEO (both are plain JSON-over-HTTPS POST APIs).
+ *
+ * bober: no retry/backoff here — a thin request/response shim only. Each
+ *        adapter owns its own error handling (429/5xx -> abstain) per
+ *        ADR-5. Add shared retry logic only if a second adapter needs the
+ *        exact same policy.
+ */
+/** Duck-typed response — deliberately NOT the global `Response` type, so
+ *  tests can construct fakes without touching the real fetch API. */
+export interface HttpResponse {
+    ok: boolean;
+    status: number;
+    json(): Promise<unknown>;
+}
+/** One outbound request's method/headers/body. */
+export interface HttpRequestInit {
+    method: string;
+    headers?: Record<string, string>;
+    body?: string;
+}
+/** Provider-agnostic injectable HTTP transport. */
+export interface HttpClient {
+    request(url: string, init: HttpRequestInit): Promise<HttpResponse>;
+}
+/**
+ * Default transport = global fetch. The sole global-fetch reference under
+ * `src/seo/`. Adapters take this as their default `http` constructor param;
+ * tests always inject a fake `HttpClient` instead.
+ */
+export declare const defaultHttpClient: HttpClient;
+//# sourceMappingURL=http.d.ts.map

package/dist/seo/adapters/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../../src/seo/adapters/http.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;qEACqE;AACrE,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1B;AAED,kDAAkD;AAClD,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,mDAAmD;AACnD,MAAM,WAAW,UAAU;IACzB,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;CACpE;AAED;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,EAAE,UAS/B,CAAC"}

package/dist/seo/adapters/http.js

@@ -0,0 +1,35 @@
+/**
+ * HttpClient — the SOLE provider-agnostic HTTP transport seam under
+ * `src/seo/` (spec-20260715-ultimate-seo-suite, Sprint 8; ADR-5).
+ *
+ * `src/seo/adapters/http.ts` is the ONLY file under `src/seo/` allowed to
+ * reference the global `fetch`. Every live adapter (`GscAdapter` this
+ * sprint, `DataForSeoAdapter` in Sprint 9) takes an injectable `HttpClient`
+ * constructor param defaulting to `defaultHttpClient`; tests inject a fake
+ * so no socket ever opens in CI. Mirrors the injectable-transport pattern
+ * in `src/medical/retrieval/medline-source.ts:37-39` and
+ * `src/medical/whoop/whoop-client.ts:40-52`, generalised to a
+ * `{method, headers, body}` request shape shared by both GSC and
+ * DataForSEO (both are plain JSON-over-HTTPS POST APIs).
+ *
+ * bober: no retry/backoff here — a thin request/response shim only. Each
+ *        adapter owns its own error handling (429/5xx -> abstain) per
+ *        ADR-5. Add shared retry logic only if a second adapter needs the
+ *        exact same policy.
+ */
+/**
+ * Default transport = global fetch. The sole global-fetch reference under
+ * `src/seo/`. Adapters take this as their default `http` constructor param;
+ * tests always inject a fake `HttpClient` instead.
+ */
+export const defaultHttpClient = {
+    async request(url, init) {
+        const res = await fetch(url, {
+            method: init.method,
+            headers: init.headers,
+            body: init.body,
+        });
+        return { ok: res.ok, status: res.status, json: () => res.json() };
+    },
+};
+//# sourceMappingURL=http.js.map

package/dist/seo/adapters/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../../../src/seo/adapters/http.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAsBH;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAe;IAC3C,KAAK,CAAC,OAAO,CAAC,GAAG,EAAE,IAAI;QACrB,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;YAC3B,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,IAAI,EAAE,IAAI,CAAC,IAAI;SAChB,CAAC,CAAC;QACH,OAAO,EAAE,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC;IACpE,CAAC;CACF,CAAC"}