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>
6.3 KiB
Topic replay public contract v1
C1 Build and scope
The offline C11 application is built by make with gcc; there are no downloaded dependencies.
Makefile, include/topic_runtime.h, src/main.c, src/plan.c, src/format_port.c and src/transport.c are fixed public support. Official grading rebuilds exactly these files plus the submitted src/publisher.c using gcc -std=c11 -O2 -Wall -Wextra -Werror -pedantic -Iinclude.
Only src/publisher.c is submitted. It implements int publisher_run(TopicRuntime *, const TopicPlan *) using the public runtime ports. All actual publication, formatting and resource operations must go through those ports; directly modifying runtime accounting/queue/allocation state, printing substitute observations or inspecting private graders is outside the project API.
This deterministic deferred transport models a broker handoff without MQTT, networking, physical boards, GNU asprintf or RSS measurements.
C2 Input and public replay commands
./topic-replay examples/normal.txt is the default demo: batch=4, fail-at=0. It contains no allocation failure.
The independent optional recovery example is ./topic-replay --batch 2 --fail-at 3 examples/recovery.txt.
General invocation is ./topic-replay [--batch N] [--fail-at K] PATH; batch N is 1..16 (default 4), K is 0..2000 (default 0). K=0 disables injected failures; otherwise exactly the Kth topic-format allocation attempt fails. If fewer attempts occur it never fails.
Input consists of at most 2000 events, with optional blank lines or lines whose first token starts with #. Each nonempty event is either P DEVICE CHANNEL SEQUENCE or F. Tokens are separated by space, TAB or CR; LF ends a line. Each line has at most 8190 bytes excluding LF. No embedded NUL, VT or FF is valid.
DEVICE and CHANNEL are 1..96 characters from ASCII A-Z, a-z, 0-9, underscore and hyphen, case sensitive. SEQUENCE is a decimal integer 0..1000000000; ASCII digits, optional leading + and arbitrary leading zeroes are allowed within the line bound. Options accept the same unsigned decimal spelling within their stated bounds.
F completes all pending deliveries and ends the current batch; consecutive F and empty inputs are valid. End of input also completes all pending deliveries. P and F ordering is preserved.
For multiple independent replay sessions, ./topic-replay --suite PATH reads rows N K INPUT_PATH and emits an array of session observations. Paths have no whitespace, each row is at most 1022 bytes excluding LF, N and K obey the same option bounds. Empty LF/CR lines and lines beginning # are ignored. Every session starts with fresh resource and transport state; suite rows are processed in order. An empty suite is valid.
Valid runs exit 0, including injected allocation failures; invalid CLI/input or I/O failure exits 2. stderr may contain arbitrary diagnostic bytes and is not part of the observation protocol.
C3 Topic formatting and failure recovery
For every P, call topic_format once with that event's exact device/channel/sequence. A successful result is the dynamically allocated NUL-terminated ASCII topic fleet/DEVICE/telemetry/CHANNEL/SEQUENCE, using canonical unsigned decimal sequence without leading zeroes.
The return value is the topic byte length excluding NUL; caller receives a unique allocation token and owns its returned char buffer. Failure returns -1 and writes NULL to the output pointer. The fixed port records real malloc/free operations, including the terminating NUL in resource byte accounting; no fixed-size replacement or bypass is permitted.
A failed allocation affects only that P: skip its enqueue and continue processing every later event. It must not discard pending successful publications. No retries for the failed event, and no extra format calls. All valid replay sessions return publisher_rc=0.
C4 Deferred handoff and ownership
Each successfully formatted P is enqueued exactly once using topic_enqueue; successful enqueue borrows the caller's buffer. Completion reads the actual original buffer later. The allocation must remain live with unchanged bytes until topic_complete finishes the delivery; topic_enqueue does not copy ownership. The fixed transport records delivery ordinal (1-based successful enqueue count), alive (integer 1 if the same allocation token remains live, otherwise 0), and topic as lowercase hex of the bytes it actually reads. It reports an empty string for a dead token, never dereferencing freed memory. The batch size is an upper bound on pending successful publications. Complete before exceeding N, at every F, and at EOF. Earlier completion is allowed, including after every P. Thus implementations may use a batch-owned pointer array or immediately complete each publication. The caller releases every successful allocation exactly once with topic_release after its completion. topic_release(NULL) is allowed and has no effect. Double release, untracked pointers and releasing queued buffers early are erroneous. No pending deliveries, live allocations or live bytes may remain when publisher_run returns.
C5 Raw observer and audit
Single-session stdout is one JSON object; suite stdout is one JSON array of those objects. JSON whitespace and object key order are unrestricted; the complete stdout must decode as one JSON value. Integer fields are JSON integers, not booleans. No other stdout text is permitted. Each session object has deliveries, publisher_rc and audit. deliveries is the ordered array of {ordinal,alive,topic}; publisher_rc is the actual return code from publisher_run. The fixed observer reports facts, including failure facts, rather than a success verdict. audit has attempts, allocated, allocation_failures, released, live_blocks, live_bytes, release_errors, enqueued, delivered, lifetime_errors, queue_errors and pending. attempts equals the number of P events; allocated equals attempts minus the single injected failure if reached; allocation_failures is 0 or 1 accordingly. released, enqueued and delivered equal allocated. All other audit values are zero on a conforming run. Each delivery has alive=1 and exact topic contents from C3 in P order, excluding failed events. Observer disposal frees leftover blocks only after emitting the audit, so disposal cannot hide leaks. There are no wall-clock, peak-allocation, stderr-size or RSS pass thresholds. Only final ownership, actual publication content/order, failure continuation and the public limits above are assessed.