From the 101 lk/man/pth code-gen sources: 63 tasks (C11 36, C++17 27, 11 canonical families), 38 skipped for scope or duplication. Each task has at least one independent contract-edge defect, boundary types rotate, and public docs state trap clauses as plain contract prose. Claude reviewed 63/63 USABLE against current digests. Difficulty is unmeasured. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
7.6 KiB
Line controller contract
Data and lifetime
The public header declares ls_init, ls_execute, ls_snapshot, ls_close, and ls_decode. Their numeric constants are LS_SLOTS=8, LS_NAME=32, LS_LINE_LIMIT=8192; states EMPTY=0, ABSENT=1, HELD=2; command kinds BIND=1, WRITE=2, PEEK=3, DROP=4, CLOSE=5. A service and a provider context are caller-owned and remain alive through the last call. Each service owns eight independent slots. Distinct services may be interleaved with different contexts and do not change each other's slots or provider events. Calls are sequential.
ls_init(service, provider, context) returns 0 and initializes all slots to EMPTY, token 0, value -1. It copies the four callbacks and retains the context pointer, which may be NULL. Provider, service, and all four callbacks must be non-NULL; otherwise it returns -22 without changing any supplied service bytes or calling a provider. A service passed to other functions must have been initialized successfully. Initialization is permitted on fresh storage or after all its resources have been closed. ls_close leaves a service initialized and reusable. No allocation or global state is needed by callers.
Each result has integer rc, state, token, and value fields. Every call with a non-NULL result writes all four fields. The function return equals result.rc. A slot result contains its current state, token (0 unless HELD), and cached value (-1 unless HELD). A no-slot result has state -1, token 0, value -1. A NULL result makes execute, snapshot, and close return -22 without any state changes or provider calls. A NULL service with a non-NULL result returns -22 and a no-slot result.
Provider calls
take(context, name, &token) returns 1 with a positive unsigned token for a new owned line, 0 when that named resource is absent, or an error in -4095..-1. These three outcomes are distinct. An absent optional request succeeds as ABSENT; an absent required request fails with -2. Any take error is propagated for either request type. Token output on absence or error is unspecified and must not be used. Each successful take returns a token different from all other live tokens in that context. There are no calls for a nonexistent token.
direction(context, token) sets output direction and returns 0 or an error in -4095..-1. set(context, token, value) sets a binary output and returns 0 or an error in -4095..-1. A failed direction or set does not change the line's previous direction/value. put(context, token) releases ownership and has no return value. The callbacks do not invoke service functions. The service forwards names and tokens without rewriting them. The context has enough capacity for all eight holdings plus one staged line; no numeric token other than zero is reserved.
For a present binding the event order is take, direction, set(initial), then put(old) if the slot previously held a line. A direction failure produces take, direction, put(new); an initial set failure produces take, direction, set, put(new). Failed binding preserves the previous slot and its old resource. A successful absent binding makes the slot ABSENT and releases the old held line after take, with no direction or set. ABSENT occupies the named slot as a state but owns no provider resource. No old resource is released on a failed take or required absence.
The service stores no event log and adds no limit to sequential calls. Any observer may choose its own storage; that observer must report a trace overflow as an observation rather than silently omit events. Provider ownership and cached values are unaffected by whether an external trace is full.
Operations
ls_execute(service, command, result) accepts a non-NULL command. BIND reads slot, optional, value, and name; WRITE reads slot and value; PEEK/DROP read slot; CLOSE ignores other fields. The slot domain is 0..7, optional and value are 0 or 1. A BIND name has 1..31 bytes from ASCII letters, digits, underscore, dot, and hyphen, terminated within its 32-byte array. Other command fields are ignored. Invalid relevant fields or kinds return -22 and a no-slot result, without provider calls or state changes.
BIND follows the provider protocol above and returns the resulting slot on success or the preserved slot on failure. Rebinding is a new request even when the name and parameters match the earlier request. WRITE on HELD calls set once; success updates the cached value and failure preserves it. WRITE on EMPTY or ABSENT returns -19 and the unchanged slot without a callback. PEEK returns the slot with rc 0 and no callbacks. DROP releases a held line once, changes any slot to EMPTY, and returns it with rc 0. Dropping an EMPTY/ABSENT slot has no callback.
ls_snapshot(service, slot, result) is PEEK without a command. An out-of-range slot returns -22 and a no-slot result. ls_close(service, result) releases every held slot in ascending slot order, clears all eight slots, and returns 0 with a no-slot result. Repeated close calls succeed and do not release anything again. Executing CLOSE has the same behavior.
Byte decoder
ls_decode(bytes, length, command) reads exactly length bytes without requiring a terminator. It returns 0 and fully initializes the public fields of command on success. Unused fields are zero and name is an empty string except for BIND. Invalid syntax returns -22 and leaves every output byte unchanged. Length above 8192 returns -7 and leaves output unchanged. A NULL command or NULL bytes with nonzero length returns -22; these argument errors take precedence over the length limit. NULL bytes with zero length is an invalid empty command.
The grammar is bind slot optional value name, set slot value, peek slot, drop slot, or close, with case-sensitive command words. One or more ASCII space or tab bytes separate words; any count of those bytes may also precede/follow a command. Numbers contain one or more ASCII digits, permit leading zeroes through the complete line limit, and must have a value in their field's domain. Signs, other whitespace, extra words, empty commands, NUL, and non-ASCII bytes are invalid. Names use the BIND name domain above. LF is not a decoder separator. The byte count includes all separators.
Console
line-console uses this same decoder and service with a built-in software provider. The provider reports missing for name missing, error -13 for blocked, and error -517 for retry; every other valid name is present. Successful takes receive consecutive positive tokens starting at 1; absence and errors do not consume a token. Direction and set succeed for acquired lines. Names have no lasting identity: every successful take is a new token. Input sequences in which this serial exceeds UINT_MAX are outside the console domain.
The console reads raw stdin through EOF. LF ends a physical line and is excluded from its decoder byte count. Each physical line yields one JSON object containing the four result fields and ending with LF; an unterminated nonempty final line also yields one object. Empty stdin yields zero stdout bytes. A line above 8192 bytes yields rc -7 and a no-slot result, is consumed through its LF/EOF, and does not affect service state. Other decode errors yield rc -22 and a no-slot result. Valid lines execute normally. Processing continues after every command error, including binary input errors. EOF closes all resources without producing another object. With readable stdin and writable stdout the process exits 0. JSON whitespace and member order are unrestricted, and additional object members are permitted; the four result fields have integer values rather than booleans. Stdout is UTF-8. Diagnostics on stderr are permitted and do not change results.