boundary-semantics-review

name

boundary-semantics-review

description

Review code that checks, transforms, maps, parses, formats, normalizes, sanitizes, encodes, decodes, truncates, or hardens values as they cross API, persistence, serialization, storage, protocol, or UI boundaries. Use to catch representation constraints leaking into domain rules, ambiguous helper names, unjustified lossy transformations, magic limits, defensive behavior outside the current scope, and validation at the wrong layer.

Boundary Semantics Review

Use this skill as a focused review pass when code moves values between system concepts and concrete representations.

Do not start by asking whether the code is "safe." Start by asking what each value means.

Classify Values First

For each important value, identify:

• Semantic role: identity, label, enum, token, timestamp, locator, key, payload, query, command, display text, or serialized record.
• Source: generated by this code, configured state, external input, persisted state, derived value, or third-party response.
• Boundary: API, database, file/object storage, queue, cache, URL, logs, UI, serialization, authorization, or process boundary.
• Operation: validate, encode, decode, parse, format, normalize, sanitize, hash, or map.
• Rule owner: which layer defines the invariant or representation rule.

If two values are both strings but have different semantic roles, review them as different concepts.

Use Precise Operation Names

Prefer names that state the semantic contract:

• validate: reject a value that violates a contract this layer owns.
• encode: map a value into a representation while preserving meaning.
• decode: recover the original value from an encoded representation.
• parse: convert a representation into a typed value.
• format: produce a representation for output or interoperability.
• normalize: make intentionally equivalent values canonical.
• sanitize: perform lossy cleanup; use only when information loss is acceptable.
• hash or fingerprint: map to a fixed-size representation where reversibility is not required and collision risk is acceptable for the use case.

Avoid vague helper names such as clean, fix, safe, process, prepare, and convert unless the call sites make the contract obvious.

Review Rules

• Do not let representation constraints become domain rules unless that is the intended contract.
• Do not use one generic helper for values with different meanings just because they share a primitive type.
• Validate at the layer that owns the invariant, not merely at the layer that finds validation convenient.
• Generated values should be safe by construction. If a generated value still needs checking, identify what boundary or persisted state makes that check necessary.
• Encoding should preserve meaning. If the operation is not reversible, name and test the collision or equivalence behavior.
• Sanitization is usually wrong for identity-bearing values because it can silently change meaning or merge distinct values.
• Treat every lossy transformation as suspicious unless a concrete storage, protocol, product, or consumer contract requires it.
• Do not let tests justify behavior by existing. First ask whether the behavior should exist in the current scope.
• Magic limits need a named source: schema limit, protocol limit, product limit, display limit, or explicit configuration. Challenge limits that have no owner.
• Separate common-path correctness from hardening. Defensive hardening should be intentional, not added by default during a PoC or first-stage implementation.
• Tests should include awkward valid values as well as invalid representations.
• Tests should assert the public behavior or abstraction unless the internal representation itself is the contract.

Red Flags

• A helper accepts string and is reused across unrelated concepts.
• A helper name describes an implementation trick instead of the value contract.
• A transformation silently changes an identity, key, token, or authorization-relevant value.
• A lossy transformation truncates, drops, clips, rewrites, or hashes data without a clear contract requiring information loss.
• A test validates a defensive behavior that has not been justified by the current product path.
• A hardcoded size or count limit appears without a schema, protocol, product, or configuration source.
• A validation rule appears in a layer that does not define the value's validity.
• Tests use only convenient examples that already fit the current representation.
• Tests assume internal representation details that callers should not know.
• Review discussion focuses on safety mechanics before classifying the value.

Review Output

When reporting an issue, include:

• The value's semantic role.
• The boundary it crosses.
• The operation the code currently performs.
• Why that operation is mismatched or owned by the wrong layer.
• The safer contract, naming, or test shape.

Useful prompt for yourself:

Is this code preserving the value's meaning, or just making it fit the current implementation?