The installed Core distribution version, stamped on and read from evidence rows.
release_version on a journal row is the operator's label and may be any
bounded string ("11.0", "staging-build-123"). It cannot tell a reader which
Core actually wrote the row. package_version is read from the installed
distribution's metadata at write time, so a window that mixes two installed
versions, or that disagrees with the version the operator declared, is visible
in the report instead of being merged into one count.
A version that cannot be proven to describe the running code (see
symfonic.platform.artifact_identity), cannot be read, or is not a bounded
label is omitted from the row rather than invented; the reader counts such
rows as unstamped.
installed_package_version() -> str | None
The version of the install that provably owns this process's code.
Resolved once, at the first call (the first journal write), and frozen.
None unless :mod:symfonic.platform.artifact_identity proves the
resolved symfonic-core dist-info owns its METADATA and every loaded
symfonic module, unchanged since the process started, and the process
did not inherit those modules from a parent it was forked from. Each later
call checks every module imported, re-imported or reloaded since, against
the same unchanged RECORD; one that fails, or a RECORD that changed or is
gone, withdraws the version for the rest of the process. Code loaded
before the first call was attested by it. Never guessed from
pyproject.toml.
Source code in src/symfonic/platform/package_version.py
| def installed_package_version() -> str | None:
"""The version of the install that provably owns this process's code.
Resolved once, at the first call (the first journal write), and frozen.
``None`` unless :mod:`symfonic.platform.artifact_identity` proves the
resolved ``symfonic-core`` dist-info owns its METADATA and every loaded
``symfonic`` module, unchanged since the process started, and the process
did not inherit those modules from a parent it was forked from. Each later
call checks every module imported, re-imported or reloaded since, against
the same unchanged RECORD; one that fails, or a RECORD that changed or is
gone, withdraws the version for the rest of the process. Code loaded
before the first call was attested by it. Never guessed from
``pyproject.toml``.
"""
from importlib import metadata # noqa: PLC0415 - evidence writers only
from symfonic.platform import artifact_identity as identity # noqa: PLC0415
with _Frozen.lock:
loaded = identity._loaded(sys.modules)
if not _Frozen.resolved:
_Frozen.resolved = True
_Frozen.seen = {name: spec for name, _, spec in loaded}
if not _same_lineage():
return None
try:
dist = metadata.distribution(DISTRIBUTION)
except metadata.PackageNotFoundError:
return None
modules = [(name, file) for name, file, _ in loaded]
_Frozen.proof = identity._attest(dist, modules, identity.process_start_ns())
version = _Frozen.proof.version if _Frozen.proof is not None else None
_Frozen.version = version if is_package_version(version) else None
elif _Frozen.version is not None:
new = [(name, file) for name, file, spec in loaded
if name not in _Frozen.seen or _Frozen.seen[name] is not spec]
if new:
_Frozen.seen = {name: spec for name, _, spec in loaded}
if not identity._still_owns(_Frozen.proof, new):
_Frozen.version = None
return _Frozen.version
|
is_package_version(value: Any) -> bool
A bounded PEP 440-shaped label; never unknown.
Source code in src/symfonic/platform/package_version.py
| def is_package_version(value: Any) -> bool:
"""A bounded PEP 440-shaped label; never ``unknown``."""
return isinstance(value, str) and value != "unknown" and bool(_LABEL.fullmatch(value))
|
package_version_binding(report: Mapping[str, Any]) -> str
Whether every in-window row of report names one declared version.
A zero verdict needs this to be package_version_bound: the manifest
declared a bounded package_version, every in-window row was stamped,
and every stamp equals the declaration. Any other value names the missing
evidence; it withholds zero and never hides an observed fallback.
Source code in src/symfonic/platform/package_version.py
| def package_version_binding(report: Mapping[str, Any]) -> str:
"""Whether every in-window row of ``report`` names one declared version.
A zero verdict needs this to be ``package_version_bound``: the manifest
declared a bounded ``package_version``, every in-window row was stamped,
and every stamp equals the declaration. Any other value names the missing
evidence; it withholds zero and never hides an observed fallback.
"""
declared = report.get("declared_package_version")
counts = report.get("package_version_counts")
unstamped = report.get("unstamped_package_version_count")
if not is_package_version(declared):
return "package_version_undeclared"
if not isinstance(counts, Mapping) or type(unstamped) is not int:
return "package_version_unreported"
if len(counts) > 1:
return "package_version_mixed"
if unstamped:
return "package_version_unstamped_rows"
if not counts:
return "package_version_unobserved"
if set(counts) != {declared}:
return "package_version_mismatch"
return "package_version_bound"
|
package_version_report(versions: Counter[str | None], manifest: Mapping[str, Any] | None) -> tuple[dict[str, Any], list[str]]
Report in-window rows by writer version, and the issues that follow.
None keys are unstamped rows (written before stamping, or by a host
whose metadata was unreadable). Two stamped versions in one window are a
finding whatever the manifest says. A manifest that declares
package_version binds every in-window row to it, unstamped ones
included; a manifest that omits it leaves unstamped rows reported but not
an issue.
Source code in src/symfonic/platform/package_version.py
| def package_version_report(
versions: Counter[str | None],
manifest: Mapping[str, Any] | None,
) -> tuple[dict[str, Any], list[str]]:
"""Report in-window rows by writer version, and the issues that follow.
``None`` keys are unstamped rows (written before stamping, or by a host
whose metadata was unreadable). Two stamped versions in one window are a
finding whatever the manifest says. A manifest that declares
``package_version`` binds every in-window row to it, unstamped ones
included; a manifest that omits it leaves unstamped rows reported but not
an issue.
"""
stamped = {version: count for version, count in versions.items() if version is not None}
unstamped = versions.get(None, 0)
issues: list[str] = []
if len(stamped) > 1:
issues.append("mixed_package_versions")
declared = manifest.get("package_version") if manifest is not None else None
if manifest is not None and "package_version" in manifest:
if not is_package_version(declared):
issues.append("invalid_manifest_package_version")
declared = None
elif unstamped or set(stamped) - {declared}:
issues.append("package_version_mismatch")
return {
"declared_package_version": declared,
"package_version_counts": dict(sorted(stamped.items())),
"unstamped_package_version_count": unstamped,
}, issues
|
stamp_package_version(row: Mapping[str, Any]) -> dict[str, Any]
Return row with the installed version added when it is readable.
Source code in src/symfonic/platform/package_version.py
| def stamp_package_version(row: Mapping[str, Any]) -> dict[str, Any]:
"""Return ``row`` with the installed version added when it is readable."""
version = installed_package_version()
return {**row, "package_version": version} if version is not None else dict(row)
|