<?php

declare( strict_types=1 );

namespace Brightfern\Archive;

/**
 * Phase-2 hook: legal archiving / retention with an audit trail. Many EU regimes
 * require e-invoices (sent AND received) to be stored immutably for years (e.g.
 * 10 in Belgium/Germany) with integrity guarantees.
 *
 * v1 ships a no-op {@see NullArchive} so the call sites exist and are wired; the
 * real implementation (WORM storage, hashing, audit log) lands later without
 * touching the send/receive pipeline.
 */
interface ArchiveInterface {

	/**
	 * Persist a document for legal retention.
	 *
	 * @param string              $direction "outbound" | "inbound".
	 * @param string              $xml       The canonical document.
	 * @param array<string,mixed> $meta      Identifiers, parties, hash inputs.
	 * @return string A retention reference/receipt id (empty if not archived).
	 */
	public function store( string $direction, string $xml, array $meta ): string;
}
