normalize

Documentation

Overview

Package normalize rewrites the volatile fields of captured Kubernetes payloads to stable, relational placeholders so the lab corpus changes only when behavior changes — never when a run merely produces fresh UIDs, resource versions, or timestamps.

The placeholders are deliberately relational, not flattened: collapsing every UID to one <uid> would erase exactly the evidence the hard scenarios exist to capture (which objects in a deletecollection fan-out are distinct, that a finalizer's terminal DELETED is the *same* object at a *higher* resourceVersion). Instead each volatile field becomes an indexed placeholder, assigned deterministically so that equal inputs map to the same placeholder, distinct inputs to distinct placeholders, and the index order reflects real order.

This package is the ONLY thing allowed to mutate a payload on its way to disk.

Index

• func Normalize(payloads []json.RawMessage) ([]any, error)
• func Single(payload json.RawMessage) (any, error)

Functions

func Normalize

func Normalize(payloads []json.RawMessage) ([]any, error)

Normalize rewrites the ordered payloads of one scenario into a single shared placeholder space, so an identity that recurs across records (e.g. the same UID in a watch event and an audit event) collapses to the same token. Input payloads are JSON; output values are generic decoded structures ready for deterministic YAML marshaling.

Indexing rules, per the design:

• uid / auditID / ip / containerID / imageID / nodeName / generateName-suffix: by first appearance;
• resourceVersion: numeric order when every observed RV in the scenario is an integer (the stream is then provably orderable), otherwise first appearance;
• timestamps: collapsed to a single non-relational token (see tsPlaceholder).

func Single

func Single(payload json.RawMessage) (any, error)

Single normalizes one payload in its own placeholder space. It is a convenience for callers (e.g. the /records API) that handle a single observation rather than a whole scenario.