@spec annotation?(term(), term()) :: boolean()

Returns whether an annotation belongs to the finite canonical vocabulary.

"progress" carries exactly one enumerated stage. "agent-action" is the shipped agent loop's coarse per-turn record: exactly the keys turn (an integer from 0 through 127, matching the loop's maximum turn count) and kind (one of tool-call, protocol-error, provider-error, or max-calls, or model-output-truncated). A phased agent run adds exactly phase (0 through 7), phase_turn (0 through 127), and mission (the phase's mission name) — all three or none, so a partial shape stays out of the vocabulary. It never carries detailed reasons, generated source, or model content — those stay in the agent's own history and, when enabled, in private inspection records.

@spec capability_refusal_key(:workflow | :mission, map()) :: binary()

Builds the public usage.capability_refusals key for one error envelope.

The key is "<environment>/<kind>/<reason>". A known atom stays readable, an unrecognized atom is the same one-way fingerprint rejection_class/1 uses, and a missing or non-atom field is unknown. Distinct keys are capped by capability_refusal_map_limit/0; further classes increment $overflow.

@spec capability_refusal_map_limit() :: 2

Maximum distinct closed-class keys retained in usage.capability_refusals.

Terminal usage admission reserves this many fingerprint-length keys plus $overflow. Two named classes is the largest such map that still admits an empty environment at the 7_000-byte event_payload_bytes floor used by terminal preflight. Further classes increment $overflow.

@spec failure_taxonomy(term()) :: map()

Projects an explicit failure value to bounded, payload-free taxonomy.

Known framework categories remain readable. An application-defined category is represented only by a stable fingerprint, so repeated failures can be grouped without putting the caller's value into a public error or trace. Values without a scalar kind field produce no public taxonomy.

@spec fingerprint(binary()) :: binary()

Returns the canonical non-reversible fingerprint for one bounded identifier.

@spec labels?(term()) :: boolean()

Returns whether a value is an already-normalized canonical-label map.

@spec llm_provider_failure(term()) :: map()

Projects an agent LLM failure to one closed, payload-free provider class.

@spec normalize_labels(term()) :: {:ok, map()} | {:error, :invalid_safe_metadata}

Validates labels and fingerprints caller-defined identifier fields.

@spec rejection_class(term()) :: map()

Projects a Lisp capability error envelope to a payload-free rejection class.

Known Kernel kind and reason atoms remain readable on canonical capability-stopped events. An unrecognized atom is retained only as a one-way fingerprint so a missed Kernel class still groups without putting the atom name on the public trace. Non-atoms, details, and messages produce no public fields.