Skip to content

docs: fix TC18.txt citation drift in e2e.rs (issue #164 batch 4, final) - #168

Merged
SoundMatt merged 1 commit into
mainfrom
docs/fix-tc18-citation-drift-e2e-batch4
Aug 20, 2026
Merged

docs: fix TC18.txt citation drift in e2e.rs (issue #164 batch 4, final)#168
SoundMatt merged 1 commit into
mainfrom
docs/fix-tc18-citation-drift-e2e-batch4

Conversation

@SoundMatt

Copy link
Copy Markdown
Owner

Summary

Final batch of issue #164 (batches 1-3: #165, #166, #167, all merged). This
covers the last flagged file, src/e2e.rs (REQ-CRC group), which the issue
explicitly called out as needing more than a mechanical line-number
relocation: TC18 §13.6 "End-to-End data protection (safe endpoints)" was
substantively reworded between RC4 and RC5 revisions — TC18.txt itself
carries Commented [BE35] through [BE41] revision markers throughout this
section, confirming the underlying spec text changed, not just its
pagination.

Every TC18.txt citation in e2e.rs's doc/test comments was re-verified
individually against the current canonical TC18.txt (not trusted from any
in-repo copy — none exists there). Per the task brief, citations that
genuinely could not be cleanly resolved were left as honest, explicit flags
rather than guessed at — this file backs REQ-CRC (frame-integrity /
safety-relevant) entries, so a wrong citation is worse than an admitted gap.

Doc-comment-only change. cargo build / cargo test --lib: 1168 tests
pass
, unchanged from batches 1-3. cargo fmt --check: clean. git diff --stat: only src/e2e.rs touched. No .fusa-reqs.json or test-logic
changes.


Cleanly relocated citations

# Old citation (stale) Fact New citation Proof (sed -n 'N p' TC18.txt)
1 TC18.txt line 3792, "Table 31 CRC32 Polynomial" Names the CRC CRC32P4; six parameters (Polynomial 0xF4ACFB13, Width 32, Initial Value/Final XOR 0xFFFFFFFF, Input/Output reflection TRUE) Table 34 "CRC32 Polynomial", TC18.txt line 4193 (sentence) / caption at line 4208, table body 4193-4207 4193: 13 The CRC will use the CRC32P4 defined by: / 4208: 14 ... Table 34: CRC32 Polynomial. Genuine table renumber: current "Table 31" now names an unrelated table ("ep_generic_config register map", line 3980). Six parameter values confirmed unchanged.
2 TC18.txt line 3789: "the CRC32 is ACF specific, which means it is calculated for multiple ACF types in one AVTPDU for each ACF type individually" CRC is computed independently per ACF type TC18.txt line 4191 (reworded, same fact) 4191: 11 In Safe command mode a CRC32 is calculated per ACF type across specific fields of an AVTPDU header, ACF header,
3 TC18.txt line 3808: "The CRC calculation for request and response follows the identical scheme" No direction bit in the CRC scheme itself TC18.txt line 4276 (near-verbatim; singular→plural) 4276: 14 The CRC calculation for requests and responses follows the identical scheme. (this line itself carries a Commented [BE39]: 051RC4 - text and figure updated marker, confirming the RC4 touch-point even though the actual wording only trivially changed here)

Each of these facts appears twice in the file (once in a /// doc comment,
once in the corresponding // test comment); both occurrences of each were
updated identically.


NOT cleanly resolved — flagged, not fixed

These are the substantive part of this batch. In every case I searched
current TC18.txt exhaustively (exact phrase + topic/keyword search around
§13.6) before concluding the old text is genuinely gone, not just moved.

1. acf_msg_length +1 rule — second clause has no surviving text (was: TC18.txt line 3798)

Old citation quoted: "Before CRC calculation it is essential to adapt the
acf_message_length by plus 1 quadlet for the CRC32 addition to the payload
and in the AVTPD to increase the ntscf_data_length or in an TSCF header the
stream_data_length by 4 octets per ACF type in the ACF payload being E-2-E
protected."

  • The first half (acf_msg_length +1) survives, reworded, at
    TC18.txt line 4272: "When calculating the CRC, it needs to be
    considered that adding the CRC to the byte_msg_payload increases the
    acf_msg_length by 1."
    — relocated the citation to this line.
  • The second half (bump ntscf_data_length/stream_data_length by 4
    octets per E-2-E-protected ACF type at the AVTPDU level) — I could not
    find this rule anywhere in current TC18.txt. grep -n "ntscf_data_length\|stream_data_length" over the whole file returns only
    the two header-diagram field labels (Figure 20/21), never in adjustment-rule
    prose. grep -ni "4 octets" finds nothing relevant either.
  • Why this matters: this module's own doc comment cites that now-missing
    clause as the reason requirement REQ-CRC-016 ("not implemented anywhere
    in this crate") exists. I left an explicit flag in the doc comment instead
    of resolving it: it's genuinely unclear whether the RC4/RC5 revision
    dropped that requirement (making REQ-CRC-016 moot) or relocated it
    somewhere my search didn't recognize.
  • Assessment: this looks like a real spec-conformance question, not just
    an unresolvable citation search — worth a follow-up issue to determine
    whether REQ-CRC-016 should be closed, restated, or left as-is.

2. Fragmented-CRC header rule — genuinely restructured (was: TC18.txt line 3801)

Old citation quoted: "For fragmented requests or responses going through CRC
calculation only the first AVTPDU and ACF header data will be used and the
payload of all segments."
This backed a known, recorded divergence
(REQ-CRC-015): rust-RCP uses the train's final fragment's header, not
the first, as the old spec text required.

  • grep -ni "first AVTPDU\|first ACF header\|payload of all segments" over
    all of TC18.txt returns nothing. This sentence does not exist anywhere in
    the current text.
  • The closest current text, TC18 §13.6 (TC18.txt lines 4274-4275): "Fragmentation,
    if applied to a message, happens after CRC calculation. So, the CRC is
    only calculated once and will be transmitted in the last segment."
    This
    supports the module's "final fragment carries the CRC" placement rule
    (REQ-CRC-008/010), but says nothing about which fragment's header
    the coverage buffer is computed over — the specific thing REQ-CRC-015
    is about. Read literally, "happens after CRC calculation" suggests the CRC
    may now be computed once, before the message is even split into fragments,
    over a single not-yet-fragmented header — sidestepping the old
    first-vs-final distinction rather than resolving it either way.
  • I left this as an explicit, unresolved flag in the doc comment rather than
    either (a) declaring the module correct or (b) inventing a citation that
    claims the old rule still applies.
  • Assessment: this is a real spec-conformance question worth its own
    follow-up issue — REQ-CRC-015's premise (a first-vs-last fragment header
    choice) may no longer map cleanly onto the current spec text at all, and
    that needs engineering judgment against the current wording, not a
    citation-only pass.

3. Figure 19/20 (ACF_ABB/ACF_GBB worked examples) — renumbered, and GBB content changed

  • Confirmed renumber: current TC18.txt captions these worked examples as
    Figure 20 ("ACF_ABB under TSCF header (example)", line 4231) and
    Figure 21 ("ACF_GBB under NTSCF header (example)", line 4264).
    "Figure 19" now names a completely different figure ("Configuration
    request", line 2860).
  • This exactly mirrors src/acf.rs's own equivalent finding, already fixed
    in issue Systemic TC18.txt citation-drift in src/*.rs doc comments (17 files, ~57% of checked citations) — mirrors c-RCP#434 #164 batch 1 (docs: fix TC18.txt citation drift in acf.rs/avtp.rs/can.rs doc comments (issue #164 batch 1) #165) — that PR's note additionally found the
    ACF_GBB example's content changed, not just its number (a different
    payload/pad byte split of the same 28-byte/7-quadlet total), under a
    Commented [BE39]: 051RC4 - text and figure updated marker immediately
    after the CRC section text.
  • e2e.rs has two golden-vector tests,
    finalize_crc_trailer_matches_figure_19_worked_example and
    finalize_crc_trailer_matches_figure_20_worked_example, whose names,
    internal comments, and assert-failure strings all still say "Figure
    19"/"Figure 20", and whose ACF_GBB test still encodes the old 7
    payload + 1 pad split. I added doc-comment notes flagging the renumber and
    content-change (mirroring acf.rs's note) but did not rename the test
    functions or touch their byte layout — that's a code/test-logic change,
    explicitly out of scope for a citation-only fix per the task brief.
  • Assessment: acf.rs's own note argues the crate's actual logic only
    depends on the aggregate acf_msg_length = 0x07/28-byte total, which is
    unaffected either way — so this is lower-severity than items 1-2 above,
    but is included here for completeness and because it touches the same
    worked examples these REQ-CRC golden vectors pin. Worth folding into the
    same follow-up issue as items 1-2, or a small standalone one, rather than
    fixing silently now.

Verification

  • cargo build: clean.
  • cargo test --lib: 1168 passed; 0 failed (unchanged from batches 1-3).
  • cargo fmt --check: clean.
  • git diff --stat: src/e2e.rs only.
  • No .fusa-reqs.json, code, or test-logic changes.

Not merging this myself — leaving open for independent review, per the task
brief. Happy to file the follow-up issue(s) for the two flagged
spec-conformance questions once this is reviewed, if that's useful.

Final batch of issue #164: re-verifies every TC18.txt citation in
e2e.rs's doc/test comments (REQ-CRC group) against the current
canonical TC18.txt, individually. Unlike batches 1-3, most of this
file's citations needed more than a line-number relocation — TC18's
§13.6 "End-to-End data protection" section was substantively reworded
between RC4 and RC5 (TC18.txt carries `Commented [BE35]`-`[BE41]`
revision markers throughout this section), not just re-paginated.

Cleanly relocated (same underlying fact, confirmed by exact/near-exact
text match):
- Table 31 "CRC32 Polynomial" -> Table 34 (genuine renumber; content
  unchanged - same six parameters/values, TC18.txt lines 4193-4208).
  "Table 31" now names an unrelated table (ep_generic_config register
  map).
- "the CRC32 is ACF specific... for each ACF type individually"
  (old TC18.txt line 3789) -> reworded, same fact, at TC18.txt line
  4191: "In Safe command mode a CRC32 is calculated per ACF type
  across specific fields of an AVTPDU header, ACF header, and the
  entire payload (except padding)."
- "The CRC calculation for request and response follows the identical
  scheme" (old line 3808) -> near-verbatim at TC18.txt line 4276
  ("requests and responses").

Flagged, deliberately NOT resolved (genuine RC4/RC5 content changes,
not just relocatable citations - see PR description for full
rationale):
- The acf_msg_length +1 quadlet rule's citation (old line 3798)
  survives reworded at TC18.txt line 4272, but its second clause
  (ntscf_data_length/stream_data_length +4 octets per ACF type,
  backing requirement REQ-CRC-016) has no surviving textual
  counterpart anywhere in current TC18.txt - full-text search finds
  nothing. Left as an honest flag rather than fabricating a citation
  for a rule that may no longer exist in the spec.
- The fragmented-CRC "first AVTPDU/ACF header" rule (old line 3801,
  backing the known REQ-CRC-015 divergence) is genuinely gone, not
  reworded - the current text (TC18.txt lines 4274-4275) no longer
  states which fragment's header the CRC covers at all, which may
  moot or restate REQ-CRC-015's premise. Flagged, not resolved.
- Figure 19 (ACF_ABB) / Figure 20 (ACF_GBB) worked examples are
  renumbered to Figure 20/21, and the ACF_GBB example's content
  changed too (different payload/pad byte split under a `Commented
  [BE39]: 051RC4 - text and figure updated` marker), mirroring
  src/acf.rs's own equivalent, already-fixed finding (issue #164
  batch 1). Test names/assert strings that embed the old figure
  numbers and the old ACF_GBB byte split are left untouched (renaming
  a test or its golden vectors is a code/test-logic change, out of
  scope for a citation-only fix) - flagged via doc-comment notes
  instead.

Doc-comment-only change: cargo build/cargo test --lib unaffected
(1168 tests pass, unchanged), cargo fmt --check clean, no public API
or .fusa-reqs.json change.

Signed-off-by: SoundMatt <47545907+SoundMatt@users.noreply.github.com>
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Signed-off-by: Matt <47545907+SoundMatt@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant