Module transparency 

Structured loss as substrate-located opacities.

Transparency<P> is a Loss monoid whose values are either Transparency::Clear (no opacity — empty light) or Transparency::Opaque (a BTreeMap from substrate location P to a per-location PropertyVerdict). The combine operation unions the opacity maps at the same path via PropertyVerdict::merge_with, which is the structural realisation of Beer’s “audit channel” (System 3*) propagating located trouble through the system rather than collapsing it to a scalar.

Catastrophic absorption

Transparency::Opaque(BTreeMap::new()) — Opaque with no entries — is the catastrophic sentinel returned by Loss::total. It is the absorbing element under combine: anything combined with it returns it. Public constructors hide this footgun:

• Transparency::clear — the identity (no opacity).
• Transparency::single — a single located opacity.
• Transparency::opaque — a single located opacity (canonical constructor name; structurally identical to single).
• Transparency::catastrophic — the absorbing element.

The Opaque(BTreeMap) variant is pub(crate): outside the terni::transparency module the variant cannot be named directly, so Transparency::Opaque(BTreeMap::new()) is not constructible from downstream code. The catastrophic sentinel can only arise through Loss::total or Transparency::catastrophic (explicit) or via Loss::combine-driven absorption from within the crate (legit, by composition). Per Seam I1 (pre-merge adversarial review, 2026-05-30): the invariant moves from “doc comment” to type system.

Why not P: Default

There is no P : Default bound. The identity element is structural (Clear carries nothing); the absorbing element is structural too (Opaque(empty)). Downstream substrate-reference types — notably prism_core::Ref — can’t sensibly have a Default impl (an “empty” @-prefixed ref is meaningless), and the Default bound on the path type would force every consumer to invent one. The enum encoding sidesteps that entirely.

Citation

The “located opacity” framing follows R. Reyes’ 2024 reconstruction of Beer’s Viable System Model, which formalises the audit channel (VSM System 3*) as a sheaf-of-troubles indexed by substrate locations rather than a single scalar of “how broken.” See the systemic.engineering corpus, cybernetics/beer-error-propagation.md.

Structs

Diagnostic

A small human-readable message accompanying a PropertyVerdict. Newtype over String to keep bare strings out of the verdict surface (no-bare-types).

OpacityMap

The opacities map carried inside Transparency::Opaque. Newtype over BTreeMap<P, PropertyVerdict> with a pub(crate) constructor: outside the terni::transparency module nothing can construct an OpacityMap directly, so the catastrophic-by-empty-map sentinel cannot be forged from downstream code.

Enums

PropertyVerdict

The verdict carried for one substrate location in a Transparency::Opaque map.

Transparency

Structured loss: empty light (Clear) or accumulated opacities at substrate locations (Opaque).

Functions

verdict_union

Union two opacity maps, merging colliding verdicts via PropertyVerdict::merge_with.