One user-space repair task per eligible HWE debug-diag / compile-deploy base ID: 320 admitted (C 218, C++ 97, build scripts 5), 1 skipped by the content filter. Each ships a public spec with a check-to-basis table, at least two defects with single-fix fixtures, a symptom-masking fixture and an alternative correct implementation. Claude re-checked all 320: structure, the HWE quality items and trace6 Docker calibration receipts against current digests (320/320 USABLE). Difficulty is unmeasured. Known follow-up: 212 tasks use 120 ad-hoc family names; the next batch maps them to the canonical list. The batch's 1,256-line progress log stays in its factory report and the 36-local branch batch15-hwe. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
69 lines
5.0 KiB
Markdown
69 lines
5.0 KiB
Markdown
# 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.
|