agent-bober 0.18.0 → 0.19.0

package/dist/seo/sources/scrape-arm-provider.js

@@ -0,0 +1,129 @@
+import { ContentSanitizer } from "../content-sanitizer.js";
+const defaultLoader = async () => {
+    // Indirection through a variable: under `moduleResolution: NodeNext` a
+    // LITERAL `import("damcrawler")` is statically resolved by tsc and fails
+    // with TS2307 when the dep is absent. Routing the specifier through a
+    // `string` variable makes tsc treat the result as `any`, so `tsc --noEmit`
+    // stays clean whether or not damcrawler is installed (mirrors
+    // `damcrawler-serp-provider.ts:54-63`, `citation-verifier.ts:74-83`).
+    const mod = "damcrawler";
+    return (await import(mod).catch(() => undefined));
+};
+/**
+ * Builds the target URL for one prompt, per configured `ScrapeEngine`
+ * (Sprint 11 — generalized from the Sprint-10 ChatGPT-only builder). Each
+ * engine's scrape target is provider-constructed from the prompt text alone
+ * (no per-target routing) — mirrors the `DamcrawlerSerpProvider` "no SSRF
+ * guard needed" rationale (this class never fetches a caller-supplied URL).
+ * The `switch` is exhaustive over `ScrapeEngine` (a compile error surfaces
+ * any future engine value left unhandled).
+ */
+function scrapeUrlFor(engine, prompt) {
+    switch (engine) {
+        case "chatgpt-ui":
+            return `https://chatgpt.com/?q=${encodeURIComponent(prompt)}`;
+        case "perplexity-ui":
+            return `https://www.perplexity.ai/search?q=${encodeURIComponent(prompt)}`;
+        default: {
+            const _exhaustive = engine;
+            return _exhaustive;
+        }
+    }
+}
+/**
+ * `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 class ScrapeArmEngineProvider {
+    egress;
+    parser;
+    extractor;
+    verifier;
+    throttle;
+    samplesPerPrompt;
+    authSession;
+    proxyUsdPerScrape;
+    proxy;
+    load;
+    name;
+    estCostUsdPerPrompt = 0;
+    constructor(egress, engine, parser, extractor, verifier, throttle, samplesPerPrompt, 
+    // Operator-supplied auth session (storageState path / profile name /
+    // cookie blob) from `config.seo.aiVisibility.scrape.authSession` — opaque
+    // to this class, passed straight through to `dam.scrape` options. NOT
+    // hardcoded (nonGoal: no auth harvesting).
+    authSession, proxyUsdPerScrape, proxy = undefined, load = defaultLoader) {
+        this.egress = egress;
+        this.parser = parser;
+        this.extractor = extractor;
+        this.verifier = verifier;
+        this.throttle = throttle;
+        this.samplesPerPrompt = samplesPerPrompt;
+        this.authSession = authSession;
+        this.proxyUsdPerScrape = proxyUsdPerScrape;
+        this.proxy = proxy;
+        this.load = load;
+        this.name = engine;
+    }
+    async probe(target, prompts, _locale) {
+        // -- STATEMENT 1: self-assert the axis FIRST, before any import (ADR-4, load-bearing barrier, sc-10-1) --
+        try {
+            this.egress.assertAllowed("ai-visibility-scrape");
+        }
+        catch {
+            return []; // axis off => abstain, zero sockets, NO loader call, NO throttle call
+        }
+        const dam = await this.load();
+        if (!dam)
+            return []; // damcrawler-not-installed (optional peer dep) => abstain, never throw
+        const sanitizer = new ContentSanitizer(dam.sanitize); // ADR-11: sanitize at the network->in-process boundary
+        const rows = [];
+        for (const prompt of prompts) {
+            for (let i = 0; i < this.samplesPerPrompt; i++) {
+                const decision = await this.throttle.acquire(this.name); // BEFORE scrape
+                if (!decision.proceed)
+                    continue; // throttle denial => skip this sample (sc-10-3), no ledger side effect
+                try {
+                    const [result] = await dam.scrape([scrapeUrlFor(this.name, prompt)], {
+                        formats: ["markdown"],
+                        proxy: this.proxy,
+                        authSession: this.authSession,
+                    });
+                    if (!result || result.error)
+                        continue; // scrape error/missing row => drop sample, never throw (sc-10-3)
+                    // sc-10-2: sanitize the raw scraped markdown BEFORE the parser runs
+                    // (Sprint-9 F1 lesson — reversing this order re-opens the
+                    // prompt-injection regression).
+                    const cleanMarkdown = sanitizer.clean(result.markdown, result.url).content;
+                    const raw = { url: result.url, markdown: cleanMarkdown };
+                    const parsed = this.parser.parse(raw); // PURE: RawScrape -> {answerText, citations}
+                    const obs = await this.extractor.extract({
+                        target,
+                        answerText: parsed.answerText,
+                        citations: parsed.citations,
+                    });
+                    const verified = await this.verifier.verify(target, obs.sourceUrls);
+                    const sourceUrls = verified.filter((v) => v.live).map((v) => v.url);
+                    const row = {
+                        prompt,
+                        provider: this.name,
+                        mentioned: obs.mentioned,
+                        citationPresent: obs.citationPresent,
+                        sourceUrls,
+                    };
+                    if (obs.rank !== undefined)
+                        row.rank = obs.rank; // never `rank: undefined`
+                    rows.push(row);
+                    await this.throttle.recordProxyCost(this.name, this.proxyUsdPerScrape); // AFTER a successful, row-producing scrape
+                }
+                catch {
+                    continue; // any error mid-sample => drop that sample, NEVER throw (sc-10-3)
+                }
+            }
+        }
+        return rows; // sc-10-3: never throws; [] is a valid abstain (zero booked, zero over-book risk at $0/prompt)
+    }
+}
+//# sourceMappingURL=scrape-arm-provider.js.map

package/dist/seo/sources/scrape-arm-provider.js.map

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

package/dist/seo/tracked-prompt-store.d.ts

@@ -0,0 +1,33 @@
+import { z } from "zod";
+export declare const TrackedPromptSetSchema: z.ZodObject<{
+    target: z.ZodString;
+    prompts: z.ZodArray<z.ZodString, "many">;
+    engines: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    samplesPerPrompt: z.ZodDefault<z.ZodNumber>;
+    locale: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    prompts: string[];
+    samplesPerPrompt: number;
+    engines: string[];
+    target: string;
+    locale?: string | undefined;
+}, {
+    prompts: string[];
+    target: string;
+    samplesPerPrompt?: number | undefined;
+    engines?: string[] | undefined;
+    locale?: string | undefined;
+}>;
+export type TrackedPromptSet = z.infer<typeof TrackedPromptSetSchema>;
+export declare class TrackedPromptStore {
+    private readonly projectRoot;
+    constructor(projectRoot: string);
+    /**
+     * Load the committed tracked-prompt set for `target`. Missing, unreadable,
+     * or malformed (fails Zod validation) all fall back to
+     * `{ target, prompts: [target], engines: [], samplesPerPrompt: 5 }`.
+     * Never throws.
+     */
+    load(target: string): Promise<TrackedPromptSet>;
+}
+//# sourceMappingURL=tracked-prompt-store.d.ts.map

package/dist/seo/tracked-prompt-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracked-prompt-store.d.ts","sourceRoot":"","sources":["../../src/seo/tracked-prompt-store.ts"],"names":[],"mappings":"AAqBA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;EASjC,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAmBtE,qBAAa,kBAAkB;IACjB,OAAO,CAAC,QAAQ,CAAC,WAAW;gBAAX,WAAW,EAAE,MAAM;IAEhD;;;;;OAKG;IACG,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;CAWtD"}

package/dist/seo/tracked-prompt-store.js

@@ -0,0 +1,68 @@
+/**
+ * TrackedPromptStore — reads the committed tracked-prompt set for a target
+ * from `.bober/seo/ai-visibility/<target>.json`
+ * (spec-20260718-in-house-ai-visibility, Sprint 6).
+ *
+ * `load()` NEVER throws: a missing file, an unreadable file, or a file that
+ * fails `TrackedPromptSetSchema.safeParse` all collapse to the SAME fallback
+ * — `{ target, prompts: [target], engines: [], samplesPerPrompt: 5 }` — which
+ * is byte-identical (for the `target`/`prompts` fields `gatherDataBundle`
+ * actually forwards into `AiVisibilityQuery`) to the pre-Sprint-6 literal at
+ * `runner.ts:421` (sc-6-2). Mirrors the read-JSON -> Zod `safeParse` ->
+ * fallback idiom of `readJob` (`src/research/job-store.ts:100-113`).
+ *
+ * `engines`/`samplesPerPrompt` are parsed for completeness (sc-6-1) but are
+ * ADVISORY ONLY — the real per-target N/engines are resolved by config at
+ * provider construction (`schema.ts:729-747`), and the caller in
+ * `runner.ts`'s `gatherDataBundle` deliberately does NOT flow them into the
+ * LOCKED `AiVisibilityQuery` shape (`data-source.ts:61`; contract nonGoal).
+ */
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { z } from "zod";
+// ── Schema ───────────────────────────────────────────────────────────
+export const TrackedPromptSetSchema = z.object({
+    target: z.string(),
+    prompts: z.array(z.string()),
+    // Advisory — never flowed into AiVisibilityQuery (contract nonGoal). A
+    // plain string array (not the config's engine enum) so a stray/unknown
+    // engine name never fails the whole file's safeParse.
+    engines: z.array(z.string()).default([]),
+    samplesPerPrompt: z.number().int().positive().default(5),
+    locale: z.string().optional(),
+});
+// ── Paths ────────────────────────────────────────────────────────────
+const TRACKED_PROMPTS_DIR = ".bober/seo/ai-visibility";
+/** fs-safe filename — mirrors `report-store.ts:34-36`'s traversal-safe sanitization. */
+function trackedPromptPath(projectRoot, target) {
+    const safeTarget = target.replace(/[^a-zA-Z0-9_-]/g, "_");
+    return join(projectRoot, TRACKED_PROMPTS_DIR, `${safeTarget}.json`);
+}
+/** The byte-identical-to-pre-Sprint-6 fallback (sc-6-2). */
+function fallback(target) {
+    return { target, prompts: [target], engines: [], samplesPerPrompt: 5 };
+}
+// ── Store ────────────────────────────────────────────────────────────
+export class TrackedPromptStore {
+    projectRoot;
+    constructor(projectRoot) {
+        this.projectRoot = projectRoot;
+    }
+    /**
+     * Load the committed tracked-prompt set for `target`. Missing, unreadable,
+     * or malformed (fails Zod validation) all fall back to
+     * `{ target, prompts: [target], engines: [], samplesPerPrompt: 5 }`.
+     * Never throws.
+     */
+    async load(target) {
+        try {
+            const raw = JSON.parse(await readFile(trackedPromptPath(this.projectRoot, target), "utf-8"));
+            const result = TrackedPromptSetSchema.safeParse(raw);
+            return result.success ? result.data : fallback(target);
+        }
+        catch {
+            return fallback(target);
+        }
+    }
+}
+//# sourceMappingURL=tracked-prompt-store.js.map

package/dist/seo/tracked-prompt-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracked-prompt-store.js","sourceRoot":"","sources":["../../src/seo/tracked-prompt-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,wEAAwE;AAExE,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC7C,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;IAClB,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IAC5B,uEAAuE;IACvE,uEAAuE;IACvE,sDAAsD;IACtD,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;IACxC,gBAAgB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;IACxD,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAC9B,CAAC,CAAC;AAIH,wEAAwE;AAExE,MAAM,mBAAmB,GAAG,0BAA0B,CAAC;AAEvD,wFAAwF;AACxF,SAAS,iBAAiB,CAAC,WAAmB,EAAE,MAAc;IAC5D,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO,CAAC,iBAAiB,EAAE,GAAG,CAAC,CAAC;IAC1D,OAAO,IAAI,CAAC,WAAW,EAAE,mBAAmB,EAAE,GAAG,UAAU,OAAO,CAAC,CAAC;AACtE,CAAC;AAED,4DAA4D;AAC5D,SAAS,QAAQ,CAAC,MAAc;IAC9B,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,gBAAgB,EAAE,CAAC,EAAE,CAAC;AACzE,CAAC;AAED,wEAAwE;AAExE,MAAM,OAAO,kBAAkB;IACA;IAA7B,YAA6B,WAAmB;QAAnB,gBAAW,GAAX,WAAW,CAAQ;IAAG,CAAC;IAEpD;;;;;OAKG;IACH,KAAK,CAAC,IAAI,CAAC,MAAc;QACvB,IAAI,CAAC;YACH,MAAM,GAAG,GAAY,IAAI,CAAC,KAAK,CAC7B,MAAM,QAAQ,CAAC,iBAAiB,CAAC,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,CACrE,CAAC;YACF,MAAM,MAAM,GAAG,sBAAsB,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;YACrD,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QACzD,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,QAAQ,CAAC,MAAM,CAAC,CAAC;QAC1B,CAAC;IACH,CAAC;CACF"}

package/dist/seo/types.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Core SEO type foundation (spec-20260715-ultimate-seo-suite, Sprint 1).
+ *
+ * Pure `type` declarations only — no runtime code, no imports. These shapes
+ * are quoted verbatim from the architecture Component Breakdown / Data Model
+ * (.bober/architecture/arch-20260715-ultimate-seo-agents-skills-architecture.md).
+ *
+ * Deliberately NOT included this sprint (later-sprint nonGoals): the
+ * `SeoDataSource` seam, capability/query types, adapters, and any import of
+ * `src/hub/finding.js` — `SeoFinding.severity` stays a plain 1..5 numeric
+ * union until the hub emitter sprint maps it onto `Finding`.
+ */
+/** The 8 SEO workflows the CLI dispatches on (architecture lines 65-73). */
+export type SeoWorkflow = "technical-audit" | "rank-track" | "content-decay" | "topical-map" | "ai-visibility" | "parasite-watch" | "internal-linking" | "schema-audit";
+/**
+ * Provenance stamped on every `DataOutcome` `"data"` arm (architecture
+ * lines 165-169). `costUsd` is set only by costed live sources (DataForSEO).
+ * `path`/`mtimeMs` are set only by file-backed sources (LocalExportSource,
+ * Sprint 6) for freshness auditing — optional so `gsc`/`dataforseo`
+ * provenance stays byte-compatible (same optional idiom as `costUsd`).
+ *
+ * Widened (spec-20260717-seo-improver-builder, Sprint 1) with `"ai-visibility"`
+ * and `"damcrawler"` — additive only; no consumer exhaustively switches on
+ * `source` (`analyzer.ts` switches on `DataOutcome.kind`, not `source`).
+ */
+export type DataProvenance = {
+    source: "local-export" | "gsc" | "dataforseo" | "ai-visibility" | "damcrawler";
+    retrievedAt: string;
+    costUsd?: number;
+    path?: string;
+    mtimeMs?: number;
+};
+/**
+ * Three-arm outcome for every `SeoDataSource` capability call (architecture
+ * lines 160-163; mirrors `RetrievalOutcome`, medline-source.ts:25-28).
+ */
+export type DataOutcome<T> = {
+    kind: "disabled";
+} | {
+    kind: "abstain";
+    reason: string;
+} | {
+    kind: "data";
+    rows: T;
+    provenance: DataProvenance;
+};
+/**
+ * Parsed from each `skills/bober.seo-*` directory's `SKILL.md`, strong/
+ * read-only, memoised per process (architecture lines 349-360).
+ *
+ * `liveWeightStatus` (spec-20260717-seo-improver-builder, Sprint 3) is a
+ * soft field encoding the documented-vs-live-weight caveat: whether the
+ * signature's invariant is corroborated by a LIVE ranking signal
+ * (`live-corroborated`), is documented-only guidance not (yet) confirmed
+ * live (`documented-only`), or unknown/unstated (`unknown`, the default).
+ * It lives ONLY on the signature — `SeoFinding` is unchanged (ADR-2).
+ */
+export type SeoSignature = {
+    playbookId: string;
+    workflows: SeoWorkflow[];
+    title: string;
+    tactic: string;
+    invariant: string;
+    primarySourceUrl: string;
+    policyClass: "auto-safe" | "human-approve";
+    evidenceGrade: "verified" | "primary-unverified" | "single-source";
+    liveWeightStatus: "live-corroborated" | "documented-only" | "unknown";
+    keywords: string[];
+    skillRef: string;
+};
+/**
+ * One SEO recommendation (architecture lines 258-267). `severity` maps to
+ * hub `Finding` urgency/severity 1..5 (finding.ts:15-16) in a LATER sprint —
+ * `Finding` is not imported here.
+ */
+export type SeoFinding = {
+    recommendation: string;
+    workflow: SeoWorkflow;
+    playbookRef: string;
+    citationUrl: string;
+    evidence: Array<{
+        metric: string;
+        value: string;
+        source: string;
+        url: string;
+    }>;
+    severity: 1 | 2 | 3 | 4 | 5;
+    humanApprovalRequired: boolean;
+    confidence: "firm" | "tentative";
+};
+/**
+ * Persisted at `.bober/seo/reports/<safeId>-seo-report.json` (architecture
+ * lines 363-372).
+ *
+ * `droppedNeverEncode` (spec-20260717-seo-improver-builder, Sprint 1 field /
+ * Sprint 2 wiring) mirrors `droppedUncited` exactly — a required plain
+ * `number` counter. Populated by `NeverEncodeFilter` (`never-encode-filter.ts`,
+ * Sprint 2), which runs in `SeoWorkflowRunner.run` between the
+ * `analysis.parsed` check and `SeoCitationGate.apply`.
+ */
+export type SeoReport = {
+    reportId: string;
+    workflow: SeoWorkflow;
+    target: string;
+    generatedAt: string;
+    findings: SeoFinding[];
+    droppedUncited: number;
+    droppedNeverEncode: number;
+    dataProvenance: DataProvenance[];
+    verdict: "pass" | "blocked";
+};
+/**
+ * Persisted at `.bober/seo/quota-ledger.json` (architecture calls this
+ * shape `QuotaLedger`, lines 375-385; named `SeoQuotaLedger` per
+ * generatorNotes to match the `Seo*` naming convention of this module).
+ */
+export type SeoQuotaLedger = {
+    [dateKey: string]: {
+        spentUsd: number;
+        scopes: {
+            [scopeKey: string]: {
+                rowsToday: number;
+                urlInspectionsToday: number;
+            };
+        };
+    };
+};
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/seo/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,4EAA4E;AAC5E,MAAM,MAAM,WAAW,GACnB,iBAAiB,GACjB,YAAY,GACZ,eAAe,GACf,aAAa,GACb,eAAe,GACf,gBAAgB,GAChB,kBAAkB,GAClB,cAAc,CAAC;AAInB;;;;;;;;;;GAUG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,MAAM,EAAE,cAAc,GAAG,KAAK,GAAG,YAAY,GAAG,eAAe,GAAG,YAAY,CAAC;IAC/E,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,IACrB;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,GACpB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,CAAC,CAAC;IAAC,UAAU,EAAE,cAAc,CAAA;CAAE,CAAC;AAI1D;;;;;;;;;;GAUG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,WAAW,EAAE,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,MAAM,CAAC;IACzB,WAAW,EAAE,WAAW,GAAG,eAAe,CAAC;IAC3C,aAAa,EAAE,UAAU,GAAG,oBAAoB,GAAG,eAAe,CAAC;IACnE,gBAAgB,EAAE,mBAAmB,GAAG,iBAAiB,GAAG,SAAS,CAAC;IACtE,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAIF;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,WAAW,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAChF,QAAQ,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC5B,qBAAqB,EAAE,OAAO,CAAC;IAC/B,UAAU,EAAE,MAAM,GAAG,WAAW,CAAC;CAClC,CAAC;AAIF;;;;;;;;;GASG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,WAAW,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,UAAU,EAAE,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,cAAc,EAAE,cAAc,EAAE,CAAC;IACjC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7B,CAAC;AAIF;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,CAAC,OAAO,EAAE,MAAM,GAAG;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE;YACN,CAAC,QAAQ,EAAE,MAAM,GAAG;gBAAE,SAAS,EAAE,MAAM,CAAC;gBAAC,mBAAmB,EAAE,MAAM,CAAA;aAAE,CAAC;SACxE,CAAC;KACH,CAAC;CACH,CAAC"}

package/dist/seo/types.js

@@ -0,0 +1,14 @@
+/**
+ * Core SEO type foundation (spec-20260715-ultimate-seo-suite, Sprint 1).
+ *
+ * Pure `type` declarations only — no runtime code, no imports. These shapes
+ * are quoted verbatim from the architecture Component Breakdown / Data Model
+ * (.bober/architecture/arch-20260715-ultimate-seo-agents-skills-architecture.md).
+ *
+ * Deliberately NOT included this sprint (later-sprint nonGoals): the
+ * `SeoDataSource` seam, capability/query types, adapters, and any import of
+ * `src/hub/finding.js` — `SeoFinding.severity` stays a plain 1..5 numeric
+ * union until the hub emitter sprint maps it onto `Finding`.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/seo/types.js.map

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

package/dist/seo/verifier.d.ts

@@ -0,0 +1,34 @@
+import type { LLMClient } from "../providers/types.js";
+import type { BoberConfig } from "../config/schema.js";
+import type { SeoFinding } from "./types.js";
+export interface SeoVerifyParams {
+    /** The citation gate's `cited` findings — the ONLY findings the verifier ever sees. */
+    findings: SeoFinding[];
+    config: BoberConfig;
+    projectRoot: string;
+    /** Injected wall-clock snapshot (ISO-8601) — the verifier never reads the clock itself. */
+    now: string;
+    /** TEST injection — default = a real client via `createClient(...)`. Tests pass a ScriptedClient. */
+    llm?: LLMClient;
+}
+export interface SeoVerifyResult {
+    /** False on disabled/parse-failure/provider-error (fail-closed) — `findings` is then the UNCHANGED input. */
+    ran: boolean;
+    findings: SeoFinding[];
+}
+/** Injectable seam so `runner.test.ts` can stub the stage (mirrors `SeoRunInput.analyzer`). */
+export interface SeoVerifier {
+    verify(params: SeoVerifyParams): Promise<SeoVerifyResult>;
+}
+export declare class SeoRecommendationVerifier implements SeoVerifier {
+    /**
+     * Never throws. Resolves `{ ran:false, findings }` (input UNCHANGED) when
+     * disabled, when the agent md can't be loaded, on any provider/transport
+     * error, or when the response can't be parsed into a valid verdicts
+     * container. Resolves `{ ran:true, findings:<folded> }` on a successful,
+     * parseable response — always a subset of the input with severities only
+     * moving down.
+     */
+    verify(params: SeoVerifyParams): Promise<SeoVerifyResult>;
+}
+//# sourceMappingURL=verifier.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"verifier.d.ts","sourceRoot":"","sources":["../../src/seo/verifier.ts"],"names":[],"mappings":"AAsCA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAIvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAI7C,MAAM,WAAW,eAAe;IAC9B,uFAAuF;IACvF,QAAQ,EAAE,UAAU,EAAE,CAAC;IACvB,MAAM,EAAE,WAAW,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,2FAA2F;IAC3F,GAAG,EAAE,MAAM,CAAC;IACZ,qGAAqG;IACrG,GAAG,CAAC,EAAE,SAAS,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,6GAA6G;IAC7G,GAAG,EAAE,OAAO,CAAC;IACb,QAAQ,EAAE,UAAU,EAAE,CAAC;CACxB;AAED,+FAA+F;AAC/F,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;CAC3D;AA8ID,qBAAa,yBAA0B,YAAW,WAAW;IAC3D;;;;;;;OAOG;IACG,MAAM,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC;CA2ChE"}

package/dist/seo/verifier.js

@@ -0,0 +1,204 @@
+/**
+ * SeoRecommendationVerifier — opt-in, downgrade-only, fail-closed adversarial
+ * verifier (spec-20260715-ultimate-seo-suite, Sprint 12).
+ *
+ * Mirrors two precedents:
+ * - The security verifier's fold semantics and fail-closed result shape
+ *   (`src/orchestrator/security-verifier-agent.ts`, and the fold at
+ *   `src/orchestrator/security-auditor-agent.ts:338-354`): `ran===false`
+ *   (disabled/parse-failure/provider-error/refusal) returns the input
+ *   findings UNCHANGED; on success, `disproved` drops a finding,
+ *   `downgraded` lowers its severity by one (floored at 1), and
+ *   `confirmed`/unaddressed keeps it unchanged. The new set is always a
+ *   strict SUBSET with severities only ever moving DOWN — never
+ *   promoted, added, or raised.
+ * - The SEO analyzer's single-shot injected-`LLMClient` + 3-tier defensive
+ *   parse (`src/seo/analyzer.ts:187-226,280-301`). Unlike the security
+ *   verifier, this is a single `llm.chat` call — NOT an agentic loop (no
+ *   `runAgenticLoop`/`resolveRoleTools`, nothing to Read/Grep/Glob: SEO
+ *   findings cite external URLs, and there is no local evidence to
+ *   re-check).
+ *
+ * NEVER throws: any disabled-flag short-circuit, agent-md-load failure,
+ * provider/transport error, or parse failure resolves
+ * `{ ran:false, findings }` — the caller (`SeoWorkflowRunner`) keeps the
+ * citation gate's findings UNCHANGED (fail-closed, sc-12-3). This is the
+ * key divergence from `SeoAnalyzer.analyze`, which propagates transport
+ * errors — the verifier is an opt-in stage whose failure must never flip
+ * the run's exit code (sc-12-4).
+ *
+ * Gated on `config.seo?.verifier?.enabled` (schema.ts:688, default false,
+ * pre-existing from Sprint 1) at TWO layers, defense-in-depth: the runner
+ * (`src/seo/runner.ts`) never constructs or calls a verifier at all when
+ * disabled (so a disabled run makes zero provider calls, sc-12-2), and
+ * `verify()` itself also short-circuits on the flag so a caller that
+ * constructs a `SeoRecommendationVerifier` directly can't accidentally
+ * trigger a provider call either.
+ */
+import { z } from "zod";
+import { createClient } from "../providers/factory.js";
+import { loadAgentDefinition } from "../orchestrator/agent-loader.js";
+import { logger } from "../utils/logger.js";
+// -- Model-facing verdict schema (defensive, never trusts the LLM blindly) --
+const SeoVerdictSchema = z.object({
+    index: z.number().int().min(0),
+    verdict: z.enum(["confirmed", "downgraded", "disproved"]),
+    confidence: z.enum(["high", "medium", "low"]),
+    reason: z.string(),
+});
+const SeoVerdictsContainerSchema = z.object({
+    verdicts: z.array(SeoVerdictSchema),
+});
+// -- Defaults -------------------------------------------------------------
+/** No `config.seo.verifier.model` field exists (schema.ts:688 has ONLY `enabled`) — this is the sole default. */
+const DEFAULT_SEO_VERIFIER_MODEL = "sonnet";
+function buildDefaultClient() {
+    // createClient is the ONLY place SDKs are imported (mirrors runner.ts's buildDefaultAnalyzer).
+    return createClient(undefined, null, undefined, DEFAULT_SEO_VERIFIER_MODEL, "SeoVerifier");
+}
+// -- Prompt assembly --------------------------------------------------------
+/**
+ * Builds the verifier's user message from ONLY the findings + the injected
+ * `now`. Deliberately excludes any sprint/contract framing — the agent md
+ * (loaded as the `system` prompt) is the fresh, contract-free adversary; this
+ * message carries just the evidence to judge.
+ */
+function buildVerifierUserMessage(findings, now) {
+    const findingsJson = JSON.stringify(findings.map((finding, index) => ({ index, ...finding })), null, 2);
+    return [
+        `Current reference date/time (for freshness judgments only): ${now}.`,
+        ``,
+        `# Findings To Verify`,
+        ``,
+        findingsJson,
+        ``,
+        `# Your Task`,
+        ``,
+        `For each finding above, attempt to DISPROVE it: is the citationUrl a genuine primary source that ` +
+            `actually backs the recommendation? Does the evidence actually support the claimed severity? Is ` +
+            `anything invented, overstated, or unsupported?`,
+        ``,
+        `Render one verdict per finding: "confirmed" (it holds — stays at its original severity), "downgraded" ` +
+            `(real but overstated — severity moves down by one), or "disproved" (the evidence does not support ` +
+            `it — dropped entirely).`,
+        ``,
+        `Output ONLY a single JSON object (no prose, no markdown fences), one entry per finding, in this exact shape:`,
+        `{"verdicts":[{"index":0,"verdict":"confirmed","confidence":"high","reason":"<one-line reason>"}]}`,
+    ].join("\n");
+}
+/** Mirrors `analyzer.ts:parseFindingsContainer` verbatim, swapping the container schema. */
+function parseVerdictsContainer(rawText) {
+    let parsed;
+    try {
+        parsed = JSON.parse(rawText.trim());
+    }
+    catch {
+        // Tier 2: extract from a fenced ```json ... ``` block.
+        const fenceMatch = /```(?:json)?\s*\n?([\s\S]*?)\n?\s*```/.exec(rawText);
+        if (fenceMatch) {
+            try {
+                parsed = JSON.parse(fenceMatch[1].trim());
+            }
+            catch {
+                // fall through to tier 3
+            }
+        }
+        // Tier 3: take the first { ... last } span.
+        if (parsed === undefined) {
+            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 response. Raw: ${rawText.slice(0, 200)}` };
+                }
+            }
+            else {
+                return { ok: false, error: `No JSON object found in response. Raw: ${rawText.slice(0, 200)}` };
+            }
+        }
+    }
+    const result = SeoVerdictsContainerSchema.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, verdicts: result.data.verdicts };
+}
+// -- Downgrade-only fold (structural — no code path raises/adds) ----------
+/**
+ * Folds verdicts onto `findings` by 0-based `index`. `disproved` drops the
+ * finding; `downgraded` lowers `severity` by exactly one, floored at 1
+ * (input `severity` is always `1..5`, so `severity-1` is always `0..4`,
+ * floored to `1..4` — the cast is safe); `confirmed` OR an unaddressed
+ * finding (no matching verdict entry, or an out-of-range `index` the model
+ * invented) is kept byte-unchanged. There is no branch here that raises a
+ * severity or pushes a finding not already present in `findings` — the
+ * downgrade-only guarantee is structural, not trusted from the model.
+ */
+function applyVerdicts(findings, verdicts) {
+    const byIndex = new Map(verdicts.map((v) => [v.index, v]));
+    const out = [];
+    findings.forEach((finding, i) => {
+        const v = byIndex.get(i);
+        if (v?.verdict === "disproved")
+            return;
+        if (v?.verdict === "downgraded") {
+            const lowered = Math.max(1, finding.severity - 1);
+            out.push({ ...finding, severity: lowered });
+            return;
+        }
+        out.push(finding); // "confirmed" OR unaddressed — fail-closed default: keep unchanged.
+    });
+    return out;
+}
+// -- SeoRecommendationVerifier ---------------------------------------------
+export class SeoRecommendationVerifier {
+    /**
+     * Never throws. Resolves `{ ran:false, findings }` (input UNCHANGED) when
+     * disabled, when the agent md can't be loaded, on any provider/transport
+     * error, or when the response can't be parsed into a valid verdicts
+     * container. Resolves `{ ran:true, findings:<folded> }` on a successful,
+     * parseable response — always a subset of the input with severities only
+     * moving down.
+     */
+    async verify(params) {
+        const { findings, config, projectRoot, now } = params;
+        // Nothing to verify — clean no-op, no LLM call needed either way
+        // (mirrors runSecurityVerifier's empty-findings short-circuit).
+        if (findings.length === 0) {
+            return { ran: true, findings };
+        }
+        // Defense-in-depth (sc-12-2): even a caller that constructs
+        // SeoRecommendationVerifier directly and bypasses the runner's own gate
+        // (Pattern E) can never trigger a provider call when the flag is off.
+        if (config.seo?.verifier?.enabled !== true) {
+            return { ran: false, findings };
+        }
+        try {
+            const definition = await loadAgentDefinition("bober-seo-verifier", projectRoot);
+            const llm = params.llm ?? buildDefaultClient();
+            const response = await llm.chat({
+                model: DEFAULT_SEO_VERIFIER_MODEL,
+                system: definition.systemPrompt,
+                messages: [{ role: "user", content: buildVerifierUserMessage(findings, now) }],
+                jsonObjectMode: true,
+            });
+            const parsedResult = parseVerdictsContainer(response.text);
+            if (!parsedResult.ok) {
+                logger.debug(`[seo-verifier] parse failed: ${parsedResult.error} — fail-closed`);
+                return { ran: false, findings };
+            }
+            return { ran: true, findings: applyVerdicts(findings, parsedResult.verdicts) };
+        }
+        catch (err) {
+            // Agent-md-load failure, provider/network error, or any other throw —
+            // fail-closed, never propagate a crash out of an opt-in stage.
+            logger.debug(`[seo-verifier] failed: ${err instanceof Error ? err.message : String(err)} — fail-closed`);
+            return { ran: false, findings };
+        }
+    }
+}
+//# sourceMappingURL=verifier.js.map