A changed folder and a state reflected on another screen are different facts. I built a small in-memory model for a replaceable latest snapshot so that distinction can be inspected. It watches no files and sends nothing to a server. Its limited responsibility is to retain pending changes and track which locally reserved revision the caller declares as acknowledged.
Establish a baseline before counting changes
The constructor token is a comparison baseline. Construction does not make delivery pending. observe advances a local revision when a different synthetic token arrives and leaves it unchanged for the same token. A service that must send its initial state needs a separate initial-sync policy. This baseline is not evidence that an operating program has already synchronized anything.
Several changes arriving before an attempt coalesce into the latest revision and token. This is not a queue that preserves every intermediate business event. It suits replaceable state such as the current count shown on a status screen. Orders and payment events that must each survive require a different structure, such as the existing SQLite business-event example.
An attempt reservation is neither a transmission nor a success
begin validates a nondecreasing integer tick supplied by the host. It creates a Ticket only when a change is pending, no attempt or unresolved outcome exists, and the relevant delay has elapsed. Network operations remain zero. The attempt count measures local reservations, not external requests, and there is no function for restarting the original business action.
A Ticket is an immutable object containing an ordinal, revision and token. finish and resolve accept the exact object issued by that instance, rejecting a lookalike copy or a ticket from another instance. This deliberately narrow single-caller exercise is not a signature check or an authenticated protocol for several processes.
Do not turn an unknown outcome into a known failure
A confirmed result declares that the host has confirmation. not_applied means the host has evidence that no remote effect occurred; after the retry delay, the pending state may receive another reservation. unknown means the effect is unresolved. Even a long wait cannot open a new reservation until resolve receives an explicit reconciliation. Calling a mere response timeout not_applied would defeat this boundary.
resolve does not read a server either. It is where a host supplies a separately obtained confirmed or not_applied observation. remote_receipt_authenticated and business_completion_proven remain False. The implementation below verifies local state transitions, not actual delivery or completion of a customer's work.
Explore the implementation
Complete independent synthetic implementation
"""In-memory teaching model for replaceable snapshots. No transport or scheduler."""
from dataclasses import dataclass
import re
@dataclass(frozen=True)
class Ticket:
ordinal: int
revision: int
token: str
class SnapshotRelay:
def __init__(self, initial_token, *, minimum_gap=2, retry_delay=3):
self._validate_token(initial_token)
for value in (minimum_gap, retry_delay):
if type(value) is not int or value < 1:
raise ValueError('INVALID_DELAY')
self._token = initial_token
self._latest = self._acked = self._serial = 0
self._active = self._unknown = None
self._clock = -1
self._ready_at = 0
self._gap, self._retry = minimum_gap, retry_delay
self._last_outcome = 'not_attempted'
@staticmethod
def _validate_token(token):
if type(token) is not str or not re.fullmatch(r'[A-Za-z0-9_-]{1,64}', token):
raise ValueError('INVALID_SYNTHETIC_TOKEN')
def _tick(self, now):
if type(now) is not int or now < 0 or now < self._clock:
raise ValueError('INVALID_OR_REVERSED_CLOCK')
self._clock = now
def observe(self, token):
"""Supply an alias, not a filesystem path or a content-authenticated digest."""
self._validate_token(token)
if token == self._token:
return False
self._token = token
self._latest += 1
return True
def begin(self, now):
"""Reserve a local attempt; returning a ticket performs no transmission."""
self._tick(now)
if (self._latest == self._acked or self._active is not None
or self._unknown is not None or now < self._ready_at):
return None
self._serial += 1
self._active = Ticket(self._serial, self._latest, self._token)
return self._active
def finish(self, ticket, outcome, now):
"""Outcome is a caller declaration, never a verified remote receipt."""
if ticket is not self._active or ticket is None:
raise ValueError('NOT_THE_ACTIVE_TICKET')
if type(outcome) is not str or outcome not in {'confirmed', 'not_applied', 'unknown'}:
raise ValueError('INVALID_OUTCOME')
self._tick(now)
self._active = None
self._last_outcome = outcome
if outcome == 'confirmed':
self._acked = ticket.revision
self._ready_at = now + self._gap
elif outcome == 'not_applied':
self._ready_at = now + self._retry
else:
self._unknown = ticket
def resolve(self, ticket, observation, now):
"""Host explicitly supplies reconciled outcome; this method reads no server."""
if ticket is not self._unknown or ticket is None:
raise ValueError('NOT_THE_UNKNOWN_TICKET')
if type(observation) is not str or observation not in {'confirmed', 'not_applied'}:
raise ValueError('INVALID_RECONCILIATION')
self._tick(now)
self._unknown = None
self._last_outcome = 'reconciled_' + observation
if observation == 'confirmed':
self._acked = ticket.revision
self._ready_at = now + self._gap
else:
self._ready_at = now + self._retry
def inspect(self):
return {'latest_revision': self._latest, 'declared_acked_revision': self._acked,
'pending': self._latest != self._acked,
'in_flight': self._active is not None,
'needs_reconciliation': self._unknown is not None,
'ready_at': self._ready_at, 'last_outcome': self._last_outcome,
'attempt_reservations': self._serial,
'network_operations': 0, 'durable_state_verified': False,
'remote_receipt_authenticated': False, 'business_completion_proven': False}
An old acknowledgement must not erase a newer change
After a reservation for revision 1, observe may create revision 2. Confirming the older Ticket advances the declared acknowledged revision only to 1. Because the latest revision is still 2, pending remains true. Resolving an uncertain response uses the same rule. The code does not automatically acknowledge everything that happens to be current when an answer arrives.
Even one active reservation leaves room for observations between starting and finishing an asynchronous delivery. This module implements neither a thread lock nor receiver-side ordering. Several workers or requests arriving out of order require a receiver revision fence and an overwrite policy. Local revision numbers alone cannot guarantee every external delivery order.
Read five synthetic records against the same contract
The records cover an unchanged baseline, a retry reservation while the folder stays quiet, retention of a newer change after an older confirmation, an unresolved outcome, and explicit reconciliation. They are actual local outputs of this Python example. They are not customer-folder observations or logs of a real network outage, and their counts must not become operating success statistics.
Twenty tests exercise repeated observations, coalescing, pending-state retention, timing, old acknowledgements, uncertainty, foreign Tickets and invalid clocks. The same suite runs after ZIP extraction. The selector below reads the five saved records; its actual scripts are checked with DOM stubs for initial display and selection. Rendered-browser inspection and external transport testing are separate scopes.
Responsibilities that remain with an operating host
The download contains the complete implementation, tests, record generator and outputs, README and reuse permission. It uses the standard library but includes no watcher, sender or scheduled job. One serial caller is required. Persistence, restart recovery, retry budgets, cancellation, permission and genuine result lookup remain host responsibilities. The integer delay values are teaching parameters rather than production timings.
I have not installed this state calculator into the original control program. That program and its automations remain preserved. The business-event module is linked to compare responsibilities, not as an implemented automatic integration. Choosing between one replaceable current state and a sequence of individually preserved events is the starting point of this example.