agent-bober 0.18.0 → 0.19.0

package/dist/seo/sources/local-export.js.map

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

package/dist/seo/sources/mention-citation-extractor.d.ts

@@ -0,0 +1,136 @@
+/**
+ * MentionCitationExtractor — deterministic host/brand matcher over a
+ * grounded-search answer (in-house-ai-visibility, Sprint 2;
+ * arch-20260717-in-house-oss-ai-visibility-architecture.md:148-159,240-245),
+ * with an OPTIONAL injected LLM-as-judge fuzzy-mention path added in
+ * Sprint 8.
+ *
+ * PURE, synchronous, network-free transform: given `{target, answerText,
+ * citations}` it decides `{mentioned, rank?, citationPresent, sourceUrls}`
+ * by string/host matching alone — no `CitationVerifier` call (Sprint 4,
+ * a nonGoal here — `sourceUrls` here are candidate URLs, not verified
+ * ones).
+ *
+ * Matching strategy (deterministic only, per the architecture):
+ *   1. Normalize `target` to a bare host (strip scheme, `www.`) via the
+ *      local `safeHost` guard — mirrors `safeOrigin`
+ *      (`damcrawler-crawl-engine.ts:122-129`) and the "no shared URL/host
+ *      util exists in `src`" note (`citation-gate.ts:30-32`).
+ *   2. `mentioned` = the target's brand token (the host's first label) OR
+ *      its full bare host appears, case-insensitive and on a word
+ *      boundary, in `answerText` OR in any citation's `title`. Word-
+ *      boundary matching (not naive `includes`) avoids substring false
+ *      positives (e.g. brand "ace" must not match inside "space").
+ *   3. `sourceUrls` = citation URLs whose host equals the target host (or
+ *      is a subdomain of it) — candidate URLs only, never verified.
+ *   4. `citationPresent` = `sourceUrls.length > 0`.
+ *   5. `rank` is never derivable deterministically this sprint, so the key
+ *      is always omitted (never `rank: undefined`) — sc-2-1 does not
+ *      require it.
+ *
+ * Empty/whitespace/malformed input (empty `target`, empty/whitespace
+ * `answerText`, empty `citations`) always yields
+ * `{ mentioned: false, citationPresent: false, sourceUrls: [] }` — this
+ * class NEVER fabricates a positive observation (sc-2-1, stopConditions).
+ *
+ * Sprint 8 — LLM-as-judge fuzzy-mention path (`LlmJudgeMentionCitationExtractor`):
+ * an OPTIONAL, injected-`llm` extractor that COMPOSES the deterministic one.
+ * It runs the deterministic pass first; only when that pass left
+ * `mentioned:false` (cost control, evaluatorNotes) does it sanitize the
+ * answer text and ask a bounded, schema-parsed LLM judge whether the
+ * answer fuzzily/paraphrasedly mentions the target. The judge FAILS SAFE
+ * to the deterministic result on any transport error or unparseable
+ * verdict — it never fabricates `mentioned:true` (sc-8-3). Production
+ * wiring (`ai-visibility-provider.ts`, `runner.ts`) still constructs the
+ * plain `DeterministicMentionCitationExtractor` with no `llm`, so the
+ * deterministic-only path remains byte-identical and this class is opt-in
+ * (sc-8-2, nonGoals: judge is NOT the default).
+ */
+import { z } from "zod";
+import type { GroundedCitation } from "../../providers/grounded-search.js";
+import type { LLMClient } from "../../providers/types.js";
+import type { ContentSanitizer } from "../content-sanitizer.js";
+/** Locked output shape — MUST match the architecture data model exactly (feeds `AiVisibilityRow`). */
+export type SampleObservation = {
+    mentioned: boolean;
+    rank?: number;
+    citationPresent: boolean;
+    sourceUrls: string[];
+};
+export interface MentionCitationExtractor {
+    extract(input: {
+        target: string;
+        answerText: string;
+        citations: GroundedCitation[];
+    }): SampleObservation | Promise<SampleObservation>;
+}
+export declare class DeterministicMentionCitationExtractor implements MentionCitationExtractor {
+    extract({ target, answerText, citations, }: {
+        target: string;
+        answerText: string;
+        citations: GroundedCitation[];
+    }): SampleObservation;
+}
+/** Bounded judge verdict — the ONLY shape the judge is allowed to return. */
+export declare const JudgeVerdictSchema: z.ZodObject<{
+    mentioned: z.ZodBoolean;
+    rank: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    mentioned: boolean;
+    rank?: number | undefined;
+}, {
+    mentioned: boolean;
+    rank?: number | undefined;
+}>;
+export type JudgeVerdict = z.infer<typeof JudgeVerdictSchema>;
+export type ParseJudgeVerdictResult = {
+    ok: true;
+    verdict: JudgeVerdict;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Never-throws 3-tier verdict parser — mirrors
+ * `validateGroundingVerdict` (`src/medical/retrieval/grounding-critic.ts:40-88`):
+ * try a direct parse, then a fenced ```json block, then the first
+ * `{...}` span; `safeParse` at the end never throws. On total failure
+ * returns `{ ok: false, error }` so the caller can fail SAFE to the
+ * deterministic result (sc-8-3) rather than propagate a throw.
+ */
+export declare function parseJudgeVerdict(rawText: string): ParseJudgeVerdictResult;
+/**
+ * OPTIONAL, injected LLM-as-judge fuzzy-mention extractor (Sprint 8;
+ * sc-8-1..sc-8-4). COMPOSES `DeterministicMentionCitationExtractor` —
+ * always runs the deterministic pass first and returns it verbatim
+ * (no judge call, cost control) when it already found a mention. Only
+ * when the deterministic pass left `mentioned:false` on a non-empty
+ * answer does this class sanitize the text (sc-8-4) and ask a bounded,
+ * schema-parsed judge whether the answer fuzzily mentions the target.
+ *
+ * FAIL-SAFE (sc-8-3): a thrown `llm.chat` transport error or an
+ * unparseable/malformed verdict falls back to the deterministic result
+ * VERBATIM — this class never fabricates `mentioned:true`. The judge
+ * only ever overrides `mentioned`/`rank`; `citationPresent`/`sourceUrls`
+ * always come from the deterministic pass (the judge does not re-derive
+ * URLs — nonGoals: not used for citation URL verification).
+ *
+ * NOT wired into production callers this sprint (`ai-visibility-provider.ts`,
+ * `runner.ts` still construct the plain `DeterministicMentionCitationExtractor`
+ * with no `llm`) — this class is exercised via unit tests injecting a
+ * scripted `LLMClient`, keeping the deterministic-only path byte-identical
+ * (sc-8-2).
+ */
+export declare class LlmJudgeMentionCitationExtractor implements MentionCitationExtractor {
+    private readonly deterministic;
+    private readonly llm;
+    private readonly model;
+    private readonly sanitizer;
+    constructor(deterministic: DeterministicMentionCitationExtractor, llm: LLMClient, model: string, sanitizer: ContentSanitizer);
+    extract(input: {
+        target: string;
+        answerText: string;
+        citations: GroundedCitation[];
+    }): Promise<SampleObservation>;
+}
+//# sourceMappingURL=mention-citation-extractor.d.ts.map

package/dist/seo/sources/mention-citation-extractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mention-citation-extractor.d.ts","sourceRoot":"","sources":["../../../src/seo/sources/mention-citation-extractor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oCAAoC,CAAC;AAC3E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAEhE,sGAAsG;AACtG,MAAM,MAAM,iBAAiB,GAAG;IAC9B,SAAS,EAAE,OAAO,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,eAAe,EAAE,OAAO,CAAC;IACzB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB,CAAC;AAEF,MAAM,WAAW,wBAAwB;IACvC,OAAO,CAAC,KAAK,EAAE;QACb,MAAM,EAAE,MAAM,CAAC;QACf,UAAU,EAAE,MAAM,CAAC;QACnB,SAAS,EAAE,gBAAgB,EAAE,CAAC;KAC/B,GAAG,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;CACpD;AAyDD,qBAAa,qCAAsC,YAAW,wBAAwB;IACpF,OAAO,CAAC,EACN,MAAM,EACN,UAAU,EACV,SAAS,GACV,EAAE;QACD,MAAM,EAAE,MAAM,CAAC;QACf,UAAU,EAAE,MAAM,CAAC;QACnB,SAAS,EAAE,gBAAgB,EAAE,CAAC;KAC/B,GAAG,iBAAiB;CA6BtB;AAID,6EAA6E;AAC7E,eAAO,MAAM,kBAAkB;;;;;;;;;EAG7B,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D,MAAM,MAAM,uBAAuB,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,YAAY,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzG;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,uBAAuB,CAqC1E;AAwBD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,gCAAiC,YAAW,wBAAwB;IAE7E,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,SAAS;gBAHT,aAAa,EAAE,qCAAqC,EACpD,GAAG,EAAE,SAAS,EACd,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,gBAAgB;IAGxC,OAAO,CAAC,KAAK,EAAE;QACnB,MAAM,EAAE,MAAM,CAAC;QACf,UAAU,EAAE,MAAM,CAAC;QACnB,SAAS,EAAE,gBAAgB,EAAE,CAAC;KAC/B,GAAG,OAAO,CAAC,iBAAiB,CAAC;CA2C/B"}

package/dist/seo/sources/mention-citation-extractor.js

@@ -0,0 +1,272 @@
+/**
+ * MentionCitationExtractor — deterministic host/brand matcher over a
+ * grounded-search answer (in-house-ai-visibility, Sprint 2;
+ * arch-20260717-in-house-oss-ai-visibility-architecture.md:148-159,240-245),
+ * with an OPTIONAL injected LLM-as-judge fuzzy-mention path added in
+ * Sprint 8.
+ *
+ * PURE, synchronous, network-free transform: given `{target, answerText,
+ * citations}` it decides `{mentioned, rank?, citationPresent, sourceUrls}`
+ * by string/host matching alone — no `CitationVerifier` call (Sprint 4,
+ * a nonGoal here — `sourceUrls` here are candidate URLs, not verified
+ * ones).
+ *
+ * Matching strategy (deterministic only, per the architecture):
+ *   1. Normalize `target` to a bare host (strip scheme, `www.`) via the
+ *      local `safeHost` guard — mirrors `safeOrigin`
+ *      (`damcrawler-crawl-engine.ts:122-129`) and the "no shared URL/host
+ *      util exists in `src`" note (`citation-gate.ts:30-32`).
+ *   2. `mentioned` = the target's brand token (the host's first label) OR
+ *      its full bare host appears, case-insensitive and on a word
+ *      boundary, in `answerText` OR in any citation's `title`. Word-
+ *      boundary matching (not naive `includes`) avoids substring false
+ *      positives (e.g. brand "ace" must not match inside "space").
+ *   3. `sourceUrls` = citation URLs whose host equals the target host (or
+ *      is a subdomain of it) — candidate URLs only, never verified.
+ *   4. `citationPresent` = `sourceUrls.length > 0`.
+ *   5. `rank` is never derivable deterministically this sprint, so the key
+ *      is always omitted (never `rank: undefined`) — sc-2-1 does not
+ *      require it.
+ *
+ * Empty/whitespace/malformed input (empty `target`, empty/whitespace
+ * `answerText`, empty `citations`) always yields
+ * `{ mentioned: false, citationPresent: false, sourceUrls: [] }` — this
+ * class NEVER fabricates a positive observation (sc-2-1, stopConditions).
+ *
+ * Sprint 8 — LLM-as-judge fuzzy-mention path (`LlmJudgeMentionCitationExtractor`):
+ * an OPTIONAL, injected-`llm` extractor that COMPOSES the deterministic one.
+ * It runs the deterministic pass first; only when that pass left
+ * `mentioned:false` (cost control, evaluatorNotes) does it sanitize the
+ * answer text and ask a bounded, schema-parsed LLM judge whether the
+ * answer fuzzily/paraphrasedly mentions the target. The judge FAILS SAFE
+ * to the deterministic result on any transport error or unparseable
+ * verdict — it never fabricates `mentioned:true` (sc-8-3). Production
+ * wiring (`ai-visibility-provider.ts`, `runner.ts`) still constructs the
+ * plain `DeterministicMentionCitationExtractor` with no `llm`, so the
+ * deterministic-only path remains byte-identical and this class is opt-in
+ * (sc-8-2, nonGoals: judge is NOT the default).
+ */
+import { z } from "zod";
+/**
+ * `try { new URL(...).hostname } catch { "" }` — URL parsing must never
+ * throw here. Accepts both a full URL (`https://target.example/page`) and
+ * a bare domain (`target.example`, `www.target.example`) by prefixing a
+ * scheme when one is absent, mirroring `safeOrigin`
+ * (`damcrawler-crawl-engine.ts:122-129`).
+ */
+function safeHost(raw) {
+    if (typeof raw !== "string" || raw.trim().length === 0)
+        return "";
+    const hasScheme = /^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//.test(raw);
+    const candidate = hasScheme ? raw : `https://${raw}`;
+    try {
+        return new URL(candidate).hostname.toLowerCase();
+    }
+    catch {
+        return "";
+    }
+}
+/** Strips a leading `www.` label — hosts are compared without it. */
+function stripWww(host) {
+    return host.startsWith("www.") ? host.slice(4) : host;
+}
+/** Bare, `www.`-stripped host for `raw` — `""` when `raw` is empty/malformed. */
+function bareHost(raw) {
+    return stripWww(safeHost(raw));
+}
+/** The host's first label — the brand token (e.g. `"target"` from `"target.example"`). */
+function brandToken(host) {
+    const [first] = host.split(".");
+    return first ?? "";
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Case-insensitive, word-boundary substring test. Word-boundary (not
+ * `includes`) prevents a brand token from matching inside an unrelated
+ * larger word (e.g. `"ace"` must not match `"space"`).
+ */
+function containsWordBoundary(haystack, needle) {
+    if (!needle)
+        return false;
+    const pattern = new RegExp(`\\b${escapeRegExp(needle)}\\b`, "i");
+    return pattern.test(haystack);
+}
+/** `true` when `citationHost` is exactly `targetHost` or a subdomain of it. Both inputs are already bare/`www.`-stripped. */
+function hostMatches(citationHost, targetHost) {
+    if (!citationHost || !targetHost)
+        return false;
+    return citationHost === targetHost || citationHost.endsWith(`.${targetHost}`);
+}
+export class DeterministicMentionCitationExtractor {
+    extract({ target, answerText, citations, }) {
+        const targetHost = bareHost(target);
+        const brand = brandToken(targetHost);
+        const safeCitations = Array.isArray(citations) ? citations : [];
+        // -- sourceUrls / citationPresent: candidate URLs whose host matches the target's host --
+        const sourceUrls = targetHost
+            ? safeCitations.filter((c) => hostMatches(bareHost(c.url), targetHost)).map((c) => c.url)
+            : [];
+        const citationPresent = sourceUrls.length > 0;
+        // -- mentioned: brand/host in answerText or any citation title, word-boundary matched --
+        const hasAnswerText = typeof answerText === "string" && answerText.trim().length > 0;
+        const mentionedInAnswer = targetHost.length > 0 &&
+            hasAnswerText &&
+            (containsWordBoundary(answerText, brand) || containsWordBoundary(answerText, targetHost));
+        const mentionedInCitationTitle = targetHost.length > 0 &&
+            safeCitations.some((c) => containsWordBoundary(c.title, brand) || containsWordBoundary(c.title, targetHost));
+        return {
+            mentioned: mentionedInAnswer || mentionedInCitationTitle,
+            citationPresent,
+            sourceUrls,
+        };
+    }
+}
+// ── Sprint 8 — LLM-as-judge fuzzy-mention path (opt-in) ─────────────────
+/** Bounded judge verdict — the ONLY shape the judge is allowed to return. */
+export const JudgeVerdictSchema = z.object({
+    mentioned: z.boolean(),
+    rank: z.number().int().positive().optional(),
+});
+/**
+ * Never-throws 3-tier verdict parser — mirrors
+ * `validateGroundingVerdict` (`src/medical/retrieval/grounding-critic.ts:40-88`):
+ * try a direct parse, then a fenced ```json block, then the first
+ * `{...}` span; `safeParse` at the end never throws. On total failure
+ * returns `{ ok: false, error }` so the caller can fail SAFE to the
+ * deterministic result (sc-8-3) rather than propagate a throw.
+ */
+export function parseJudgeVerdict(rawText) {
+    let parsed;
+    try {
+        parsed = JSON.parse(rawText.trim());
+    }
+    catch {
+        const fenceMatch = /```(?:json)?\s*\n?([\s\S]*?)\n?\s*```/.exec(rawText);
+        if (fenceMatch) {
+            try {
+                parsed = JSON.parse(fenceMatch[1].trim());
+            }
+            catch {
+                // Fall through
+            }
+        }
+        if (!parsed) {
+            const braceStart = rawText.indexOf("{");
+            const braceEnd = rawText.lastIndexOf("}");
+            if (braceStart !== -1 && braceEnd > braceStart) {
+                try {
+                    parsed = JSON.parse(rawText.slice(braceStart, braceEnd + 1));
+                }
+                catch {
+                    return { ok: false, error: `No valid JSON object found in judge response. Raw: ${rawText.slice(0, 200)}` };
+                }
+            }
+            else {
+                return { ok: false, error: `No JSON object found in judge response. Raw: ${rawText.slice(0, 200)}` };
+            }
+        }
+    }
+    const result = JudgeVerdictSchema.safeParse(parsed);
+    if (!result.success) {
+        const issues = result.error.issues.map((i) => `  - ${i.path.join(".")}: ${i.message}`).join("\n");
+        return { ok: false, error: issues };
+    }
+    return { ok: true, verdict: result.data };
+}
+function buildJudgeSystemPrompt(target) {
+    return (`You are an independent fact-checker judging whether a search-engine answer ` +
+        `mentions a specific brand/website, INCLUDING fuzzy/paraphrased references ` +
+        `that clearly refer to it without using its exact name or domain.\n\n` +
+        `Target brand/site: ${target}\n\n` +
+        `Output ONLY a single JSON object (no prose, no markdown fences, no tool calls) with EXACTLY this shape:\n` +
+        `{"mentioned": boolean, "rank": number}\n\n` +
+        `Rules:\n` +
+        `- "mentioned" must be true ONLY if the answer text meaningfully refers to the target brand/site (fuzzy/paraphrased mentions count; a coincidental or unrelated similar word does not).\n` +
+        `- "rank" is OPTIONAL: include it ONLY as a positive integer giving the target's approximate position among ranked/listed items in the answer; omit the key entirely if the answer has no ranking or you are unsure.\n` +
+        `- If the answer text is empty, unrelated, or you are unsure whether it refers to the target, "mentioned" must be false.\n` +
+        `- Output the JSON object and nothing else.`);
+}
+function buildJudgeUserContent(sanitizedAnswerText, citations) {
+    const citationBlock = citations.length > 0 ? citations.map((c, i) => `[${i + 1}] ${c.title} — ${c.url}`).join("\n") : "(no citations)";
+    return `Answer text to judge:\n${sanitizedAnswerText}\n\nCitations:\n${citationBlock}`;
+}
+/**
+ * OPTIONAL, injected LLM-as-judge fuzzy-mention extractor (Sprint 8;
+ * sc-8-1..sc-8-4). COMPOSES `DeterministicMentionCitationExtractor` —
+ * always runs the deterministic pass first and returns it verbatim
+ * (no judge call, cost control) when it already found a mention. Only
+ * when the deterministic pass left `mentioned:false` on a non-empty
+ * answer does this class sanitize the text (sc-8-4) and ask a bounded,
+ * schema-parsed judge whether the answer fuzzily mentions the target.
+ *
+ * FAIL-SAFE (sc-8-3): a thrown `llm.chat` transport error or an
+ * unparseable/malformed verdict falls back to the deterministic result
+ * VERBATIM — this class never fabricates `mentioned:true`. The judge
+ * only ever overrides `mentioned`/`rank`; `citationPresent`/`sourceUrls`
+ * always come from the deterministic pass (the judge does not re-derive
+ * URLs — nonGoals: not used for citation URL verification).
+ *
+ * NOT wired into production callers this sprint (`ai-visibility-provider.ts`,
+ * `runner.ts` still construct the plain `DeterministicMentionCitationExtractor`
+ * with no `llm`) — this class is exercised via unit tests injecting a
+ * scripted `LLMClient`, keeping the deterministic-only path byte-identical
+ * (sc-8-2).
+ */
+export class LlmJudgeMentionCitationExtractor {
+    deterministic;
+    llm;
+    model;
+    sanitizer;
+    constructor(deterministic, llm, model, sanitizer) {
+        this.deterministic = deterministic;
+        this.llm = llm;
+        this.model = model;
+        this.sanitizer = sanitizer;
+    }
+    async extract(input) {
+        const { target, answerText, citations } = input;
+        const deterministicResult = this.deterministic.extract(input);
+        // Cost control (evaluatorNotes): the judge only runs on answers the
+        // deterministic pass did NOT already mark mentioned.
+        if (deterministicResult.mentioned)
+            return deterministicResult;
+        // Never spend an LLM call on an empty/whitespace answer, and never let
+        // a judge turn one into `mentioned:true` (sc-8-3).
+        const hasAnswerText = typeof answerText === "string" && answerText.trim().length > 0;
+        if (!hasAnswerText)
+            return deterministicResult;
+        // sc-8-4: sanitize BEFORE building the judge prompt. A sanitizer that
+        // drops the text entirely (fail-closed, e.g. threats detected) leaves
+        // nothing for the judge to reason about — fail safe without calling it.
+        const sanitizedAnswerText = this.sanitizer.clean(answerText, target).content;
+        if (sanitizedAnswerText.trim().length === 0)
+            return deterministicResult;
+        let rawText;
+        try {
+            const response = await this.llm.chat({
+                model: this.model,
+                system: buildJudgeSystemPrompt(target),
+                messages: [{ role: "user", content: buildJudgeUserContent(sanitizedAnswerText, citations) }],
+                jsonObjectMode: true,
+            });
+            rawText = response.text;
+        }
+        catch {
+            return deterministicResult; // fail-safe: transport error -> deterministic result (sc-8-3)
+        }
+        const parsed = parseJudgeVerdict(rawText);
+        if (!parsed.ok)
+            return deterministicResult; // fail-safe: unparseable verdict -> deterministic result (sc-8-3)
+        const result = {
+            mentioned: parsed.verdict.mentioned,
+            citationPresent: deterministicResult.citationPresent,
+            sourceUrls: deterministicResult.sourceUrls,
+        };
+        if (parsed.verdict.rank !== undefined)
+            result.rank = parsed.verdict.rank; // never `rank: undefined`
+        return result;
+    }
+}
+//# sourceMappingURL=mention-citation-extractor.js.map

package/dist/seo/sources/mention-citation-extractor.js.map

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

package/dist/seo/sources/scrape-arm-provider.d.ts

@@ -0,0 +1,109 @@
+/**
+ * ScrapeArmEngineProvider — the damcrawler UI-scrape `AiVisibilityProvider`
+ * arm (in-house-ai-visibility, Sprint 10; arch-20260717-in-house-oss-ai-
+ * visibility-architecture.md:101-114,307-310; ADR-4).
+ *
+ * A near-fusion of TWO existing templates, deliberately mirrored rather than
+ * reinvented:
+ *   - `DamcrawlerSerpProvider` (`./damcrawler-serp-provider.ts:69-106`) —
+ *     guard-first/lazy-load/never-throw shape, and its docstring's rationale
+ *     for omitting an `assertSafeUrl` SSRF guard (`:14-18`): the scrape
+ *     target is PROVIDER-constructed (the ChatGPT-UI endpoint for a given
+ *     prompt), not caller-supplied free-text, so there is no SSRF surface
+ *     here the way there is for `DamcrawlerCitationVerifier`'s
+ *     caller-supplied candidate urls.
+ *   - `ApiSpineEngineProvider` (`./api-spine-provider.ts:72-125`) — the
+ *     N-samples-per-prompt loop: sanitize -> extract -> verify -> emit one
+ *     raw `AiVisibilityRow` per real observation, never a pre-aggregate.
+ *
+ * This class is the FIRST live consumer of the `"ai-visibility-scrape"`
+ * egress axis (previously axis-only, `../egress.ts:6-7`). The axis is
+ * self-asserted as the FIRST statement inside `probe()` — the load-bearing
+ * barrier per ADR-4 — so axis-off means zero sockets AND zero damcrawler
+ * import AND zero `ScrapeThrottle.acquire` calls (sc-10-1,
+ * byte-identical-when-off).
+ *
+ * When the axis is ON, each sample runs:
+ *   `throttle.acquire` -> `dam.scrape` -> `ContentSanitizer.clean` (BEFORE
+ *   the parser — the Sprint-9 F1 prompt-injection lesson: an unsanitized
+ *   scraped answer reaching the extractor/verifier/builder would re-open
+ *   that regression, arch:346 "critical") -> `EngineScrapeParser.parse`
+ *   (PURE) -> `MentionCitationExtractor.extract` -> `CitationVerifier.verify`
+ *   -> `ScrapeThrottle.recordProxyCost` (only after a row is produced) ->
+ *   push a row labeled `this.name` (`"chatgpt-ui"` (Sprint 10) or
+ *   `"perplexity-ui"` (Sprint 11) — distinct from every API-arm provider
+ *   label, sc-10-4/sc-11-1 unmixable-by-label).
+ *
+ * `estCostUsdPerPrompt = 0` — the scrape arm books ZERO USD to the
+ * `SeoQuotaGovernor`; its real proxy cost lives entirely in the
+ * `ScrapeThrottle`'s independent ledger (Sprint 9). Unlike
+ * `ApiSpineEngineProvider.probe` (which THROWS when every attempted sample
+ * fails, so its non-zero USD is never over-booked, `api-spine-provider.ts
+ * :117-122`), this arm books $0 — a total failure has no over-book risk, so
+ * it returns `[]` (abstain) instead of throwing (sc-10-3, "a scrape error
+ * degrades to abstain (never throws)", read literally).
+ */
+import type { SeoEgressGuard } from "../egress.js";
+import type { AiVisibilityRow } from "../data-source.js";
+import type { AiVisibilityProvider } from "./ai-visibility-adapter.js";
+import type { MentionCitationExtractor } from "./mention-citation-extractor.js";
+import type { CitationVerifier } from "./citation-verifier.js";
+import type { ScrapeThrottle } from "../scrape-throttle.js";
+import type { EngineScrapeParser } from "./engine-scrape-parser-chatgpt.js";
+/** The scrape arm's engine labels (net-new; `AiVisibilityRow.provider` is a plain string). Both `"chatgpt-ui"` (Sprint 10) and `"perplexity-ui"` (Sprint 11) are live — see `scrapeUrlFor` below. */
+export type ScrapeEngine = "chatgpt-ui" | "perplexity-ui";
+/**
+ * NARROW view of the ONLY damcrawler surface this arm calls — mirrors
+ * `DamcrawlerSearchModule` (`./damcrawler-serp-provider.ts:43-49`) and
+ * `DamcrawlerVerifyModule` (`./citation-verifier.ts:62-69`). Defined LOCALLY
+ * (never imported from the real dep) so tests never need the package.
+ * `options` carries the operator-supplied auth session / proxy opaquely —
+ * this class does no auth harvesting or proxy sourcing (nonGoals).
+ */
+export interface DamcrawlerScrapeModule {
+    scrape(urls: string[], options: {
+        formats?: string[];
+        proxy?: string;
+        authSession?: unknown;
+    }): Promise<Array<{
+        url: string;
+        title: string;
+        markdown: string;
+        links?: Array<{
+            url: string;
+            text?: string;
+        }>;
+        error?: string;
+    }>>;
+    sanitize(raw: string, options?: {
+        sourceUrl?: string;
+    }): {
+        content: string;
+        hadThreats: boolean;
+    };
+}
+/** Loader seam — the default performs the lazy dynamic import; tests inject a FAKE module (or `undefined` to simulate the dep being absent). */
+export type DamcrawlerScrapeLoader = () => Promise<DamcrawlerScrapeModule | undefined>;
+/**
+ * `AiVisibilityProvider` backed by a gated damcrawler UI scrape.
+ * Guard-first, lazy-load, throttle-metered, sanitize-before-parse,
+ * never-throw; books zero USD to the governor (proxy cost is tracked
+ * independently by the injected `ScrapeThrottle`).
+ */
+export declare class ScrapeArmEngineProvider implements AiVisibilityProvider {
+    private readonly egress;
+    private readonly parser;
+    private readonly extractor;
+    private readonly verifier;
+    private readonly throttle;
+    private readonly samplesPerPrompt;
+    private readonly authSession;
+    private readonly proxyUsdPerScrape;
+    private readonly proxy;
+    private readonly load;
+    readonly name: ScrapeEngine;
+    readonly estCostUsdPerPrompt = 0;
+    constructor(egress: SeoEgressGuard, engine: ScrapeEngine, parser: EngineScrapeParser, extractor: MentionCitationExtractor, verifier: CitationVerifier, throttle: ScrapeThrottle, samplesPerPrompt: number, authSession: unknown, proxyUsdPerScrape: number, proxy?: string | undefined, load?: DamcrawlerScrapeLoader);
+    probe(target: string, prompts: string[], _locale?: string): Promise<AiVisibilityRow[]>;
+}
+//# sourceMappingURL=scrape-arm-provider.d.ts.map

package/dist/seo/sources/scrape-arm-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scrape-arm-provider.d.ts","sourceRoot":"","sources":["../../../src/seo/sources/scrape-arm-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AACvE,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,iCAAiC,CAAC;AAChF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,KAAK,EAAE,kBAAkB,EAAa,MAAM,mCAAmC,CAAC;AAGvF,qMAAqM;AACrM,MAAM,MAAM,YAAY,GAAG,YAAY,GAAG,eAAe,CAAC;AAE1D;;;;;;;GAOG;AACH,MAAM,WAAW,sBAAsB;IACrC,MAAM,CACJ,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,OAAO,CAAA;KAAE,GACrE,OAAO,CAAC,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,KAAK,CAAC;YAAE,GAAG,EAAE,MAAM,CAAC;YAAC,IAAI,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAAC;IACnI,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,OAAO,CAAA;KAAE,CAAC;CACnG;AAED,gJAAgJ;AAChJ,MAAM,MAAM,sBAAsB,GAAG,MAAM,OAAO,CAAC,sBAAsB,GAAG,SAAS,CAAC,CAAC;AAmCvF;;;;;GAKG;AACH,qBAAa,uBAAwB,YAAW,oBAAoB;IAKhE,OAAO,CAAC,QAAQ,CAAC,MAAM;IAEvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IAKjC,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,iBAAiB;IAClC,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAlBvB,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,mBAAmB,KAAK;gBAGd,MAAM,EAAE,cAAc,EACvC,MAAM,EAAE,YAAY,EACH,MAAM,EAAE,kBAAkB,EAC1B,SAAS,EAAE,wBAAwB,EACnC,QAAQ,EAAE,gBAAgB,EAC1B,QAAQ,EAAE,cAAc,EACxB,gBAAgB,EAAE,MAAM,EAKxB,WAAW,EAAE,OAAO,EACpB,iBAAiB,EAAE,MAAM,EACzB,KAAK,GAAE,MAAM,GAAG,SAAqB,EACrC,IAAI,GAAE,sBAAsC;IAKzD,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;CA8D7F"}