<?php
/**
 * LolaCore — MemoryBootstrapInterface
 *
 * Contract for addon memory bootstraps. Addons implement this interface
 * to contribute baseline facts to the memory table on activation and
 * at periodic refresh intervals.
 *
 * @package LolaCore
 * @license GPL-2.0-or-later
 * @since   1.2.0
 */

declare(strict_types=1);

namespace LolaCore\Addon\Contract;

if (!defined('ABSPATH')) {
    exit;
}

interface MemoryBootstrapInterface
{
    /**
     * Generate baseline facts derived from the current site state.
     *
     * Each fact is an associative array with the following keys:
     *  - content         (string, required) — Human-readable fact in English.
     *  - fact_type        (string, required) — One of: site_state, performance_metric, plugin_conflict.
     *  - importance       (int, required)    — Score from 1 (low) to 10 (critical).
     *  - structured_data  (array, optional)  — Machine-readable payload for the fact.
     *
     * Implementations MUST derive all data from the live site state.
     * Hardcoded values, demo data, or placeholder text are forbidden (PRD P1).
     *
     * The runner enforces a maximum of MAX_CANDIDATES_PER_ADDON (8) facts.
     * If more are returned, only the top 8 by importance are kept.
     *
     * @return array<int, array{content: string, fact_type: string, importance: int, structured_data?: array}>
     */
    public function generateBaselineFacts(): array;

    /**
     * How often this bootstrap should re-run, in seconds.
     *
     * Return 0 to run only on activation (no periodic refresh).
     * Recommended values:
     *  - 21600  (6 hours)  — time-sensitive data (support tickets)
     *  - 43200  (12 hours) — moderately volatile (ecommerce stats)
     *  - 86400  (24 hours) — slow-changing data (code snippets)
     */
    public function refreshInterval(): int;

    /**
     * Unique slug identifying this addon's bootstrap.
     *
     * Must match the addon's domain slug used in lolacore_addon_domains.
     * Examples: 'woocommerce_pro', 'wpcode', 'fluent_support'.
     */
    public function addonSlug(): string;
}
