1	<?php
2
3	declare(strict_types=1);
4
5	namespace LambdaTwelve\OneRecord\Server\Spi;
6
7	use DateTimeImmutable;
8	use LambdaTwelve\OneRecord\Model\LogisticsEvent;
9	use LambdaTwelve\OneRecord\Rdf\Iri;
10
11	/**
12	* An append-only log of events per logistics object. Events are never
13	* changed or deleted through the API (the spec), so the interface has no
14	* update; eraseFor() exists for the host's data-protection operation only.
15	*
16	* Every event a store receives carries cargo:eventDate: the server refuses a
17	* posted event without one and the checked builder refuses to build one. A
18	* store may rely on that for its occurred-at filters and sorting; the
19	* in-memory store's fallbacks to the receipt time are defensive only.
20	*/
21	interface LogisticsEventStore
22	{
23	/**
24	* Appending an event whose IRI already exists is a StoreException: event
25	* IRIs are minted by the server, so a repeat is a bug, never an update.
26	*
27	* @throws StoreException
28	*/
29	public function append(LogisticsEvent $event): void;
30
31	public function get(Iri $eventIri): ?LogisticsEvent;
32
33	/**
34	* @return list<LogisticsEvent>
35	*/
36	public function query(Iri $logisticsObject, EventQuery $query): array;
37
38	/**
39	* When the list for this object last changed: the newest `created` among
40	* its events (not the last one appended, which differs only under a
41	* non-monotonic clock), for Last-Modified on the collection.
42	*/
43	public function lastModified(Iri $logisticsObject): ?DateTimeImmutable;
44
45	/**
46	* Removes every event of an object: the host forgetting it (DataHolder::forget()).
47	*/
48	public function eraseFor(Iri $logisticsObject): void;
49	}