symfonic.platform.artifact_identity

artifact_identity

Prove that an installed symfonic-core dist-info owns the imported code.

importlib.metadata returns the first matching dist-info on sys.path. That says nothing about which code the process runs: a source checkout ahead of an install, an editable install of another checkout, a hand-edited file or an in-place upgrade all leave a readable version that describes other bytes.

A version is attributed only when all of these hold, else None:

• the distribution is not an editable (direct_url.json) install;
• its RECORD lists every loaded symfonic module, at the path the module was imported from, with a sha256 that matches the file. A loaded module the RECORD does not list (added later, sourceless, or another distribution's) withholds the version;
• symfonic/__init__.py, this module and the stamping module are among them, so a foreign tree cannot pass by importing nothing the RECORD lists;
• the RECORD lists METADATA with a matching sha256, and the version is read from those same bytes, so an edited version label is not attributed;
• none of those files, nor the RECORD, changed after the process started. The start time is read from /proc; where it cannot be read the answer is None.

This is consistency between the RECORD and the .py files on disk, not build authenticity: a RECORD rewritten to match edited files before the process starts passes, and the bytecode actually executed is not hashed.

is_editable

is_editable(dist: Any) -> bool

True when the install records an editable source directory.

Source code in src/symfonic/platform/artifact_identity.py

def is_editable(dist: Any) -> bool:
    """True when the install records an editable source directory."""
    try:
        raw = dist.read_text("direct_url.json")
        info = json.loads(raw) if raw else {}
    except (OSError, ValueError):
        return True  # unreadable install provenance is not proof of a wheel
    return isinstance(info, dict) and bool((info.get("dir_info") or {}).get("editable"))

loaded_modules

loaded_modules(modules: dict[str, Any]) -> list[tuple[str, str]]

(name, file) for every loaded symfonic source module.

Source code in src/symfonic/platform/artifact_identity.py

def loaded_modules(modules: dict[str, Any]) -> list[tuple[str, str]]:
    """``(name, file)`` for every loaded ``symfonic`` source module."""
    return [(name, file) for name, file, _ in _loaded(modules)]

owned_version

owned_version(dist: Any, modules: list[tuple[str, str]], started: int | None) -> str | None

dist's version if it provably owns modules; otherwise None.

Source code in src/symfonic/platform/artifact_identity.py

def owned_version(dist: Any, modules: list[tuple[str, str]], started: int | None) -> str | None:
    """``dist``'s version if it provably owns ``modules``; otherwise ``None``."""
    proof = _attest(dist, modules, started)
    return proof.version if proof is not None else None

process_start_ns

process_start_ns() -> int | None

This process's start time in epoch nanoseconds, never later than the truth.

Start ticks are truncated and the uptime sample is padded by its 10 ms resolution, so the value can only be early: a file written after the real start is always newer than it, and one written in the last ~20 ms before it may also count as newer, which withholds the version (fail closed).

Source code in src/symfonic/platform/artifact_identity.py

def process_start_ns() -> int | None:
    """This process's start time in epoch nanoseconds, never later than the truth.

    Start ticks are truncated and the uptime sample is padded by its 10 ms
    resolution, so the value can only be early: a file written after the real
    start is always newer than it, and one written in the last ~20 ms before
    it may also count as newer, which withholds the version (fail closed).
    """
    now = time.time_ns()
    try:
        with open("/proc/self/stat", "rb") as stream:
            stat = stream.read()
        with open("/proc/uptime", "rb") as stream:
            uptime = float(stream.read().split()[0])
        ticks = int(stat[stat.rindex(b")") + 2:].split()[19])
        hertz = os.sysconf("SC_CLK_TCK")
    except (OSError, ValueError, IndexError):
        return None
    since_start = int((uptime + 0.01) * 1_000_000_000) - ticks * 1_000_000_000 // hertz
    return now - since_start

verify_modules

verify_modules(dist: Any, modules: Iterable[tuple[str, str]], started: int) -> bool

Whether every listed module is dist's recorded, unchanged file.

Source code in src/symfonic/platform/artifact_identity.py

def verify_modules(dist: Any, modules: Iterable[tuple[str, str]], started: int) -> bool:
    """Whether every listed module is ``dist``'s recorded, unchanged file."""
    read = _read_record(dist, started)
    if read is None:
        return False
    try:
        entries = _entries(read[1])
    except (UnicodeDecodeError, csv.Error):
        return False
    proof = _Proof(dist, read[0], hashlib.sha256(read[1]).digest(), entries, started, "")
    return _owned(proof, modules)