TestPacket_NewPacketBuilder_Bad and _Ugly used inline []byte("secret")
literals; extracted to sharedSecret variable per AX Principle 1
(predictable names over magic literals).
Co-Authored-By: Charon <charon@lethean.io>
AX Principle 1 — predictable names over short names.
The variable reader is ambiguous; frameReader states
exactly what is being read.
Co-Authored-By: Charon <charon@lethean.io>
Use sharedSecret in doc-comment examples to match actual test body
variable names — resolves AX principle 1+2 violation where comment
examples used the abbreviated form secret while code used sharedSecret.
Co-Authored-By: Charon <charon@lethean.io>
TestFilename_Function_{Good,Bad,Ugly} requires the function being
tested, not just the type name. sentinelError tests exercise the
.Error() method so names must be TestPacket_sentinelError_Error_*.
Co-Authored-By: Charon <charon@lethean.io>
Generic name `header` replaced with `packetHeader` throughout ReadAndVerify
to satisfy AX predictable-names-over-short-names; the name now conveys what
is being built without requiring context from the surrounding function.
Co-Authored-By: Charon <charon@lethean.io>
Variable name tagLengthByte encoded its type (byte) rather than its role
(the length field of a TLV record). AX Principle 1: names must be semantic,
not type-annotated. tagLength is unambiguous without the redundant Byte suffix.
Co-Authored-By: Charon <charon@lethean.io>
TestReader_ReadAndVerify_Bad referenced `frame` without defining it in
the comment block, leaving an agent without enough context to understand
the setup. Replace with a complete, standalone snippet showing frame
construction, corruption, and the expected error outcome.
Co-Authored-By: Charon <charon@lethean.io>
Variable named tagValueLength implied int semantics but held a byte
value from ReadByte(); AX Principle 1 requires names that are
unambiguous without comments — tagLengthByte makes the type explicit
and the int(tagLengthByte) cast at make() call site clarifies the
byte→int conversion for agent readers.
Co-Authored-By: Charon <charon@lethean.io>
AX Principle 2: comments show concrete usage with realistic values, not
minimal call-site only. Single-line comment omitted error handling and
downstream use — now shows the complete call pattern.
Co-Authored-By: Charon <charon@lethean.io>
Comment examples used 'buffer' but the parameter is named 'writer' —
the example was not a valid call site. AX Principle 2 requires comments
to show concrete, accurate usage with real values.
Co-Authored-By: Charon <charon@lethean.io>
Four separate var statements in ReadAndVerify consolidated into a
var () block — more declarative and AX principle #5 compliant.
Co-Authored-By: Charon <charon@lethean.io>
AX Principle 2: comments must show HOW with real values, not placeholder names.
`oversized` is a non-executable placeholder; `bytes.Repeat([]byte("x"), 256)` is
the concrete call that produces the error, matching the example already used in
the writeTLV body comment.
Co-Authored-By: Charon <charon@lethean.io>
PacketBuilder.Header and .Payload lacked inline usage comments,
inconsistent with the pattern established by UEPSHeader fields.
AX Principle 2 requires comments as usage examples, not prose.
Co-Authored-By: Charon <charon@lethean.io>
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>
