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>
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>
Numeric suffixes (frame1, frame2) violate AX principle 1 — predictable
names over short names. Descriptive names make the test intent clear
without reading the assertions.
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>
AX Principle 1 — predictable names over short names. Test comments showing
writeTLV usage had buf (abbreviated) while the actual code used buffer
(descriptive). Comments are usage examples that agents learn from; the name
must match what an agent would write.
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/non-standard names.
errorA and errorB are not ecosystem-standard; err is the correct
name for error variables. Each call now checks err immediately after
capture, matching the established Go and Core convention.
Co-Authored-By: Charon <charon@lethean.io>
Comment was teaching agents to use the banned errors package.
Direct sentinel comparison (err == errTLVValueTooLarge) is correct.
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>
TestPacket_MarshalAndSign_Ugly commented "modifying any byte breaks HMAC
verification" (prose description) but never called ReadAndVerify to prove it.
Replaced with a usage-example comment and an actual ReadAndVerify call that
asserts errIntegrityViolation is returned — AX Principle 2.
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 1 — predictable names over short names. Comments showing
usage examples must use the same full names as the implementation:
'buffer' not 'buf'.
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. 'result' does not
describe what it holds; 'encodedTLV' names the TLV-encoded byte slice
exactly, matching the function under test.
Co-Authored-By: Charon <charon@lethean.io>
TagHMAC and TagPayload had inline prose comments ("The Signature",
"The Data") that restated what the names already convey. Replace
with concrete call-site examples per AX Principle 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>
AX Principle 2 — comments must be usage examples, not prose descriptions.
The leading "verifies a well-formed signed frame" line restated the test
name without adding information; the usage example below it was sufficient.
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>
The comment was a duplicate of errTLVValueTooLarge's example.
Fixed to show how tlvError defines new sentinels.
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>
One test file per source file is mandatory per AX conventions. reader.go
had no corresponding test file — this adds the three required test cases
covering valid round-trip, tampered frame rejection, and wrong-secret rejection.
Co-Authored-By: Charon <charon@lethean.io>
Renamed `allowedPublicKeyMu` to `allowedPublicKeyMutex` in PeerRegistry.
`Mu` is an abbreviation that violates AX Principle 1 (predictable names
over short names) — the full word `Mutex` removes any ambiguity about
what the field represents.
Co-Authored-By: Charon <charon@lethean.io>
