Module compose 

Layer composition (REQ-COMPOSE-001).

A pin names one realm and one layer. That was fine while a layer held one organisation’s tools, and it broke the first time a consumer needed two: the PulseEngine tools that CHECK their work and the upstream tools that BUILD it (varve#52). Putting both in one layer would place releases we do not control under a qualification claim covering tools we do — so instead a layer may COMPOSE another.

An include is a manifest entry of payload kind layer, whose digest is the included layer’s manifest digest and whose annotations name its realm. It lives in the signed payload, so the composition is signed; and because the digest is the identity, an include cannot silently drift.

Everything here fails closed. A cycle is refused rather than followed, depth is bounded, and a tool exposed by two layers is an ERROR naming both — varve does not pick a winner, for the same reason a pin that does not resolve uniquely is an error and not a fallback.

Structs

Include

One layer this manifest composes.

LayerView

A lenient view of a layer manifest — just what composition needs.

PayloadConflict

Two layers of one composition offering the same (name, version) as different bytes (REQ-COMPOSEEXPORT-001 clause 2).

PayloadOrigin

Where one payload of a composition came from and what it claims to be. The identity the collision rule is stated over (REQ-COMPOSEEXPORT-001 clause 2).

Enums

ComposeError

Constants

ANN_INCLUDE_LAYER

Annotation carrying the included layer’s identity, for error messages that can name it before it has been fetched.

ANN_INCLUDE_REALM

Annotation naming the realm an included layer belongs to. Absent means the including layer’s own realm.

MAX_DEPTH

How deep a composition graph may go. Generous for real use (a layer including a layer including a base), small enough that a malicious or mistaken graph cannot spend the client’s time.

Functions

includes

The layers a view directly composes, in manifest order.

union_payloads

Union the payloads every layer of a composition offers, applying the rule that is NOT the tool rule (REQ-COMPOSEEXPORT-001 clause 2).

union_tools

Union the tool names a composition exposes, refusing any name that appears in more than one layer. Returns tool → the digest of the layer providing it.

view

Read the composition-relevant parts of a manifest. An unparseable manifest is an error, never an empty view — silently reporting “no includes” for a layer we could not read is the failure mode that hides a composition.

walk

Walk a composition graph breadth-first from a root manifest, refusing cycles and excessive depth. fetch supplies a manifest for a digest, or None if that layer is not installed — a missing layer is the caller’s error to report (with its corrective varve install), not this walker’s to invent.