agent-bober 0.17.1 → 0.19.0

package/dist/seo/scrape-throttle.js

@@ -0,0 +1,149 @@
+/**
+ * ScrapeThrottle — per-engine scrape rate window + proxy-USD ledger,
+ * SEPARATE from the governor USD ledger, SAME mutex + atomic-write +
+ * fail-closed discipline as `SeoQuotaGovernor` (spec-20260718-in-house-
+ * ai-visibility, Sprint 9; arch ScrapeThrottle §208-220 / ADR-3).
+ *
+ * The scrape arm's `estCostUsdPerPrompt` is booked as $0 to the
+ * `SeoQuotaGovernor` — its real proxy cost is tracked HERE, in an
+ * independent, independently-capped filesystem ledger keyed by engine
+ * string at `.bober/seo/scrape-throttle-ledger.json` (a DISTINCT path
+ * from `.bober/seo/quota-ledger.json`). The two ledgers are never
+ * cross-reconciled (arch §320).
+ *
+ * `acquire(engine)` both DECIDES and CONSUMES a rate slot in one
+ * read-modify-write under the shared per-path mutex (`withLedgerLock`,
+ * reused from `quota-ledger.ts` — path-generic, so this ledger gets its
+ * own serialization chain and cannot interfere with the governor's).
+ * It writes ONLY on the granting branch — a refusal has no side effect,
+ * mirroring `SeoQuotaGovernor.admit()`.
+ *
+ * `recordProxyCost(engine, usd)` is the governor's `record()` twin:
+ * heals a corrupt ledger back to `{}`, accrues a NaN/negative-guarded
+ * USD amount, and writes atomically (temp-file + rename) so a crash
+ * mid-write never leaves a torn file.
+ *
+ * Fail-closed: a corrupt/unreadable ledger makes `acquire` treat proxy
+ * spend as `+Infinity` (mirrors the governor's Infinity-on-corrupt
+ * refuse) and deny with `reason: "proxy-budget"`. A MISSING ledger
+ * (first run) is a fresh `{}` — allow.
+ *
+ * The clock is INJECTED (`() => ISO string`, mirrors
+ * `DamcrawlerCrawlEngine.now`), never `Date.now()` — deterministic
+ * rate-window tests drive it across the window boundary explicitly.
+ *
+ * ISOLATED sprint: no scrape-provider wiring (Sprint 10), no config-
+ * schema field (caps come from the constructor), no egress coupling.
+ */
+import { readFile, writeFile, rename } from "node:fs/promises";
+import { randomBytes } from "node:crypto";
+import { dirname } from "node:path";
+import { ensureDir } from "../utils/fs.js";
+import { withLedgerLock } from "./quota-ledger.js";
+// -- Persistence helpers (mirror quota-ledger.ts, own shape) ----------------
+/**
+ * Read the scrape-throttle ledger from disk.
+ *
+ * - Missing file (ENOENT) => fresh empty ledger `{}` (offline/first-run, NOT corrupt).
+ * - Existing-but-unreadable or unparseable JSON => `"corrupt"` sentinel so the
+ *   caller can fail closed (treat proxy spend as at-ceiling).
+ */
+async function readScrapeLedger(path) {
+    let raw;
+    try {
+        raw = await readFile(path, "utf-8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return {};
+        return "corrupt";
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return "corrupt";
+    }
+}
+/**
+ * Atomically overwrite the scrape-throttle ledger: write a unique temp file,
+ * then rename (POSIX-atomic) so a crash mid-write can never leave a torn file.
+ */
+async function writeScrapeLedgerAtomic(path, ledger) {
+    await ensureDir(dirname(path));
+    const tmp = `${path}.${process.pid}.${Date.now()}.${randomBytes(4).toString("hex")}.tmp`;
+    await writeFile(tmp, JSON.stringify(ledger, null, 2) + "\n", {
+        encoding: "utf-8",
+        mode: 0o600,
+    });
+    await rename(tmp, path);
+}
+// -- Throttle -----------------------------------------------------------------
+export class ScrapeThrottle {
+    ledgerPath;
+    limits;
+    now;
+    constructor(ledgerPath, limits, 
+    // Injected clock (ISO string, mirrors DamcrawlerCrawlEngine.now) — NEVER Date.now().
+    now = () => new Date().toISOString()) {
+        this.ledgerPath = ledgerPath;
+        this.limits = limits;
+        this.now = now;
+    }
+    /**
+     * Decide whether `engine` may scrape now, consuming a rate slot on grant.
+     * Read-modify-write under the per-path mutex; writes ONLY on the granting
+     * branch (a refusal has no side effect on the ledger, mirroring
+     * `SeoQuotaGovernor.admit()`/`record()` no-write-on-refuse).
+     */
+    async acquire(engine) {
+        return withLedgerLock(this.ledgerPath, async () => {
+            const fresh = await readScrapeLedger(this.ledgerPath); // read fresh from disk INSIDE the lock
+            if (fresh === "corrupt") {
+                // Fail-closed: mirror the governor's Infinity-on-corrupt spend, which
+                // trips the budget check rather than the rate-window check.
+                return { proceed: false, reason: "proxy-budget" };
+            }
+            const nowMs = new Date(this.now()).getTime();
+            const existing = fresh[engine];
+            const row = existing ? { ...existing } : { windowStart: nowMs, count: 0, proxyUsdSpent: 0 };
+            // Fixed-window reset: once the window has elapsed, start a fresh one.
+            if (nowMs - row.windowStart >= this.limits.windowMs) {
+                row.windowStart = nowMs;
+                row.count = 0;
+            }
+            if (row.proxyUsdSpent >= this.limits.maxProxyUsd) {
+                return { proceed: false, reason: "proxy-budget" };
+            }
+            if (row.count + 1 > this.limits.maxPerWindow) {
+                return { proceed: false, reason: "rate-window" };
+            }
+            row.count += 1;
+            const ledger = { ...fresh, [engine]: row };
+            await writeScrapeLedgerAtomic(this.ledgerPath, ledger);
+            return { proceed: true };
+        });
+    }
+    /**
+     * Persist completed proxy spend for `engine`. Heals a corrupt ledger back
+     * to `{}` (corruption blocks `acquire`, not `recordProxyCost` — mirrors
+     * `SeoQuotaGovernor.record()`). Guards NaN/negative/zero cost so a bad
+     * value can never corrupt or reduce the running total. Concurrent calls
+     * sharing `ledgerPath` never lose an update (per-path mutex + read-fresh-
+     * inside-lock + atomic write).
+     */
+    async recordProxyCost(engine, usd) {
+        await withLedgerLock(this.ledgerPath, async () => {
+            const fresh = await readScrapeLedger(this.ledgerPath); // read fresh from disk INSIDE the lock
+            const ledger = fresh === "corrupt" ? {} : fresh; // record() heals; corruption blocks acquire, not recordProxyCost
+            const nowMs = new Date(this.now()).getTime();
+            const row = (ledger[engine] ??= { windowStart: nowMs, count: 0, proxyUsdSpent: 0 });
+            // Guard NaN/negative/zero cost (mirrors quota-governor.ts:180-182) — never corrupt proxyUsdSpent.
+            if (Number.isFinite(usd) && usd > 0) {
+                row.proxyUsdSpent += usd;
+            }
+            await writeScrapeLedgerAtomic(this.ledgerPath, ledger);
+        });
+    }
+}
+//# sourceMappingURL=scrape-throttle.js.map

package/dist/seo/scrape-throttle.js.map

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

package/dist/seo/serp-provider.d.ts

@@ -0,0 +1,52 @@
+/**
+ * SerpProvider port (spec-20260717-seo-improver-builder, Sprint 8; ADR-10).
+ * Mirrors the ADR-5 `AiVisibilityProvider` port shape
+ * (`sources/ai-visibility-adapter.ts:73-79`) — `name`, an `estCostUsd*`
+ * metadata field, one async method returning a typed `DataOutcome`.
+ *
+ * Two implementers this sprint:
+ *  - `DataForSeoSerpProvider` (`sources/dataforseo-serp-provider.ts`) — a
+ *    thin delegate over the existing, already egress+governor-gated
+ *    `DataForSeoAdapter.serp` path. Axis `"serp-provider"`; metered USD
+ *    booked INSIDE the wrapped adapter (never re-booked here).
+ *  - `DamcrawlerSerpProvider` (`sources/damcrawler-serp-provider.ts`) — a
+ *    zero-USD scrape via damcrawler's `search()`. Axis `"site-crawl"`
+ *    (ADR-10: SAME risk surface as the crawler, NOT `"serp-provider"`,
+ *    which means "licensed metered API").
+ *
+ * `resolveSerpProvider` below is the `config.seo.serp.provider` selection
+ * factory (default `"dataforseo"`, preserving today's serp output
+ * byte-identically) — mirrors `selectSource` (`runner.ts:177-195`) in
+ * shape, but is NOT wired into `selectSource`/the router this sprint
+ * (Sprint 9, nonGoal); callers construct+inject it directly.
+ */
+import type { BoberConfig } from "../config/schema.js";
+import type { DataOutcome } from "./types.js";
+import type { SerpRow } from "./data-source.js";
+import type { SeoEgressGuard } from "./egress.js";
+import type { DataForSeoAdapter } from "./sources/dataforseo-adapter.js";
+/**
+ * Provider-agnostic SERP port. `serp(keyword, location)` returns already
+ * degrade-safe `DataOutcome<SerpRow[]>` — `disabled`/`abstain`/`data`, NEVER
+ * throws (both implementers uphold this, per their own docstrings).
+ */
+export interface SerpProvider {
+    readonly name: "dataforseo" | "damcrawler";
+    /**
+     * Documented per-result USD price (0.0006 for dataforseo, 0 for
+     * damcrawler). Metadata only — actual USD is booked (or not booked) by
+     * the concrete implementation, never by a caller reading this field.
+     */
+    readonly estCostUsdPerResult: number;
+    serp(keyword: string, location: string): Promise<DataOutcome<SerpRow[]>>;
+}
+/**
+ * Select which self-gating `SerpProvider` `config.seo.serp.provider` names
+ * (default `"dataforseo"`). This factory does NO gating itself — each
+ * returned provider asserts its own egress axis on `.serp()` — it only
+ * decides which already-constructed dependency to wrap. Callers supply the
+ * `DataForSeoAdapter` and `SeoEgressGuard` they already built (mirrors the
+ * dependency-injection style used throughout `src/seo/sources/`).
+ */
+export declare function resolveSerpProvider(config: BoberConfig, dataForSeoAdapter: DataForSeoAdapter, egress: SeoEgressGuard): SerpProvider;
+//# sourceMappingURL=serp-provider.d.ts.map

package/dist/seo/serp-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serp-provider.d.ts","sourceRoot":"","sources":["../../src/seo/serp-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AAIzE;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,YAAY,CAAC;IAC3C;;;;OAIG;IACH,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;CAC1E;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,WAAW,EACnB,iBAAiB,EAAE,iBAAiB,EACpC,MAAM,EAAE,cAAc,GACrB,YAAY,CAKd"}

package/dist/seo/serp-provider.js

@@ -0,0 +1,17 @@
+import { DataForSeoSerpProvider } from "./sources/dataforseo-serp-provider.js";
+import { DamcrawlerSerpProvider } from "./sources/damcrawler-serp-provider.js";
+/**
+ * Select which self-gating `SerpProvider` `config.seo.serp.provider` names
+ * (default `"dataforseo"`). This factory does NO gating itself — each
+ * returned provider asserts its own egress axis on `.serp()` — it only
+ * decides which already-constructed dependency to wrap. Callers supply the
+ * `DataForSeoAdapter` and `SeoEgressGuard` they already built (mirrors the
+ * dependency-injection style used throughout `src/seo/sources/`).
+ */
+export function resolveSerpProvider(config, dataForSeoAdapter, egress) {
+    const providerName = config.seo?.serp?.provider ?? "dataforseo";
+    return providerName === "damcrawler"
+        ? new DamcrawlerSerpProvider(egress)
+        : new DataForSeoSerpProvider(dataForSeoAdapter);
+}
+//# sourceMappingURL=serp-provider.js.map

package/dist/seo/serp-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serp-provider.js","sourceRoot":"","sources":["../../src/seo/serp-provider.ts"],"names":[],"mappings":"AA2BA,OAAO,EAAE,sBAAsB,EAAE,MAAM,uCAAuC,CAAC;AAC/E,OAAO,EAAE,sBAAsB,EAAE,MAAM,uCAAuC,CAAC;AAkB/E;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CACjC,MAAmB,EACnB,iBAAoC,EACpC,MAAsB;IAEtB,MAAM,YAAY,GAAG,MAAM,CAAC,GAAG,EAAE,IAAI,EAAE,QAAQ,IAAI,YAAY,CAAC;IAChE,OAAO,YAAY,KAAK,YAAY;QAClC,CAAC,CAAC,IAAI,sBAAsB,CAAC,MAAM,CAAC;QACpC,CAAC,CAAC,IAAI,sBAAsB,CAAC,iBAAiB,CAAC,CAAC;AACpD,CAAC"}

package/dist/seo/sources/ai-visibility-adapter.d.ts

@@ -0,0 +1,87 @@
+/**
+ * AiVisibilityAdapter — the AI-visibility/GEO `SeoDataSource`
+ * (spec-20260717-seo-improver-builder, Sprint 5). Near-verbatim clone of
+ * `DataForSeoAdapter.serp` (`./dataforseo-adapter.ts:190-238`) — SAME ADR-5
+ * guard→admit→call→record→degrade shape — except the injected transport is
+ * an `AiVisibilityProvider` port (not an `HttpClient`), the axis is
+ * `"ai-visibility"` (not `"serp-provider"`), and `QuotaRequest.source` is
+ * `"ai-visibility"`.
+ *
+ * ADR-5 (`.bober/architecture/arch-20260716-seo-improver-builder-extension-adr-5.md`)
+ * is the load-bearing decision here: the concrete AI-visibility provider is
+ * DELIBERATELY unpinned (Stage-1 found no evidence pinning Perplexity,
+ * Profound, or any other vendor). This adapter therefore depends on an
+ * injected `AiVisibilityProvider` port, never a vendor SDK — swapping
+ * providers means writing a new `AiVisibilityProvider` implementation
+ * OUTSIDE `src/seo/`, with zero changes to this adapter, the seam, or the
+ * egress model. A single `ai-visibility` egress axis gates every provider
+ * (no per-vendor axis — that would explode `selectSource`'s all-off
+ * predicate and threaten the byte-identical-when-off invariant).
+ *
+ * `aiVisibility()` begins with the same two gates, IN ORDER, before any
+ * network work:
+ *   1. `this.egress.assertAllowed("ai-visibility")` — throws when the axis
+ *      is off; caught immediately and converted to `abstain` WITHOUT ever
+ *      calling `this.provider.probe()`.
+ *   2. `this.governor.admit(req)` — synchronous, never throws, no side
+ *      effect; refused admission also aborts before `probe()` runs.
+ * Only after BOTH gates pass does the injected provider run its probe. Any
+ * probe error degrades to `{ kind: "abstain", reason: "source-error" }` —
+ * this method NEVER throws to the caller, and `governor.record()` is called
+ * ONLY after a successful `probe()` (nothing is ever booked for a failed
+ * probe).
+ *
+ * The real global `fetch` is referenced NOWHERE in this file — the injected
+ * `AiVisibilityProvider` is the sole transport, and no vendor SDK is
+ * imported anywhere under `src/seo/` (sc-5-4). Tests inject a hand-rolled
+ * fake provider; production wiring for a real provider is a later sprint
+ * (Sprint 9, nonGoal here).
+ */
+import type { SeoEgressGuard } from "../egress.js";
+import type { SeoQuotaGovernor } from "../quota-governor.js";
+import type { SeoDataSource, SeoCapability, SearchAnalyticsQuery, SearchAnalyticsRow, UrlInspectionQuery, UrlInspectionRow, SerpQuery, SerpRow, KeywordQuery, KeywordRow, BacklinkQuery, BacklinkRow, AiVisibilityQuery, AiVisibilityRow, LinkGraphQuery, LinkGraphRow } from "../data-source.js";
+import type { DataOutcome } from "../types.js";
+/**
+ * Provider-agnostic AI-visibility port (ADR-5). The concrete vendor
+ * (Perplexity, a self-hosted probe harness, a future provider) lives
+ * OUTSIDE `src/seo/` and is injected via the `AiVisibilityAdapter`
+ * constructor — this interface is the ONLY provider surface this module
+ * knows about.
+ *
+ * `probe()` returns already-typed `AiVisibilityRow[]` — each concrete
+ * provider is responsible for mapping its own vendor response shape into
+ * this row type; the adapter does no vendor-specific parsing.
+ */
+export interface AiVisibilityProvider {
+    /** Provider identifier (surfaced in `AiVisibilityRow.provider` by the concrete implementation, not by this adapter). */
+    readonly name: string;
+    /** Fixed per-prompt USD price — the adapter computes `estCostUsd = estCostUsdPerPrompt * prompts.length`. */
+    readonly estCostUsdPerPrompt: number;
+    probe(target: string, prompts: string[], locale?: string): Promise<AiVisibilityRow[]>;
+}
+/**
+ * AI-visibility `SeoDataSource`. Serves ONLY `ai-visibility` — every other
+ * capability is `{ kind: "disabled" }` unconditionally (this adapter is not
+ * a GSC/DataForSEO/crawl source).
+ */
+export declare class AiVisibilityAdapter implements SeoDataSource {
+    private readonly egress;
+    private readonly governor;
+    private readonly provider;
+    constructor(egress: SeoEgressGuard, governor: SeoQuotaGovernor, provider: AiVisibilityProvider);
+    capabilities(): SeoCapability[];
+    /**
+     * AI-visibility probe. ADR-5 preamble (egress gate, then quota gate) runs
+     * before any network work; USD cost is `estCostUsdPerPrompt * prompts.length`
+     * — booked in `admit()` (estimate) and `record()` (actual, identical since
+     * the price is a fixed per-prompt rate).
+     */
+    aiVisibility(q: AiVisibilityQuery): Promise<DataOutcome<AiVisibilityRow[]>>;
+    searchAnalytics(_q: SearchAnalyticsQuery): Promise<DataOutcome<SearchAnalyticsRow[]>>;
+    urlInspection(_q: UrlInspectionQuery): Promise<DataOutcome<UrlInspectionRow[]>>;
+    serp(_q: SerpQuery): Promise<DataOutcome<SerpRow[]>>;
+    keywords(_q: KeywordQuery): Promise<DataOutcome<KeywordRow[]>>;
+    backlinks(_q: BacklinkQuery): Promise<DataOutcome<BacklinkRow[]>>;
+    linkGraph(_q: LinkGraphQuery): Promise<DataOutcome<LinkGraphRow[]>>;
+}
+//# sourceMappingURL=ai-visibility-adapter.d.ts.map

package/dist/seo/sources/ai-visibility-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-visibility-adapter.d.ts","sourceRoot":"","sources":["../../../src/seo/sources/ai-visibility-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,KAAK,EAAE,gBAAgB,EAAgB,MAAM,sBAAsB,CAAC;AAC3E,OAAO,KAAK,EACV,aAAa,EACb,aAAa,EACb,oBAAoB,EACpB,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,EAChB,SAAS,EACT,OAAO,EACP,YAAY,EACZ,UAAU,EACV,aAAa,EACb,WAAW,EACX,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,YAAY,EACb,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,WAAW,EAAkB,MAAM,aAAa,CAAC;AAE/D;;;;;;;;;;GAUG;AACH,MAAM,WAAW,oBAAoB;IACnC,wHAAwH;IACxH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,6GAA6G;IAC7G,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAAC;CACvF;AAED;;;;GAIG;AACH,qBAAa,mBAAoB,YAAW,aAAa;IAErD,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAGzB,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAJR,MAAM,EAAE,cAAc,EACtB,QAAQ,EAAE,gBAAgB,EAG1B,QAAQ,EAAE,oBAAoB;IAGjD,YAAY,IAAI,aAAa,EAAE;IAI/B;;;;;OAKG;IACG,YAAY,CAAC,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,WAAW,CAAC,eAAe,EAAE,CAAC,CAAC;IA2C3E,eAAe,CAAC,EAAE,EAAE,oBAAoB,GAAG,OAAO,CAAC,WAAW,CAAC,kBAAkB,EAAE,CAAC,CAAC;IAIrF,aAAa,CAAC,EAAE,EAAE,kBAAkB,GAAG,OAAO,CAAC,WAAW,CAAC,gBAAgB,EAAE,CAAC,CAAC;IAI/E,IAAI,CAAC,EAAE,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC,OAAO,EAAE,CAAC,CAAC;IAIpD,QAAQ,CAAC,EAAE,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC,UAAU,EAAE,CAAC,CAAC;IAI9D,SAAS,CAAC,EAAE,EAAE,aAAa,GAAG,OAAO,CAAC,WAAW,CAAC,WAAW,EAAE,CAAC,CAAC;IAIjE,SAAS,CAAC,EAAE,EAAE,cAAc,GAAG,OAAO,CAAC,WAAW,CAAC,YAAY,EAAE,CAAC,CAAC;CAG1E"}

package/dist/seo/sources/ai-visibility-adapter.js

@@ -0,0 +1,85 @@
+/**
+ * AI-visibility `SeoDataSource`. Serves ONLY `ai-visibility` — every other
+ * capability is `{ kind: "disabled" }` unconditionally (this adapter is not
+ * a GSC/DataForSEO/crawl source).
+ */
+export class AiVisibilityAdapter {
+    egress;
+    governor;
+    provider;
+    constructor(egress, governor, 
+    // Injectable, provider-agnostic port — REQUIRED, no default (ADR-5: no
+    // vendor is pinned, so there is no sane default to fall back to).
+    provider) {
+        this.egress = egress;
+        this.governor = governor;
+        this.provider = provider;
+    }
+    capabilities() {
+        return ["ai-visibility"];
+    }
+    /**
+     * AI-visibility probe. ADR-5 preamble (egress gate, then quota gate) runs
+     * before any network work; USD cost is `estCostUsdPerPrompt * prompts.length`
+     * — booked in `admit()` (estimate) and `record()` (actual, identical since
+     * the price is a fixed per-prompt rate).
+     */
+    async aiVisibility(q) {
+        // -- STATEMENT 1: egress gate (ADR-5) --
+        try {
+            this.egress.assertAllowed("ai-visibility");
+        }
+        catch {
+            return { kind: "abstain", reason: "egress-ai-visibility-disabled" };
+        }
+        // -- STATEMENT 2: quota gate (ADR-5); synchronous, never throws --
+        const estCostUsd = this.provider.estCostUsdPerPrompt * q.prompts.length;
+        const admitReq = {
+            source: "ai-visibility",
+            capability: "ai-visibility",
+            scope: {},
+            estRows: q.prompts.length, // inert for non-gsc sources (quota-governor.ts admit()/record())
+            estCostUsd,
+        };
+        const decision = this.governor.admit(admitReq);
+        if (!decision.admit) {
+            return { kind: "abstain", reason: decision.reason };
+        }
+        // -- Only now may the provider open a socket. --
+        try {
+            const rows = await this.provider.probe(q.target, q.prompts, q.locale);
+            // Fixed per-prompt price — the actual charge equals the estimate.
+            const actualCostUsd = estCostUsd;
+            await this.governor.record(admitReq, actualCostUsd); // ONLY after success
+            const provenance = {
+                source: "ai-visibility",
+                retrievedAt: new Date().toISOString(),
+                costUsd: actualCostUsd,
+            };
+            return { kind: "data", rows, provenance };
+        }
+        catch {
+            return { kind: "abstain", reason: "source-error" }; // provider error -> abstain, NEVER throw, NOTHING booked
+        }
+    }
+    // -- Capabilities this adapter does not serve (all { kind: "disabled" }) --
+    async searchAnalytics(_q) {
+        return { kind: "disabled" };
+    }
+    async urlInspection(_q) {
+        return { kind: "disabled" };
+    }
+    async serp(_q) {
+        return { kind: "disabled" };
+    }
+    async keywords(_q) {
+        return { kind: "disabled" };
+    }
+    async backlinks(_q) {
+        return { kind: "disabled" };
+    }
+    async linkGraph(_q) {
+        return { kind: "disabled" };
+    }
+}
+//# sourceMappingURL=ai-visibility-adapter.js.map

package/dist/seo/sources/ai-visibility-adapter.js.map

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

package/dist/seo/sources/api-spine-provider.d.ts

@@ -0,0 +1,66 @@
+/**
+ * ApiSpineEngineProvider — one grounded-search engine's `AiVisibilityProvider`
+ * (in-house-ai-visibility, Sprint 2, wired in Sprint 4;
+ * arch-20260717-in-house-oss-ai-visibility-architecture.md:44,84-97,278).
+ *
+ * Mirrors `DamcrawlerSerpProvider`'s injected-deps + `readonly name`/
+ * `readonly estCost...` shape (`./damcrawler-serp-provider.ts:69-101`), but
+ * the injected transport is a Sprint-1 `GroundedSearchClient` (not
+ * damcrawler). There is still no egress gate here — the transport's own
+ * network call is ungated (that remains the ADAPTER's/factory's job) — but
+ * as of Sprint 4 this class DOES own two boundary responsibilities per
+ * ADR-11: (1) sanitize every piece of grounded free-text (`answerText` +
+ * each candidate citation url) via the injected `ContentSanitizer` BEFORE
+ * the row is built, and (2) verify each sanitized candidate url via the
+ * injected `CitationVerifier` (gated by the `site-crawl` axis inside the
+ * verifier itself) and retain ONLY `live === true` urls in `row.sourceUrls`
+ * — an unverifiable citation NEVER reaches a row (sc-4-2).
+ *
+ * `probe()` runs `samplesPerPrompt` (N) independent grounded-search samples
+ * per prompt and emits ONE raw `AiVisibilityRow` per real observation —
+ * never a pre-aggregate ("Every arm emits raw per-(prompt,provider,sample)
+ * AiVisibilityRows ... so API and scrape signal are structurally
+ * unmixable", architecture:44). Each row is stamped with `this.name`
+ * (`= client.engine`), so a future multiplexer can tell which engine
+ * produced which observation without any additional bookkeeping.
+ *
+ * Cost accounting (ADR-3, `arch-20260717-in-house-oss-ai-visibility-adr-3.md`):
+ * the LOCKED `AiVisibilityAdapter` books `estCostUsdPerPrompt * prompts.length`
+ * (`ai-visibility-adapter.ts:114`) — it has no notion of N. So N MUST be
+ * baked into `estCostUsdPerPrompt` here: `estCostUsdPerPrompt = perCallUsd *
+ * samplesPerPrompt`. Getting this wrong under-books the USD ceiling.
+ *
+ * Sample-failure contract (sc-2-4, architecture:278 "Sample throws =>
+ * dropped (wider CI); all fail => abstain, nothing booked"): a single
+ * rejecting sample is caught and `continue`d — it never throws out of the
+ * loop, is never mislabeled, and never fabricates a citation. If EVERY
+ * attempted sample across every prompt rejects, `probe()` throws instead of
+ * returning `[]` — the (not-yet-wired) adapter converts any probe throw
+ * into `abstain` + books nothing (`ai-visibility-adapter.ts:141-143`), which
+ * is exactly the "all fail => abstain, nothing booked" outcome. Calling
+ * `probe()` with zero prompts or `samplesPerPrompt <= 0` attempts nothing
+ * and returns `[]` without throwing (there is no failure to report). This
+ * contract is unaffected by the Sprint-4 sanitize/verify additions: verifier
+ * errors stay INSIDE `probe` (fail-closed, `live:false`) and never throw
+ * out of the sample loop — so cost accounting in the adapter (which books
+ * only after a successful `probe()`) is unaffected by a verification
+ * failure.
+ */
+import type { AiVisibilityProvider } from "./ai-visibility-adapter.js";
+import type { AiVisibilityRow } from "../data-source.js";
+import type { GroundedEngine, GroundedSearchClient } from "../../providers/grounded-search.js";
+import type { MentionCitationExtractor } from "./mention-citation-extractor.js";
+import type { CitationVerifier } from "./citation-verifier.js";
+import type { ContentSanitizer } from "../content-sanitizer.js";
+export declare class ApiSpineEngineProvider implements AiVisibilityProvider {
+    private readonly client;
+    private readonly extractor;
+    private readonly samplesPerPrompt;
+    private readonly verifier;
+    private readonly sanitizer;
+    readonly name: GroundedEngine;
+    readonly estCostUsdPerPrompt: number;
+    constructor(client: GroundedSearchClient, extractor: MentionCitationExtractor, samplesPerPrompt: number, perCallUsd: number, verifier: CitationVerifier, sanitizer: ContentSanitizer);
+    probe(target: string, prompts: string[], locale?: string): Promise<AiVisibilityRow[]>;
+}
+//# sourceMappingURL=api-spine-provider.d.ts.map

package/dist/seo/sources/api-spine-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-spine-provider.d.ts","sourceRoot":"","sources":["../../../src/seo/sources/api-spine-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AACvE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,KAAK,EAAkB,cAAc,EAAE,oBAAoB,EAAE,MAAM,oCAAoC,CAAC;AAC/G,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,iCAAiC,CAAC;AAChF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAEhE,qBAAa,sBAAuB,YAAW,oBAAoB;IAK/D,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IAEjC,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAT5B,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;gBAGlB,MAAM,EAAE,oBAAoB,EAC5B,SAAS,EAAE,wBAAwB,EACnC,gBAAgB,EAAE,MAAM,EACzC,UAAU,EAAE,MAAM,EACD,QAAQ,EAAE,gBAAgB,EAC1B,SAAS,EAAE,gBAAgB;IAMxC,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;CAsD5F"}

package/dist/seo/sources/api-spine-provider.js

@@ -0,0 +1,68 @@
+export class ApiSpineEngineProvider {
+    client;
+    extractor;
+    samplesPerPrompt;
+    verifier;
+    sanitizer;
+    name;
+    estCostUsdPerPrompt;
+    constructor(client, extractor, samplesPerPrompt, perCallUsd, verifier, sanitizer) {
+        this.client = client;
+        this.extractor = extractor;
+        this.samplesPerPrompt = samplesPerPrompt;
+        this.verifier = verifier;
+        this.sanitizer = sanitizer;
+        this.name = client.engine; // every row is stamped with the injected client's engine
+        this.estCostUsdPerPrompt = perCallUsd * samplesPerPrompt; // ADR-3: N baked in, once, from the SAME N used below
+    }
+    async probe(target, prompts, locale) {
+        const rows = [];
+        let attempted = 0;
+        for (const prompt of prompts) {
+            for (let i = 0; i < this.samplesPerPrompt; i++) {
+                attempted += 1;
+                let answer;
+                try {
+                    answer = await this.client.search(prompt, locale);
+                }
+                catch {
+                    continue; // sc-2-4: drop the failed sample — never throw, never mislabel, never merge
+                }
+                // sc-4-3: sanitize every piece of grounded free-text at the
+                // network->in-process boundary BEFORE the row is built — the
+                // sanitized answerText feeds the extractor, and every candidate
+                // citation url is sanitized before it is handed to the verifier.
+                const sanitizedAnswerText = this.sanitizer.clean(answer.answerText, target).content;
+                const sanitizedCitations = answer.citations.map((c) => ({
+                    ...c,
+                    url: this.sanitizer.clean(c.url, c.url).content,
+                }));
+                const obs = await this.extractor.extract({ target, answerText: sanitizedAnswerText, citations: sanitizedCitations });
+                // sc-4-2: verify every candidate url; retain ONLY live===true urls.
+                // The verifier itself is fail-closed (site-crawl off / dep absent /
+                // scrape error all degrade to live:false) — never fabricate a live
+                // citation here.
+                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; // optional-key omission — never `rank: undefined`
+                rows.push(row);
+            }
+        }
+        // Every attempted sample rejected (and at least one was attempted): throw
+        // so the caller (a future adapter) can degrade to abstain + book nothing,
+        // rather than silently returning an empty-but-successful `[]`.
+        if (attempted > 0 && rows.length === 0) {
+            throw new Error("ApiSpineEngineProvider: every sample rejected");
+        }
+        return rows;
+    }
+}
+//# sourceMappingURL=api-spine-provider.js.map

package/dist/seo/sources/api-spine-provider.js.map

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