[c-RCP-AUDIT-01] Wire TC18 Table 27's 16 unmapped error codes to real response paths

[SoundMatt]

Background

include/rcp/errors.h defines rcp_wire_error_t, the 17 numbered wire error codes assigned by TC18's own Table 27 (the values an RC Server places in an Acknowledge/Response frame's err field to tell an RC Client what went wrong). REQ-WIREERR-001 covers the enum itself.

The header's own comment is already honest about the gap:

"This header intentionally does not attempt to wire every internal rcp_errc_t/rcp_<mod>_errc_t value in the codebase onto one of these seventeen codes... rcp_e2e_wire_error() below is the one concrete mapping this milestone adds... Additional mappings (e.g. sequencer.h's REQUEST_NOT_FOUND-shaped failures, authz.h's UNAUTHORIZED_ACCESS-shaped failures) are real future work, not modeled here."

Confirmed by grep (2026-08-07): only errors.c/errors.h reference the 17 RCP_ERROR_* constants anywhere in the codebase. No endpoint module, server.c, authz.c, sequencer.c, or any request_*.c actually populates a real error response's err field with the correct numbered code for most failure conditions. Only 1 of 17 codes is wired to a real path today: RCP_ERROR_POCI_FAILURE via rcp_e2e_wire_error() (CRC32/E2E mismatch).

This is safety-relevant: an RC Client's ability to correctly diagnose why a request failed depends on the RC Server returning the right numbered code, not a generic/wrong one or none at all.

The 16 unmapped codes and their TC18 meaning

RCP_ERROR_UNSUPPORTED_CMD           = 1,  // the addressed operation/endpoint doesn't support the requested command
RCP_ERROR_SEQUENCER_NOT_KNOWN       = 2,  // the referenced sequencer index isn't configured
RCP_ERROR_UNAUTHORIZED_ACCESS       = 3,  // the caller isn't permitted to perform this request
RCP_ERROR_LOCKED_MEM_ACCESS         = 4,  // the addressed register/memory is locked against this access
RCP_ERROR_REQUEST_CANCELED          = 5,  // the request was canceled before it completed
RCP_ERROR_REQUEST_NOT_FOUND         = 6,  // the referenced request (e.g. to cancel) is not known
RCP_ERROR_EP_ERROR                  = 7,  // the addressed endpoint reported an internal fault
RCP_ERROR_EP_NOT_FOUND              = 8,  // the addressed endpoint (byte_bus_id) does not exist
RCP_ERROR_PWM_IN_NO_SIGNAL          = 9,  // a PWM input endpoint has no signal to report
RCP_ERROR_REQUEST_STORAGE_OVERFLOW  = 10, // the request-storage capacity is exhausted
RCP_ERROR_REQUEST_REJECTED          = 11, // the request was well-formed but rejected on other grounds
// 12 (POCI_FAILURE) already wired
RCP_ERROR_PRESENTATION_TIME_TOO_FAR = 13, // a timed request's presentation_time is outside the acceptable window
RCP_ERROR_GPTP_FAIL                 = 14, // gPTP time sync is unavailable or has failed
RCP_ERROR_INVALID_PARAMETER         = 15, // a request field's value is out of range or otherwise invalid
RCP_ERROR_CHAIN_ABORTED             = 16, // a chained request sequence was aborted before completion
RCP_ERROR_CHAIN_ERROR               = 17, // a chained request sequence failed internally

What needs to happen (for the agent picking this up)

1. Scope first, don't just start wiring. For each of the 16 codes, find every internal failure condition in the codebase that semantically matches it. Candidate locations, not exhaustive: server.c (routing/dispatch — EP_NOT_FOUND, UNSUPPORTED_CMD), authz.c (UNAUTHORIZED_ACCESS, LOCKED_MEM_ACCESS), sequencer.c/request_compound.c (SEQUENCER_NOT_KNOWN, REQUEST_STORAGE_OVERFLOW), request_cancel.c (REQUEST_CANCELED, REQUEST_NOT_FOUND), request_chained.c (CHAIN_ABORTED, CHAIN_ERROR), request_timed.c (PRESENTATION_TIME_TOO_FAR, GPTP_FAIL), every ep_*.c (EP_ERROR, PWM_IN_NO_SIGNAL in ep_pwm.c specifically), and general request validation (INVALID_PARAMETER).
2. Verify against TC18 text directly which specific conditions each code is meant to cover — don't guess from the enum's one-line paraphrase alone. errors.h's own comment says the numeric values are "the protocol's on-wire contract" reproduced exactly, but the enumerator names/descriptions are this implementation's own paraphrase, not the spec's wording — go back to the primary source (OA_TC18_specification_v_0.5.1_RC.pdf, Table 27 and the surrounding per-request-type error prose) for each mapping.
3. Wire each mapping into the real response-construction path — likely a per-module rcp_<x>_wire_error() function mirroring rcp_e2e_wire_error()'s existing shape, called wherever that failure is actually detected and a response is being constructed.
4. Test each mapping — a real request that triggers the failure condition and asserts the response's err field carries the correct code, not just that an error occurred.
5. Add/update .fusa-reqs.json entries with real tc18 citations to TC18's Table 27 and the specific per-request-type error-condition prose, following this repo's per-function //cfusa:req tagging convention.
6. Verify with a freshly-built, CI-pinned cfusa (check the exact tag in .github/workflows/ci.yml, never trust a cached binary) — check 0 errors, trace --req-coverage 100 --sec-tested 100.
7. Given the size (potentially touching every module), consider whether this should ship as several smaller PRs (e.g. grouped by which module owns the mapping) rather than one large one — this repo's established pattern favors small, fully-verified PRs over big-bang changes.

Not in scope for this issue

• Codes 1 and 12 already have real mappings (UNSUPPORTED_CMD is presumably already used somewhere for command rejection — verify this as part of scoping rather than assuming; POCI_FAILURE is confirmed wired via rcp_e2e_wire_error()).
• This issue is about wiring existing internal failures to the right wire code — it is not about inventing new failure detection that doesn't exist today (e.g. if nothing in the codebase currently detects "gPTP sync unavailable" at all, that's a separate, larger feature gap worth its own issue, not silently folded into this one).

[SoundMatt]

First slice merged: #167 (v0.117.0, BREAKING).

Done:

• rcp_acf_build_error_response() — the primitive that was missing entirely (this library had 0/17 codes actually wired to real response bytes anywhere, including mock.c's own reference integration).
• Compound-wait's reserved evt[2:0]=011b case now sends a real UNSUPPORTED_CMD error response end-to-end — the one rejection path in rcp_server_endpoint_admit() that already has byte_bus_id/transaction_num decoded at the point of rejection.
• rcp_server_endpoint_admit() gained an rcp_wire_error_t *out_error output parameter (breaking, both call sites updated).
• mock.c's rcp_mock_server_dispatch() now actually builds and returns the response.

Important scoping finding for whoever picks up the rest: most of rcp_server_endpoint_admit()'s other 7 rejection paths reject before byte_bus_id/transaction_num (or the opcode-specific fields needed to pick the right Table 27 code) are decoded. TC18 §12.9.6 requires both fields in the response, so those paths can't produce a conformant response without restructuring — decoding enough to identify the request before rejecting, or deferring the reject decision. This isn't a simple "add another if branch" for each — worth a dedicated design pass before touching them, not a mechanical repeat of this PR's pattern.

Still open: 7 rejection paths, 15 of 16 Table 27 codes (SEQUENCER_NOT_KNOWN, UNAUTHORIZED_ACCESS, LOCKED_MEM_ACCESS, REQUEST_CANCELED, REQUEST_NOT_FOUND, EP_ERROR, EP_NOT_FOUND, PWM_IN_NO_SIGNAL, REQUEST_STORAGE_OVERFLOW, REQUEST_REJECTED, PRESENTATION_TIME_TOO_FAR, GPTP_FAIL, INVALID_PARAMETER, CHAIN_ABORTED, CHAIN_ERROR).

[SoundMatt]

Tracking checklist for the remaining 15 codes + 7 rejection paths, mapped to real code locations after a closer read. Working through these in order; will check off and link the merging PR for each as it lands.

Batch A — cancellation-triggered (clean, matches existing 1:1 dispatch-response shape):

• REQUEST_NOT_FOUND (6) — rcp_server_endpoint_cancel_single() already returns RCP_CANCEL_RESULT_NOT_FOUND; mock.c's apply_cancellation() currently discards it ((void)rcp_server_endpoint_cancel_single(...)). byte_bus_id/target_tn are both already decoded at that point.

Batch B — larger design question, separate from Batch A:

• REQUEST_CANCELED (5) — TC18 §11.2.3: "Each request that is cancelled will send an error response with the error code = REQUEST_CANCELED." This is NOT a response to the cancel request itself — each individual request removed by clear-all/clear-single/clear-non-safestate gets its OWN error response, using ITS OWN byte_bus_id/transaction_num. A clear-all could cancel many requests at once. This needs a multi-response fanout the current 1:1 rcp_mock_server_dispatch() API shape doesn't support — real API design work, not a repeat of Batch A's pattern. Scoping separately.

Batch C — Timed request admission (request_timed.c):

• PRESENTATION_TIME_TOO_FAR (13), GPTP_FAIL (14) — need to check what request_timed.c currently validates before wiring.

Batch D — Chained request handling (request_chained.c):

• CHAIN_ABORTED (16), CHAIN_ERROR (17)

Batch E — Routing (server.c/mock.c dispatch):

• EP_NOT_FOUND (8) — already partially handled as RCP_MOCK_DISPATCH_ERR_UNKNOWN_BUS in mock.c's find_slot() path; needs the same real-response treatment. Also the Table 27 note "if a Trigger request refers to a nonexisting EP" — a second, distinct trigger for the same code.

Batch F — Access control (authz.c/regmap.c):

• UNAUTHORIZED_ACCESS (3), LOCKED_MEM_ACCESS (4)

Batch G — The big one, already flagged: decode-before-reject restructuring.

• INVALID_PARAMETER (15), SEQUENCER_NOT_KNOWN (2), REQUEST_STORAGE_OVERFLOW (10) — these are the rcp_server_endpoint_admit() rejection paths that currently reject before byte_bus_id/transaction_num are decoded. Needs a real design pass (decode first, then check storage/validity; or a lighter-weight peek that extracts just bus_id/txn before the heavier per-kind decode) — not attempted until Batch A-F establish the response-building pattern more broadly.

Batch H — Endpoint/config-specific:

• EP_ERROR (7), PWM_IN_NO_SIGNAL (9), REQUEST_REJECTED (11) — endpoint-internal fault reporting and RC-Server-config-phase rejection; need their own per-module investigation.

Already done: UNSUPPORTED_CMD (1, compound-wait reserved evt, #167), POCI_FAILURE (12, rcp_e2e_wire_error() value-mapping — still needs a real consumer check, not yet confirmed to reach an actual response either).

[SoundMatt]

Batch A done: #168 (v0.118.0), merged and verified. REQUEST_NOT_FOUND now sent for clear-single cancellation targets that aren't found. Moving to Batch D (CHAIN_ABORTED/CHAIN_ERROR) next — turns out cleanly tractable, since rcp_mock_server_dispatch_frame() already has a per-member response array (not the single-response constraint that blocks Batch B/REQUEST_CANCELED).

[SoundMatt]

Batch D done: #169 (v0.119.0), merged and verified. CHAIN_ERROR/CHAIN_ABORTED now sent as real per-member responses in rcp_mock_server_dispatch_frame(), each carrying its own transaction_num — no fanout problem here since that function's result array is already per-member.

Progress so far: 4 of 17 codes now have real wiring (UNSUPPORTED_CMD, REQUEST_NOT_FOUND, CHAIN_ERROR, CHAIN_ABORTED). Continuing to batch E (EP_NOT_FOUND routing) next.