@lynxflow/seo-engine 2.8.0 → 3.2.0

package/dist/product-usage-analytics.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Product-usage analytics for the module catalog.
+ *
+ * Turns raw module lifecycle events into the adoption figures an operator
+ * needs: who uses which module, where workflows fail and which catalog entries
+ * nobody opens. The analysis is pure and order-stable so the same export
+ * always produces the same report.
+ */
+export interface ProductUsageEvent {
+    moduleId: string;
+    eventName: "module_opened" | "module_completed" | "module_failed";
+    userId: string;
+    timestamp: string;
+    durationMs?: number;
+}
+export interface ModuleUsageSummary {
+    moduleId: string;
+    opens: number;
+    completions: number;
+    failures: number;
+    uniqueUsers: number;
+    completionRatePct: number;
+    failureRatePct: number;
+    medianDurationMs: number | null;
+    adoptionPct: number;
+}
+export interface ProductUsageReport {
+    totalEvents: number;
+    activeUsers: number;
+    modules: ModuleUsageSummary[];
+    unusedModuleIds: string[];
+    topModules: string[];
+    recommendations: string[];
+}
+/**
+ * Aggregates usage events for a catalog of modules.
+ *
+ * Events with an unparseable timestamp or an empty module/user identifier are
+ * ignored. Durations are only considered when they are finite and
+ * non-negative. Adoption is measured against every user observed in the
+ * period, while completion and failure rates are measured against opens.
+ */
+export declare function analyzeProductUsage(events: ProductUsageEvent[], catalogModuleIds: string[], options?: {
+    now?: Date;
+    staleDays?: number;
+}): ProductUsageReport;

package/dist/profiles/behavioral-cohort.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Behavioral Cohort & Dynamic Segment Engine — RudderStack & Segment Personas Parity
+ *
+ * Évalue l'appartenance d'un profil utilisateur à une cohorte comportementale dynamique :
+ * - Actions réalisées ("A effectué l'événement 'add_to_cart' >= 2 fois dans les 7 derniers jours").
+ * - Actions négatives ("N'a PAS effectué l'événement 'purchase' dans les 7 derniers jours").
+ * - Filtres sur les propriétés d'événements (ex: `value >= 100`).
+ * - Filtres sur les traits utilisateurs (ex: `plan == 'pro'`, `country == 'FR'`).
+ */
+export type PropertyFilterOperator = "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "contains" | "exists";
+export interface PropertyFilter {
+    property: string;
+    operator: PropertyFilterOperator;
+    value?: unknown;
+}
+export interface EventCondition {
+    eventName: string;
+    frequency?: {
+        min?: number;
+        max?: number;
+    };
+    withinDays?: number;
+    propertyFilters?: PropertyFilter[];
+}
+export interface BehavioralCohortDefinition {
+    id: string;
+    name: string;
+    description?: string;
+    traitFilters?: PropertyFilter[];
+    performedEvents?: EventCondition[];
+    notPerformedEvents?: EventCondition[];
+    /** 'all' = AND logifue entre tous les blocs, 'any' = OR logique */
+    matchType?: "all" | "any";
+}
+export interface HistoricalEvent {
+    name: string;
+    occurredAt: string | number;
+    properties?: Record<string, unknown>;
+}
+export interface BehavioralUserHistory {
+    userId: string;
+    traits?: Record<string, unknown>;
+    events: HistoricalEvent[];
+}
+export interface CohortEvaluationResult {
+    isMember: boolean;
+    matchedConditions: string[];
+    unmatchedConditions: string[];
+}
+export declare class BehavioralCohortEngine {
+    /**
+     * Évalue si un utilisateur correspond à la définition d'une cohorte comportementale.
+     */
+    static evaluateUser(cohort: BehavioralCohortDefinition, user: BehavioralUserHistory, referenceTime?: string | number): CohortEvaluationResult;
+    /**
+     * Filtre une liste d'utilisateurs et renvoie les identifiants de ceux qui font partie de la cohorte.
+     */
+    static filterCohort(cohort: BehavioralCohortDefinition, users: BehavioralUserHistory[], referenceTime?: string | number): string[];
+}

package/dist/profiles/customer-360.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Customer 360 Feature Store & Cohort Aggregator — RudderStack Profiles Parity
+ *
+ * Agrège les événements bruts d'un utilisateur pour calculer ses caractéristiques (features)
+ * comportementales, financières et de cycle de vie :
+ * 1. Métriques financières : Lifetime Value (LTV), nombre de commandes, Panier Moyen (AOV).
+ * 2. Segmentation RFM (Récence, Fréquence, Montant) et attribution de segments (Champions, Fidèles, À risque, Perdus).
+ * 3. Stades du cycle de vie client (prospect, lead, active_customer, at_risk, churned).
+ * 4. Détection du canal et du terminal préférés.
+ */
+export type LifecycleStage = "prospect" | "lead" | "new_customer" | "active_customer" | "at_risk" | "churned";
+export interface RfmAnalysis {
+    recencyDays: number;
+    recencyScore: number;
+    frequencyScore: number;
+    monetaryScore: number;
+    segment: "Champions" | "Loyal Customers" | "Potential Loyalists" | "New Customers" | "At Risk" | "Hibernating" | "Lost";
+}
+export interface Customer360Profile {
+    userId: string;
+    anonymousIds: string[];
+    firstSeenAt: string;
+    lastSeenAt: string;
+    totalEvents: number;
+    totalPageViews: number;
+    totalOrders: number;
+    lifetimeValue: number;
+    averageOrderValue: number;
+    preferredDevice: "desktop" | "mobile" | "tablet" | "unknown";
+    preferredChannel: string;
+    lifecycleStage: LifecycleStage;
+    rfm: RfmAnalysis;
+    traits: Record<string, unknown>;
+}
+export declare function computeRfmSegment(recencyDays: number, orderCount: number, monetaryTotal: number): RfmAnalysis;
+/**
+ * Calcule le profil 360° et le Feature Store d'un utilisateur à partir de sa chronologie d'événements.
+ */
+export declare function computeCustomer360Profile(userId: string, events: Array<Record<string, unknown>>, referenceDate?: Date): Customer360Profile;

package/dist/providers/firecrawl-provider.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 🕷️ Firecrawl Provider (Partner Extension)
+ * Interacts with Firecrawl API for modern LLM-ready markdown extraction and web scraping.
+ */
+export interface FirecrawlScrapeOptions {
+    formats?: ("markdown" | "html" | "rawHtml" | "screenshot")[];
+    onlyMainContent?: boolean;
+    waitFor?: number;
+    mobile?: boolean;
+}
+export interface FirecrawlScrapeResult {
+    success: boolean;
+    markdown?: string;
+    html?: string;
+    metadata?: {
+        title?: string;
+        description?: string;
+        statusCode?: number;
+        ogImage?: string;
+    };
+    error?: string;
+}
+export declare class FirecrawlProvider {
+    readonly name = "Firecrawl";
+    private apiKey;
+    private baseUrl;
+    constructor(apiKey?: string, baseUrl?: string);
+    isConfigured(): boolean;
+    scrapeUrl(url: string, options?: FirecrawlScrapeOptions): Promise<FirecrawlScrapeResult>;
+}

package/dist/providers/firecrawl.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 🕷️ Firecrawl Provider (Partner Extension G5)
+ * Injects Firecrawl scraping / markdown extraction behind the SearchProvider interface.
+ * API key is optional and private: when missing, every call returns a typed
+ * empty result instead of throwing at runtime.
+ */
+import type { SearchProvider } from "./search-provider";
+export interface FirecrawlScrapeOptions {
+    formats?: ("markdown" | "html" | "rawHtml" | "screenshot")[];
+    onlyMainContent?: boolean;
+    waitFor?: number;
+    mobile?: boolean;
+}
+export interface FirecrawlScrapeResult {
+    success: boolean;
+    markdown?: string;
+    html?: string;
+    metadata?: {
+        title?: string;
+        description?: string;
+        statusCode?: number;
+        ogImage?: string;
+    };
+    error?: string;
+}
+export declare class FirecrawlProvider implements SearchProvider {
+    readonly name = "Firecrawl";
+    private apiKey;
+    private baseUrl;
+    constructor(apiKey?: string, baseUrl?: string);
+    isConfigured(): boolean;
+    scrapeUrl(url: string, options?: FirecrawlScrapeOptions): Promise<FirecrawlScrapeResult>;
+}

package/dist/providers/profound-provider.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 🔮 Profound Provider (Partner Extension)
+ * Integrates Profound API for tracking brand citations & share of voice across AI engines
+ * (ChatGPT Search, Perplexity, Google Gemini, Claude, Copilot).
+ */
+export interface ProfoundCitationMetric {
+    engine: "chatgpt" | "perplexity" | "gemini" | "claude" | "copilot";
+    shareOfVoicePct: number;
+    totalCitations: number;
+    sentimentScore: number;
+    topCitedUrls: string[];
+}
+export interface ProfoundBrandVisibilityResult {
+    brand: string;
+    domain: string;
+    averageAiVisibilityScore: number;
+    engines: ProfoundCitationMetric[];
+    isConfigured: boolean;
+    error?: string;
+}
+export declare class ProfoundProvider {
+    readonly name = "Profound";
+    private apiKey;
+    private baseUrl;
+    constructor(apiKey?: string, baseUrl?: string);
+    isConfigured(): boolean;
+    getBrandAiVisibility(brand: string, domain: string): Promise<ProfoundBrandVisibilityResult>;
+}

package/dist/providers/profound.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 🔮 Profound Provider (Partner Extension G5)
+ * Injects Profound AI-visibility / brand citation tracking behind the SearchProvider interface.
+ * API key is optional and private: when missing, every call returns a typed
+ * empty result instead of throwing at runtime.
+ */
+import type { SearchProvider } from "./search-provider";
+export interface ProfoundCitationMetric {
+    engine: "chatgpt" | "perplexity" | "gemini" | "claude" | "copilot";
+    shareOfVoicePct: number;
+    totalCitations: number;
+    sentimentScore: number;
+    topCitedUrls: string[];
+}
+export interface ProfoundBrandVisibilityResult {
+    brand: string;
+    domain: string;
+    averageAiVisibilityScore: number;
+    engines: ProfoundCitationMetric[];
+    isConfigured: boolean;
+    error?: string;
+}
+export declare class ProfoundProvider implements SearchProvider {
+    readonly name = "Profound";
+    private apiKey;
+    private baseUrl;
+    constructor(apiKey?: string, baseUrl?: string);
+    isConfigured(): boolean;
+    getBrandAiVisibility(brand: string, domain: string): Promise<ProfoundBrandVisibilityResult>;
+}

package/dist/providers/search-provider.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 🔌 Generic injectable provider interface for LynxSEO partner extensions.
+ * Every partner provider (SE Ranking, Firecrawl, Profound, ...) implements
+ * this contract so the engine can swap/mock them without knowing the API.
+ */
+export interface SearchProvider {
+    readonly name: string;
+    isConfigured(): boolean;
+}

package/dist/providers/seranking-provider.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 👑 SE Ranking Provider (Partner Extension)
+ * Integrates SE Ranking API for SERP position tracking and competitor ranking data.
+ */
+export interface SeRankingKeywordPosition {
+    keyword: string;
+    position: number;
+    previousPosition: number;
+    searchVolume: number;
+    cpc: number;
+    landingPageUrl: string;
+}
+export interface SeRankingSitePositionsResult {
+    siteId: string;
+    totalKeywords: number;
+    top3Count: number;
+    top10Count: number;
+    keywords: SeRankingKeywordPosition[];
+    isConfigured: boolean;
+    error?: string;
+}
+export declare class SeRankingProvider {
+    readonly name = "SERanking";
+    private apiKey;
+    private baseUrl;
+    constructor(apiKey?: string, baseUrl?: string);
+    isConfigured(): boolean;
+    getKeywordPositions(siteId: string): Promise<SeRankingSitePositionsResult>;
+}

package/dist/providers/seranking.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 👑 SE Ranking Provider (Partner Extension G5)
+ * Injects SE Ranking SERP position tracking behind the SearchProvider interface.
+ * API key is optional and private: when missing, every call returns a typed
+ * empty result instead of throwing at runtime.
+ */
+import type { SearchProvider } from "./search-provider";
+export interface SeRankingKeywordPosition {
+    keyword: string;
+    position: number;
+    previousPosition: number;
+    searchVolume: number;
+    cpc: number;
+    landingPageUrl: string;
+}
+export interface SeRankingSitePositionsResult {
+    siteId: string;
+    totalKeywords: number;
+    top3Count: number;
+    top10Count: number;
+    keywords: SeRankingKeywordPosition[];
+    isConfigured: boolean;
+    error?: string;
+}
+export declare class SeRankingProvider implements SearchProvider {
+    readonly name = "SERanking";
+    private apiKey;
+    private baseUrl;
+    constructor(apiKey?: string, baseUrl?: string);
+    isConfigured(): boolean;
+    getKeywordPositions(siteId: string): Promise<SeRankingSitePositionsResult>;
+}

package/dist/pseo-cli.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env bun
+/**
+ * 🚀 LynxSEO pSEO Agentic CLI
+ *
+ * Commands:
+ *   generate   Generates an entire pSEO cluster from datasets
+ *   preflight  Audits generated pages for thin content & broken internal link graphs
+ */
+export declare function runCli(args?: string[]): Promise<import("./cluster-generator").ClusterGenerationResult | import("./pseo-preflight-gate").PreflightReport | undefined>;

package/dist/pseo-feasibility-scorer.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 🎯 pSEO Dataset Feasibility Scorer
+ *
+ * Evaluates whether a structured dataset is genuinely viable for programmatic SEO
+ * before generating hundreds or thousands of pages.
+ *
+ * Prevents penalty-bait, thin content, and Google Scaled Content Abuse.
+ */
+export interface DatasetFieldDef {
+    name: string;
+    type: "string" | "number" | "boolean" | "array" | "object";
+    isComputed?: boolean;
+    isProprietary?: boolean;
+    fillRatePct: number;
+}
+export interface PseoDatasetEvaluationInput {
+    datasetName: string;
+    totalRecords: number;
+    fields: DatasetFieldDef[];
+    intentType: "transactional" | "commercial_investigation" | "informational_utility" | "generic_definitional";
+    updateFrequencyDays?: number;
+    hasFirstPartyData?: boolean;
+}
+export interface PseoFeasibilityReport {
+    feasibilityScore: number;
+    verdict: "READY_FOR_SCALE" | "NEEDS_ENRICHMENT" | "REJECT_PENALTY_RISK";
+    depthGrade: "Deep (20+ fields)" | "Competent (15-19 fields)" | "Marginal (10-14 fields)" | "Thin (<10 fields)";
+    metrics: {
+        totalFieldsCount: number;
+        denseFieldsCount: number;
+        computedFieldsCount: number;
+        proprietarySignalsScore: number;
+        intentSuitabilityScore: number;
+    };
+    passedGates: string[];
+    blockingGaps: string[];
+    actionableRecommendations: string[];
+}
+export declare class PseoFeasibilityScorer {
+    /**
+     * Evaluates a dataset structure and assigns a viability score.
+     */
+    static evaluate(input: PseoDatasetEvaluationInput): PseoFeasibilityReport;
+}

package/dist/pseo-geo-citability-booster.d.ts

@@ -0,0 +1,75 @@
+/**
+ * 🚀 pSEO GEO Citability Booster
+ *
+ * Transforms raw programmatic SEO rows and templates into high-citability pages
+ * engineered specifically to dominate AI answer engines (ChatGPT Search, Perplexity,
+ * Claude 3.7, Google AI Overviews).
+ *
+ * Implements the empirical findings from Princeton KDD 2024:
+ * 1. Answer-First Architecture: 40-60 word definitive factual synthesis immediately post-H2 (+37% visibility).
+ * 2. High Statistical Density: Structured numerical comparisons, ranges, percentages (+41% retrieval priority).
+ * 3. Authoritative Source Grounding: Explicit attribution to verified external bodies (+28% selection rate).
+ * 4. RAG Chunk Optimization: High-entropy key takeaways table formatted for LLM chunk extractors.
+ */
+import { type CitabilityScoreResult } from "./geo-citability-scorer";
+export interface PseoRowData {
+    primaryKeyword: string;
+    category?: string;
+    entityName?: string;
+    competitorOrLocation?: string;
+    metrics?: Record<string, string | number>;
+    pricing?: string | number;
+    rating?: number;
+    reviewCount?: number;
+    features?: string[];
+    attributes?: Record<string, string>;
+}
+export interface BoostedPseoContent {
+    answerFirstBlock: {
+        heading: string;
+        text: string;
+        wordCount: number;
+        markdown: string;
+    };
+    keyStatisticsTable: {
+        headers: string[];
+        rows: Array<[string, string]>;
+        markdown: string;
+    };
+    authoritativeGrounding: {
+        citations: Array<{
+            sourceName: string;
+            url?: string;
+            anchorText: string;
+        }>;
+        markdown: string;
+    };
+    fullEnrichedSectionMarkdown: string;
+    citabilityAudit: CitabilityScoreResult;
+    isSafeFromHallucinationBait: boolean;
+    recommendations: string[];
+}
+export declare class PseoGeoCitabilityBooster {
+    /**
+     * Generates a Princeton KDD-compliant Answer-First block for any programmatic row.
+     */
+    static generateAnswerFirstBlock(row: PseoRowData, language?: "fr" | "en"): {
+        heading: string;
+        text: string;
+        wordCount: number;
+        markdown: string;
+    };
+    /**
+     * Generates a high-entropy structured statistics table for RAG extractors.
+     */
+    static generateStatisticsTable(row: PseoRowData, language?: "fr" | "en"): {
+        headers: string[];
+        rows: Array<[string, string]>;
+        markdown: string;
+    };
+    /**
+     * Boosts an entire programmatic record into a complete GEO Citability module.
+     */
+    static boostPseoRow(row: PseoRowData, language?: "fr" | "en"): BoostedPseoContent;
+    static boostPage(row: PseoRowData, language?: "fr" | "en"): BoostedPseoContent;
+}

package/dist/pseo-preflight-gate.d.ts

@@ -0,0 +1,73 @@
+/**
+ * 🛡️ pSEO Preflight Quality Gate & Link-Graph Validator
+ *
+ * Automates pre-publication verification across all generated pSEO documents:
+ * 1. Thin Content Detection (minimum word count check)
+ * 2. Strict 5-FAQ Schema.org Validation
+ * 3. Orphan Page & Broken Internal-Link Graph Detection
+ * 4. Slug Collision & Canonical Integrity Check
+ * 5. NAP Consistency Check (Name, Address, Phone must match)
+ */
+import { ProgrammaticPageDocument } from "./persistent-page-store";
+import { type PseoPageVolume, type IndexabilityGateResult, type IndexabilityGateOptions } from "./real-volume-indexability-gate";
+export interface PreflightIssue {
+    slug: string;
+    severity: "critical" | "warning" | "info";
+    rule: string;
+    message: string;
+}
+export interface PreflightReport {
+    passed: boolean;
+    totalPages: number;
+    criticalIssuesCount: number;
+    warningIssuesCount: number;
+    issues: PreflightIssue[];
+    metrics: {
+        averageWordCount: number;
+        minWordCount: number;
+        maxWordCount: number;
+        internalLinksVerified: number;
+        orphanPagesDetected: number;
+    };
+}
+export declare class PseoPreflightGate {
+    private minWordCount;
+    constructor(options?: {
+        minWordCount?: number;
+    });
+    /**
+     * Runs the complete preflight quality audit over a collection of generated pages
+     */
+    validateCluster(pages: ProgrammaticPageDocument[]): PreflightReport;
+    /**
+     * Evaluates indexability of generated pages based on search volume to optimize
+     * Googlebot crawl budget for very large page architectures.
+     * High-volume pages are indexed and submitted to sitemaps; zero/low-volume pages
+     * receive 'noindex, follow' to protect crawl budget while preserving internal linking.
+     */
+    static evaluateCrawlBudget(pages: Array<{
+        slug: string;
+        searchVolume?: number;
+    }>, minVolumeThreshold?: number): CrawlBudgetReport;
+    /**
+     * Delegates to RealVolumeIndexabilityGate for advanced crawl budget protection
+     * with custom directives, volume thresholds, and summary analytics.
+     */
+    static evaluateRealVolumeGate(pages: PseoPageVolume[], options?: IndexabilityGateOptions): IndexabilityGateResult;
+}
+export interface PreflightIndexabilityDecision {
+    slug: string;
+    searchVolume: number;
+    robotsDirective: "index, follow" | "noindex, follow";
+    includeInSitemap: boolean;
+    priority: number;
+    reason: string;
+}
+export interface CrawlBudgetReport {
+    totalPagesEvaluated: number;
+    indexedPagesCount: number;
+    noindexedPagesCount: number;
+    crawlBudgetReductionPct: number;
+    decisions: PreflightIndexabilityDecision[];
+    sitemapEligibleSlugs: string[];
+}

package/dist/pseo-publisher-bridge.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 🚀 Programmatic SEO Multi-Destination Publishing Bridge
+ *
+ * Allows 1-click publishing of programmatic SEO landing page batches to:
+ * - WordPress REST API
+ * - Cloudflare Pages / Static Markdown bundles (Frontmatter + Markdown)
+ * - Webhook dispatch (n8n, Make, Zapier, custom Edge Workers)
+ */
+export interface PseoPagePayload {
+    slug: string;
+    title: string;
+    htmlContent: string;
+    markdownContent?: string;
+    metaDescription?: string;
+    canonicalUrl?: string;
+    keywords?: string[];
+    schemaJsonLd?: Record<string, unknown>;
+    author?: string;
+    publishedAt?: string;
+}
+export interface WordPressPublishTarget {
+    type: "wordpress";
+    apiUrl: string;
+    username: string;
+    appPassword: string;
+    postType?: "pages" | "posts";
+    status?: "publish" | "draft";
+}
+export interface WebhookPublishTarget {
+    type: "webhook";
+    webhookUrl: string;
+    secretToken?: string;
+}
+export interface StaticExportPublishTarget {
+    type: "static_bundle";
+    format?: "markdown_frontmatter" | "json_ndjson";
+}
+export type PseoPublishTarget = WordPressPublishTarget | WebhookPublishTarget | StaticExportPublishTarget;
+export interface PublishResultItem {
+    slug: string;
+    success: boolean;
+    publishedUrl?: string;
+    error?: string;
+}
+export interface PublishBatchSummary {
+    total: number;
+    succeeded: number;
+    failed: number;
+    results: PublishResultItem[];
+}
+export declare class PseoPublisherBridge {
+    /**
+     * Publishes a batch of programmatic SEO pages to the specified target.
+     */
+    static publishBatch(pages: PseoPagePayload[], target: PseoPublishTarget): Promise<PublishBatchSummary>;
+    private static publishToStaticBundle;
+    private static publishToWebhook;
+    private static publishToWordPress;
+}

package/dist/pseo-quality-circuit-breaker.d.ts

@@ -0,0 +1,60 @@
+/**
+ * ⚡ pSEO Quality Gate & Canary Circuit Breaker (The 5% Failure Threshold Rule)
+ *
+ * Enforces strict pre-flight sampling before batch publishing:
+ * 1. Stratified Sampling: selects a representative sample across dense, median, and sparse rows.
+ * 2. Multi-Axis Automated Auditing: Information Gain Scorer + Technical SEO Rules Auditor.
+ * 3. 5% Circuit Breaker: If > 5% of sampled pages fail, HALT generation & deployment immediately.
+ */
+import { type InformationGainResult } from "./information-gain-scorer";
+import { type PageAuditInput, type TechnicalIssue } from "./technical-rules-auditor";
+import { type CitabilityScoreResult } from "./geo-citability-scorer";
+import { type GoogleAiReadinessResult } from "./google-ai-readiness-auditor";
+export interface PseoSampleRecord {
+    id: string;
+    path: string;
+    renderedMarkdown: string;
+    auditInput: PageAuditInput;
+    fieldsPopulatedCount: number;
+    renderedHtml?: string;
+    headers?: Record<string, string>;
+    robotsTxt?: string;
+}
+export interface SampleAuditResult {
+    recordId: string;
+    path: string;
+    passed: boolean;
+    informationGain: InformationGainResult;
+    geoCitability: CitabilityScoreResult;
+    isSafeFromHallucinationBait: boolean;
+    technicalIssues: TechnicalIssue[];
+    googleAiReadiness?: GoogleAiReadinessResult;
+    rejectionReasons: string[];
+}
+export interface CircuitBreakerReport {
+    totalMatrixSize: number;
+    sampleSize: number;
+    failureRatePct: number;
+    circuitBreakerTripped: boolean;
+    verdict: "DEPLOYMENT_APPROVED" | "CIRCUIT_BREAKER_HALTED";
+    passedCount: number;
+    failedCount: number;
+    averageGeoCitabilityScore: number;
+    sampleResults: SampleAuditResult[];
+    blockingRootCauses: string[];
+    recommendation: string;
+}
+export declare class PseoQualityCircuitBreaker {
+    static readonly FAILURE_THRESHOLD_PCT = 5;
+    /**
+     * Extracts a stratified sample from a dataset (default 10 prototype records).
+     * Balances across dense (most populated), median, and sparse records.
+     */
+    static extractStratifiedSample<T extends {
+        fieldsPopulatedCount: number;
+    }>(records: T[], sampleSize?: number): T[];
+    /**
+     * Runs the 5% Circuit Breaker audit on an extracted batch of prototype pages.
+     */
+    static runCircuitBreaker(samples: PseoSampleRecord[], totalMatrixSize?: number): CircuitBreakerReport;
+}