Skip to content

topmark.config.validation

topmark / config / validation

Stage-aware validation logs for config loading and preflight checks.

This module defines small, typed containers that group shared diagnostics by validation stage during TopMark's config-loading lifecycle. It complements the generic diagnostic substrate in topmark.diagnostic.model rather than replacing it: diagnostics remain ordinary Diagnostic entries collected in a mutable MutableDiagnosticLog or immutable FrozenDiagnosticLog, while this module adds stage-aware structure around those logs.

The staged model currently distinguishes three validation stages:

  • TOML_SOURCE: whole-source TOML validation and other source-local TOML issues.
  • MERGED_CONFIG: layered-config deserialization, merge-time checks, config invariants, and typed override-application diagnostics.
  • RUNTIME_APPLICABILITY: sanitization recoveries and other preflight/runtime applicability diagnostics.

These containers serve two roles in the current staged config-validation model:

  • preserve stage-local diagnostics so validation boundaries remain explicit,
  • provide a flattened compatibility view in stage order for callers that still consume a single MutableDiagnosticLog at reporting or output boundaries.

ValidationStage

Bases: str, Enum

Named validation stages for config-loading and preflight diagnostics.

MutableValidationLogs dataclass 

MutableValidationLogs(
    *,
    toml_source=MutableDiagnosticLog(),
    merged_config=MutableDiagnosticLog(),
    runtime_applicability=MutableDiagnosticLog(),
)

Mutable staged diagnostic logs for config validation.

Attributes:

Name Type Description
toml_source MutableDiagnosticLog

Diagnostics from whole-source TOML validation and source-local TOML issues.
merged_config MutableDiagnosticLog

Diagnostics from layered config deserialization, merge-time checks, invariants, and typed override application.
runtime_applicability MutableDiagnosticLog

Diagnostics from sanitization and recoverable runtime/preflight applicability checks.

freeze 

freeze()

Return an immutable snapshot of the staged validation logs.

Source code in src/topmark/config/validation.py 
76
77
78
79
80
81
82
def freeze(self) -> FrozenValidationLogs:
    """Return an immutable snapshot of the staged validation logs."""
    return FrozenValidationLogs(
        toml_source=self.toml_source.freeze(),
        merged_config=self.merged_config.freeze(),
        runtime_applicability=self.runtime_applicability.freeze(),
    )

merge_with 

merge_with(other)

Return staged validation logs merged with a higher-precedence draft.

Diagnostics accumulate within each validation stage. The merged result keeps this instance's diagnostics first and appends diagnostics from the higher-precedence other draft afterward, preserving insertion order within each stage.

Parameters:

Name Type Description Default
other MutableValidationLogs

Higher-precedence staged validation logs to append.

 required

Returns:

Type Description
MutableValidationLogs

A new staged validation-log container containing the merged result.
Source code in src/topmark/config/validation.py 
 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
def merge_with(self, other: MutableValidationLogs) -> MutableValidationLogs:
    """Return staged validation logs merged with a higher-precedence draft.

    Diagnostics accumulate within each validation stage. The merged result keeps
    this instance's diagnostics first and appends diagnostics from the
    higher-precedence `other` draft afterward, preserving insertion order within
    each stage.

    Args:
        other: Higher-precedence staged validation logs to append.

    Returns:
        A new staged validation-log container containing the merged result.
    """
    return MutableValidationLogs(
        toml_source=MutableDiagnosticLog.from_iterable(
            [
                *self.toml_source,
                *other.toml_source,
            ],
        ),
        merged_config=MutableDiagnosticLog.from_iterable(
            [
                *self.merged_config.items,
                *other.merged_config.items,
            ]
        ),
        runtime_applicability=MutableDiagnosticLog.from_iterable(
            [
                *self.runtime_applicability.items,
                *other.runtime_applicability.items,
            ]
        ),
    )

flattened 

flattened()

Return a flattened compatibility view in stage order.

Diagnostics are concatenated without rewriting their messages so the flattened compatibility diagnostic view remains stable at reporting and output boundaries.

Source code in src/topmark/config/validation.py 
119
120
121
122
123
124
125
126
127
128
def flattened(self) -> MutableDiagnosticLog:
    """Return a flattened compatibility view in stage order.

    Diagnostics are concatenated without rewriting their messages so the
    flattened compatibility diagnostic view remains stable at reporting and
    output boundaries.
    """
    return MutableDiagnosticLog.from_iterable(
        list(self.toml_source) + list(self.merged_config) + list(self.runtime_applicability)
    )

FrozenValidationLogs dataclass 

FrozenValidationLogs(
    *, toml_source, merged_config, runtime_applicability
)

Immutable staged diagnostic logs for immutable FrozenConfig snapshots.

thaw 

thaw()

Return a mutable copy of these staged validation logs.

Source code in src/topmark/config/validation.py 
139
140
141
142
143
144
145
def thaw(self) -> MutableValidationLogs:
    """Return a mutable copy of these staged validation logs."""
    return MutableValidationLogs(
        toml_source=self.toml_source.thaw(),
        merged_config=self.merged_config.thaw(),
        runtime_applicability=self.runtime_applicability.thaw(),
    )

flattened 

flattened()

Return a flattened immutable compatibility view in stage order.

This helper is intended for reporting and output boundaries that still consume a single immutable diagnostic log.

Source code in src/topmark/config/validation.py 
147
148
149
150
151
152
153
154
155
def flattened(self) -> FrozenDiagnosticLog:
    """Return a flattened immutable compatibility view in stage order.

    This helper is intended for reporting and output boundaries that still
    consume a single immutable diagnostic log.
    """
    return MutableDiagnosticLog.from_iterable(
        list(self.toml_source) + list(self.merged_config) + list(self.runtime_applicability)
    ).freeze()