cadrumo.core.prose_elision module

Canonical elision primitive for length-capped operator-facing prose.

A diagnostic, finding, or issue whose message is assembled from taxpayer data has a length nobody authored: fixed prose plus interpolated terms sized by the household rather than by the writer. When such a message crosses its field’s cap the model raises, and a NON-BLOCKING advisory becomes a blocking failure – the filing stops at exactly the moment the advisory had something to say. Cap enforcement on system-assembled prose therefore cuts rather than refuses.

Making that a property of the TYPE is the point. A clamp applied at the call site is only as complete as the author’s memory: the next builder added to the module raises, and nothing catches it until a real household is large enough. A type that elides is total by construction, so no present or future author carries a character budget in their head.

Three homes grew this same clamp independently, with three different markers and three different behaviours – a word-boundary-aware type validator using " [...]", a mid-word call-site clamp using "…", and a third hard-cut call-site clamp using "...". Nothing made them agree, and two of the three were partial (a construction site that forgot the wrapper still raised). This module is their single home, so an operator meets one elision convention rather than three and a new capped prose field inherits the behaviour instead of reimplementing it.

The elision is deliberately VISIBLE. A silently shortened advisory is its own defect: these messages carry remedies, and an operator cannot tell a terse message from a cut one. The marker costs six characters to make the difference legible.

Eliding is a floor, not a licence. A message that reaches the validator has already lost words an operator was meant to read, so authoring-time headroom assertions still belong on messages whose length scales with taxpayer data.

PROSE_ELISION_MARKER: Final[str]

Appended to prose the cap truncated, so the elision is visible to a reader.

elide_to_cap(value, *, cap)

Return value shortened to at most cap characters, marking any cut.

Total: every input produces a string of at most cap characters, so a caller can rely on the result satisfying the bound whatever the data.

Cuts on a word boundary where one is reasonably placed rather than mid-word, because a message ending in half an identifier reads as corruption rather than as truncation. “Reasonably placed” means past the halfway mark of the available room; a boundary earlier than that would discard more than it saves, so the cut falls mid-word instead.

A cap too small to hold the marker leaves no room to signal anything, so the value is hard-cut to the bound. That case does not arise for prose fields in this tree – the tightest declared cap is an order of magnitude larger – but the function stays total rather than producing a string longer than the cap it was asked to satisfy.

Parameters:

• value (str) – The prose to bound.

• cap (int) – The maximum length of the result, in characters.

Return type:

str

Returns:

value unchanged when it already fits, otherwise a shortened form ending in PROSE_ELISION_MARKER.

elided_prose(cap, *, min_length=1, strip_whitespace=False)

Return a str annotation that elides to cap instead of refusing.

The returned annotation carries the cap as a real constraint, so the bound stays readable on the model and discoverable by anything that inspects field metadata; the eliding validator runs first, so the constraint sees an already-bounded value and never fires on length.

Use this for prose the SYSTEM assembles. Operator-supplied text – a note typed at the CLI, an imported feedback package – should keep a raising cap: the operator can shorten what they wrote, and silently swallowing half of it would be the worse failure.

Parameters:

• cap (int) – The field’s maximum length, in characters.

• min_length (int) – Minimum length after elision; the default rejects empty prose, which is a real defect rather than a short message.

• strip_whitespace (bool) – Whether to strip surrounding whitespace, for fields that already declared that constraint.

Return type:

object

Returns:

An Annotated str suitable as a field annotation.

class ElidedProse(cap, min_length=1, strip_whitespace=False)

Bases: object

Annotated metadata declaring an eliding prose cap.

Carries the same constraint set as elided_prose() but as metadata rather than as a returned annotation, so a field can be written Annotated[str, ElidedProse(512)]. That form is a literal type expression, which a static type checker can follow; assigning the result of a call to a name and using the name as an annotation is not, and leaves the field’s type unknown along with every value read from it.

Parameters:

• cap (int) – The field’s maximum length, in characters.

• min_length (int) – Minimum length after elision.

• strip_whitespace (bool) – Whether to strip surrounding whitespace.

cap: int

min_length: int

strip_whitespace: bool

property max_length: int

Return the cap under the name field-metadata inspectors look for.

elided_prose() placed a StringConstraints in the field metadata, and callers read max_length off it to size their own buffers. Exposing the same name here keeps that contract intact: the bound stays discoverable by anything inspecting metadata, which is the property the eliding annotation documents.