Documentation
¶
Overview ¶
Package wp3codec implements the WP3 commitment codec: the dependency-free canonical JSON subset frozen under "Canonical evaluation commitments" in docs/specs/lexical-relevance-floor-v0.md and restated word-for-word by docs/specs/change-frontier-v0.md CF-V0-019.
CF-V0-019 requires this definition to be "reused, not independently approximated". No shared Go implementation existed when Change Frontier V0 was built, and neither near neighbour could be reused without emitting different bytes:
- internal/lrf/canonical.go is the LRF *wire* serializer. It emits JSON numbers for the inputs tuple and a terminal LF, both of which this codec forbids.
- internal/cem/wire.CanonicalString uses a different escape profile: it emits the short forms \b \f \n \r \t where this codec requires the lowercase \u00xx form for every U+0000..U+001F scalar.
This package is therefore the single implementation every consumer shares. It lives outside internal/frontier precisely so that internal/lrf and internal/tcq can adopt it without an import cycle, and it depends on nothing but the standard library so that "dependency-free" stays true.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrInvalid = errors.New("wp3codec: invalid canonical value")
ErrInvalid is the sentinel every codec rejection wraps. Callers translate it to their own profile code; the reason text is diagnostic only and must not be rendered into a wire envelope (CF-V0-024).
Functions ¶
func Encode ¶
Encode serializes one value to its exact canonical bytes: no whitespace, no terminal LF, keys sorted by raw UTF-8 bytes, arrays in declared order.
func Verify ¶
Verify performs the check CF-V0-019 requires before hashing: parse the candidate bytes, reserialize them, and require byte equality. This comparison — not Parse — is what enforces canonicity. Because Encode sorts keys, strips whitespace, and emits only the minimal escape form, one comparison rejects mis-ordered keys, insignificant whitespace, short and uppercase-hex and optional escapes, and a trailing LF, all at once.
Types ¶
type Kind ¶
type Kind uint8
Kind enumerates the only value types the codec admits. JSON numbers are deliberately absent: every count, ordinal, and offset travels as a decimal string instead.
type Member ¶
Member is one object entry. Keys are compared and sorted by their raw UTF-8 bytes, never by code point or locale.
type Value ¶
type Value struct {
// contains filtered or unexported fields
}
Value is an immutable canonical value. The zero Value is JSON null, which makes an accidentally unset field encode as null rather than as a panic.
func Decimal ¶
Decimal returns the codec representation of a count, ordinal, or offset: a base-10 string with no sign and no leading zero except "0". A negative input has no canonical form, so it is rejected rather than silently signed.
func Object ¶
Object returns an object value. Members are stored sorted by raw UTF-8 key bytes so that encoding is a straight walk and two objects built in different declaration orders are indistinguishable.
func Parse ¶
Parse reads the JSON subset the codec admits. It is deliberately NOT limited to canonical bytes: CF-V0-019 gives a closed list of what makes input invalid — "a duplicate object key, invalid UTF-8, a BOM, an unpaired surrogate, or a forbidden value" — and insignificant whitespace, the short escapes, and uppercase hex are not on it. The clause then mandates a separate "parse, reserialize, and require byte equality" step, which would be dead code if Parse already rejected every non-canonical byte sequence. So Parse accepts the broader subset and decodes it to scalars, Encode emits the one canonical form, and Verify's comparison is the thing that refuses non-canonical bytes. That division is also what lets this package canonicalize input at all, which an independent consumer needs under CF-V0-028.
JSON numbers stay a parse error: they are "a forbidden value" by the clause's own words, not a spelling of an admitted one.
func String ¶
String returns a string value. Validity of the scalars is checked at encode time so that construction stays total.
Source Files