# Numeric timer bank protocol v1 This deterministic service replaces clock hardware by explicit signed tick coordinates. The initial bank is empty at time 0; no wall clock, sleep, device, network, or external file is used. ## Coordinates and channels All input numbers are decimal integers. IDs are 0..15. Times, phase offsets, epochs and shift deltas are in [-1000000000,1000000000]. Periods are in [1,1000000]. All calculations and counters use signed 64-bit integers. Inputs outside these ranges are rejected. Internal next times may exceed 1000000000 by at most one period. No input requires overflow or division by a nonpositive number. A channel has period P, canonical phase R in [0,P), epoch E, mode COUNT or LATEST, enabled flag, next due coordinate, cumulative fired count and cumulative skipped count. The canonical phase is the unique integer congruent to the supplied phase modulo P. The scheduled coordinates are E + R + k*P for every integer k, including negative k. At configuration or rearming, next is the smallest scheduled coordinate strictly greater than current bank time; an exact boundary is not replayed. Channel IDs are independent; observable channel order is ascending ID. ## Commands and responses Input is ASCII, one command per line, at most 255 bytes excluding newline; words are separated by ASCII whitespace. Leading/trailing whitespace and empty lines are allowed; empty lines produce no output. Commands and mode names are case sensitive. Extra/missing tokens or malformed numbers produce `ERR syntax`. A valid numeric token outside its allowed range produces `ERR range`. Unknown commands produce `ERR syntax`. Every rejected command preserves all bank/channel state. Commands below are available immediately; INIT is optional. - `INIT now`: clear every channel and set current time, even if it moves backward. Response `OK INIT now`. - `PUT id period phase epoch mode`: create or replace the ID; enabled=1, fired=skipped=0, next strictly after current time. Response `OK PUT id`. Mode must be COUNT or LATEST, otherwise `ERR syntax`. - `PEEK id`: print the STATE line described below; absent ID gives `ERR missing`. - `ENABLE id flag`: flag is 0 or 1; absent ID gives `ERR missing`. Disabling stores next=0. Enabling (including enabling an already enabled channel) recomputes next strictly after current time. Counters are preserved. Response `OK ENABLE id flag`. - `SHIFT id delta`: replace the canonical phase by the residue of old canonical phase + delta; preserve epoch, mode, enabled and counters; recompute next if enabled, otherwise next=0. Absent ID gives `ERR missing`. Response `OK SHIFT id`. - `DROP id`: remove the channel, or `ERR missing`. Response `OK DROP id`. - `TICK target`: target must be at least current time, otherwise `ERR backward`. For each enabled channel, consume every scheduled coordinate in (old time,target] that has not been consumed. Channels with no due coordinate produce no EVT line. One report is produced per due channel: `EVT id due first last skipped next`. `due` is the number of consumed coordinates; `next` is the smallest scheduled coordinate strictly after target. In COUNT mode `first` and `last` are the earliest/latest consumed coordinates and `skipped=0`. In LATEST mode the effective emitted coordinate is the latest consumed coordinate: both `first` and `last` equal it and `skipped=due-1`. The channel's fired counter increases by due, skipped counter by skipped. Output begins with `BEGIN target n`, where n is the number of EVT lines, followed by ascending-ID EVT lines and `END target`. Current time becomes target even for an empty bank or no due channels. - `LIST`: output `LIST n` then one STATE line per configured ID in ascending order. Disabled channels are included. No END line. - `STATS`: output `STATS now configured enabled fired skipped`; counters are sums over currently configured channels only, so DROP/replacement removes the old channel's contribution. STATE line: `STATE id period phase epoch mode enabled next fired skipped`. Every scalar is printed in decimal with one space between fields. Every response line ends in a newline. No additional stdout text is allowed. Diagnostic stderr is allowed. Valid or rejected commands do not terminate the service; EOF after a sequence produces exit code 0. ## Build, embedding and self test `make` uses gcc with C11 and builds `timer-demo`. `./timer-demo < demo.in` is the default COUNT scenario; `./timer-demo < latest.in` exercises the other policy. A single process may receive thousands of commands. Both demonstrations have manually specified expected transcripts beside them. `make check` compares those two transcripts. Public declarations in phase.h may be used by small local probes. All five declared candidate files must remain a self-contained C11 implementation; main.c and this document are immutable support materials used for a clean rebuild by acceptance. The public API uses return 0 for success and negative TIMER_* codes for rejected operations. Neither public examples nor a successful build substitute for all requirements above.