package de.gecheckt.pdf.umbenenner.application.port.out;

/**
 * Outbound port for initialising the SQLite persistence schema at program startup.
 * <p>
 * This port is invoked exactly once per program run, <em>before</em> the batch
 * document processing loop begins. The initialisation must ensure that all tables,
 * indices, and constraints required for document persistence are present in the SQLite file.
 * <p>
 * <strong>Timing:</strong> The adapter implementation must perform the schema
 * initialisation eagerly and synchronously. Lazy or deferred initialisation during
 * the document processing loop is not the intent of this port.
 * <p>
 * <strong>Failure handling:</strong> If the schema cannot be initialised, the
 * implementation must throw {@link DocumentPersistenceException}. The bootstrap
 * layer must catch this exception and abort the run with exit code&nbsp;1.
 * <p>
 * <strong>Idempotency:</strong> Calling {@link #initializeSchema()} on a database
 * that already has the correct schema must succeed without error (e.g. via
 * {@code CREATE TABLE IF NOT EXISTS} semantics).
 * <p>
 * <strong>Architecture boundary:</strong> No JDBC, SQLite, or filesystem types appear
 * in this interface. All schema DDL and connection management are confined to the
 * {@code adapter-out} implementation.
 *
 */
public interface PersistenceSchemaInitializationPort {

    /**
     * Creates or verifies the persistence schema.
     * <p>
     * Must be called once at program start, before any document processing begins.
     * The method must be idempotent: calling it on an already-initialised database
     * must not fail or alter existing data.
     *
     * @throws DocumentPersistenceException if the schema cannot be created or verified
     */
    void initializeSchema();
}
