agent-bober 0.18.0 → 0.19.0

package/dist/seo/data-source.d.ts

@@ -0,0 +1,156 @@
+/**
+ * SeoDataSource seam (spec-20260715-ultimate-seo-suite, Sprint 6).
+ *
+ * The unified interface every data provider (offline `LocalExportSource`,
+ * this sprint; live `gsc`/`dataforseo` adapters, sprints 8-9) implements.
+ * Capability/query/row shapes are quoted from the architecture Component
+ * Breakdown / Data Model (.bober/architecture/
+ * arch-20260715-ultimate-seo-agents-skills-architecture.md:143-212).
+ *
+ * `DataOutcome`/`DataProvenance` are the canonical outcome union defined in
+ * `./types.js` (Sprint 1) — RE-EXPORTED here, never redefined.
+ */
+import type { DataOutcome } from "./types.js";
+export type { DataOutcome, DataProvenance } from "./types.js";
+/**
+ * The seven data capabilities a `SeoDataSource` may serve. Widened from five
+ * to seven (spec-20260717-seo-improver-builder, Sprint 1) with
+ * `"ai-visibility"` and `"link-graph"` — a closed union, so every
+ * implementer + any exhaustive `Record<SeoCapability, ...>` map is forced by
+ * the compiler to account for the two new members.
+ */
+export type SeoCapability = "search-analytics" | "url-inspection" | "serp" | "keywords" | "backlinks" | "ai-visibility" | "link-graph";
+export type SearchAnalyticsQuery = {
+    siteUrl: string;
+    startDate: string;
+    endDate: string;
+    dimensions: Array<"query" | "page" | "country" | "device">;
+    rowLimit?: number;
+};
+export type UrlInspectionQuery = {
+    siteUrl: string;
+    inspectionUrl: string;
+};
+export type SerpQuery = {
+    keyword: string;
+    location: string;
+    priority?: "standard" | "priority" | "live";
+};
+export type KeywordQuery = {
+    keywords: string[];
+    location: string;
+};
+export type BacklinkQuery = {
+    target: string;
+    limit?: number;
+};
+/**
+ * AI-visibility/GEO probe query — one batch of prompts against a target
+ * (architecture Data Model, arch-20260716-...-architecture.md:64; F5).
+ */
+export type AiVisibilityQuery = {
+    target: string;
+    prompts: string[];
+    locale?: string;
+};
+/** Site-crawl internal-link-graph query (architecture:65; F7). */
+export type LinkGraphQuery = {
+    rootUrl: string;
+    limit?: number;
+};
+/** GSC Search-Analytics export, flattened. */
+export type SearchAnalyticsRow = {
+    query?: string;
+    page?: string;
+    country?: string;
+    device?: string;
+    clicks: number;
+    impressions: number;
+    ctr: number;
+    position: number;
+};
+/** GSC URL-Inspection export or local crawl output. */
+export type UrlInspectionRow = {
+    url: string;
+    coverageState?: string;
+    indexingState?: string;
+    lastCrawlTime?: string;
+    robotsTxtState?: string;
+    pageFetchState?: string;
+};
+export type SerpRow = {
+    keyword: string;
+    position: number;
+    url: string;
+    title?: string;
+    location?: string;
+};
+export type KeywordRow = {
+    keyword: string;
+    searchVolume?: number;
+    cpc?: number;
+    competition?: number;
+    location?: string;
+};
+export type BacklinkRow = {
+    sourceUrl: string;
+    targetUrl: string;
+    anchor?: string;
+    dofollow?: boolean;
+};
+/**
+ * One AI-answer probe result — one row per (prompt, provider) pair
+ * (architecture:64; F5). `citationPresent`/`sourceUrls` capture whether the
+ * AI answer cited the target at all, distinct from `mentioned` (brand
+ * mentioned in the answer text without a citation).
+ */
+export type AiVisibilityRow = {
+    prompt: string;
+    provider: string;
+    mentioned: boolean;
+    rank?: number;
+    citationPresent: boolean;
+    sourceUrls: string[];
+};
+/**
+ * One internal/external link edge from a site crawl — flat rows, not a
+ * nested graph (architecture:65, ADR-6; F7).
+ */
+export type LinkGraphRow = {
+    fromUrl: string;
+    toUrl: string;
+    anchor?: string;
+    internal: boolean;
+};
+/**
+ * One crawled page's sanitized content (architecture:66, ADR-11; F6/F7).
+ * `content` has already been passed through `ContentSanitizer` by the time
+ * it reaches this row — no further sanitization is required downstream. No
+ * `Query` pair this sprint (the crawl query lives on `CrawlEngine`, a later
+ * sprint).
+ */
+export type CrawlPageRow = {
+    url: string;
+    title?: string;
+    content: string;
+};
+/**
+ * Implemented by every SEO data provider (offline or live). Each method
+ * returns a `DataOutcome` and — per the discipline mirrored from
+ * `RetrievalOutcome` (`src/medical/retrieval/medline-source.ts:25-28`) —
+ * NEVER throws to the caller: absent/unsupported capability maps to
+ * `{ kind: "disabled" }`, a parseable-but-empty result maps to
+ * `{ kind: "abstain", reason }`.
+ */
+export interface SeoDataSource {
+    /** The capabilities this source can currently serve (advertises only what it can). */
+    capabilities(): SeoCapability[];
+    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[]>>;
+    aiVisibility(q: AiVisibilityQuery): Promise<DataOutcome<AiVisibilityRow[]>>;
+    linkGraph(q: LinkGraphQuery): Promise<DataOutcome<LinkGraphRow[]>>;
+}
+//# sourceMappingURL=data-source.d.ts.map

package/dist/seo/data-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-source.d.ts","sourceRoot":"","sources":["../../src/seo/data-source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAI9D;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GACrB,kBAAkB,GAClB,gBAAgB,GAChB,MAAM,GACN,UAAU,GACV,WAAW,GACX,eAAe,GACf,YAAY,CAAC;AAIjB,MAAM,MAAM,oBAAoB,GAAG;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,KAAK,CAAC,OAAO,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,CAAC,CAAC;IAC3D,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5E,MAAM,MAAM,SAAS,GAAG;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,UAAU,GAAG,UAAU,GAAG,MAAM,CAAC;CAC7C,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpE,MAAM,MAAM,aAAa,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/D;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvF,kEAAkE;AAClE,MAAM,MAAM,cAAc,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAMjE,8CAA8C;AAC9C,MAAM,MAAM,kBAAkB,GAAG;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,uDAAuD;AACvD,MAAM,MAAM,gBAAgB,GAAG;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,OAAO,GAAG;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,OAAO,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,eAAe,EAAE,OAAO,CAAC;IACzB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,CAAC;AAElG;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAI5E;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B,sFAAsF;IACtF,YAAY,IAAI,aAAa,EAAE,CAAC;IAChC,eAAe,CAAC,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,WAAW,CAAC,kBAAkB,EAAE,CAAC,CAAC,CAAC;IACrF,aAAa,CAAC,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,WAAW,CAAC,gBAAgB,EAAE,CAAC,CAAC,CAAC;IAC/E,IAAI,CAAC,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;IACpD,QAAQ,CAAC,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC;IAC9D,SAAS,CAAC,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,WAAW,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;IAGjE,YAAY,CAAC,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,WAAW,CAAC,eAAe,EAAE,CAAC,CAAC,CAAC;IAC5E,SAAS,CAAC,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,WAAW,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC;CACpE"}

package/dist/seo/data-source.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=data-source.js.map

package/dist/seo/data-source.js.map

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

package/dist/seo/egress.d.ts

@@ -0,0 +1,39 @@
+/** SeoEgressGuard — five independently opt-in live-data egress axes, all default false (spec-20260715-ultimate-seo-suite, Sprint 1; widened spec-20260717-seo-improver-builder, Sprint 1; widened again in-house-ai-visibility, Sprint 3; mirrors medical/egress.ts:17-59, ADR-6). */
+import type { BoberConfig } from "../config/schema.js";
+/**
+ * The five independent live-data egress axes. All default FALSE
+ * (code-enforced zero-egress). `ai-visibility-scrape` (Sprint 3) is
+ * axis-only this sprint — no scrape provider composes it yet (Sprint 10).
+ */
+export type SeoEgressAxis = "search-console" | "serp-provider" | "ai-visibility" | "site-crawl" | "ai-visibility-scrape";
+/**
+ * Guards outbound egress for the SEO pipeline's live-data adapters (Google
+ * Search Console, DataForSEO, AI-visibility provider, damcrawler site-crawl,
+ * AI-visibility UI-scrape arm).
+ *
+ * The five axes operate INDEPENDENTLY — opting in one does NOT opt in any
+ * other. All default false when absent from config. `assertAllowed` throws
+ * if the axis is not opted in, providing a hard code-enforced barrier that
+ * every network-opening adapter method must call first (ADR-5).
+ *
+ * bober: plain decision object; no network import here; swap for a shared
+ *        policy engine if per-scope granularity is ever needed.
+ */
+export declare class SeoEgressGuard {
+    private readonly searchConsole;
+    private readonly serpProvider;
+    private readonly aiVisibility;
+    private readonly siteCrawl;
+    private readonly aiVisibilityScrape;
+    constructor(searchConsole: boolean, serpProvider: boolean, aiVisibility?: boolean, siteCrawl?: boolean, aiVisibilityScrape?: boolean);
+    /** Build from BoberConfig seo section; all five axes default false when absent. */
+    static fromConfig(config: BoberConfig): SeoEgressGuard;
+    /** Returns true only when the axis has been explicitly opted in via config. */
+    isAllowed(axis: SeoEgressAxis): boolean;
+    /**
+     * Throws an Error when the axis is not enabled.
+     * Returns void (not throws) when the axis is allowed.
+     */
+    assertAllowed(axis: SeoEgressAxis): void;
+}
+//# sourceMappingURL=egress.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"egress.d.ts","sourceRoot":"","sources":["../../src/seo/egress.ts"],"names":[],"mappings":"AAAA,sRAAsR;AACtR,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvD;;;;GAIG;AACH,MAAM,MAAM,aAAa,GACrB,gBAAgB,GAChB,eAAe,GACf,eAAe,GACf,YAAY,GACZ,sBAAsB,CAAC;AAE3B;;;;;;;;;;;;GAYG;AACH,qBAAa,cAAc;IAEvB,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,YAAY;IAG7B,OAAO,CAAC,QAAQ,CAAC,YAAY;IAC7B,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,kBAAkB;gBANlB,aAAa,EAAE,OAAO,EACtB,YAAY,EAAE,OAAO,EAGrB,YAAY,GAAE,OAAe,EAC7B,SAAS,GAAE,OAAe,EAC1B,kBAAkB,GAAE,OAAe;IAGtD,mFAAmF;IACnF,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,WAAW,GAAG,cAAc;IAWtD,+EAA+E;IAC/E,SAAS,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO;IAmBvC;;;OAGG;IACH,aAAa,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI;CAKzC"}

package/dist/seo/egress.js

@@ -0,0 +1,64 @@
+/**
+ * Guards outbound egress for the SEO pipeline's live-data adapters (Google
+ * Search Console, DataForSEO, AI-visibility provider, damcrawler site-crawl,
+ * AI-visibility UI-scrape arm).
+ *
+ * The five axes operate INDEPENDENTLY — opting in one does NOT opt in any
+ * other. All default false when absent from config. `assertAllowed` throws
+ * if the axis is not opted in, providing a hard code-enforced barrier that
+ * every network-opening adapter method must call first (ADR-5).
+ *
+ * bober: plain decision object; no network import here; swap for a shared
+ *        policy engine if per-scope granularity is ever needed.
+ */
+export class SeoEgressGuard {
+    searchConsole;
+    serpProvider;
+    aiVisibility;
+    siteCrawl;
+    aiVisibilityScrape;
+    constructor(searchConsole, serpProvider, 
+    // NEW axes, DEFAULTED so the ~99 existing 2-4-arg `new SeoEgressGuard(...)`
+    // call sites across the adapter test files keep compiling untouched.
+    aiVisibility = false, siteCrawl = false, aiVisibilityScrape = false) {
+        this.searchConsole = searchConsole;
+        this.serpProvider = serpProvider;
+        this.aiVisibility = aiVisibility;
+        this.siteCrawl = siteCrawl;
+        this.aiVisibilityScrape = aiVisibilityScrape;
+    }
+    /** Build from BoberConfig seo section; all five axes default false when absent. */
+    static fromConfig(config) {
+        const seo = config.seo;
+        return new SeoEgressGuard(seo?.egress?.["search-console"] ?? false, seo?.egress?.["serp-provider"] ?? false, seo?.egress?.["ai-visibility"] ?? false, seo?.egress?.["site-crawl"] ?? false, seo?.egress?.["ai-visibility-scrape"] ?? false);
+    }
+    /** Returns true only when the axis has been explicitly opted in via config. */
+    isAllowed(axis) {
+        switch (axis) {
+            case "search-console":
+                return this.searchConsole;
+            case "serp-provider":
+                return this.serpProvider;
+            case "ai-visibility":
+                return this.aiVisibility;
+            case "site-crawl":
+                return this.siteCrawl;
+            case "ai-visibility-scrape":
+                return this.aiVisibilityScrape;
+            default: {
+                const _exhaustive = axis; // compile error if a SeoEgressAxis value is unhandled
+                return _exhaustive;
+            }
+        }
+    }
+    /**
+     * Throws an Error when the axis is not enabled.
+     * Returns void (not throws) when the axis is allowed.
+     */
+    assertAllowed(axis) {
+        if (!this.isAllowed(axis)) {
+            throw new Error(`Egress axis '${axis}' not enabled`);
+        }
+    }
+}
+//# sourceMappingURL=egress.js.map

package/dist/seo/egress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"egress.js","sourceRoot":"","sources":["../../src/seo/egress.ts"],"names":[],"mappings":"AAeA;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,cAAc;IAEN;IACA;IAGA;IACA;IACA;IAPnB,YACmB,aAAsB,EACtB,YAAqB;IACtC,4EAA4E;IAC5E,qEAAqE;IACpD,eAAwB,KAAK,EAC7B,YAAqB,KAAK,EAC1B,qBAA8B,KAAK;QANnC,kBAAa,GAAb,aAAa,CAAS;QACtB,iBAAY,GAAZ,YAAY,CAAS;QAGrB,iBAAY,GAAZ,YAAY,CAAiB;QAC7B,cAAS,GAAT,SAAS,CAAiB;QAC1B,uBAAkB,GAAlB,kBAAkB,CAAiB;IACnD,CAAC;IAEJ,mFAAmF;IACnF,MAAM,CAAC,UAAU,CAAC,MAAmB;QACnC,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC;QACvB,OAAO,IAAI,cAAc,CACvB,GAAG,EAAE,MAAM,EAAE,CAAC,gBAAgB,CAAC,IAAI,KAAK,EACxC,GAAG,EAAE,MAAM,EAAE,CAAC,eAAe,CAAC,IAAI,KAAK,EACvC,GAAG,EAAE,MAAM,EAAE,CAAC,eAAe,CAAC,IAAI,KAAK,EACvC,GAAG,EAAE,MAAM,EAAE,CAAC,YAAY,CAAC,IAAI,KAAK,EACpC,GAAG,EAAE,MAAM,EAAE,CAAC,sBAAsB,CAAC,IAAI,KAAK,CAC/C,CAAC;IACJ,CAAC;IAED,+EAA+E;IAC/E,SAAS,CAAC,IAAmB;QAC3B,QAAQ,IAAI,EAAE,CAAC;YACb,KAAK,gBAAgB;gBACnB,OAAO,IAAI,CAAC,aAAa,CAAC;YAC5B,KAAK,eAAe;gBAClB,OAAO,IAAI,CAAC,YAAY,CAAC;YAC3B,KAAK,eAAe;gBAClB,OAAO,IAAI,CAAC,YAAY,CAAC;YAC3B,KAAK,YAAY;gBACf,OAAO,IAAI,CAAC,SAAS,CAAC;YACxB,KAAK,sBAAsB;gBACzB,OAAO,IAAI,CAAC,kBAAkB,CAAC;YACjC,OAAO,CAAC,CAAC,CAAC;gBACR,MAAM,WAAW,GAAU,IAAI,CAAC,CAAC,sDAAsD;gBACvF,OAAO,WAAW,CAAC;YACrB,CAAC;QACH,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,aAAa,CAAC,IAAmB;QAC/B,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CAAC,gBAAgB,IAAI,eAAe,CAAC,CAAC;QACvD,CAAC;IACH,CAAC;CACF"}

package/dist/seo/hub-emitter.d.ts

@@ -0,0 +1,28 @@
+import type { Finding } from "../hub/finding.js";
+import type { SeoAnalysis } from "./analyzer.js";
+import type { Logger } from "../utils/logger.js";
+/** Hub Finding emitter — mirrors `SecurityFindingSink` (`security-hub.ts:29`). */
+export type SeoFindingSink = (finding: Finding) => Promise<void>;
+export declare class SeoHubEmitter {
+    /**
+     * Build one hub `Finding` per CITED `SeoFinding` in `analysis.findings`.
+     * PURE — never reads the clock (`now` is injected).
+     *
+     * `kind` mapping: `humanApprovalRequired: true` -> `"action"`;
+     * otherwise `"risk"` (informational/low-severity findings could be
+     * refined to `"watch"` in a later sprint — not required by sc-11-4).
+     *
+     * `title` is STABLE across retries (feeds the id hash via
+     * `deriveFindingId`) — built from `workflow` + a slice of the
+     * recommendation text, never the full free-text body.
+     */
+    mapToFindings(analysis: SeoAnalysis, now: string): Finding[];
+    /**
+     * Map and emit `analysis`'s cited findings through the injected sink.
+     * Best-effort: NEVER throws. A failure raised by the sink (or the
+     * mapping) is caught and logged via `log.warn` — it must never alter the
+     * runner's exit code (mirrors `emitSecurityFindings`, `security-hub.ts:164-177`).
+     */
+    emit(analysis: SeoAnalysis, sink: SeoFindingSink, log: Pick<Logger, "warn">, now: string): Promise<void>;
+}
+//# sourceMappingURL=hub-emitter.d.ts.map

package/dist/seo/hub-emitter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hub-emitter.d.ts","sourceRoot":"","sources":["../../src/seo/hub-emitter.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAEjD,kFAAkF;AAClF,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAgBjE,qBAAa,aAAa;IACxB;;;;;;;;;;;OAWG;IACH,aAAa,CAAC,QAAQ,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,EAAE;IAsC5D;;;;;OAKG;IACG,IAAI,CACR,QAAQ,EAAE,WAAW,EACrB,IAAI,EAAE,cAAc,EACpB,GAAG,EAAE,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,EACzB,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,IAAI,CAAC;CASjB"}

package/dist/seo/hub-emitter.js

@@ -0,0 +1,95 @@
+/**
+ * SeoHubEmitter — maps cited `SeoFinding`s into the canonical hub `Finding`
+ * shape and emits them via an injected sink (spec-20260715-ultimate-seo-suite,
+ * Sprint 11). Mirrors `src/orchestrator/security-hub.ts:39-177` — the FIRST
+ * use of the import-only `src/hub/finding.ts` from this module.
+ *
+ * `Finding`/`FindingSchema` are IMPORTED, never redefined (sc-11-4). The
+ * mapper is PURE (never reads the clock — `now` is caller-injected, mirrors
+ * `mapAuditToFindings`); the sink is a dependency the caller binds to the
+ * real `ingestFinding` (`src/hub/finding-store.ts`) at the fs boundary.
+ *
+ * Uncited findings are dropped TWICE (belt-and-suspenders with
+ * `SeoCitationGate`, arch line 325): callers are expected to pass only
+ * `SeoCitationGate.apply(...).cited` findings, but `mapToFindings` ALSO
+ * skips any finding whose `citationUrl` is missing/empty as a second,
+ * independent guard (sc-11-5).
+ */
+import { createHash } from "node:crypto";
+/**
+ * Content-stable id: hash of domain|title|kind. Replicated locally (same
+ * precedent as `security-hub.ts:33-41`) rather than imported — an id hash,
+ * NOT a schema-level redefinition of `Finding`.
+ */
+function deriveFindingId(domain, title, kind) {
+    return createHash("sha256").update(`${domain}|${title}|${kind}`).digest("hex").slice(0, 16);
+}
+/** Flatten one `SeoFinding.evidence` entry into a hub `evidence[]` string. */
+function formatEvidence(entry) {
+    return `${entry.metric}=${entry.value} (${entry.source}) ${entry.url}`;
+}
+export class SeoHubEmitter {
+    /**
+     * Build one hub `Finding` per CITED `SeoFinding` in `analysis.findings`.
+     * PURE — never reads the clock (`now` is injected).
+     *
+     * `kind` mapping: `humanApprovalRequired: true` -> `"action"`;
+     * otherwise `"risk"` (informational/low-severity findings could be
+     * refined to `"watch"` in a later sprint — not required by sc-11-4).
+     *
+     * `title` is STABLE across retries (feeds the id hash via
+     * `deriveFindingId`) — built from `workflow` + a slice of the
+     * recommendation text, never the full free-text body.
+     */
+    mapToFindings(analysis, now) {
+        const out = [];
+        for (const finding of analysis.findings) {
+            // Belt-and-suspenders with SeoCitationGate — skip any uncited finding
+            // that slipped through, even though callers are expected to pass only
+            // gate.cited (sc-11-5).
+            if (!finding.citationUrl || finding.citationUrl.trim().length === 0)
+                continue;
+            const kind = finding.humanApprovalRequired ? "action" : "risk";
+            const title = `[seo] ${finding.workflow}: ${finding.recommendation.slice(0, 80)}`;
+            out.push({
+                id: deriveFindingId("seo", title, kind),
+                domain: "seo",
+                title,
+                kind,
+                urgency: finding.severity,
+                severity: finding.severity,
+                evidence: [
+                    finding.recommendation,
+                    ...finding.evidence.map(formatEvidence),
+                    `cite:${finding.citationUrl}`,
+                ],
+                surfacedAt: now,
+                tags: [
+                    "seo",
+                    `workflow:${finding.workflow}`,
+                    `playbook:${finding.playbookRef}`,
+                    `confidence:${finding.confidence}`,
+                ],
+                status: "open",
+            });
+        }
+        return out;
+    }
+    /**
+     * Map and emit `analysis`'s cited findings through the injected sink.
+     * Best-effort: NEVER throws. A failure raised by the sink (or the
+     * mapping) is caught and logged via `log.warn` — it must never alter the
+     * runner's exit code (mirrors `emitSecurityFindings`, `security-hub.ts:164-177`).
+     */
+    async emit(analysis, sink, log, now) {
+        try {
+            for (const finding of this.mapToFindings(analysis, now)) {
+                await sink(finding);
+            }
+        }
+        catch (err) {
+            log.warn(`SEO hub emission failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+}
+//# sourceMappingURL=hub-emitter.js.map

package/dist/seo/hub-emitter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hub-emitter.js","sourceRoot":"","sources":["../../src/seo/hub-emitter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AASzC;;;;GAIG;AACH,SAAS,eAAe,CAAC,MAAc,EAAE,KAAa,EAAE,IAAY;IAClE,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,GAAG,MAAM,IAAI,KAAK,IAAI,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAC9F,CAAC;AAED,8EAA8E;AAC9E,SAAS,cAAc,CAAC,KAAqE;IAC3F,OAAO,GAAG,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,KAAK,KAAK,KAAK,CAAC,MAAM,KAAK,KAAK,CAAC,GAAG,EAAE,CAAC;AACzE,CAAC;AAED,MAAM,OAAO,aAAa;IACxB;;;;;;;;;;;OAWG;IACH,aAAa,CAAC,QAAqB,EAAE,GAAW;QAC9C,MAAM,GAAG,GAAc,EAAE,CAAC;QAE1B,KAAK,MAAM,OAAO,IAAI,QAAQ,CAAC,QAAQ,EAAE,CAAC;YACxC,sEAAsE;YACtE,sEAAsE;YACtE,wBAAwB;YACxB,IAAI,CAAC,OAAO,CAAC,WAAW,IAAI,OAAO,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC;gBAAE,SAAS;YAE9E,MAAM,IAAI,GAAoB,OAAO,CAAC,qBAAqB,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC;YAChF,MAAM,KAAK,GAAG,SAAS,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC;YAElF,GAAG,CAAC,IAAI,CAAC;gBACP,EAAE,EAAE,eAAe,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC;gBACvC,MAAM,EAAE,KAAK;gBACb,KAAK;gBACL,IAAI;gBACJ,OAAO,EAAE,OAAO,CAAC,QAAQ;gBACzB,QAAQ,EAAE,OAAO,CAAC,QAAQ;gBAC1B,QAAQ,EAAE;oBACR,OAAO,CAAC,cAAc;oBACtB,GAAG,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,cAAc,CAAC;oBACvC,QAAQ,OAAO,CAAC,WAAW,EAAE;iBAC9B;gBACD,UAAU,EAAE,GAAG;gBACf,IAAI,EAAE;oBACJ,KAAK;oBACL,YAAY,OAAO,CAAC,QAAQ,EAAE;oBAC9B,YAAY,OAAO,CAAC,WAAW,EAAE;oBACjC,cAAc,OAAO,CAAC,UAAU,EAAE;iBACnC;gBACD,MAAM,EAAE,MAAM;aACf,CAAC,CAAC;QACL,CAAC;QAED,OAAO,GAAG,CAAC;IACb,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,IAAI,CACR,QAAqB,EACrB,IAAoB,EACpB,GAAyB,EACzB,GAAW;QAEX,IAAI,CAAC;YACH,KAAK,MAAM,OAAO,IAAI,IAAI,CAAC,aAAa,CAAC,QAAQ,EAAE,GAAG,CAAC,EAAE,CAAC;gBACxD,MAAM,IAAI,CAAC,OAAO,CAAC,CAAC;YACtB,CAAC;QACH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,GAAG,CAAC,IAAI,CAAC,4BAA4B,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC3F,CAAC;IACH,CAAC;CACF"}

package/dist/seo/index.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Public surface of `src/seo/` (spec-20260715-ultimate-seo-suite, Sprint 1).
+ * Focused local barrel — mirrors `src/config/index.ts` (selective named
+ * re-exports, `type` keyword for types). Deliberately does NOT re-export
+ * `SeoConfigSchema` from `src/config/schema.js` — that barrel intentionally
+ * omits section schemas (`src/config/index.ts:1-58`); consumers import
+ * section schemas directly from `./schema.js`.
+ */
+export type { SeoWorkflow, DataProvenance, DataOutcome, SeoSignature, SeoFinding, SeoReport, SeoQuotaLedger, } from "./types.js";
+export { SeoEgressGuard } from "./egress.js";
+export type { SeoEgressAxis } from "./egress.js";
+export { SeoQuotaGovernor } from "./quota-governor.js";
+export type { QuotaRequest, QuotaDecision, QuotaRefusalReason } from "./quota-governor.js";
+export { SeoPlaybookParser } from "./parser.js";
+export { SeoPlaybookIndex } from "./playbook-index.js";
+export { SeoPlaybookRetriever } from "./retriever.js";
+export type { SeoRetrieveInput, SeoRetrieveResult } from "./retriever.js";
+export type { SeoDataSource, SeoCapability, SearchAnalyticsQuery, SearchAnalyticsRow, UrlInspectionQuery, UrlInspectionRow, SerpQuery, SerpRow, KeywordQuery, KeywordRow, BacklinkQuery, BacklinkRow, } from "./data-source.js";
+export { LocalExportSource } from "./sources/local-export.js";
+export { GscAdapter } from "./sources/gsc-adapter.js";
+export { DataForSeoAdapter } from "./sources/dataforseo-adapter.js";
+export type { HttpClient, HttpResponse, HttpRequestInit } from "./adapters/http.js";
+export { SeoAnalyzer } from "./analyzer.js";
+export type { SeoAnalyzeInput, SeoAnalysis, SeoDataBundle } from "./analyzer.js";
+export { AiVisibilityScorer } from "./ai-visibility-scorer.js";
+export type { AiVisibilityMetric } from "./ai-visibility-scorer.js";
+export { SeoCitationGate } from "./citation-gate.js";
+export type { SeoBlockThreshold, CitationGateResult } from "./citation-gate.js";
+export { NeverEncodeFilter, NEVER_ENCODE_PATTERNS } from "./never-encode-filter.js";
+export type { NeverEncodeResult } from "./never-encode-filter.js";
+export { SeoReportStore, deriveReportId } from "./report-store.js";
+export { SeoHubEmitter } from "./hub-emitter.js";
+export type { SeoFindingSink } from "./hub-emitter.js";
+export { SeoWorkflowRunner, selectSource } from "./runner.js";
+export type { SeoRunInput, SeoRunOutcome } from "./runner.js";
+export { SeoRecommendationVerifier } from "./verifier.js";
+export type { SeoVerifier, SeoVerifyParams, SeoVerifyResult } from "./verifier.js";
+export { registerSeoCommand } from "./command.js";
+export type { SeoCommandOverrides } from "./command.js";
+export { runBenchmark } from "./benchmark/harness.js";
+export type { SeoBenchmarkCase, CorpusMetrics } from "./benchmark/harness.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/seo/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,YAAY,EACV,WAAW,EACX,cAAc,EACd,WAAW,EACX,YAAY,EACZ,UAAU,EACV,SAAS,EACT,cAAc,GACf,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAE3F,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AACtD,YAAY,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAE1E,YAAY,EACV,aAAa,EACb,aAAa,EACb,oBAAoB,EACpB,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,EAChB,SAAS,EACT,OAAO,EACP,YAAY,EACZ,UAAU,EACV,aAAa,EACb,WAAW,GACZ,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AAEpE,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAEpF,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEjF,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,YAAY,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAEpE,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,YAAY,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAEhF,OAAO,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AACpF,YAAY,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAElE,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEnE,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,YAAY,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC9D,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE9D,OAAO,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAC;AAC1D,YAAY,EAAE,WAAW,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAEnF,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAClD,YAAY,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAExD,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,YAAY,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/seo/index.js

@@ -0,0 +1,19 @@
+export { SeoEgressGuard } from "./egress.js";
+export { SeoQuotaGovernor } from "./quota-governor.js";
+export { SeoPlaybookParser } from "./parser.js";
+export { SeoPlaybookIndex } from "./playbook-index.js";
+export { SeoPlaybookRetriever } from "./retriever.js";
+export { LocalExportSource } from "./sources/local-export.js";
+export { GscAdapter } from "./sources/gsc-adapter.js";
+export { DataForSeoAdapter } from "./sources/dataforseo-adapter.js";
+export { SeoAnalyzer } from "./analyzer.js";
+export { AiVisibilityScorer } from "./ai-visibility-scorer.js";
+export { SeoCitationGate } from "./citation-gate.js";
+export { NeverEncodeFilter, NEVER_ENCODE_PATTERNS } from "./never-encode-filter.js";
+export { SeoReportStore, deriveReportId } from "./report-store.js";
+export { SeoHubEmitter } from "./hub-emitter.js";
+export { SeoWorkflowRunner, selectSource } from "./runner.js";
+export { SeoRecommendationVerifier } from "./verifier.js";
+export { registerSeoCommand } from "./command.js";
+export { runBenchmark } from "./benchmark/harness.js";
+//# sourceMappingURL=index.js.map

package/dist/seo/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/seo/index.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAG7C,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAGvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAiBtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AAIpE,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAG5C,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAG/D,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAGrD,OAAO,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAGpF,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEnE,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAGjD,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAG9D,OAAO,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAC;AAG1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAGlD,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/seo/never-encode-filter.d.ts

@@ -0,0 +1,45 @@
+/**
+ * NeverEncodeFilter — pure, total, DROP-only runtime never-encode belt
+ * (spec-20260717-seo-improver-builder, Sprint 2; ADR-3). Third belt after
+ * parse-time drop (`parser.ts:111`, `policyClassRaw === "never-encode"`) and
+ * the skill-content lint (`skills-content.test.ts:26-33`). This belt catches
+ * an LLM-*synthesized* banned tactic at runtime — one that was never in a
+ * skill file, so belts 1/2 never see it — even when it carries a
+ * well-formed `citationUrl` that would otherwise sail through
+ * `SeoCitationGate` (`citation-gate.ts:66-90`).
+ *
+ * Pure and total, mirroring `SeoCitationGate.apply` exactly: imports ONLY
+ * `./types.js`. No LLM, no egress, no filesystem, no clock, no
+ * `Math.random`. Identical input always yields identical output; never
+ * throws. DROP-only (ADR-3 option table, nonGoal #1): unlike the citation
+ * gate, this filter does NOT compute a `blocked`/exit-2 flag — a single
+ * hallucinated phrase must not brick an otherwise-clean run.
+ */
+import type { SeoFinding } from "./types.js";
+export type NeverEncodeResult = {
+    /** Findings whose recommendation/evidence matches NO banned tactic — the ONLY findings passed downstream. */
+    kept: SeoFinding[];
+    /** Findings whose recommendation/evidence matches a banned never-encode tactic. */
+    dropped: SeoFinding[];
+};
+/**
+ * Single exported const so the parser floor (`retriever.ts:34-37`), the
+ * benchmark's test-local mirror (`benchmark/harness.ts:79-86`), and this
+ * filter share intent (generatorNotes). Case-insensitive, `\b`-anchored to
+ * avoid over-matching clean recommendations ("Fix duplicate title tags...",
+ * "Add a self-referencing canonical tag."). Covers all 8 sc-2-2 classes:
+ * parasite SEO, expired-domain, paid/bought links, PBN/link schemes, mass AI
+ * pages, cloaking, doorway pages, AI-recommendation poisoning. The first 6
+ * are the existing set (`skills-content.test.ts:26-33`); PBN/cloaking/
+ * doorway are new for this sprint.
+ */
+export declare const NEVER_ENCODE_PATTERNS: readonly RegExp[];
+export declare class NeverEncodeFilter {
+    /**
+     * Partitions `findings` into `kept`/`dropped` by banned-tactic text
+     * matching. Pure and total: identical input always yields identical
+     * output. DROP-only — never computes a block/exit-code signal (ADR-3).
+     */
+    apply(findings: SeoFinding[]): NeverEncodeResult;
+}
+//# sourceMappingURL=never-encode-filter.d.ts.map

package/dist/seo/never-encode-filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"never-encode-filter.d.ts","sourceRoot":"","sources":["../../src/seo/never-encode-filter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,MAAM,MAAM,iBAAiB,GAAG;IAC9B,6GAA6G;IAC7G,IAAI,EAAE,UAAU,EAAE,CAAC;IACnB,mFAAmF;IACnF,OAAO,EAAE,UAAU,EAAE,CAAC;CACvB,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB,EAAE,SAAS,MAAM,EAUlD,CAAC;AAWF,qBAAa,iBAAiB;IAC5B;;;;OAIG;IACH,KAAK,CAAC,QAAQ,EAAE,UAAU,EAAE,GAAG,iBAAiB;CAcjD"}

package/dist/seo/never-encode-filter.js

@@ -0,0 +1,51 @@
+/**
+ * Single exported const so the parser floor (`retriever.ts:34-37`), the
+ * benchmark's test-local mirror (`benchmark/harness.ts:79-86`), and this
+ * filter share intent (generatorNotes). Case-insensitive, `\b`-anchored to
+ * avoid over-matching clean recommendations ("Fix duplicate title tags...",
+ * "Add a self-referencing canonical tag."). Covers all 8 sc-2-2 classes:
+ * parasite SEO, expired-domain, paid/bought links, PBN/link schemes, mass AI
+ * pages, cloaking, doorway pages, AI-recommendation poisoning. The first 6
+ * are the existing set (`skills-content.test.ts:26-33`); PBN/cloaking/
+ * doorway are new for this sprint.
+ */
+export const NEVER_ENCODE_PATTERNS = [
+    /\bplace\b[^.]*\b(parasite|high-?authority host|third-?party host)/i, // parasite SEO
+    /\b(?:buy(?:ing)?|purchas(?:e|ing))\b[^.]*\blinks?\b/i, // paid/bought links
+    /\bregister(ing)?\b[^.]*\bexpired domain/i, // expired-domain
+    /\bgenerate\b[^.]*\bmass\b[^.]*\bpages\b/i, // mass AI pages
+    /\b(?:mass[-\s]?generat(?:e|ing)|generat(?:e|ing)[-\s]?mass)\b/i, // mass AI pages
+    /\bpoison/i, // AI-recommendation poisoning
+    /\b(?:private blog network|pbn|link scheme|link network|link farm)\b/i, // PBN / link schemes
+    /\bcloak(?:ing|ed)?\b/i, // cloaking
+    /\bdoorway\s+pages?\b/i, // doorway pages
+];
+/** Scans `recommendation` + all evidence fields (metric/value/source/url) for a banned tactic match. */
+function matchesBannedTactic(finding) {
+    const evidenceText = finding.evidence
+        .map((e) => `${e.metric} ${e.value} ${e.source} ${e.url}`)
+        .join(" ");
+    const text = `${finding.recommendation} ${evidenceText}`;
+    return NEVER_ENCODE_PATTERNS.some((pattern) => pattern.test(text));
+}
+export class NeverEncodeFilter {
+    /**
+     * Partitions `findings` into `kept`/`dropped` by banned-tactic text
+     * matching. Pure and total: identical input always yields identical
+     * output. DROP-only — never computes a block/exit-code signal (ADR-3).
+     */
+    apply(findings) {
+        const kept = [];
+        const dropped = [];
+        for (const finding of findings) {
+            if (matchesBannedTactic(finding)) {
+                dropped.push(finding);
+            }
+            else {
+                kept.push(finding);
+            }
+        }
+        return { kept, dropped };
+    }
+}
+//# sourceMappingURL=never-encode-filter.js.map

package/dist/seo/never-encode-filter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"never-encode-filter.js","sourceRoot":"","sources":["../../src/seo/never-encode-filter.ts"],"names":[],"mappings":"AA0BA;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAsB;IACtD,oEAAoE,EAAE,eAAe;IACrF,sDAAsD,EAAE,oBAAoB;IAC5E,0CAA0C,EAAE,iBAAiB;IAC7D,0CAA0C,EAAE,gBAAgB;IAC5D,gEAAgE,EAAE,gBAAgB;IAClF,WAAW,EAAE,8BAA8B;IAC3C,sEAAsE,EAAE,qBAAqB;IAC7F,uBAAuB,EAAE,WAAW;IACpC,uBAAuB,EAAE,gBAAgB;CAC1C,CAAC;AAEF,wGAAwG;AACxG,SAAS,mBAAmB,CAAC,OAAmB;IAC9C,MAAM,YAAY,GAAG,OAAO,CAAC,QAAQ;SAClC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,GAAG,EAAE,CAAC;SACzD,IAAI,CAAC,GAAG,CAAC,CAAC;IACb,MAAM,IAAI,GAAG,GAAG,OAAO,CAAC,cAAc,IAAI,YAAY,EAAE,CAAC;IACzD,OAAO,qBAAqB,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;AACrE,CAAC;AAED,MAAM,OAAO,iBAAiB;IAC5B;;;;OAIG;IACH,KAAK,CAAC,QAAsB;QAC1B,MAAM,IAAI,GAAiB,EAAE,CAAC;QAC9B,MAAM,OAAO,GAAiB,EAAE,CAAC;QAEjC,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;YAC/B,IAAI,mBAAmB,CAAC,OAAO,CAAC,EAAE,CAAC;gBACjC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACxB,CAAC;iBAAM,CAAC;gBACN,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACrB,CAAC;QACH,CAAC;QAED,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IAC3B,CAAC;CACF"}