amos 9d633e9e67 Batch 15 (20261023-C-hwe-scale-15): 320 HWE-derived repair tasks
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>
2026-10-27 01:55:56 +08:00

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.