<?php
/**
 * ModuleSchemaInterface — Contract for module-owned database schemas.
 *
 * Every feature module that owns database tables MUST provide a schema class
 * implementing this interface.  The schema class is the single source of truth
 * for both table structure (SQL) and the mapping of table-key → table-class.
 *
 * Lifecycle:
 *   1. Module::boot() instantiates its own Schema object.
 *   2. Module calls $plugin->modules->get_db_tables()->register_module_tables(
 *          $schema->get_table_map()
 *      ) to publish its tables to the shared registry.
 *   3. DatabaseInstaller::run_upgrade() collects schemas from all modules
 *      via the 'ultraguard_pro/collect_module_schemas' filter and runs
 *      dbDelta on each CREATE TABLE string.
 *
 * @package UltraguardPro\contracts
 */

namespace UltraguardPro\contracts;

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

interface ModuleSchemaInterface {

    /**
     * Return CREATE TABLE SQL for every table this module owns.
     *
     * Keys are the full prefixed table names (e.g. '{prefix}ultraguard_scan_results').
     * The SQL must be dbDelta-compatible (single-space column separator, uppercase SQL keywords).
     *
     * @return array<string, string>  table_name → CREATE TABLE SQL
     */
    public function get_schemas(): array;

    /**
     * Return the module's table key → FQCN map for the DatabaseTablesModule registry.
     *
     * Keys are short table keys (e.g. 'scan_results').
     * Values are fully-qualified class names that extend BaseTable.
     *
     * @return array<string, class-string>
     */
    public function get_table_map(): array;

    /**
     * Return the unique module identifier this schema belongs to.
     *
     * Used for logging and debugging only.
     *
     * @return string
     */
    public function get_module_id(): string;
}
