AX Principle 2 — comments as usage examples: the ReadAndVerify doc
comment only showed the success path; both errMissingHMAC and
errIntegrityViolation sentinel branches are now illustrated so callers
can copy-paste correct dispatch logic.
Co-Authored-By: Charon <charon@lethean.io>
AX Principle 2: comments show usage examples, not descriptions.
The trailing "raw bytes after the 0xFF payload tag" restated what
the tag constant already communicates — deleted.
Co-Authored-By: Charon <charon@lethean.io>
Comment "→ covers all header TLVs before the HMAC tag" was prose
describing effect rather than showing usage with concrete values,
violating AX Principle 2 (comments as usage examples, not descriptions).
Replaced with a full usage example showing all three messageAuthCode calls.
Co-Authored-By: Charon <charon@lethean.io>
Variables e, a, b violate AX Principle 1 (predictable names over short names).
Renamed to sentinel, sentinelFirst, sentinelSecond across test functions and
the usage-example comment in packet.go.
Co-Authored-By: Charon <charon@lethean.io>
TestPacket_sentinelError_{Good,Bad,Ugly} were absent — AX requires all
three test categories for every exported and package-level function.
The Error() method on sentinelError had no direct coverage.
Co-Authored-By: Charon <charon@lethean.io>
The comment on `sentinelError` restated the `errTLVValueTooLarge`
declaration directly above it (AX principle 2 violation). Replaced
with a distinct concrete example showing how to define any sentinel
of this type.
Co-Authored-By: Charon <charon@lethean.io>
AX Principle 2 — comments must show realistic usage with actual values from
the codebase, not placeholder examples. The sentinelError type comment used
errNotFound (a fictional variable) instead of errTLVValueTooLarge (the actual
sentinel declared on the next line).
Co-Authored-By: Charon <charon@lethean.io>
AX Principle 2 requires comments to show concrete usage with realistic values.
The writeTLV comment used `intentID` (a variable name) as a placeholder
rather than a real value; replaced with `0x01` and added error-capture
pattern to show the full call site shape.
Co-Authored-By: Charon <charon@lethean.io>
Comment described assertion in prose ("integrity violation" in error message) rather
than showing the concrete sentinel pattern. Test also failed to verify err identity
consistently with TestReader_ReadAndVerify_Ugly and packet_test.go error tests.
Co-Authored-By: Charon <charon@lethean.io>
Replaces `header := UEPSHeader{}` with `var header UEPSHeader` for
consistency with the surrounding zero-value var declarations in the
same block — predictable, uniform pattern over mixed init styles.
Co-Authored-By: Charon <charon@lethean.io>
AX-2 — the Error() method on sentinelError had no comment; added a
concrete call-and-result example so an agent can understand the
sentinel identity contract without tracing the type definition.
Co-Authored-By: Charon <charon@lethean.io>
sentinelError had no comment, violating AX Principle 2 (comments as
usage examples). Added a concrete call-site example showing sentinel
identity comparison pattern.
Co-Authored-By: Charon <charon@lethean.io>
AX Principle 2: usage example comments must show realistic call sites.
The writeTLV header comments used `buffer` as the first argument name,
but the parameter is `writer` and all callers pass `frameBuffer`.
Co-Authored-By: Charon <charon@lethean.io>
The type name uepsError used the package abbreviation as a prefix, which
adds no semantic value inside the ueps package and violates AX Principle 1
(predictable names over short names). sentinelError names what the type IS:
an immutable, comparable error value.
Co-Authored-By: Charon <charon@lethean.io>
The type was named packetError but also used in reader.go for reader-side
sentinel errors (errMissingHMAC, errIntegrityViolation). The name implied
packet-only scope, misleading agents reading reader.go. uepsError names the
type after the package it belongs to, matching AX principle 1.
Co-Authored-By: Charon <charon@lethean.io>
AX Principle 2 — comments must show usage examples, not restate what
the code already says. The inline comment in the default branch of
ReadAndVerify's tag-switch duplicated the three lines beneath it verbatim,
adding zero information.
Co-Authored-By: Charon <charon@lethean.io>
Test doc-comments used `// //` to prefix expected-result lines, producing
comments-within-comments rather than clean usage examples. Strip the
redundant inner `//` so all lines read as plain code-example comments.
Co-Authored-By: Charon <charon@lethean.io>
signedData was ambiguous — it did not convey that the buffer holds
accumulated header TLVs fed as input to HMAC, nor whether data was
already signed or pending signing. hmacInputBuffer makes the purpose
unambiguous on first read (AX Principle 1: predictable names over
short names).
Co-Authored-By: Charon <charon@lethean.io>
TagCurrentLayer, TagTargetLayer, TagIntent, and TagThreatScore were
exported constants with no comment, violating AX Principle 2 (comments
as usage examples). Each now has a concrete writeTLV call showing the
tag, value encoding, and valid range where relevant.
Co-Authored-By: Charon <charon@lethean.io>
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>
