@lynxflow/seo-engine 2.8.0 → 3.2.0

package/dist/analytics/batch-export-scheduler.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Batch Export Scheduler & Formatter
+ * Clean-room implementation inspired by enterprise analytics pipelines (PostHog / Snowflake / BigQuery / S3 / GCS).
+ * Provides window planning, interval chunking, NDJSON / CSV serialization, partition path generation,
+ * and delivery job manifests with retry scheduling.
+ */
+export type SchedulerExportDestinationType = 's3' | 'gcs' | 'bigquery' | 'snowflake' | 'webhook';
+export type SchedulerExportFormat = 'ndjson' | 'csv' | 'json';
+export type SchedulerExportInterval = 'hourly' | 'daily' | 'every_6_hours' | 'every_12_hours';
+export interface SchedulerExportConfig {
+    id: string;
+    name: string;
+    destination: SchedulerExportDestinationType;
+    format: SchedulerExportFormat;
+    interval: SchedulerExportInterval;
+    destinationConfig: {
+        bucket?: string;
+        prefix?: string;
+        datasetId?: string;
+        tableId?: string;
+        endpointUrl?: string;
+        headers?: Record<string, string>;
+    };
+    compression?: 'gzip' | 'none';
+    includeMetadata?: boolean;
+    maxRetries?: number;
+}
+export interface ExportTimeWindow {
+    windowStart: string;
+    windowEnd: string;
+    partitionPath: string;
+    sequenceNumber: number;
+}
+export interface BatchExportJobManifest {
+    jobId: string;
+    exportConfigId: string;
+    window: ExportTimeWindow;
+    recordCount: number;
+    uncompressedBytes: number;
+    formattedOutput: string;
+    status: 'pending' | 'processing' | 'completed' | 'failed';
+    attempts: number;
+    nextRetryAt?: string;
+    error?: string;
+}
+export interface AnalyticsRecord {
+    id: string;
+    eventName: string;
+    timestamp: string;
+    distinctId: string;
+    properties: Record<string, unknown>;
+    ip?: string;
+    url?: string;
+}
+export declare class BatchExportScheduler {
+    private config;
+    constructor(config: SchedulerExportConfig);
+    /**
+     * Calculates scheduled export windows between two timestamps.
+     */
+    planWindows(startDate: Date, endDate: Date): ExportTimeWindow[];
+    /**
+     * Generates partition path based on date and config (e.g. year=2026/month=10/day=25/hour=14/export_001.ndjson)
+     */
+    generatePartitionPath(date: Date, sequence: number): string;
+    /**
+     * Formats records into NDJSON, CSV, or JSON array according to configuration.
+     */
+    formatRecords(records: AnalyticsRecord[]): {
+        formatted: string;
+        bytes: number;
+    };
+    /**
+     * Creates a batch job manifest ready for execution.
+     */
+    createJobManifest(window: ExportTimeWindow, records: AnalyticsRecord[]): BatchExportJobManifest;
+    /**
+     * Calculates next retry timestamp using exponential backoff with jitter.
+     */
+    calculateNextRetry(attempt: number, baseDelaySec?: number): string;
+    private getIntervalStepMs;
+}

package/dist/analytics/behavioral-cohort-analyzer.d.ts

@@ -0,0 +1,68 @@
+/**
+ * BehavioralCohortAnalyzer — Analyse de cohortes comportementales réelles & matrice de rétention (Parité PostHog / Mixpanel).
+ *
+ * Calcule la rétention réelle semaine par semaine ou jour par jour à partir des flux d'événements :
+ * - Inception de la cohorte (semaine/jour de première interaction ou d'action spécifique)
+ * - Critères d'inclusion comportementaux (a réalisé X, n'a pas réalisé Y, propriétés utilisateur)
+ * - Matrice de rétention triangulaire (Période 0 à Période N)
+ * - Taux d'attrition (churn rate) et durée de vie médiane observée
+ */
+export interface CohortCondition {
+    type: 'performed_event' | 'not_performed_event' | 'user_property';
+    eventName?: string;
+    minCount?: number;
+    timeWindowDays?: number;
+    propertyKey?: string;
+    propertyOperator?: 'equals' | 'contains' | 'gt' | 'lt' | 'exists';
+    propertyValue?: unknown;
+}
+export interface BehavioralCohortRetentionDefinition {
+    id: string;
+    name: string;
+    description?: string;
+    targetEvent?: string;
+    interval: 'day' | 'week' | 'month';
+    maxIntervals: number;
+    conditions: CohortCondition[];
+}
+export interface UserEventInput {
+    userId: string;
+    name: string;
+    timestamp: number | string;
+    properties?: Record<string, unknown>;
+    userProperties?: Record<string, unknown>;
+}
+export interface CohortIntervalStats {
+    intervalIndex: number;
+    intervalLabel: string;
+    activeUsers: number;
+    retentionPct: number;
+}
+export interface CohortRetentionRow {
+    cohortKey: string;
+    cohortStartDate: string;
+    cohortSize: number;
+    intervals: CohortIntervalStats[];
+}
+export interface BehavioralCohortAnalysisResult {
+    cohortId: string;
+    cohortName: string;
+    totalQualifiedUsers: number;
+    intervalType: 'day' | 'week' | 'month';
+    cohortRows: CohortRetentionRow[];
+    averageRetentionByInterval: number[];
+    overallChurnRatePct: number;
+    averageActiveLifespanIntervals: number;
+}
+export declare class BehavioralCohortAnalyzer {
+    /**
+     * Analyse les événements réels pour produire la matrice de rétention exacte.
+     */
+    static analyze(definition: BehavioralCohortRetentionDefinition, events: UserEventInput[], options?: {
+        referenceDate?: Date;
+    }): BehavioralCohortAnalysisResult;
+    private static matchesConditions;
+    private static resolveCohortMeta;
+    private static getIntervalDurationMs;
+    private static getIntervalLabel;
+}

package/dist/analytics/bofu-quick-wins-opportunity-scorer.d.ts

@@ -0,0 +1,60 @@
+/**
+ * @license AGPL-3.0-or-later
+ * LynxSEO - BofuQuickWinsOpportunityScorer
+ *
+ * Repris et adapté sous licence AGPL-3.0-or-later depuis:
+ * - inspiration/02-seo-pages-et-pseo/repos/seomachine (seo_bofu_rankings.py & research_quick_wins.py)
+ *
+ * Fonctionnalités :
+ * 1. Détection des Quick Wins SEO : mots-clés à portée de tir (Positions #4-#10 et Page 2 #11-#20).
+ * 2. Classification sémantique de l'intention dans l'entonnoir (BOFU, MOFU, TOFU).
+ * 3. Calcul du score d'opportunité d'impact commercial (Volume × Multiplicateur Intent ÷ Difficulté).
+ * 4. Estimation du gain de trafic mensuel potentiel lors d'un passage en Top 3.
+ * 5. Recommandations tactiques prescriptives par mot-clé (Maillage, Balises, Schema.org, Tableau comparatif).
+ */
+export type FunnelIntentStage = "bofu" | "mofu" | "tofu";
+export type StrikingDistanceTier = "top_10_striking" | "page_2_quick_win" | "long_tail_opportunity";
+export interface KeywordRankingInput {
+    keyword: string;
+    currentPosition: number;
+    searchVolume: number;
+    keywordDifficulty: number;
+    targetUrl: string;
+    currentCpcEur?: number;
+    hasSerpFeatures?: string[];
+}
+export interface ScoredQuickWinOpportunity {
+    keyword: string;
+    currentPosition: number;
+    searchVolume: number;
+    keywordDifficulty: number;
+    targetUrl: string;
+    funnelStage: FunnelIntentStage;
+    tier: StrikingDistanceTier;
+    opportunityScore: number;
+    estimatedMonthlyTrafficGain: number;
+    prescriptiveActions: string[];
+}
+export interface QuickWinsOpportunitySummary {
+    totalAnalyzed: number;
+    bofuCount: number;
+    mofuCount: number;
+    tofuCount: number;
+    strikingDistanceCount: number;
+    pageTwoQuickWinsCount: number;
+    potentialTrafficGainSum: number;
+    topOpportunities: ScoredQuickWinOpportunity[];
+}
+export declare class BofuQuickWinsOpportunityScorer {
+    private static readonly BOFU_REGEX;
+    private static readonly MOFU_REGEX;
+    /**
+     * Identifie l'étape du funnel en fonction des tokens du mot-clé.
+     */
+    static classifyIntent(keyword: string): FunnelIntentStage;
+    /**
+     * Analyse une liste de mots-clés et classe les opportunités par ordre d'impact décroissant.
+     */
+    static scoreOpportunities(keywords: KeywordRankingInput[]): QuickWinsOpportunitySummary;
+    private static formulateActions;
+}

package/dist/analytics/bot-crawl-frequency-predictor.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 🤖 Bot Crawl Frequency & Revisit Predictor
+ * Clean-room implementation inspired by Botify Log Analyzer & OnCrawl Crawl Frequency.
+ *
+ * Ingests search engine bot crawl hits, measures crawl intervals and velocity,
+ * flags crawl abandonment on high-priority pages, and detects indexing recency lag after content updates.
+ *
+ * @license AGPL-3.0-or-later
+ */
+export interface BotCrawlHit {
+    url: string;
+    botType: "googlebot" | "bingbot" | "other";
+    timestamp: number;
+    statusCode: number;
+    bytesTransferred?: number;
+}
+export interface PageCrawlMetadata {
+    url: string;
+    lastmod?: number;
+    internalPageRank?: number;
+    monthlyOrganicTraffic?: number;
+    isIndexable?: boolean;
+}
+export interface UrlCrawlProfile {
+    url: string;
+    totalHits: number;
+    googlebotHits: number;
+    bingbotHits: number;
+    firstSeenTimestamp: number;
+    lastSeenTimestamp: number;
+    daysSinceLastCrawl: number;
+    averageIntervalDays: number;
+    hitsPerWeek: number;
+    hasRecencyLag: boolean;
+    lagDays: number;
+    status: "healthy_crawl" | "abandoned" | "over_crawled_stale" | "unseen";
+}
+export interface BotCrawlReport {
+    totalHitsAnalyzed: number;
+    uniqueUrlsCrawled: number;
+    totalCatalogSize: number;
+    botCoverageRatio7d: number;
+    botCoverageRatio30d: number;
+    averageSiteCrawlIntervalDays: number;
+    abandonedHighPriorityPages: UrlCrawlProfile[];
+    recencyLagPages: UrlCrawlProfile[];
+    overCrawledStalePages: UrlCrawlProfile[];
+    topCrawledUrls: UrlCrawlProfile[];
+    summary: {
+        healthGrade: "A" | "B" | "C" | "D" | "F";
+        actionableAdvice: string[];
+    };
+}
+export declare class BotCrawlFrequencyPredictor {
+    private static readonly ONE_DAY_MS;
+    /**
+     * Evaluates bot crawl logs against catalog metadata.
+     */
+    static analyze(hits: BotCrawlHit[], catalog: PageCrawlMetadata[], currentTimestamp?: number): BotCrawlReport;
+    private static emptyReport;
+}

package/dist/analytics/bot-signal-bitmask-decoder.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Bot Signal Bitmask Decoder & Conviction Engine
+ * Clean-room implementation of compact telemetry bitmask decoding,
+ * server-side corroboration, and headless crawler detection.
+ * Inspired by modern anti-scraping telemetry standards.
+ */
+export declare const CLIENT_BOT_SIGNAL_MASKS: {
+    readonly automationApi: number;
+    readonly zeroOuterDimensions: number;
+    readonly missingChrome: number;
+    readonly swiftShader: number;
+    readonly emptyPlugins: number;
+    readonly defaultViewport800x600: number;
+    readonly defaultViewport1024x768: number;
+    readonly impossibleDimensions: number;
+    readonly outerDimensionsWeird: number;
+    readonly pluginApiAbsence: number;
+    readonly defaultViewport1280x1200: number;
+    readonly squareScreen: number;
+    readonly missingScreenDimensions: number;
+};
+export type ClientBotSignalName = keyof typeof CLIENT_BOT_SIGNAL_MASKS;
+export declare const CLIENT_BOT_SIGNAL_NAMES: ClientBotSignalName[];
+export declare const CLIENT_BOT_SIGNAL_WEIGHTS: Record<ClientBotSignalName, number>;
+export declare const STRONG_CLIENT_BOT_SIGNAL_BITS: number;
+export declare const ALL_CLIENT_BOT_SIGNAL_BITS: number;
+export declare const MIN_PLAUSIBLE_SCREEN_DIMENSION = 200;
+export declare const MAX_PLAUSIBLE_SCREEN_DIMENSION = 8192;
+export interface BotSignalEvaluationInput {
+    bitmask: number;
+    reportedScore?: number;
+    screenWidth?: number;
+    screenHeight?: number;
+    userAgent?: string;
+    isNativeApp?: boolean;
+}
+export interface BotConvictionVerdict {
+    isConvictedBot: boolean;
+    convictionReason?: string;
+    recomputedScore: number;
+    clientScore: number;
+    decodedSignals: ClientBotSignalName[];
+    strongSignals: ClientBotSignalName[];
+    corroboratingSignals: ClientBotSignalName[];
+    confidence: "none" | "low" | "medium" | "high" | "definitive";
+}
+export declare class BotSignalBitmaskDecoder {
+    /**
+     * Decomposes a raw bitmask into human-readable signal names.
+     */
+    static decodeMask(mask: number): ClientBotSignalName[];
+    /**
+     * Reconstructs the integer bitmask from an array of signal names.
+     */
+    static encodeSignals(signals: ClientBotSignalName[]): number;
+    /**
+     * Evaluates client signals + server environment to produce a definitive verdict.
+     */
+    static evaluateVerdict(input: BotSignalEvaluationInput): BotConvictionVerdict;
+}

package/dist/analytics/bot-simulation-diff-auditor.d.ts

@@ -0,0 +1,59 @@
+/**
+ * BotSimulationDiffAuditor — Audit Différentiel Multi User-Agent & Détecteur de Cloaking
+ *
+ * Parité : Screaming Frog (User-Agent Switcher & Compare Mode) & OnCrawl (Bot Simulation).
+ *
+ * Simule et compare les réponses HTTP pour une même URL sous 3 profils d'User-Agent :
+ * 1. Googlebot Smartphone (Crawler principal de Google - Mobile First)
+ * 2. Googlebot Desktop
+ * 3. Navigateur Humain Standard (Chrome Desktop)
+ *
+ * Détecte les anomalies de délivrance et risques de pénalité algorithmique :
+ * - Cloaking intentionnel ou accidentel (contenu radicalement différent servi aux bots vs humains).
+ * - Code de statut HTTP divergent (ex: 200 OK pour l'humain mais 403/503/404 pour Googlebot dû au CDN ou pare-feu WAF).
+ * - En-tête X-Robots-Tag divergent (ex: 'noindex' injecté uniquement pour Googlebot).
+ * - Redirection discriminatoire (ex: bot redirigé vers la page d'accueil ou paywall).
+ * - Disparité de contenu Mobile-First (liens ou texte manquants sur la version smartphone).
+ *
+ * Implémentation Clean-Room sous licence AGPL-3.0.
+ */
+export interface UaHttpResponse {
+    statusCode: number;
+    headers: Record<string, string>;
+    finalUrl: string;
+    bodyLength: number;
+    wordCount: number;
+    title?: string | null;
+    metaRobots?: string | null;
+    xRobotsTag?: string | null;
+}
+export interface BotSimulationInput {
+    url: string;
+    googlebotSmartphone: UaHttpResponse;
+    googlebotDesktop: UaHttpResponse;
+    humanChrome: UaHttpResponse;
+}
+export type DisparitySeverity = "low" | "medium" | "high" | "critical";
+export interface DisparityIssue {
+    type: "status_code_mismatch" | "redirect_mismatch" | "x_robots_tag_mismatch" | "meta_robots_mismatch" | "content_length_divergence" | "mobile_first_disparity" | "cloaking_suspected";
+    severity: DisparitySeverity;
+    message: string;
+    recommendation: string;
+}
+export interface BotSimulationReport {
+    url: string;
+    cloakingRiskScore: number;
+    isCloakingSuspected: boolean;
+    statusComparison: {
+        googlebotSmartphone: number;
+        googlebotDesktop: number;
+        humanChrome: number;
+    };
+    hasWafBotBlock: boolean;
+    hasMobileFirstDisparity: boolean;
+    issues: DisparityIssue[];
+    generatedAt: string;
+}
+export declare class BotSimulationDiffAuditor {
+    audit(input: BotSimulationInput): BotSimulationReport;
+}

package/dist/analytics/breadcrumb-list-microdata-schema-parity-validator.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @license AGPL-3.0-or-later
+ * LynxSEO - BreadcrumbListMicrodataSchemaParityValidator
+ * Validates structural and content parity between visible HTML breadcrumbs
+ * and Schema.org BreadcrumbList structured data for Google SERP snippet enhancement.
+ */
+export interface BreadcrumbItem {
+    position: number;
+    name: string;
+    url?: string;
+}
+export interface BreadcrumbParityInput {
+    htmlTrail?: BreadcrumbItem[];
+    schemaTrail?: BreadcrumbItem[];
+    htmlString?: string;
+    jsonLdScript?: string | object;
+}
+export interface BreadcrumbMismatch {
+    position: number;
+    type: "missing_in_schema" | "missing_in_html" | "name_mismatch" | "url_mismatch" | "invalid_position_index" | "missing_item_url";
+    severity: "critical" | "warning";
+    description: string;
+    htmlValue?: string;
+    schemaValue?: string;
+}
+export interface BreadcrumbParityReport {
+    isParityValid: boolean;
+    score: number;
+    trailLength: number;
+    htmlItems: BreadcrumbItem[];
+    schemaItems: BreadcrumbItem[];
+    mismatches: BreadcrumbMismatch[];
+    generatedValidJsonLd: object;
+    recommendations: string[];
+}
+export declare class BreadcrumbListMicrodataSchemaParityValidator {
+    /**
+     * Validates parity between visible HTML breadcrumbs and Schema.org BreadcrumbList.
+     */
+    validate(input: BreadcrumbParityInput): BreadcrumbParityReport;
+    private extractHtmlBreadcrumbs;
+    private extractSchemaBreadcrumbs;
+    private normalize;
+    private normalizeUrl;
+}

package/dist/analytics/broken-image-detector.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Broken Image Detector & Visual Asset Health Auditor
+ * Clean-room implementation inspired by OpenReplay img module & Web Performance audits.
+ * Detects missing images, HTTP errors, 0-pixel dimensions, missing dimensions causing CLS, and alt text gaps.
+ *
+ * @license AGPL-3.0-or-later
+ */
+export interface ImageAuditInput {
+    src: string;
+    pageUrl: string;
+    naturalWidth?: number;
+    naturalHeight?: number;
+    hasAlt: boolean;
+    hasExplicitDimensions: boolean;
+    loadDurationMs?: number;
+    errorStatus?: 'ok' | 'error_404' | 'error_cors' | 'error_timeout' | 'zero_dimensions';
+    isAboveTheFold?: boolean;
+}
+export interface BrokenImageIssue {
+    src: string;
+    pageUrl: string;
+    issueType: 'missing_404' | 'cors_blocked' | 'timeout' | 'zero_dimensions' | 'missing_alt' | 'missing_dimensions_cls';
+    severity: 'critical' | 'warning' | 'info';
+    recommendation: string;
+}
+export interface ImageHealthReport {
+    totalAudited: number;
+    brokenCount: number;
+    healthyCount: number;
+    healthScore: number;
+    issues: BrokenImageIssue[];
+    domainBreakdown: Record<string, number>;
+}
+export declare class BrokenImageDetector {
+    static auditImages(images: ImageAuditInput[]): ImageHealthReport;
+}

package/dist/analytics/brotli-zstd-compression-efficiency-auditor.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @license AGPL-3.0-or-later
+ * LynxSEO - BrotliZstdCompressionEfficiencyAuditor
+ * Audits HTTP response compression (Brotli 'br', Zstandard 'zstd', gzip, uncompressed),
+ * forecasting byte savings and latency reduction across compressible MIME types.
+ */
+export interface CompressionAuditResourceInput {
+    url: string;
+    contentType: string;
+    transferSizeBytes: number;
+    uncompressedSizeBytes?: number;
+    contentEncoding?: string;
+}
+export type HttpCompressionFormat = "zstd" | "br" | "gzip" | "none" | "other";
+export interface ResourceCompressionFinding {
+    url: string;
+    contentType: string;
+    currentEncoding: HttpCompressionFormat;
+    transferSizeBytes: number;
+    isCompressibleMime: boolean;
+    isOptimal: boolean;
+    potentialBrotliSavingsBytes: number;
+    potentialZstdSavingsBytes: number;
+    recommendation: string;
+}
+export interface CompressionEfficiencyReport {
+    totalResourcesAudited: number;
+    compressibleResourcesCount: number;
+    uncompressedCount: number;
+    gzipOnlyCount: number;
+    brotliOrZstdCount: number;
+    overallCompressionEfficiencyScore: number;
+    totalPotentialSavingsBytes: number;
+    findings: ResourceCompressionFinding[];
+    strategicAdvice: string[];
+}
+export declare class BrotliZstdCompressionEfficiencyAuditor {
+    private static readonly COMPRESSIBLE_MIMES;
+    /**
+     * Audits resources for modern Zstandard / Brotli compression vs legacy gzip or raw text.
+     */
+    audit(resources: CompressionAuditResourceInput[]): CompressionEfficiencyReport;
+}

package/dist/analytics/calendar-heatmap-engine.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Calendar Heatmap Activity & Intensity Matrix Engine
+ * Clean-room implementation for mapping year/month multi-week activity grids,
+ * computing intensity quartiles, and detecting day-of-week anomalies.
+ * Parity: PostHog Calendar Heatmap & GitHub Contribution Matrix.
+ */
+export interface CalendarDayActivity {
+    date: string;
+    count: number;
+    value?: number;
+}
+export interface CalendarMatrixCell {
+    date: string;
+    dayOfWeek: number;
+    weekNumber: number;
+    count: number;
+    intensityLevel: 0 | 1 | 2 | 3 | 4;
+}
+export interface DayOfWeekProfile {
+    dayOfWeek: number;
+    dayName: string;
+    totalCount: number;
+    avgCountPerDay: number;
+    isPeakDay: boolean;
+}
+export interface CalendarHeatmapMatrix {
+    startDate: string;
+    endDate: string;
+    totalDays: number;
+    totalActivityCount: number;
+    maxDayCount: number;
+    cells: CalendarMatrixCell[];
+    dayOfWeekProfiles: DayOfWeekProfile[];
+    streakDays: number;
+}
+export declare class CalendarHeatmapEngine {
+    /**
+     * Builds a normalized 52-week calendar heatmap grid with intensity quantiles.
+     */
+    static buildMatrix(activities: CalendarDayActivity[], startDateStr?: string, endDateStr?: string): CalendarHeatmapMatrix;
+}

package/dist/analytics/canary-flag-guardrail-engine.d.ts

@@ -0,0 +1,80 @@
+/**
+ * CanaryFlagGuardrailEngine — Déploiement Canari & Coupe-Circuit Automatisé pour Feature Flags
+ *
+ * Parité : LaunchDarkly (Guardrail Metrics & Auto-Rollback) & PostHog (Early Access Phased Rollouts).
+ *
+ * Automatise les releases progressives de nouvelles fonctionnalités avec sécurité absolue :
+ * 1. Déploiement par paliers (ex: 5% -> 25% -> 50% -> 100%).
+ * 2. Surveillance continue des métriques de garde-fou (Guardrails) :
+ *    - Différentiel de taux d'erreur (JS / HTTP 500) entre la population exposée et le contrôle.
+ *    - Régression de latence P95 / P99.
+ *    - Taux de plantage (Crash rate).
+ * 3. Coupe-circuit d'urgence (Circuit Breaker) : Rétrogradation instantanée du rollout à 0%
+ *    si une régression dépasse le seuil critique toléré.
+ * 4. Progression automatique au palier supérieur si les métriques restent saines.
+ *
+ * Implémentation Clean-Room sous licence AGPL-3.0.
+ */
+export interface CanaryStageConfig {
+    percentage: number;
+    minDurationMinutes: number;
+}
+export interface CanaryGuardrailThresholds {
+    /** Différentiel maximum toléré de taux d'erreur en points de % (ex: 0.5 pour +0.5%) */
+    maxErrorRateDeltaPct: number;
+    /** Régression de latence P95 tolérée en % (ex: 20 pour +20%) */
+    maxLatencyRegressionPct: number;
+    /** Taille d'échantillon minimale requise pour déclencher une décision statistique */
+    minSampleSize: number;
+}
+export interface CanaryCohortMetrics {
+    totalEvaluations: number;
+    errorCount: number;
+    p95LatencyMs: number;
+}
+export interface CanaryAuditLogEntry {
+    timestamp: string;
+    fromPercentage: number;
+    toPercentage: number;
+    action: "stage_advanced" | "circuit_breaker_tripped" | "manual_override" | "completed";
+    reason: string;
+}
+export interface CanaryReleaseState {
+    flagKey: string;
+    status: "idle" | "running" | "tripped" | "completed";
+    currentStageIndex: number;
+    currentRolloutPercentage: number;
+    stageStartedAt: string;
+    circuitBreakerTripped: boolean;
+    tripReason?: string;
+    auditTrail: CanaryAuditLogEntry[];
+}
+export declare class CanaryFlagGuardrailEngine {
+    private state;
+    private stages;
+    private thresholds;
+    constructor(flagKey: string, stages?: CanaryStageConfig[], thresholds?: CanaryGuardrailThresholds);
+    getState(): CanaryReleaseState;
+    /**
+     * Démarre le déploiement canari au premier palier.
+     */
+    start(now?: Date): CanaryReleaseState;
+    /**
+     * Évalue la santé du déploiement en comparant la cohorte exposée au groupe de contrôle.
+     * Déclenche le coupe-circuit en cas d'anomalie ou avance le palier si sain.
+     */
+    evaluateHealth(exposed: CanaryCohortMetrics, control: CanaryCohortMetrics, now?: Date): CanaryReleaseState;
+    /**
+     * Déclenche le coupe-circuit d'urgence (Rollback immédiat à 0%).
+     */
+    private tripCircuitBreaker;
+    /**
+     * Avance au palier de déploiement suivant.
+     */
+    private advanceStage;
+    /**
+     * Réinitialisation manuelle après correction d'un bug.
+     */
+    manualResume(overridePercentage?: number, now?: Date): CanaryReleaseState;
+    private logAction;
+}