Skip to content

topmark.toml.machine.payloads

topmark / toml / machine / payloads

Payload builders for TOML-domain machine-readable output.

This module contains pure helpers that build strongly typed payload dataclasses for machine-readable TOML provenance output.

Responsibilities

This module performs no I/O and does not shape JSON envelopes or NDJSON records.

build_toml_provenance_payload 

build_toml_provenance_payload(resolved_toml)

Build a machine-readable layered TOML provenance payload.

Parameters:

Name Type Description Default
resolved_toml ResolvedTopmarkTomlSources

Resolved TOML sources for the current run.

 required

Returns:

Type Description
TomlProvenancePayload

Provenance payload with ordered layers, starting with the built-in
TomlProvenancePayload

defaults layer when present.

Raises:

Type Description
ValueError

If config provenance layers do not align with the resolved TOML sources, or if config provenance layer resolved to an invalid TOML source.
TomlRenderError

If an invalid files serialization mode is specified while rendering API- or CLI-originated layers back to TopMark TOML.
Source code in src/topmark/toml/machine/payloads.py 
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
def build_toml_provenance_payload(
    resolved_toml: ResolvedTopmarkTomlSources,
) -> TomlProvenancePayload:
    """Build a machine-readable layered TOML provenance payload.

    Args:
        resolved_toml: Resolved TOML sources for the current run.

    Returns:
        Provenance payload with ordered layers, starting with the built-in
        defaults layer when present.

    Raises:
        ValueError: If config provenance layers do not align with the resolved
            TOML sources, or if config provenance layer resolved to an invalid
            TOML source.
        TomlRenderError: If an invalid files serialization mode is specified
            while rendering API- or CLI-originated layers back to TopMark TOML.
    """  # noqa: DOC503
    layers: list[ConfigLayer] = build_config_layers_from_resolved_toml_sources(
        resolved_toml.sources
    )

    # Keep payload layers aligned with the resolved/config-derived layer order so
    # the machine-readable provenance view mirrors the effective precedence model.
    out_layers: list[TomlProvenanceLayerPayload] = []
    # File-backed sources are consumed only for non-synthetic layers. Synthetic
    # default/API/CLI layers are reconstructed directly from the in-memory config.
    remaining_sources: Iterator[ResolvedTopmarkTomlSource] = iter(resolved_toml.sources)

    for layer in layers:
        scope_root: str | None = str(layer.scope_root) if layer.scope_root is not None else None

        if layer.kind == ConfigLayerKind.DEFAULT:
            toml_fragment: dict[str, object] = _normalize_toml_fragment(
                build_default_topmark_toml_table()
            )
        elif layer.kind in {ConfigLayerKind.API, ConfigLayerKind.CLI}:
            toml_fragment = _normalize_toml_fragment(
                config_to_topmark_toml_table(layer.config.freeze()),
            )  # May raise TomlRenderError for invalid file-serialization settings.
        else:
            source: ResolvedTopmarkTomlSource | None = next(remaining_sources, None)
            while source is not None and source.parsed is None:
                source = next(remaining_sources, None)

            if source is None:
                raise ValueError("config provenance layers do not align with resolved TOML sources")

            parsed: ParsedTopmarkToml | None = source.parsed
            if parsed is None:
                raise ValueError("config provenance layer resolved to an invalid TOML source")

            toml_fragment = _normalize_toml_fragment(parsed.toml_fragment)

        out_layers.append(
            TomlProvenanceLayerPayload(
                origin=str(layer.origin),
                kind=layer.kind.value,
                precedence=layer.precedence,
                scope_root=scope_root,
                toml=toml_fragment,
            )
        )

    return TomlProvenancePayload(layers=out_layers)