The comment said "threat score incremented" and the error string said
"(ThreatScore +100)" but ReadAndVerify never mutates ThreatScore — it
only returns an error. Updated the comment to show the caller's
responsibility (header.ThreatScore += 100) and removed the parenthetical
from the error string.
Co-Authored-By: Charon <charon@lethean.io>
AX Principle 2 requires comments to show concrete usage, not describe
behaviour. The old comment restated when fields are populated; the new
comment shows the dispatch call an agent would make after ReadAndVerify.
Co-Authored-By: Charon <charon@lethean.io>
AX Principle 2 — comments as usage examples, not restatements.
ParsedPacket carried the identical dispatch example twice: once above
the type and again above ReadAndVerify. The type-level copy added no
new information; replaced with a field-reference note that describes
what the struct exposes without duplicating the call-site example.
Co-Authored-By: Charon <charon@lethean.io>
ParsedPacket comment used `_ = packet.Header.IntentID` — a discard
pattern that is not a realistic usage example (AX-2 violation). Replaced
with `dispatch(packet.Header.IntentID, packet.Header.ThreatScore, packet.Payload)`
to show how callers actually consume the parsed packet fields.
Co-Authored-By: Charon <charon@lethean.io>
tlvError used an abbreviated subsystem name (tlv = Type-Length-Value),
requiring domain knowledge to decode. packetError is self-describing
from the path alone, matching the AX rule: predictable names over short names.
Co-Authored-By: Charon <charon@lethean.io>
Per AX Principle 2, comments must show concrete usage, not describe intent.
The `default:` branch comment now demonstrates the write calls rather than
explaining what they protect against.
Co-Authored-By: Charon <charon@lethean.io>
The default switch-case comment in ReadAndVerify restated the three
lines immediately following it verbatim, violating AX Principle 2
(comments as usage examples, not code descriptions). Replaced with a
single line explaining the security intent of the behaviour.
Co-Authored-By: Charon <charon@lethean.io>
tagByte described the storage type (a byte), not the purpose. All
constants in the package use Tag* naming (TagVersion, TagPayload, etc.)
so the loop variable should match: tagType aligns with the domain
vocabulary and satisfies AX Principle 1 (predictable names over short
names).
Co-Authored-By: Charon <charon@lethean.io>
The comment omitted tagValueLength from the signedData write sequence,
making it an incorrect usage example (AX Principle 2).
Co-Authored-By: Charon <charon@lethean.io>
The inner scope re-declared `var err error` immediately before assigning
from `io.ReadAll`, unnecessarily shadowing the `err` already in scope from
`reader.ReadByte()`. Removing the shadow simplifies the control flow and
eliminates the redundant declaration (AX Principle 1 — names should not
introduce unnecessary cognitive overhead).
Co-Authored-By: Charon <charon@lethean.io>
The default switch case comment referenced `unknownTag` which does not
exist in scope; the actual variable is `tagByte`. AX Principle 2 requires
comments to show real, runnable examples — not invented identifiers.
Co-Authored-By: Charon <charon@lethean.io>
AX Principle 1 — the `Byte` suffix encodes storage type not semantics,
and the intermediate `tagLength` variable was an immediate int cast of
`tagLengthByte` with no additional meaning. Collapsed to a single
`tagValueLength` variable that names what it is, not how it is stored.
Co-Authored-By: Charon <charon@lethean.io>
The variable name `signature` is ambiguous — any cryptographic operation
produces a signature. `hmacSignature` is unambiguous and self-describing,
consistent with the TagHMAC comment that already used `hmacSignature` as
the example parameter name.
Co-Authored-By: Charon <charon@lethean.io>
AX Principle 2: comments must show usage, not describe intent in prose.
The default switch branch comment was prose-first; rewritten as a
concrete call-site example that shows what the code does and why.
Co-Authored-By: Charon <charon@lethean.io>
AX Principle 2 — comments as usage examples. The default switch case in
ReadAndVerify silently included unknown extension tags in signedData with
no explanation of why; added a concrete comment showing the pattern and
the security rationale (tag-injection prevention).
Co-Authored-By: Charon <charon@lethean.io>
Internal numbered step comments (1. Read Tag, 2. Handle Payload Tag, etc.)
restate what the code does rather than showing concrete usage examples.
Per RFC-CORE-008 Principle 2: delete comments that restate what the code
already expresses; keep only usage examples with realistic values.
Co-Authored-By: Charon <charon@lethean.io>
payload was declared via var at the top of ReadAndVerify; the inner
payloadBytes := io.ReadAll + payload = payloadBytes pattern introduced
an unnecessary name that added no semantic value. Assign directly to
the outer payload variable instead.
Co-Authored-By: Charon <charon@lethean.io>
AX Principle 1: names should convey semantic meaning, not implementation
perspective. `remaining` describes a buffer operation; `payloadBytes`
describes what the data IS — the packet payload content.
Co-Authored-By: Charon <charon@lethean.io>
`tag` is not in the accepted single-letter exception list (i, _, t, c).
`tagByte` is self-describing: the byte value of the TLV tag field.
Co-Authored-By: Charon <charon@lethean.io>
MAC is an abbreviation requiring context; expectedMessageAuthCode matches
the established messageAuthCode pattern and is self-describing (AX §1).
Co-Authored-By: Charon <charon@lethean.io>
AX Principle 1 — Predictable Names Over Short Names: `length` and
`lengthByte` are too generic for the TLV parsing context. Renamed to
`tagLength` and `tagLengthByte` so the variable names are
self-describing at read time.
Co-Authored-By: Charon <charon@lethean.io>
AX Principle 2: "If a comment restates what the type signature already says,
delete it." The "Store for processing" comment above the switch statement added
no information — the switch itself communicates that action.
Co-Authored-By: Charon <charon@lethean.io>
AX Principle 2 requires comments to show correct usage patterns.
errMissingHMAC and errIntegrityViolation are tlvError sentinels (comparable
values), so the examples should use == not errors.Is from the banned errors
package.
Co-Authored-By: Charon <charon@lethean.io>
AX-2 violation: usage examples belong at the declaration site, not
scattered inside function bodies. The errIntegrityViolation usage hint
was already present at the variable declaration (line 17) and was
duplicated inside ReadAndVerify, creating noise in the implementation.
Co-Authored-By: Charon <charon@lethean.io>
AX Principle 2: comments show usage, not prose descriptions of what the code
does. The two inline comments in ReadAndVerify described buffer reconstruction
in words rather than showing a call — deleted per RFC-025 §2.
Co-Authored-By: Charon <charon@lethean.io>
AX Principle 1: predictable names over short names. The generic
local variable `value` required surrounding context to understand;
`tagValue` is self-documenting at every read site in the switch.
Co-Authored-By: Charon <charon@lethean.io>
Test names encode intent — prose descriptions add zero information.
Per AX-2: if comment restates the signature, delete it.
Co-Authored-By: Charon <charon@lethean.io>
Seven setter/getter comments restated the function signature rather than
showing a concrete call (AX Principle 2). Replaced all with real invocation
examples so agents know exactly how to call each method.
Co-Authored-By: Charon <charon@lethean.io>
errMissingHMAC and errIntegrityViolation comments were prose
descriptions. Replaced with errors.Is() usage patterns.
Co-Authored-By: Charon <charon@lethean.io>
Single-letter variables in comments teach bad habits to agents.
Usage examples must use predictable names matching AX principle 1.
Co-Authored-By: Charon <charon@lethean.io>
NewBuilder, MarshalAndSign, ReadAndVerify, PacketBuilder, and ParsedPacket
comments now show concrete call-site examples with real values instead of
restating what the type signatures already convey.
Co-Authored-By: Charon <charon@lethean.io>
Abbreviated constant names violated AX Principle 1 (Predictable Names Over
Short Names). The struct fields already used CurrentLayer/TargetLayer — the
constants now match, eliminating the inconsistency.
Co-Authored-By: Charon <charon@lethean.io>
