Comment promised errTLVValueTooLarge but test only checked err != nil.
AX Principle 2 requires comments to be accurate usage examples —
the comment implied sentinel identity so the assertion must verify it.
Co-Authored-By: Charon <charon@lethean.io>
AX principle 2 requires comments to show usage with real values. The
MarshalAndSign call in the NewPacketBuilder doc comment used a variable
name (sharedSecret) instead of a concrete literal.
Co-Authored-By: Charon <charon@lethean.io>
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>
Receiver name `packetError` shadowed the type name and violated AX
Principle 1 — names must be predictable and not require a comment
to explain. `packetErrorValue` is unambiguous as the bound value.
Co-Authored-By: Charon <charon@lethean.io>
`packetErr` is an abbreviation of the full type name `packetError`.
AX Principle 1 requires predictable names over short names — receiver
renamed to the full type name to eliminate mapping overhead.
Co-Authored-By: Charon <charon@lethean.io>
Single-letter receiver `e` is not in the AX-permitted list
(i, _, t, c). Renamed to `packetErr` for predictable naming.
Co-Authored-By: Charon <charon@lethean.io>
Commented-out var declarations are not usage examples — they are dead
code that adds noise. AX Principle 2 requires comments to show concrete
usage, not linger as disabled code.
Co-Authored-By: Charon <charon@lethean.io>
packetErr is a shortened form of packetError, violating AX Principle 1
(predictable names over short names). Single-letter e is explicitly
permitted for value receivers per RFC-CORE-008-AGENT-EXPERIENCE.md.
Co-Authored-By: Charon <charon@lethean.io>
RFC-025 Principle 1: single-letter names are only permitted for i (range),
_ (discards), t (tests), and c (*core.Core). The receiver variable e is
not in the allowed list — packetErr is predictable and removes the mapping
overhead.
Co-Authored-By: Charon <charon@lethean.io>
AX Principle 2: comments show HOW with real values, not prose descriptions.
`// 0x09 = IPv9` described the constant; `// header.Version = 0x09 // IPv9`
shows the assignment as used, matching all other UEPSHeader field comments.
Co-Authored-By: Charon <charon@lethean.io>
AX Principle 2: comments show HOW with real values, not variable
references. Replace builder.Header.Version with the concrete 0x09
literal so the comment matches what the output annotation shows.
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>
Comment on line 126 showed `err` but implementation used `verifyError`,
violating AX Principle 2 (comment must match usage example) and Principle 1
(err is the RFC-sanctioned idiomatic name for local error variables).
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>
AX Principle 2: comments that restate what the surrounding code already
says are noise. The inline comment inside TestReader_ReadAndVerify_Ugly
duplicated the usage example already present in the function docstring.
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>
AX Principle 2: comments must be usage examples, not prose descriptions.
"Corrupt the last byte of the payload/frame" restates what the adjacent
code does rather than demonstrating a call with concrete values.
Co-Authored-By: Charon <charon@lethean.io>
tagByte described the storage representation; tagType names the semantic
role (the T in TLV = Type-Length-Value), matching AX Principle 1.
Co-Authored-By: Charon <charon@lethean.io>
AX Principle 2: comments must show concrete usage, not prose rationale.
"Assumed innocent until proven guilty" explains intent but shows no usage.
Replaced with a concrete mutation example per the RFC convention.
Co-Authored-By: Charon <charon@lethean.io>
AX Principle 1: predictable names over short names. Parameters named
`tag` and `value` lack context; `tagByte` and `tagValue` are
self-documenting and consistent with the naming used in reader.go.
Co-Authored-By: Charon <charon@lethean.io>
AX Principle 2: comments must be usage examples, not prose descriptions.
The inline comment restated intent in English rather than showing a concrete call.
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>
AX Principle 2 — comments must show concrete usage with realistic values,
not abstract placeholder names. The struct-level comment for PacketBuilder
used `intentID` and `payload` (undefined in context); replaced with 0x01
and []byte("ping") so an agent reading it sees an exact working call.
Co-Authored-By: Charon <charon@lethean.io>
Comment used abbreviated `w` instead of the actual parameter name `writer`,
violating AX Principle 1 (predictable names over short names).
Co-Authored-By: Charon <charon@lethean.io>
AX Principle 2: comments must show usage with concrete values, not
restate what the type signature already says. All other UEPSHeader
field comments used assignment examples; ThreatScore was the outlier.
Co-Authored-By: Charon <charon@lethean.io>
AX Principle 1 — predictable names over short names. The const-block comment
used buf and sig; updated to buffer and hmacSignature to match the descriptive
naming used throughout the rest of the package.
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>
// TLV Types restated what Tag* names already made obvious (AX §2 violation).
Replace with a concrete usage example showing the three-tag write sequence.
Co-Authored-By: Charon <charon@lethean.io>
CurrentLayer and TargetLayer had prose descriptions restating the field
names. AX Principle 2 requires comments to show concrete usage with real
values, not restate what the type signature already says.
Co-Authored-By: Charon <charon@lethean.io>
AX Principle 2 — comments show HOW with real values, not prose describing
what the code does. "Verify each expected tag is present in the frame"
restated intent with zero new information; replaced with a concrete call
showing the bytes.Contains check and the expected result.
Co-Authored-By: Charon <charon@lethean.io>
Generic name "buffer" violates predictable-names-over-short-names.
"frameBuffer" names the thing by what it holds.
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>
AX principle 2 requires comments to show HOW via concrete examples,
not describe WHAT the code does in prose.
Co-Authored-By: Charon <charon@lethean.io>
MarshalAndSign had a prose comment "We write these first because they
are part of what we sign." — deleted per AX Principle 2 (comments as
usage examples, not prose descriptions). Replaced with a concrete
writeTLV call showing the wire encoding output.
Co-Authored-By: Charon <charon@lethean.io>
Test names must match the exact function name (NewPacketBuilder), not an
abbreviated form (NewBuilder). AX principle 1: predictable names over short names.
Co-Authored-By: Charon <charon@lethean.io>
Misaligned const tag values and trailing comment spacing violated
gofmt canonical formatting, reducing readability for agents scanning
the TLV tag table.
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>
Ambiguous constructor name required reading the return type to know what
it builds. NewPacketBuilder is self-documenting without context.
Co-Authored-By: Charon <charon@lethean.io>
TestReader_ReadAndVerify_Ugly previously tested wrong-secret (errIntegrityViolation),
duplicating the Bad case. Replaced with a hand-crafted frame that omits the HMAC TLV,
exercising the errMissingHMAC sentinel that was entirely untested.
Co-Authored-By: Charon <charon@lethean.io>
AX Principle 2: comments must show usage, not restate the name.
"semantic token identifying the packet's purpose" repeats what IntentID
already says — replaced with a concrete value example.
Co-Authored-By: Charon <charon@lethean.io>
