What causes "cacheengine: negative segment measurement" in JuliusBrussee/caveman?

Map tokenizer failure to 0 or omit the segment instead of -1

cacheengine: negative segment measurement

Error message

cacheengine: negative segment measurement

What it means

Thrown by stablePrefix when a leading Stable && Cacheable segment has Tokens < 0 or ExpectedCalls < 0. Token counts and reuse estimates feed breakpoint sizing, so negative measurements are rejected outright.

Source

Thrown at cacheengine/engine.go:336

		profile.Attribution = AttributionNone
	}
	return profile
}

func stablePrefix(segments []Segment, maxBytes int) ([]byte, []Segment, error) {
	var prefix []byte
	var stable []Segment
	seenNames := map[string]bool{}
	for _, segment := range segments {
		if !segment.Stable || !segment.Cacheable {
			break
		}
		if !validIdentity(segment.Name, 1024, false) || len(segment.Content) == 0 || seenNames[segment.Name] {
			return nil, nil, errors.New("cacheengine: stable segment needs name and content")
		}
		seenNames[segment.Name] = true
		if segment.Tokens < 0 || segment.ExpectedCalls < 0 {
			return nil, nil, errors.New("cacheengine: negative segment measurement")
		}
		if maxBytes < 8 || len(segment.Name) > maxBytes-8 || len(segment.Content) > maxBytes-8-len(segment.Name) || len(prefix) > maxBytes-8-len(segment.Name)-len(segment.Content) {
			return nil, nil, errors.New("cacheengine: stable prefix exceeds configured byte limit")
		}
		if len(segment.Name) > math.MaxUint32 || len(segment.Content) > math.MaxUint32 {
			return nil, nil, errors.New("cacheengine: segment exceeds framing limit")
		}
		prefix = appendFrame(prefix, segment.Name, segment.Content)
		stable = append(stable, segment)
	}
	return prefix, stable, nil
}

func appendFrame(dst []byte, name string, content []byte) []byte {
	var lengths [8]byte
	binary.BigEndian.PutUint32(lengths[:4], uint32(len(name)))
	binary.BigEndian.PutUint32(lengths[4:], uint32(len(content)))
	dst = append(dst, lengths[:]...)

View on GitHub (pinned to 27d5a3981a)

Solutions

Map tokenizer failure to 0 or omit the segment instead of -1
Use 0 for 'unknown' ExpectedCalls (the engine substitutes defaultCalls when calls == 0)
Clamp externally sourced counters to >= 0 before building segments

Example fix

// before
tok, err := tokenizer.Count(text) // returns -1 on error
seg := cacheengine.Segment{Name: "sys", Stable: true, Cacheable: true, Content: b, Tokens: tok}

// after
tok := 0
if n, err := tokenizer.Count(text); err == nil {
    tok = n
}
seg := cacheengine.Segment{Name: "sys", Stable: true, Cacheable: true, Content: b, Tokens: tok}

Defensive patterns

Strategy: validation

Validate before calling

for i, s := range segs { if s.Tokens < 0 { segs[i].Tokens = 0 }; if s.ExpectedCalls < 0 { segs[i].ExpectedCalls = 0 } }

Type guard

func segmentMeasurementsValid(s cacheengine.Segment) bool { return s.Tokens >= 0 && s.ExpectedCalls >= 0 }

Prevention

Map tokenizer errors to 0, never -1
Clamp external counters to >= 0

When it happens

Trigger: Passing a stable segment whose Tokens was set by a tokenizer that returned -1 on failure, or whose ExpectedCalls is negative after a metrics delta computation.

Common situations: Using -1 as a tokenizer error sentinel and forwarding it into the segment; estimating expected calls by subtracting historical counts that cross zero; unmarshalling counters from an external API that reports -1 for 'unknown'.

Related errors

AI-assisted analysis of JuliusBrussee/caveman@27d5a3981a (2026-08-15). Data as JSON: /api/errors/a95e77759d3bae72. Report an issue: GitHub.