agent-bober 0.18.0 → 0.19.0

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"}

package/dist/seo/ai-visibility-provider.d.ts

@@ -0,0 +1,171 @@
+/**
+ * ai-visibility-provider.ts — the API-spine seam wiring (in-house-ai-
+ * visibility, Sprint 3, widened Sprint 4; arch-20260717-in-house-oss-ai-
+ * visibility-architecture.md:42,50-63,67-77,297-314; ADR-3, ADR-5).
+ *
+ * Mirrors `serp-provider.ts` in shape (a port implementer + a factory
+ * function living alongside the seam, `serp-provider.ts:55-64`): composes
+ * ONLY viable per-engine `ApiSpineEngineProvider` arms (Sprint 2) into an
+ * `AiVisibilityMultiplexer` and hands the result to `selectSource`, which
+ * routes it into the LOCKED `AiVisibilityAdapter` (`sources/ai-visibility-
+ * adapter.ts`) — the port, the `AiVisibilityRow` shape, and the adapter body
+ * are all untouched here (nonGoals).
+ *
+ * Sprint 4 adds the `CitationVerifier` + `ContentSanitizer` each arm needs
+ * (sc-4-3, sc-4-4 D1-Recommended): this is the SOLE production site that
+ * constructs `ApiSpineEngineProvider`, and `egress` is already in scope here
+ * (a parameter of this function), so a single `DamcrawlerCitationVerifier
+ * (egress)` is constructed once and shared across every arm — the verifier
+ * self-gates the `site-crawl` axis on every `verify()` call, so sharing one
+ * instance across engines is safe (it holds no per-arm state).
+ *
+ * The `ContentSanitizer` here wraps `defaultGroundedTextSanitizeFn` (below),
+ * NOT a damcrawler-backed `sanitize` export. Two reasons: (1) the text this
+ * boundary sanitizes — an LLM's grounded `answerText` + its citation urls —
+ * is NOT damcrawler-scraped, it comes straight from `GroundedSearchClient
+ * .search()`; damcrawler's `sanitize` remains the load-bearing sanitizer for
+ * the actual scraped citation BODY, inside `DamcrawlerCitationVerifier`
+ * itself, gated by `site-crawl` (`./sources/citation-verifier.ts`). (2)
+ * `ContentSanitizer` requires a SYNCHRONOUS `SanitizeFn`
+ * (`content-sanitizer.ts:29`), while any damcrawler export can only be
+ * reached via an ASYNC lazy `import()` — and this factory is itself
+ * synchronous (no `Promise` in its return type), so a damcrawler-backed
+ * sanitizer could not be constructed here even behind a gate. This second,
+ * always-on boundary is a genuine (not a no-op) layer: it strips recognized
+ * prompt-injection role/instruction markers the grounding LLM could echo
+ * back from a page it read during its own web search.
+ *
+ * No scrape arm, scorer, or LLM judge land in this module — those are later
+ * sprints (Sprint 8, 10 nonGoals). The Perplexity engine (Sprint 7,
+ * `PerplexitySonarClient`, `../providers/grounded-search.js`) composes
+ * automatically through the loop below once `deps.makeClient("perplexity")`
+ * returns a client — no logic change here was needed.
+ */
+import type { BoberConfig } from "../config/schema.js";
+import type { SeoEgressGuard } from "./egress.js";
+import type { AiVisibilityProvider } from "./sources/ai-visibility-adapter.js";
+import type { AiVisibilityRow } from "./data-source.js";
+import type { GroundedEngine, GroundedSearchClient } from "../providers/grounded-search.js";
+import type { MentionCitationExtractor } from "./sources/mention-citation-extractor.js";
+import type { LLMClient } from "../providers/types.js";
+import type { ScrapeThrottle } from "./scrape-throttle.js";
+import type { DamcrawlerScrapeLoader } from "./sources/scrape-arm-provider.js";
+/**
+ * Default `SanitizeFn` for `ApiSpineEngineProvider`'s `answerText`/citation-
+ * url boundary (sc-4-3). `String.prototype.replace` resets a global
+ * pattern's `lastIndex` on every call, so reusing the shared, module-level
+ * `RegExp` instances across calls is safe.
+ */
+export declare function defaultGroundedTextSanitizeFn(raw: string): {
+    content: string;
+    hadThreats: boolean;
+};
+/**
+ * Injected seam (mirrors the `deps` shape in the architecture doc's
+ * `resolveAiVisibilityProvider` section). `makeClient` returns `undefined`
+ * when an engine has no usable key/credential — that arm is skipped
+ * entirely, never composed (the no-key viability check, ADR-3/ADR-5).
+ * Production wiring builds a real `LiveGroundedSearchClient` per keyed
+ * engine (`runner.ts`'s `defaultAiVisibilityDeps`); tests inject fakes so
+ * this factory — and every caller of it — stays network-free (sc-3-4).
+ *
+ * `scrapeThrottle` (Sprint 10) is OPTIONAL — `resolveAiVisibilityProvider`
+ * composes the damcrawler UI-scrape arm(s) ONLY when this dep is present AND
+ * the `ai-visibility-scrape` axis is on AND a matching engine is configured.
+ * As of Sprint 11, `defaultAiVisibilityDeps` (`../runner.ts`) constructs a
+ * REAL `ScrapeThrottle` from `config`/`projectRoot` in production — this dep
+ * is no longer test-only (sc-11-2).
+ *
+ * `makeJudgeLlm` (Sprint 11, sc-11-3) is OPTIONAL — when present AND
+ * `config.seo.aiVisibility.judge.enabled` is true, `resolveAiVisibilityProvider`
+ * wraps each API arm's extractor in a `LlmJudgeMentionCitationExtractor`
+ * built from the returned `{ client, model }`. Returning `undefined` (e.g.
+ * no API key) keeps the plain `deps.extractor` in use — no-key-safe, mirrors
+ * `makeClient`'s viability-check idiom.
+ *
+ * `scrapeLoad` (Sprint 11) is OPTIONAL test injection for the scrape arm's
+ * `DamcrawlerScrapeLoader` seam — `undefined` in production lets each
+ * `ScrapeArmEngineProvider` fall back to its own real lazy `damcrawler`
+ * import (`./sources/scrape-arm-provider.ts`'s `defaultLoader`); tests
+ * inject a fake module so a scrape-composition test never needs the real
+ * dependency installed.
+ */
+export interface AiVisibilityDeps {
+    makeClient: (engine: GroundedEngine) => GroundedSearchClient | undefined;
+    extractor: MentionCitationExtractor;
+    scrapeThrottle?: ScrapeThrottle;
+    makeJudgeLlm?: () => {
+        client: LLMClient;
+        model: string;
+    } | undefined;
+    scrapeLoad?: DamcrawlerScrapeLoader;
+}
+/**
+ * Fans one `probe()` call out to every configured arm and CONCATENATES
+ * their rows — arms are NEVER merged, cross-arm signal is never combined
+ * (architecture:44; each row already carries its own `provider` label, so a
+ * consumer can always tell which engine produced which observation).
+ *
+ * `estCostUsdPerPrompt` is the plain sum of each arm's ALREADY N-baked price
+ * (`ApiSpineEngineProvider.estCostUsdPerPrompt = perCallUsd * samplesPerPrompt`,
+ * Sprint 2, ADR-3) — this class must NOT re-multiply by N.
+ */
+export declare class AiVisibilityMultiplexer implements AiVisibilityProvider {
+    private readonly arms;
+    readonly name = "ai-visibility-multiplexer";
+    readonly estCostUsdPerPrompt: number;
+    constructor(arms: AiVisibilityProvider[]);
+    /**
+     * One arm rejecting => its rows are simply omitted, the other arms still
+     * emit (architecture:277). If EVERY arm rejects (and there is at least one
+     * arm), rethrow instead of resolving `[]` — the LOCKED `AiVisibilityAdapter`
+     * converts any probe throw into `abstain` + books nothing
+     * (`ai-visibility-adapter.ts:141-143`), which is exactly the "all fail =>
+     * abstain, nothing booked" invariant `ApiSpineEngineProvider.probe` already
+     * upholds one level down (sc-2-4). Resolving `[]` here instead would let
+     * the adapter book USD for zero rows on a total outage — the rethrow keeps
+     * that impossible.
+     */
+    probe(target: string, prompts: string[], locale?: string): Promise<AiVisibilityRow[]>;
+}
+/**
+ * Select which per-engine arms are viable and compose them into an
+ * `AiVisibilityMultiplexer` — mirrors `resolveSerpProvider`
+ * (`serp-provider.ts:55-64`) in DI style: this factory does NO gating of its
+ * own beyond the viability checks below; each returned provider is already
+ * fully constructed from already-built dependencies. The API spine and the
+ * scrape arm(s) (Sprint 10/11) land in the SAME `arms` array and share the
+ * ONE multiplexer — they stay unmixable because each row carries its own
+ * `provider` label (sc-10-4; `AiVisibilityMultiplexer` never merges rows).
+ *
+ * An arm is added when EITHER:
+ *   (a) the `ai-visibility` axis is on AND a configured engine is keyed
+ *       (`deps.makeClient` returns a client) — the existing API-spine loop, or
+ *   (b) the `ai-visibility-scrape` axis is on AND `deps.scrapeThrottle` is
+ *       provided (the scrape arm needs an already-built throttle, see
+ *       `AiVisibilityDeps` docstring) — one arm is composed per engine in
+ *       `cfg.scrape.engines` (`"chatgpt-ui"` and/or `"perplexity-ui"`,
+ *       sc-11-1), each with its matching `EngineScrapeParser`.
+ * Both API and scrape arms reuse the SAME shared `DamcrawlerCitationVerifier`
+ * (self-gates `site-crawl` per call, holds no per-arm state — safe to share).
+ *
+ * `apiAxisOn` (Sprint 11, sc-11-3): each API arm's extractor is
+ * `deps.extractor` (the plain deterministic pass) UNLESS BOTH
+ * `cfg.judge?.enabled` is true AND `deps.makeJudgeLlm()` returns a usable
+ * `{ client, model }` — in which case every API arm gets a SHARED
+ * `LlmJudgeMentionCitationExtractor` wrapping a fresh
+ * `DeterministicMentionCitationExtractor` (the judge always composes the
+ * deterministic pass, never replaces it). The scrape arm(s) always stay on
+ * `deps.extractor` — the judge is API-arms only (contract: "for each API
+ * arm"). judge-disabled (or no llm resolvable) is BYTE-IDENTICAL to before:
+ * `apiExtractor` stays exactly `deps.extractor`, no judge/extractor is
+ * constructed at all (sc-11-3, Pitfall 5).
+ *
+ * Returns `undefined` (never an empty-arms multiplexer) when NEITHER axis is
+ * on, `config.seo.aiVisibility` is absent, or no arm ends up viable (no key /
+ * no scrape engine configured / no throttle dep). `selectSource` falls back
+ * to the offline `LocalExportSource` in that case (no-key-safe,
+ * byte-identical-when-off).
+ */
+export declare function resolveAiVisibilityProvider(config: BoberConfig, egress: SeoEgressGuard, deps: AiVisibilityDeps): AiVisibilityProvider | undefined;
+//# sourceMappingURL=ai-visibility-provider.d.ts.map

package/dist/seo/ai-visibility-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-visibility-provider.d.ts","sourceRoot":"","sources":["../../src/seo/ai-visibility-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oCAAoC,CAAC;AAC/E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,KAAK,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,iCAAiC,CAAC;AAC5F,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,yCAAyC,CAAC;AACxF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAgB,sBAAsB,EAAE,MAAM,kCAAkC,CAAC;AAwB7F;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;CAAE,CASnG;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,CAAC,MAAM,EAAE,cAAc,KAAK,oBAAoB,GAAG,SAAS,CAAC;IACzE,SAAS,EAAE,wBAAwB,CAAC;IACpC,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,YAAY,CAAC,EAAE,MAAM;QAAE,MAAM,EAAE,SAAS,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC;IACtE,UAAU,CAAC,EAAE,sBAAsB,CAAC;CACrC;AAED;;;;;;;;;GASG;AACH,qBAAa,uBAAwB,YAAW,oBAAoB;IAItD,OAAO,CAAC,QAAQ,CAAC,IAAI;IAHjC,QAAQ,CAAC,IAAI,+BAA+B;IAC5C,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;gBAER,IAAI,EAAE,oBAAoB,EAAE;IAIzD;;;;;;;;;;OAUG;IACG,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;CAgB5F;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,cAAc,EACtB,IAAI,EAAE,gBAAgB,GACrB,oBAAoB,GAAG,SAAS,CA+ElC"}

package/dist/seo/ai-visibility-provider.js

@@ -0,0 +1,165 @@
+import { ApiSpineEngineProvider } from "./sources/api-spine-provider.js";
+import { DamcrawlerCitationVerifier } from "./sources/citation-verifier.js";
+import { ContentSanitizer } from "./content-sanitizer.js";
+import { ScrapeArmEngineProvider } from "./sources/scrape-arm-provider.js";
+import { ChatgptUiScrapeParser } from "./sources/engine-scrape-parser-chatgpt.js";
+import { PerplexityUiScrapeParser } from "./sources/engine-scrape-parser-perplexity.js";
+import { DeterministicMentionCitationExtractor, LlmJudgeMentionCitationExtractor } from "./sources/mention-citation-extractor.js";
+/**
+ * Recognized prompt-injection role/instruction markers — fenced
+ * `<system>`/`<|im_start|>`-style tags and "ignore previous instructions"
+ * phrasing — the class of payload a grounding LLM could echo back verbatim
+ * from a page it read during its own web search. Not damcrawler-grade
+ * threat classification (that stays `DamcrawlerCitationVerifier`'s job for
+ * scraped citation bodies); this is a narrower, dependency-free, always-on
+ * second layer for the LLM's own free-text summary + citation urls.
+ */
+const GROUNDED_TEXT_INJECTION_PATTERNS = [
+    /<\s*\/?\s*(system|assistant|\|im_start\|?|\|im_end\|?)[^>]*>/gi,
+    /\bignore\s+(all\s+|any\s+)?(previous|prior|above)\s+instructions\b/gi,
+];
+/**
+ * Default `SanitizeFn` for `ApiSpineEngineProvider`'s `answerText`/citation-
+ * url boundary (sc-4-3). `String.prototype.replace` resets a global
+ * pattern's `lastIndex` on every call, so reusing the shared, module-level
+ * `RegExp` instances across calls is safe.
+ */
+export function defaultGroundedTextSanitizeFn(raw) {
+    let content = raw;
+    let hadThreats = false;
+    for (const pattern of GROUNDED_TEXT_INJECTION_PATTERNS) {
+        const stripped = content.replace(pattern, "");
+        if (stripped !== content)
+            hadThreats = true;
+        content = stripped;
+    }
+    return { content: content.trim(), hadThreats };
+}
+/**
+ * Fans one `probe()` call out to every configured arm and CONCATENATES
+ * their rows — arms are NEVER merged, cross-arm signal is never combined
+ * (architecture:44; each row already carries its own `provider` label, so a
+ * consumer can always tell which engine produced which observation).
+ *
+ * `estCostUsdPerPrompt` is the plain sum of each arm's ALREADY N-baked price
+ * (`ApiSpineEngineProvider.estCostUsdPerPrompt = perCallUsd * samplesPerPrompt`,
+ * Sprint 2, ADR-3) — this class must NOT re-multiply by N.
+ */
+export class AiVisibilityMultiplexer {
+    arms;
+    name = "ai-visibility-multiplexer";
+    estCostUsdPerPrompt;
+    constructor(arms) {
+        this.arms = arms;
+        this.estCostUsdPerPrompt = arms.reduce((sum, arm) => sum + arm.estCostUsdPerPrompt, 0);
+    }
+    /**
+     * One arm rejecting => its rows are simply omitted, the other arms still
+     * emit (architecture:277). If EVERY arm rejects (and there is at least one
+     * arm), rethrow instead of resolving `[]` — the LOCKED `AiVisibilityAdapter`
+     * converts any probe throw into `abstain` + books nothing
+     * (`ai-visibility-adapter.ts:141-143`), which is exactly the "all fail =>
+     * abstain, nothing booked" invariant `ApiSpineEngineProvider.probe` already
+     * upholds one level down (sc-2-4). Resolving `[]` here instead would let
+     * the adapter book USD for zero rows on a total outage — the rethrow keeps
+     * that impossible.
+     */
+    async probe(target, prompts, locale) {
+        // The `async` wrapper (not a bare `.map((arm) => arm.probe(...))`) matters:
+        // it captures a SYNCHRONOUS throw from a misbehaving arm as a rejected
+        // promise too, so `Promise.allSettled` never has an exception escape past
+        // it before every arm has had a chance to run.
+        const settled = await Promise.allSettled(this.arms.map(async (arm) => arm.probe(target, prompts, locale)));
+        const fulfilled = settled.filter((s) => s.status === "fulfilled");
+        if (this.arms.length > 0 && fulfilled.length === 0) {
+            throw new Error("AiVisibilityMultiplexer: every arm failed");
+        }
+        return fulfilled.flatMap((s) => s.value);
+    }
+}
+/**
+ * Select which per-engine arms are viable and compose them into an
+ * `AiVisibilityMultiplexer` — mirrors `resolveSerpProvider`
+ * (`serp-provider.ts:55-64`) in DI style: this factory does NO gating of its
+ * own beyond the viability checks below; each returned provider is already
+ * fully constructed from already-built dependencies. The API spine and the
+ * scrape arm(s) (Sprint 10/11) land in the SAME `arms` array and share the
+ * ONE multiplexer — they stay unmixable because each row carries its own
+ * `provider` label (sc-10-4; `AiVisibilityMultiplexer` never merges rows).
+ *
+ * An arm is added when EITHER:
+ *   (a) the `ai-visibility` axis is on AND a configured engine is keyed
+ *       (`deps.makeClient` returns a client) — the existing API-spine loop, or
+ *   (b) the `ai-visibility-scrape` axis is on AND `deps.scrapeThrottle` is
+ *       provided (the scrape arm needs an already-built throttle, see
+ *       `AiVisibilityDeps` docstring) — one arm is composed per engine in
+ *       `cfg.scrape.engines` (`"chatgpt-ui"` and/or `"perplexity-ui"`,
+ *       sc-11-1), each with its matching `EngineScrapeParser`.
+ * Both API and scrape arms reuse the SAME shared `DamcrawlerCitationVerifier`
+ * (self-gates `site-crawl` per call, holds no per-arm state — safe to share).
+ *
+ * `apiAxisOn` (Sprint 11, sc-11-3): each API arm's extractor is
+ * `deps.extractor` (the plain deterministic pass) UNLESS BOTH
+ * `cfg.judge?.enabled` is true AND `deps.makeJudgeLlm()` returns a usable
+ * `{ client, model }` — in which case every API arm gets a SHARED
+ * `LlmJudgeMentionCitationExtractor` wrapping a fresh
+ * `DeterministicMentionCitationExtractor` (the judge always composes the
+ * deterministic pass, never replaces it). The scrape arm(s) always stay on
+ * `deps.extractor` — the judge is API-arms only (contract: "for each API
+ * arm"). judge-disabled (or no llm resolvable) is BYTE-IDENTICAL to before:
+ * `apiExtractor` stays exactly `deps.extractor`, no judge/extractor is
+ * constructed at all (sc-11-3, Pitfall 5).
+ *
+ * Returns `undefined` (never an empty-arms multiplexer) when NEITHER axis is
+ * on, `config.seo.aiVisibility` is absent, or no arm ends up viable (no key /
+ * no scrape engine configured / no throttle dep). `selectSource` falls back
+ * to the offline `LocalExportSource` in that case (no-key-safe,
+ * byte-identical-when-off).
+ */
+export function resolveAiVisibilityProvider(config, egress, deps) {
+    const cfg = config.seo?.aiVisibility;
+    if (!cfg)
+        return undefined; // nothing configured at all
+    const apiAxisOn = egress.isAllowed("ai-visibility");
+    const scrapeAxisOn = egress.isAllowed("ai-visibility-scrape");
+    if (!apiAxisOn && !scrapeAxisOn)
+        return undefined; // both axes off => offline fallback
+    // Shared across every arm (Sprint 4, extended Sprint 10): the verifier
+    // self-gates `site-crawl` on every `verify()` call and holds no per-arm
+    // state; the sanitizer's `SanitizeFn` is a pure function — both are safe
+    // to share across API arms (the scrape arm builds its OWN sanitizer from
+    // the loaded damcrawler module, not this one — see `ScrapeArmEngineProvider`).
+    const verifier = new DamcrawlerCitationVerifier(egress);
+    const sanitizer = new ContentSanitizer(defaultGroundedTextSanitizeFn);
+    const arms = [];
+    if (apiAxisOn) {
+        // sc-11-3: judge wraps the API-arm extractor ONLY when enabled AND an
+        // llm resolves — otherwise `apiExtractor` stays exactly `deps.extractor`
+        // (byte-identical-when-disabled, Pitfall 5). One shared judge instance
+        // (mirrors sharing `verifier`/`sanitizer` above) — the judge itself is
+        // stateless per call.
+        let apiExtractor = deps.extractor;
+        if (cfg.judge?.enabled) {
+            const judge = deps.makeJudgeLlm?.();
+            if (judge) {
+                apiExtractor = new LlmJudgeMentionCitationExtractor(new DeterministicMentionCitationExtractor(), judge.client, judge.model, sanitizer);
+            }
+        }
+        for (const engineCfg of cfg.engines) {
+            const client = deps.makeClient(engineCfg.engine);
+            if (!client)
+                continue; // no key/credential for this engine => skip (viability check)
+            arms.push(new ApiSpineEngineProvider(client, apiExtractor, cfg.samplesPerPrompt, engineCfg.perCallUsd, verifier, sanitizer));
+        }
+    }
+    if (scrapeAxisOn && deps.scrapeThrottle && cfg.scrape) {
+        const scrapeCfg = cfg.scrape;
+        const throttle = deps.scrapeThrottle;
+        const parserFor = (engine) => engine === "perplexity-ui" ? new PerplexityUiScrapeParser() : new ChatgptUiScrapeParser();
+        for (const engine of scrapeCfg.engines) {
+            arms.push(new ScrapeArmEngineProvider(egress, engine, parserFor(engine), deps.extractor, verifier, throttle, cfg.samplesPerPrompt, scrapeCfg.authSession, scrapeCfg.proxyUsdPerScrape, scrapeCfg.proxy, deps.scrapeLoad));
+        }
+    }
+    return arms.length > 0 ? new AiVisibilityMultiplexer(arms) : undefined; // no-key-safe / no-throttle-safe
+}
+//# sourceMappingURL=ai-visibility-provider.js.map

package/dist/seo/ai-visibility-provider.js.map

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

package/dist/seo/ai-visibility-scorer.d.ts

@@ -0,0 +1,43 @@
+/**
+ * AiVisibilityScorer — PURE aggregation of raw AiVisibilityRow observations
+ * into per-(prompt,provider) rates + a deterministic Wilson 95% CI
+ * (in-house-ai-visibility, Sprint 5; ADR-5).
+ *
+ * PURE, synchronous, network-free transform: groups the raw per-sample
+ * `AiVisibilityRow[]` STRICTLY by (prompt, provider) — arms are NEVER
+ * merged, even when they share a prompt — and folds each group into one
+ * `AiVisibilityMetric` carrying mention/citation rates, an optional mean
+ * rank, a deduped `sourceUrls` union (first-seen order), and a
+ * deterministic Wilson 95% score interval over the mention indicator
+ * (z=1.96, no RNG, no `Date`). Never throws.
+ *
+ * This module is consumed ANALYZER-SIDE (`analyzer.ts`'s
+ * `describeAiVisibility`, gated on `provenance.source === "ai-visibility"`)
+ * to fold N raw rows into rates+CI for the LLM prompt — the metric is a
+ * derived, in-prompt-only projection and is never persisted to the locked
+ * `SeoDataBundle.aiVisibility` (`DataOutcome<AiVisibilityRow[]>`).
+ */
+import type { AiVisibilityRow } from "./data-source.js";
+/** Derived, in-analyzer projection — NOT persisted to the locked SeoDataBundle. */
+export type AiVisibilityMetric = {
+    prompt: string;
+    provider: string;
+    samples: number;
+    mentionRate: number;
+    citationRate: number;
+    /** OMITTED (never `undefined`) when no row in the group carries a `rank`. */
+    meanRank?: number;
+    /** Wilson 95% score interval over the mention indicator (z=1.96). */
+    mentionRateCi95: [number, number];
+    /** Deduped union of every row's `sourceUrls`, first-seen order preserved. */
+    sourceUrls: string[];
+};
+export declare class AiVisibilityScorer {
+    /**
+     * Groups `rows` strictly by `(prompt, provider)` — arms are NEVER merged,
+     * even when they share a prompt. Empty input yields `[]`. Preserves
+     * first-seen group order. Never throws.
+     */
+    aggregate(rows: AiVisibilityRow[]): AiVisibilityMetric[];
+}
+//# sourceMappingURL=ai-visibility-scorer.d.ts.map

package/dist/seo/ai-visibility-scorer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-visibility-scorer.d.ts","sourceRoot":"","sources":["../../src/seo/ai-visibility-scorer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAExD,mFAAmF;AACnF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,eAAe,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,6EAA6E;IAC7E,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB,CAAC;AAqFF,qBAAa,kBAAkB;IAC7B;;;;OAIG;IACH,SAAS,CAAC,IAAI,EAAE,eAAe,EAAE,GAAG,kBAAkB,EAAE;CAoBzD"}

package/dist/seo/ai-visibility-scorer.js

@@ -0,0 +1,102 @@
+const Z = 1.96; // 95% two-sided; hard-coded, no config, no RNG
+const Z_SQUARED = Z * Z;
+/**
+ * Wilson 95% score interval for `successes` out of `n` Bernoulli trials.
+ *
+ * `n <= 1` is a SPECIAL CASE returning the degenerate `[rate, rate]` — the
+ * raw Wilson formula does NOT naturally collapse to a point interval for a
+ * single sample (e.g. 1/1 yields roughly `[0.207, 1.0]`), so a single
+ * observation is reported with zero spread instead of a misleadingly wide
+ * one-sample interval.
+ */
+function wilsonCi95(successes, n) {
+    if (n <= 1) {
+        const rate = n === 1 ? successes / n : 0;
+        return [rate, rate];
+    }
+    const p = successes / n;
+    const denom = 1 + Z_SQUARED / n;
+    const center = (p + Z_SQUARED / (2 * n)) / denom;
+    const margin = (Z * Math.sqrt(p * (1 - p) / n + Z_SQUARED / (4 * n * n))) / denom;
+    // The Wilson interval is naturally bounded in [0, 1]; clamp defensively.
+    const lower = Math.max(0, center - margin);
+    const upper = Math.min(1, center + margin);
+    return [lower, upper];
+}
+/**
+ * Collision-safe composite grouping key — `JSON.stringify` of the tuple
+ * rather than naive string concatenation (a delimiter like `"::"` could
+ * appear inside a prompt or provider string and silently merge two arms).
+ */
+function groupKey(prompt, provider) {
+    return JSON.stringify([prompt, provider]);
+}
+/** Mean of every row's `rank`, or `undefined` when no row carries one. */
+function computeMeanRank(rows) {
+    const ranks = rows.map((r) => r.rank).filter((r) => typeof r === "number");
+    if (ranks.length === 0)
+        return undefined;
+    return ranks.reduce((sum, r) => sum + r, 0) / ranks.length;
+}
+/** Deduped union of every row's `sourceUrls`, preserving first-seen order. */
+function dedupeSourceUrls(rows) {
+    const seen = new Set();
+    const result = [];
+    for (const row of rows) {
+        const urls = Array.isArray(row.sourceUrls) ? row.sourceUrls : [];
+        for (const url of urls) {
+            if (!seen.has(url)) {
+                seen.add(url);
+                result.push(url);
+            }
+        }
+    }
+    return result;
+}
+/** Folds one (prompt,provider) group's rows into a single `AiVisibilityMetric`. */
+function scoreGroup(rows) {
+    const { prompt, provider } = rows[0];
+    const n = rows.length;
+    const mentionedCount = rows.filter((r) => r.mentioned === true).length;
+    const citedCount = rows.filter((r) => r.citationPresent === true).length;
+    const meanRank = computeMeanRank(rows);
+    const metric = {
+        prompt,
+        provider,
+        samples: n,
+        mentionRate: mentionedCount / n,
+        citationRate: citedCount / n,
+        mentionRateCi95: wilsonCi95(mentionedCount, n),
+        sourceUrls: dedupeSourceUrls(rows),
+    };
+    // Pattern B: OMIT the key entirely rather than setting `meanRank: undefined`.
+    return meanRank === undefined ? metric : { ...metric, meanRank };
+}
+export class AiVisibilityScorer {
+    /**
+     * Groups `rows` strictly by `(prompt, provider)` — arms are NEVER merged,
+     * even when they share a prompt. Empty input yields `[]`. Preserves
+     * first-seen group order. Never throws.
+     */
+    aggregate(rows) {
+        if (!Array.isArray(rows) || rows.length === 0)
+            return [];
+        const groups = new Map();
+        for (const row of rows) {
+            const key = groupKey(row.prompt, row.provider);
+            const existing = groups.get(key);
+            if (existing) {
+                existing.push(row);
+            }
+            else {
+                groups.set(key, [row]);
+            }
+        }
+        const metrics = [];
+        for (const groupRows of groups.values()) {
+            metrics.push(scoreGroup(groupRows));
+        }
+        return metrics;
+    }
+}
+//# sourceMappingURL=ai-visibility-scorer.js.map

package/dist/seo/ai-visibility-scorer.js.map

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

package/dist/seo/analyzer.d.ts

@@ -0,0 +1,58 @@
+import type { LLMClient } from "../providers/types.js";
+import type { SeoWorkflow, SeoFinding, DataOutcome, DataProvenance } from "./types.js";
+import type { SearchAnalyticsRow, UrlInspectionRow, SerpRow, KeywordRow, BacklinkRow, AiVisibilityRow, LinkGraphRow } from "./data-source.js";
+import type { SeoRetrieveResult } from "./retriever.js";
+import type { BoberConfig } from "../config/schema.js";
+/**
+ * Per-capability optional `DataOutcome<Row[]>` — a source may abstain/
+ * disable per capability. `aiVisibility`/`linkGraph` were added additively
+ * (spec-20260717-seo-improver-builder, Sprint 9; ADR-7) — an arm left
+ * `undefined` (a capability `WORKFLOW_CAPABILITIES` omits for the running
+ * workflow) renders as "not requested" (`describeDataOutcome` below), never
+ * as an error.
+ */
+export type SeoDataBundle = {
+    searchAnalytics?: DataOutcome<SearchAnalyticsRow[]>;
+    urlInspection?: DataOutcome<UrlInspectionRow[]>;
+    serp?: DataOutcome<SerpRow[]>;
+    keywords?: DataOutcome<KeywordRow[]>;
+    backlinks?: DataOutcome<BacklinkRow[]>;
+    aiVisibility?: DataOutcome<AiVisibilityRow[]>;
+    linkGraph?: DataOutcome<LinkGraphRow[]>;
+};
+export type SeoAnalyzeInput = {
+    workflow: SeoWorkflow;
+    target: string;
+    /** The existing retriever output (retriever.ts:22-25) — the arch calls this `SeoPlaybookContext`. */
+    context: SeoRetrieveResult;
+    data: SeoDataBundle;
+    /**
+     * Accepted for interface parity with the architecture's `SeoAnalyzeInput`
+     * (arch:250-256) and the Sprint 11 runner contract. Not consumed by this
+     * sprint's `analyze` body — `llm`/`model` are constructor-injected, and no
+     * analyzer behaviour this sprint reads `config`.
+     */
+    config: BoberConfig;
+    /** Injected wall-clock snapshot (ISO-8601) — the analyzer never reads the clock itself. */
+    now: string;
+};
+export type SeoAnalysis = {
+    workflow: SeoWorkflow;
+    target: string;
+    findings: SeoFinding[];
+    /** false when the LLM output could not be parsed (fail-closed, sc-10-2). */
+    parsed: boolean;
+    dataProvenance: DataProvenance[];
+};
+export declare class SeoAnalyzer {
+    private readonly llm;
+    private readonly model;
+    constructor(llm: LLMClient, model: string);
+    /**
+     * Never throws on a PARSE failure (returns `parsed: false` with empty
+     * findings). Does NOT catch a transport error from `llm.chat` — that
+     * rejects the returned promise, distinct from a parse failure.
+     */
+    analyze(input: SeoAnalyzeInput): Promise<SeoAnalysis>;
+}
+//# sourceMappingURL=analyzer.d.ts.map

package/dist/seo/analyzer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyzer.d.ts","sourceRoot":"","sources":["../../src/seo/analyzer.ts"],"names":[],"mappings":"AA6BA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,cAAc,EAAgB,MAAM,YAAY,CAAC;AACrG,OAAO,KAAK,EACV,kBAAkB,EAClB,gBAAgB,EAChB,OAAO,EACP,UAAU,EACV,WAAW,EACX,eAAe,EACf,YAAY,EACb,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAKvD;;;;;;;GAOG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,eAAe,CAAC,EAAE,WAAW,CAAC,kBAAkB,EAAE,CAAC,CAAC;IACpD,aAAa,CAAC,EAAE,WAAW,CAAC,gBAAgB,EAAE,CAAC,CAAC;IAChD,IAAI,CAAC,EAAE,WAAW,CAAC,OAAO,EAAE,CAAC,CAAC;IAC9B,QAAQ,CAAC,EAAE,WAAW,CAAC,UAAU,EAAE,CAAC,CAAC;IACrC,SAAS,CAAC,EAAE,WAAW,CAAC,WAAW,EAAE,CAAC,CAAC;IACvC,YAAY,CAAC,EAAE,WAAW,CAAC,eAAe,EAAE,CAAC,CAAC;IAC9C,SAAS,CAAC,EAAE,WAAW,CAAC,YAAY,EAAE,CAAC,CAAC;CACzC,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,EAAE,WAAW,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,qGAAqG;IACrG,OAAO,EAAE,iBAAiB,CAAC;IAC3B,IAAI,EAAE,aAAa,CAAC;IACpB;;;;;OAKG;IACH,MAAM,EAAE,WAAW,CAAC;IACpB,2FAA2F;IAC3F,GAAG,EAAE,MAAM,CAAC;CACb,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,QAAQ,EAAE,WAAW,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,UAAU,EAAE,CAAC;IACvB,4EAA4E;IAC5E,MAAM,EAAE,OAAO,CAAC;IAChB,cAAc,EAAE,cAAc,EAAE,CAAC;CAClC,CAAC;AA6OF,qBAAa,WAAW;IAEpB,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,KAAK;gBADL,GAAG,EAAE,SAAS,EACd,KAAK,EAAE,MAAM;IAGhC;;;;OAIG;IACG,OAAO,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,WAAW,CAAC;CAsB5D"}