agent-bober 0.17.1 → 0.19.0

package/dist/seo/runner.js

@@ -0,0 +1,512 @@
+import { createClient } from "../providers/factory.js";
+import { FactStore, factsDbPath, ensureFactsDir } from "../state/facts.js";
+import { ingestFinding } from "../hub/finding-store.js";
+import { logger } from "../utils/logger.js";
+import { LiveGroundedSearchClient, PerplexitySonarClient } from "../providers/grounded-search.js";
+import { ScrapeThrottle } from "./scrape-throttle.js";
+import { SeoPlaybookIndex } from "./playbook-index.js";
+import { SeoPlaybookRetriever } from "./retriever.js";
+import { SeoEgressGuard } from "./egress.js";
+import { SeoQuotaGovernor } from "./quota-governor.js";
+import { LocalExportSource } from "./sources/local-export.js";
+import { GscAdapter } from "./sources/gsc-adapter.js";
+import { DataForSeoAdapter } from "./sources/dataforseo-adapter.js";
+import { CrawlSource } from "./sources/crawl-source.js";
+import { DamcrawlerCrawlEngine } from "./sources/damcrawler-crawl-engine.js";
+import { ContentSanitizer } from "./content-sanitizer.js";
+import { resolveSerpProvider } from "./serp-provider.js";
+import { AiVisibilityAdapter } from "./sources/ai-visibility-adapter.js";
+import { resolveAiVisibilityProvider } from "./ai-visibility-provider.js";
+import { DeterministicMentionCitationExtractor } from "./sources/mention-citation-extractor.js";
+import { WORKFLOW_CAPABILITIES } from "./workflow-capabilities.js";
+import { TrackedPromptStore } from "./tracked-prompt-store.js";
+import { SeoAnalyzer } from "./analyzer.js";
+import { SeoCitationGate } from "./citation-gate.js";
+import { NeverEncodeFilter } from "./never-encode-filter.js";
+import { SeoReportStore, deriveReportId } from "./report-store.js";
+import { SeoHubEmitter } from "./hub-emitter.js";
+import { SeoRecommendationVerifier } from "./verifier.js";
+// ── Defaults ─────────────────────────────────────────────────────────
+const DEFAULT_TARGET_FALLBACK = "unspecified-target";
+/**
+ * bober: `config.seo` has no `model` field — this is the sole model the
+ *        runner defaults to for the analyzer's LLM client. Add
+ *        `config.seo.model` if per-project model choice is ever needed.
+ */
+const DEFAULT_SEO_MODEL = "sonnet";
+function buildDefaultAnalyzer() {
+    // createClient is the ONLY place SDKs are imported. BOBER_TEST_DETERMINISTIC=1
+    // makes this an inert stub client, but tests should still inject a scripted
+    // analyzer (via input.analyzer) so a real network call is never even attempted.
+    const client = createClient(undefined, null, undefined, DEFAULT_SEO_MODEL, "seo");
+    return new SeoAnalyzer(client, DEFAULT_SEO_MODEL);
+}
+/**
+ * bober: per-engine default model is hardcoded here (not read from config —
+ *        `config.seo.aiVisibility.engines[]` carries no `model` field this
+ *        sprint). Promote to a per-engine config field if a project ever
+ *        needs a different model than these defaults. "perplexity" has no
+ *        entry: it does NOT go through `createClient`/`LLMClient` at all
+ *        (Sprint 7) — `PerplexitySonarClient` reads its own model default,
+ *        so it is intentionally absent from this table, not merely unset.
+ */
+const AI_VISIBILITY_DEFAULT_MODEL = {
+    anthropic: DEFAULT_SEO_MODEL,
+    openai: "gpt-4.1",
+};
+/** Env var each engine's key is read from — mirrors `factory.ts`'s `validateApiKey`. */
+const AI_VISIBILITY_KEY_ENV = {
+    anthropic: "ANTHROPIC_API_KEY",
+    openai: "OPENAI_API_KEY",
+};
+/**
+ * Production `AiVisibilityDeps.makeClient` — returns `undefined` (no-key-safe)
+ * for any engine lacking its documented env-var key. "perplexity" is handled
+ * by an EARLY, separate branch (Sprint 7): Perplexity Sonar is a direct HTTP
+ * `chat/completions` API, not an `LLMClient` provider, so it is constructed
+ * directly as a `PerplexitySonarClient` and MUST NOT fall through to the
+ * generic `createClient` path below (that path has no "perplexity" entry in
+ * either table above, so it would otherwise return `undefined` — this branch
+ * exists so a Perplexity-keyed engine composes a real arm instead). Only
+ * when a key is present does the generic path call `createClient`, so a
+ * misconfigured/no-key run never throws the zero-network guard error that
+ * `runner.test.ts:34-44` asserts on.
+ */
+function defaultMakeClient(engine) {
+    if (engine === "perplexity") {
+        // Sonar is BYOK HTTP, not routed through createClient — no-key-safe:
+        // absent PERPLEXITY_API_KEY => undefined, arm skipped (sc-7-2).
+        if (!process.env["PERPLEXITY_API_KEY"])
+            return undefined;
+        return new PerplexitySonarClient(); // defaults: env key + global-fetch transport + "sonar"
+    }
+    const envVar = AI_VISIBILITY_KEY_ENV[engine];
+    const model = AI_VISIBILITY_DEFAULT_MODEL[engine];
+    if (!envVar || !model || !process.env[envVar])
+        return undefined;
+    const client = createClient(undefined, null, undefined, model, "ai-visibility");
+    return new LiveGroundedSearchClient(engine, client, model);
+}
+// ── selectSource + CapabilitySeoRouter (sc-9-1, sc-9-2, sc-9-3) ─────────
+function quotaLedgerPath(projectRoot) {
+    return `${projectRoot}/.bober/seo/quota-ledger.json`;
+}
+/**
+ * The scrape arm's proxy/rate ledger — DISTINCT from `quotaLedgerPath` above
+ * (Pitfall 6, sc-11-2): the two ledgers are never cross-reconciled
+ * (`scrape-throttle.ts` docstring lines 8-12).
+ */
+function scrapeThrottleLedgerPath(projectRoot) {
+    return `${projectRoot}/.bober/seo/scrape-throttle-ledger.json`;
+}
+/**
+ * Production `AiVisibilityDeps` — real client builder + the deterministic
+ * extractor (Sprint 2), plus (Sprint 11) a real `ScrapeThrottle` and a
+ * no-key-safe judge-llm builder, both built ONLY when their config section is
+ * present:
+ *
+ * - `scrapeThrottle` (sc-11-2) is constructed from `config.seo.aiVisibility.scrape`
+ *   (path under `projectRoot`, caps from config) ONLY when that section is
+ *   present — absent config leaves `scrapeThrottle` undefined, so
+ *   `resolveAiVisibilityProvider` never composes a scrape arm (no-config-safe,
+ *   mirrors `defaultMakeClient`'s no-key-safe idiom). This is what makes the
+ *   `ai-visibility-scrape` axis + a configured scrape engine LIVE in a real
+ *   `selectSource` run (Pitfall 1: BOTH `ai-visibility` and
+ *   `ai-visibility-scrape` must be on for the scrape arm to produce rows,
+ *   since it is routed through the LOCKED `AiVisibilityAdapter`'s
+ *   `ai-visibility` gate).
+ * - `makeJudgeLlm` (sc-11-3) mirrors `defaultMakeClient`'s guard order
+ *   (Pattern B): it returns `undefined` BEFORE calling `createClient` when
+ *   `ANTHROPIC_API_KEY` is absent — no-key-safe. Only built when
+ *   `config.seo.aiVisibility.judge?.enabled` is true; otherwise `makeJudgeLlm`
+ *   stays undefined and `resolveAiVisibilityProvider` never constructs a
+ *   judge (byte-identical-when-disabled, sc-11-3).
+ *
+ * `scrapeLoad` is intentionally NOT set here — production always uses each
+ * `ScrapeArmEngineProvider`'s own real lazy `damcrawler` loader (the class's
+ * constructor default); only tests inject a fake.
+ */
+function defaultAiVisibilityDeps(config, projectRoot) {
+    const deps = {
+        makeClient: defaultMakeClient,
+        extractor: new DeterministicMentionCitationExtractor(),
+    };
+    const scrapeCfg = config.seo?.aiVisibility?.scrape;
+    if (scrapeCfg) {
+        deps.scrapeThrottle = new ScrapeThrottle(scrapeThrottleLedgerPath(projectRoot), {
+            maxPerWindow: scrapeCfg.maxPerWindow,
+            windowMs: scrapeCfg.windowMs,
+            maxProxyUsd: scrapeCfg.maxProxyUsd,
+        });
+    }
+    const judgeCfg = config.seo?.aiVisibility?.judge;
+    if (judgeCfg?.enabled) {
+        deps.makeJudgeLlm = () => {
+            // Pitfall 3 / Pattern B: return undefined BEFORE createClient when
+            // unkeyed — runner.test.ts mocks createClient to THROW, so an eager
+            // call here would fail the whole file on a no-key run.
+            if (!process.env["ANTHROPIC_API_KEY"])
+                return undefined;
+            const model = judgeCfg.model ?? DEFAULT_SEO_MODEL;
+            const client = createClient(undefined, null, undefined, model, "ai-visibility");
+            return { client, model };
+        };
+    }
+    return deps;
+}
+/**
+ * Shared "unrouted" stub — every method resolves `{ kind: "disabled" }`
+ * regardless of which capability method is invoked. `CapabilitySeoRouter`
+ * dispatches to this for any capability key absent from its `routes` map.
+ */
+const DISABLED_SOURCE = {
+    capabilities: () => [],
+    searchAnalytics: async () => ({ kind: "disabled" }),
+    urlInspection: async () => ({ kind: "disabled" }),
+    serp: async () => ({ kind: "disabled" }),
+    keywords: async () => ({ kind: "disabled" }),
+    backlinks: async () => ({ kind: "disabled" }),
+    aiVisibility: async () => ({ kind: "disabled" }),
+    linkGraph: async () => ({ kind: "disabled" }),
+};
+/**
+ * CapabilitySeoRouter — dispatches each `SeoDataSource` capability method to
+ * the ONE source that owns that capability key (spec-20260717-seo-improver-
+ * builder, Sprint 9; replaces `CompositeSeoSource`). Assembled by
+ * `selectSource` per the ADR-8/ADR-10 route table (sc-9-3). An unrouted
+ * capability (absent from `routes`) resolves `{ kind: "disabled" }` via
+ * `DISABLED_SOURCE` — the router itself never throws (sc-9-1).
+ */
+class CapabilitySeoRouter {
+    routes;
+    constructor(routes) {
+        this.routes = routes;
+    }
+    /**
+     * `Object.keys(routes)`, NOT a union of each routed source's OWN
+     * `capabilities()` — a routed source may itself advertise capabilities
+     * this router does not route to it (sprint briefing §11 Pitfall 8).
+     */
+    capabilities() {
+        return Object.keys(this.routes);
+    }
+    searchAnalytics(q) {
+        return (this.routes["search-analytics"] ?? DISABLED_SOURCE).searchAnalytics(q);
+    }
+    urlInspection(q) {
+        return (this.routes["url-inspection"] ?? DISABLED_SOURCE).urlInspection(q);
+    }
+    serp(q) {
+        return (this.routes["serp"] ?? DISABLED_SOURCE).serp(q);
+    }
+    keywords(q) {
+        return (this.routes["keywords"] ?? DISABLED_SOURCE).keywords(q);
+    }
+    backlinks(q) {
+        return (this.routes["backlinks"] ?? DISABLED_SOURCE).backlinks(q);
+    }
+    aiVisibility(q) {
+        return (this.routes["ai-visibility"] ?? DISABLED_SOURCE).aiVisibility(q);
+    }
+    linkGraph(q) {
+        return (this.routes["link-graph"] ?? DISABLED_SOURCE).linkGraph(q);
+    }
+}
+/**
+ * SerpProviderSource — adapts a `SerpProvider` port's `serp(keyword,
+ * location)` (`serp-provider.ts:36-45`) into this file's `SeoDataSource`
+ * seam, whose `serp` method takes a single `SerpQuery` (sprint briefing
+ * Pattern C). Serves ONLY `serp`; every other capability is
+ * `{ kind: "disabled" }` unconditionally. `q.priority` is dropped by this
+ * shim — byte-identical, because `DataForSeoAdapter.serp` already defaults
+ * an absent `priority` to `"standard"` (`dataforseo-adapter.ts:199`).
+ */
+class SerpProviderSource {
+    provider;
+    constructor(provider) {
+        this.provider = provider;
+    }
+    capabilities() {
+        return ["serp"];
+    }
+    serp(q) {
+        return this.provider.serp(q.keyword, q.location);
+    }
+    async searchAnalytics(_q) {
+        return { kind: "disabled" };
+    }
+    async urlInspection(_q) {
+        return { kind: "disabled" };
+    }
+    async keywords(_q) {
+        return { kind: "disabled" };
+    }
+    async backlinks(_q) {
+        return { kind: "disabled" };
+    }
+    async aiVisibility(_q) {
+        return { kind: "disabled" };
+    }
+    async linkGraph(_q) {
+        return { kind: "disabled" };
+    }
+}
+/**
+ * Build the `SeoDataSource` for a run from the FOUR independent egress axes
+ * (widened from two, spec-20260717-seo-improver-builder Sprint 9). ALL FOUR
+ * axes off (default) -> `LocalExportSource` (zero egress, no credentials
+ * touched, no governor/ledger constructed, `import('damcrawler')` never
+ * evaluated — sc-9-2). This `return` is the FIRST statement after the
+ * predicate, strictly BEFORE `SeoQuotaGovernor.load` (sprint briefing
+ * Pattern B / Pitfall 2) — that ordering is what makes the all-off path
+ * provably zero-construction.
+ *
+ * Otherwise, assemble a `CapabilitySeoRouter` per the deterministic
+ * ADR-8/ADR-10 route table (sc-9-3):
+ *   - `url-inspection`: `GscAdapter` when `search-console` is on (GSC always
+ *     wins, ADR-8); else `CrawlSource` when `site-crawl` is on.
+ *   - `link-graph`: `CrawlSource` when `site-crawl` is on.
+ *   - `serp`: the config-selected `SerpProvider` (`resolveSerpProvider`,
+ *     ADR-10), wrapped in `SerpProviderSource`, whenever `serp-provider` OR
+ *     `site-crawl` is on (whichever axis the selected provider itself
+ *     requires; each provider re-asserts its own axis on call).
+ *   - `keywords`/`backlinks`: `DataForSeoAdapter` when `serp-provider` is on.
+ *   - `ai-visibility`: `AiVisibilityAdapter` wrapping the composed
+ *     `resolveAiVisibilityProvider(...)` result when `ai-visibility` is on
+ *     AND at least one configured engine is keyed (Sprint 3); the offline
+ *     `LocalExportSource` arm otherwise (no-key-safe fallback).
+ */
+export async function selectSource(config, projectRoot, deps) {
+    const egress = SeoEgressGuard.fromConfig(config);
+    const searchConsoleAllowed = egress.isAllowed("search-console");
+    const serpProviderAllowed = egress.isAllowed("serp-provider");
+    const aiVisibilityAllowed = egress.isAllowed("ai-visibility");
+    const siteCrawlAllowed = egress.isAllowed("site-crawl");
+    if (!searchConsoleAllowed && !serpProviderAllowed && !aiVisibilityAllowed && !siteCrawlAllowed) {
+        return new LocalExportSource();
+    }
+    const governor = await SeoQuotaGovernor.load(quotaLedgerPath(projectRoot), config);
+    const routes = {};
+    if (searchConsoleAllowed) {
+        const gsc = new GscAdapter(egress, governor);
+        routes["search-analytics"] = gsc;
+        routes["url-inspection"] = gsc; // ADR-8: GSC wins url-inspection when on
+    }
+    if (siteCrawlAllowed) {
+        const crawlSource = new CrawlSource(governor, new DamcrawlerCrawlEngine(egress), 
+        // bober: identity sanitizer for CrawlSource's OWN (defense-in-depth,
+        // sc-7-3) layer only. As of the Sprint 9 fix, `DamcrawlerCrawlEngine`
+        // sanitizes EVERY method (crawl/urlVisibility/linkGraph) at the
+        // network->in-process boundary via the real `dam.sanitize`
+        // (damcrawler-crawl-engine.ts F1) — that is now the genuine, load-
+        // bearing sanitization layer for every row this source returns.
+        // Leaving this second layer as identity is safe (it is redundant, not
+        // sole) — wiring the loaded module's `sanitize` export through here
+        // too would require exposing the engine's already-loaded damcrawler
+        // module, which `selectSource` cannot reach without duplicating the
+        // engine's own guard/load sequence. Follow-up: thread a real
+        // `dam.sanitize` here if CrawlSource is ever given its own loader.
+        new ContentSanitizer((raw) => ({ content: raw, hadThreats: false })));
+        routes["link-graph"] = crawlSource;
+        if (!searchConsoleAllowed) {
+            routes["url-inspection"] = crawlSource; // ADR-8: fallback only when GSC is off
+        }
+    }
+    // Built unconditionally on this (not-all-off) branch and reused for
+    // keywords/backlinks AND as the resolveSerpProvider dependency — each
+    // self-gates its own axis on call, so constructing it here is inert until
+    // a routed method is actually invoked (sprint briefing §4).
+    const dataForSeo = new DataForSeoAdapter(egress, governor);
+    if (serpProviderAllowed) {
+        routes["keywords"] = dataForSeo;
+        routes["backlinks"] = dataForSeo;
+    }
+    if (serpProviderAllowed || siteCrawlAllowed) {
+        routes["serp"] = new SerpProviderSource(resolveSerpProvider(config, dataForSeo, egress)); // ADR-10
+    }
+    if (aiVisibilityAllowed) {
+        // Sprint 3 (in-house-ai-visibility): compose the in-house API-spine
+        // multiplexer via the factory. No-key-safe: when no configured engine
+        // is keyed (or `config.seo.aiVisibility` is absent/empty), the factory
+        // returns `undefined` and this falls back to the offline
+        // `LocalExportSource` arm exactly as before — never a bogus live
+        // adapter with zero arms.
+        const aiVisibilityProvider = resolveAiVisibilityProvider(config, egress, deps ?? defaultAiVisibilityDeps(config, projectRoot));
+        routes["ai-visibility"] = aiVisibilityProvider
+            ? new AiVisibilityAdapter(egress, governor, aiVisibilityProvider)
+            : new LocalExportSource();
+    }
+    return new CapabilitySeoRouter(routes);
+}
+// ── Data gathering ───────────────────────────────────────────────────
+/**
+ * Gathers ONLY the capabilities `WORKFLOW_CAPABILITIES` lists for `workflow`
+ * (spec-20260717-seo-improver-builder, Sprint 9; ADR-7) — an omitted
+ * capability is never called on `source` at all (not called-then-discarded),
+ * so the metered `ai-visibility` capability incurs zero cost/network for a
+ * workflow that does not consume it (sc-9-4). An omitted arm resolves
+ * `undefined` on `SeoDataBundle`, which the analyzer already renders as "not
+ * requested" (`analyzer.ts:127-128`).
+ *
+ * The `ai-visibility` arm (spec-20260718-in-house-ai-visibility, Sprint 6)
+ * loads the committed `TrackedPromptStore` set for `target` INSIDE the
+ * `requested.has("ai-visibility")` ternary — never hoisted above
+ * `Promise.all` — so a workflow that does not request `ai-visibility` never
+ * touches the filesystem for this store (sc-6-4). Only `prompts`/`locale`
+ * flow into the LOCKED `AiVisibilityQuery` (`data-source.ts:61`); the file's
+ * `engines`/`samplesPerPrompt` are advisory and are NOT forwarded (contract
+ * nonGoal — config resolves the real N/engines at provider construction).
+ */
+async function gatherDataBundle(source, workflow, target, now, projectRoot) {
+    const day = now.slice(0, 10);
+    const requested = new Set(WORKFLOW_CAPABILITIES[workflow]);
+    const searchAnalyticsQuery = {
+        siteUrl: target,
+        startDate: day,
+        endDate: day,
+        dimensions: ["query", "page"],
+    };
+    const urlInspectionQuery = { siteUrl: target, inspectionUrl: target };
+    const serpQuery = { keyword: target, location: "us" };
+    const keywordQuery = { keywords: [target], location: "us" };
+    const backlinkQuery = { target };
+    const linkGraphQuery = { rootUrl: target };
+    const [searchAnalytics, urlInspection, serp, keywords, backlinks, aiVisibility, linkGraph] = await Promise.all([
+        requested.has("search-analytics") ? source.searchAnalytics(searchAnalyticsQuery) : undefined,
+        requested.has("url-inspection") ? source.urlInspection(urlInspectionQuery) : undefined,
+        requested.has("serp") ? source.serp(serpQuery) : undefined,
+        requested.has("keywords") ? source.keywords(keywordQuery) : undefined,
+        requested.has("backlinks") ? source.backlinks(backlinkQuery) : undefined,
+        requested.has("ai-visibility")
+            ? (async () => {
+                const set = await new TrackedPromptStore(projectRoot).load(target);
+                const query = { target, prompts: set.prompts };
+                if (set.locale !== undefined)
+                    query.locale = set.locale; // omit key entirely when absent (sc-6-2)
+                return source.aiVisibility(query);
+            })()
+            : undefined,
+        requested.has("link-graph") ? source.linkGraph(linkGraphQuery) : undefined,
+    ]);
+    return { searchAnalytics, urlInspection, serp, keywords, backlinks, aiVisibility, linkGraph };
+}
+// ── Hub emission ─────────────────────────────────────────────────────
+/**
+ * Emit `analysis`'s cited findings into the priority hub. Best-effort:
+ * `SeoHubEmitter.emit` already catches and logs sink failures internally,
+ * so this helper never throws and never affects the runner's exit code.
+ *
+ * An injected `findingSink` (tests) is used as-is. Otherwise a `FactStore`
+ * is opened lazily — only when there is at least one Finding to emit — so a
+ * clean/all-uncited run never touches the filesystem for hub purposes.
+ */
+async function emitFindingsToHub(analysis, projectRoot, now, findingSink) {
+    const emitter = new SeoHubEmitter();
+    if (findingSink !== undefined) {
+        await emitter.emit(analysis, findingSink, logger, now);
+        return;
+    }
+    // Check emptiness BEFORE opening a store — mapToFindings is pure and cheap.
+    if (emitter.mapToFindings(analysis, now).length === 0)
+        return;
+    let store;
+    try {
+        await ensureFactsDir(projectRoot);
+        const opened = new FactStore(factsDbPath(projectRoot));
+        store = opened;
+        const defaultSink = async (finding) => {
+            await ingestFinding(opened, finding, { now });
+        };
+        await emitter.emit(analysis, defaultSink, logger, now);
+    }
+    catch (err) {
+        logger.warn(`SEO hub emission failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    finally {
+        store?.close();
+    }
+}
+// ── SeoWorkflowRunner ────────────────────────────────────────────────
+export class SeoWorkflowRunner {
+    /**
+     * Run one SEO workflow end-to-end. NEVER throws — every failure mode
+     * (context/source/gather/analyze/persist errors, a `parsed: false`
+     * analysis, or a blocked citation gate) resolves to `exitCode: 2`;
+     * only a fully successful, non-blocked run resolves to `exitCode: 0`.
+     */
+    async run(input) {
+        try {
+            const target = input.target ?? input.config.seo?.defaultTarget ?? DEFAULT_TARGET_FALLBACK;
+            const context = await new SeoPlaybookRetriever(new SeoPlaybookIndex()).retrieve({
+                workflow: input.workflow,
+                target,
+            });
+            const source = input.dataSource ?? (await selectSource(input.config, input.projectRoot));
+            const data = await gatherDataBundle(source, input.workflow, target, input.now, input.projectRoot);
+            const analyzer = input.analyzer ?? buildDefaultAnalyzer();
+            const analysis = await analyzer.analyze({
+                workflow: input.workflow,
+                target,
+                context,
+                data,
+                config: input.config,
+                now: input.now,
+            });
+            if (!analysis.parsed) {
+                // Fail-closed (sc-11-5): no report, ZERO hub emits.
+                return { exitCode: 2 };
+            }
+            // Third never-encode belt (spec-20260717-seo-improver-builder, Sprint 2;
+            // ADR-3): drops an LLM-synthesized banned tactic BEFORE the citation
+            // gate, even when it carries a well-formed citationUrl that would
+            // otherwise sail through `SeoCitationGate` untouched.
+            const scrubbed = new NeverEncodeFilter().apply(analysis.findings);
+            const threshold = input.config.seo?.blockThreshold ?? "critical-uncited";
+            const gate = new SeoCitationGate().apply(scrubbed.kept, threshold);
+            // Opt-in, downgrade-only adversarial verifier stage (Sprint 12),
+            // between the citation gate and persistence. The `enabled` check
+            // lives HERE (not just inside `verify()`) so the disabled path never
+            // even constructs a `SeoRecommendationVerifier` or makes a provider
+            // call — byte-identical to the no-verifier run (sc-12-2). The
+            // verifier consumes ONLY `gate.cited` and can only shrink/downgrade
+            // it; `gate.blocked` (used below) is derived from `gate.dropped` and
+            // is NEVER recomputed from the verifier's output, so a verifier
+            // failure structurally cannot change the exit code or block decision
+            // (sc-12-4).
+            let cited = gate.cited;
+            if (input.config.seo?.verifier?.enabled === true) {
+                const verifier = input.verifier ?? new SeoRecommendationVerifier();
+                const verifyResult = await verifier.verify({
+                    findings: gate.cited,
+                    config: input.config,
+                    projectRoot: input.projectRoot,
+                    now: input.now,
+                });
+                cited = verifyResult.findings;
+            }
+            const report = {
+                reportId: deriveReportId(input.now, input.workflow, target),
+                workflow: input.workflow,
+                target,
+                generatedAt: input.now,
+                findings: cited,
+                droppedUncited: gate.dropped.length,
+                droppedNeverEncode: scrubbed.dropped.length,
+                dataProvenance: analysis.dataProvenance,
+                verdict: gate.blocked ? "blocked" : "pass",
+            };
+            await new SeoReportStore().save(input.projectRoot, report);
+            // Best-effort hub emit of the (possibly verifier-folded) cited
+            // findings ONLY, AFTER persist. A hub failure never changes the exit
+            // code.
+            const citedAnalysis = { ...analysis, findings: cited };
+            await emitFindingsToHub(citedAnalysis, input.projectRoot, input.now, input.findingSink);
+            return { report, exitCode: gate.blocked ? 2 : 0 };
+        }
+        catch {
+            // Unexpected throw (context/source/gather/analyze/persist) -> fail-closed.
+            return { exitCode: 2 };
+        }
+    }
+}
+//# sourceMappingURL=runner.js.map

package/dist/seo/runner.js.map

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

package/dist/seo/scrape-throttle.d.ts

@@ -0,0 +1,84 @@
+/**
+ * ScrapeThrottle — per-engine scrape rate window + proxy-USD ledger,
+ * SEPARATE from the governor USD ledger, SAME mutex + atomic-write +
+ * fail-closed discipline as `SeoQuotaGovernor` (spec-20260718-in-house-
+ * ai-visibility, Sprint 9; arch ScrapeThrottle §208-220 / ADR-3).
+ *
+ * The scrape arm's `estCostUsdPerPrompt` is booked as $0 to the
+ * `SeoQuotaGovernor` — its real proxy cost is tracked HERE, in an
+ * independent, independently-capped filesystem ledger keyed by engine
+ * string at `.bober/seo/scrape-throttle-ledger.json` (a DISTINCT path
+ * from `.bober/seo/quota-ledger.json`). The two ledgers are never
+ * cross-reconciled (arch §320).
+ *
+ * `acquire(engine)` both DECIDES and CONSUMES a rate slot in one
+ * read-modify-write under the shared per-path mutex (`withLedgerLock`,
+ * reused from `quota-ledger.ts` — path-generic, so this ledger gets its
+ * own serialization chain and cannot interfere with the governor's).
+ * It writes ONLY on the granting branch — a refusal has no side effect,
+ * mirroring `SeoQuotaGovernor.admit()`.
+ *
+ * `recordProxyCost(engine, usd)` is the governor's `record()` twin:
+ * heals a corrupt ledger back to `{}`, accrues a NaN/negative-guarded
+ * USD amount, and writes atomically (temp-file + rename) so a crash
+ * mid-write never leaves a torn file.
+ *
+ * Fail-closed: a corrupt/unreadable ledger makes `acquire` treat proxy
+ * spend as `+Infinity` (mirrors the governor's Infinity-on-corrupt
+ * refuse) and deny with `reason: "proxy-budget"`. A MISSING ledger
+ * (first run) is a fresh `{}` — allow.
+ *
+ * The clock is INJECTED (`() => ISO string`, mirrors
+ * `DamcrawlerCrawlEngine.now`), never `Date.now()` — deterministic
+ * rate-window tests drive it across the window boundary explicitly.
+ *
+ * ISOLATED sprint: no scrape-provider wiring (Sprint 10), no config-
+ * schema field (caps come from the constructor), no egress coupling.
+ */
+/** Persisted at `.bober/seo/scrape-throttle-ledger.json` — keyed by engine string. */
+export type ScrapeProxyLedger = {
+    [engine: string]: {
+        windowStart: number;
+        count: number;
+        proxyUsdSpent: number;
+    };
+};
+/** `acquire()` decision. Note `proceed`, NOT `allowed` — per contract sc-9-1. */
+export type ThrottleDecision = {
+    proceed: true;
+} | {
+    proceed: false;
+    reason: "rate-window" | "proxy-budget";
+};
+/** Caps injected via constructor — no config-schema field this sprint (isolation). */
+export type ScrapeThrottleLimits = {
+    /** Max `acquire()` grants per rolling fixed window, per engine. */
+    maxPerWindow: number;
+    /** Fixed-window length in milliseconds. */
+    windowMs: number;
+    /** Max cumulative `proxyUsdSpent` per engine before `acquire` denies. */
+    maxProxyUsd: number;
+};
+export declare class ScrapeThrottle {
+    private readonly ledgerPath;
+    private readonly limits;
+    private readonly now;
+    constructor(ledgerPath: string, limits: ScrapeThrottleLimits, now?: () => string);
+    /**
+     * Decide whether `engine` may scrape now, consuming a rate slot on grant.
+     * Read-modify-write under the per-path mutex; writes ONLY on the granting
+     * branch (a refusal has no side effect on the ledger, mirroring
+     * `SeoQuotaGovernor.admit()`/`record()` no-write-on-refuse).
+     */
+    acquire(engine: string): Promise<ThrottleDecision>;
+    /**
+     * Persist completed proxy spend for `engine`. Heals a corrupt ledger back
+     * to `{}` (corruption blocks `acquire`, not `recordProxyCost` — mirrors
+     * `SeoQuotaGovernor.record()`). Guards NaN/negative/zero cost so a bad
+     * value can never corrupt or reduce the running total. Concurrent calls
+     * sharing `ledgerPath` never lose an update (per-path mutex + read-fresh-
+     * inside-lock + atomic write).
+     */
+    recordProxyCost(engine: string, usd: number): Promise<void>;
+}
+//# sourceMappingURL=scrape-throttle.d.ts.map

package/dist/seo/scrape-throttle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scrape-throttle.d.ts","sourceRoot":"","sources":["../../src/seo/scrape-throttle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAWH,sFAAsF;AACtF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,CAAC,MAAM,EAAE,MAAM,GAAG;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC;CACjF,CAAC;AAEF,iFAAiF;AACjF,MAAM,MAAM,gBAAgB,GAAG;IAAE,OAAO,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,aAAa,GAAG,cAAc,CAAA;CAAE,CAAC;AAE9G,sFAAsF;AACtF,MAAM,MAAM,oBAAoB,GAAG;IACjC,mEAAmE;IACnE,YAAY,EAAE,MAAM,CAAC;IACrB,2CAA2C;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB,yEAAyE;IACzE,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AA0CF,qBAAa,cAAc;IAEvB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,MAAM;IAEvB,OAAO,CAAC,QAAQ,CAAC,GAAG;gBAHH,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,oBAAoB,EAE5B,GAAG,GAAE,MAAM,MAAuC;IAGrE;;;;;OAKG;IACG,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAkCxD;;;;;;;OAOG;IACG,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAelE"}