Render cache keys

A value cannot be represented safely in a render-cache key.

Attributes

• path - Location of the rejected value within the semantic variation.
• reason - Human-readable reason the value was rejected.

Notify an observer after one cached component subtree was replayed.

component is the live boundary from the current call, never an archived object. key_digest is exactly 64 lowercase hexadecimal characters without a backend-key prefix. artifact_bytes is the stored value's validated UTF-8 size, and frame_count includes the boundary frame. kind distinguishes a Component.Cache hit from a transparent <c-cache> fragment hit. For a fragment, component is the live built-in Cache boundary from the current call. Return values and observer failures do not alter the committed hit.

The dataclass is shallowly frozen. Observers should copy the scalar fields they need instead of retaining the live component through this context.

citry: Citry

component: Component

kind: Literal['component', 'fragment']

key_digest: str

artifact_bytes: int

frame_count: int

Build the exact physical key for one component variation.

This helper does not construct the component, run input hooks, or call a component's Cache.vary() method. Callers supply the already-computed semantic variation value.

Parameters

• component type[Component] - Component class whose stable class ID identifies the entry.
• vary object - Semantic variation accepted by Citry's canonical key encoder.
• version int | str - Author-controlled exact integer or non-empty string version.

Returns

str: A short ASCII key suitable for deleting one exact backend entry.

Raises

• TypeError - If ``component`` is not a Component class.
• ValueError - If ``version`` is invalid.
• CacheKeyError - If ``vary`` cannot be encoded safely.

Build the exact physical key for one named fragment variation.

Like <c-cache>, this unwraps an outer Const marker from key, vary, and version before validation and encoding.

Parameters

• citry Citry - Engine whose cache scope and local revision apply.
• key str - Exact non-empty semantic fragment name.
• vary object - Semantic variation accepted by Citry's canonical key encoder.
• version int | str - Author-controlled exact integer or non-empty string version.

Returns

str: A short ASCII key suitable for deleting one exact backend entry.

Raises

• TypeError - If ``citry`` is not a Citry instance.
• ValueError - If ``key`` or ``version`` is invalid.
• CacheKeyError - If ``vary`` cannot be encoded safely.