<?php
/**
 * Settings repository contract.
 *
 * Phase-8 persistence seam for the §13 Settings aggregate. The
 * interface deliberately exposes only three operations — load,
 * save, reset — because Phase 8's minimum scope is "the admin
 * page round-trips a single blob"; field-level partial updates
 * are deferred to a follow-up slice that can layer atomic
 * mutation helpers on top of this contract without breaking
 * existing callers.
 *
 * Contract:
 *
 *   - {@see self::load()} MUST return
 *     {@see PluginSettings::defaults()} when no value has ever
 *     been stored. Implementations MAY treat a malformed stored
 *     payload as an additional "no value" branch and recover by
 *     returning defaults; observability of that recovery path
 *     is a Phase-11 concern.
 *
 *   - {@see self::save()} overwrites the entire blob. Callers
 *     that need to mutate a single field MUST {@see self::load()}
 *     first, apply the appropriate {@see PluginSettings} wither,
 *     and {@see self::save()} the result.
 *
 *   - {@see self::reset()} deletes the stored value, so the next
 *     {@see self::load()} returns
 *     {@see PluginSettings::defaults()}.
 *
 * Implementations are free to throw on persistence-layer
 * failures from {@see self::save()} / {@see self::reset()}; the
 * contract does not require those operations to be infallible.
 *
 * @package CommerceLinkBuilder\Application\Settings
 */

declare(strict_types=1);

namespace CommerceLinkBuilder\Application\Settings;

/**
 * Phase-8 settings persistence contract.
 *
 * See the file-level docblock for the load / save / reset
 * semantics and the rationale for not exposing field-level
 * partial updates in this slice.
 */
interface SettingsRepository {

	/**
	 * Load the current settings snapshot.
	 *
	 * Returns {@see PluginSettings::defaults()} when no value
	 * has ever been stored. Implementations MAY treat a
	 * malformed stored payload as an additional "no value"
	 * branch and recover by returning defaults.
	 */
	public function load(): PluginSettings;

	/**
	 * Persist the supplied settings snapshot, overwriting any
	 * previously-stored blob in its entirety.
	 *
	 * @param PluginSettings $settings Snapshot to persist.
	 */
	public function save( PluginSettings $settings ): void;

	/**
	 * Delete the stored settings blob.
	 *
	 * After a successful call, the next {@see self::load()}
	 * MUST return {@see PluginSettings::defaults()}.
	 */
	public function reset(): void;
}
