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

import java.time.Instant;

/**
 * Outbound port for system time access.
 * <p>
 * This port abstracts access to the system clock, enabling the batch run to:
 * <ul>
 *   <li>Record timestamps for batch run start and completion</li>
 *   <li>Generate or verify document timestamps for traceability</li>
 *   <li>Support testing with controlled time values</li>
 * </ul>
 * <p>
 * By isolating time access behind a port, the application can be tested with
 * deterministic time values without requiring system clock manipulation.
 *
 */
public interface ClockPort {

    /**
     * Returns the current moment in time.
     * <p>
     * Implementations should return the current system time (or a controlled test value).
     * The returned instant is UTC-based and suitable for persistent storage and logging.
     *
     * @return the current instant
     */
    Instant now();
}
