qleisli 0.2.9

Experimental quantum language with linear ownership, exact contracts and independent finite IR verification
Documentation
#!/usr/bin/env python3
"""Exercise the documented quickstart with an already installed executable.

Runs outside the checkout with no helper tools on the child's PATH. Does not
download, install or publish anything. Python 3.11+ is a development dependency.
Copyright 2026 Masahiko G. Yamada. SPDX-License-Identifier: Apache-2.0
"""

import argparse
import json
import math
import os
from pathlib import Path
import re
import subprocess
import tempfile
import tomllib


def require(condition, message):
    if not condition:
        raise ValueError(message)


def quickstart(path):
    text = path.read_text(encoding="utf-8")
    matches = re.findall(
        r"<!-- quickstart:bell -->\s*```qli\n(.*?)```\s*<!-- /quickstart:bell -->",
        text, re.DOTALL,
    )
    require(len(matches) == 1, f"expected one marked Bell program in {path}")
    return text, matches[0]


def quickstart_manifest(text):
    matches = re.findall(
        r"<!-- quickstart:manifest -->\s*```toml\n(.*?)```\s*<!-- /quickstart:manifest -->",
        text, re.DOTALL,
    )
    require(len(matches) == 1, "expected one marked edition manifest")
    manifest = tomllib.loads(matches[0])
    require(manifest == {"schema-version": 2, "qrate": {"edition": "2026"}},
            "quickstart must declare edition 2026 explicitly")
    return matches[0]


def check_registry_links(root, landing, version):
    # Package documentation must remain usable after docs-old is deleted.
    historical = []
    for target in re.findall(r"\[[^\]]+\]\(([^)]+)\)", landing):
        require(target.startswith(("https://", "#")), f"relative registry link: {target}")
        prefix = "https://github.com/MGYamada/Qleisli/blob/"
        if target.startswith(prefix):
            ref, relative = target[len(prefix):].split("/", 1)
            path = relative.split("#")[0]
            require(ref == "v" + version, "registry link uses an unreviewed source version")
            require(not path.startswith("docs-old/") and (
                not path.startswith("docs/")
                or path == "docs/lean-backend-plan-v0.3.md"
                or path.startswith("docs/imaginary-v1/")), "registry link targets retired documentation")
            require((root / path).is_file(), f"missing registry link target: {target}")
    return historical


def check(root, binary):
    package = tomllib.loads((root / "Cargo.toml").read_text())["package"]
    registry = root / package["readme"]
    readme, source = quickstart(root / "README.md")
    landing, landing_source = quickstart(registry)
    require(source == landing_source, "repository and registry quickstarts differ")
    manifest = quickstart_manifest(readme)
    require(manifest == quickstart_manifest(landing), "quickstart edition manifests differ")
    install = f'cargo install {package["name"]} --version {package["version"]} --locked'
    for text in [readme, landing]:
        require(install in text, "quickstart install command differs from manifest")
    # The registry page must not depend on relative repository links or MathJax.
    historical = check_registry_links(root, landing, package["version"])
    require("```math" not in landing and "$$" not in landing,
            "registry README requires a math renderer")

    with tempfile.TemporaryDirectory(prefix="qleisli-installed-") as directory:
        work = Path(directory)
        empty_path = work / "no-helper-tools"
        empty_path.mkdir()
        selected = os.environ.get("QLEISLI_KERNEL")
        require(selected and Path(selected).is_file(), "select a matching native checker with QLEISLI_KERNEL")
        env = dict(os.environ, PATH=str(empty_path), QLEISLI_KERNEL=str(Path(selected).resolve()))

        def invoke(*args, status=0, structured=True):
            command = [str(binary), *args]
            if structured:
                command.append("--format=json")
            result = subprocess.run(command, cwd=work, env=env, capture_output=True,
                                    text=True, timeout=60, check=False)
            require(result.returncode == status and not result.stderr,
                    f"{args}: exit {result.returncode}: {result.stderr or result.stdout}")
            if not structured:
                return result.stdout
            payload = json.loads(result.stdout)
            require(payload["format"] == "qleisli.result" and payload["version"] == 1,
                    "unexpected JSON envelope")
            require(payload["outcome"] == ("error" if status else "ok"),
                    "unexpected command outcome")
            return payload

        def write_project(name, body):
            project = work / name
            project.mkdir()
            (project / "Qargo.toml").write_text(manifest, encoding="utf-8")
            (project / "main.qli").write_text(body, encoding="utf-8")

        write_project("bell", source)
        missing = {key: value for key, value in env.items() if key != "QLEISLI_KERNEL"}
        rejected = subprocess.run([str(binary), "check", "bell", "--format=json"], cwd=work,
                                  env=missing, capture_output=True, text=True, timeout=60)
        require(rejected.returncode == 1 and json.loads(rejected.stdout)["diagnostics"][0]["code"] == "project",
                "missing native checker must reject without discovery or download")
        invoke("check", "bell", structured=False)
        output = invoke("run", "bell", structured=False)
        text_distribution = {bits: float(weight) for bits, weight in
                             (row.split(": ") for row in output.splitlines())}
        require(set(text_distribution) == {"00", "11"}
                and all(math.isclose(p, 0.5, abs_tol=1e-12, rel_tol=0)
                        for p in text_distribution.values()), "wrong Bell distribution")
        invoke("sample", "bell", "--shots=8", "--seed=0", structured=False)
        require(invoke("check", "bell")["result"] == {"verified": True},
                "Bell was not verified")
        sampled = invoke("sample", "bell", "--shots=8", "--seed=0")
        shots = sampled["result"]["shots"]
        require(len(shots) == 8 and all(s["bits"] in [[False, False], [True, True]]
                                      for s in shots), "invalid Bell shots")

        # Resolve an ordinary embedded .qli library module, not only built-ins.
        write_project("bundled-library", """
use std::quantum::init0;
use std::quantum::join;
use std::quantum::split;
use std::transforms::qft2;
use std::observe::measure_z;
observe fn main() -> (CBit, CBit) {
    let (a, b) = split(qft2(join(init0(), init0())));
    (measure_z(a), measure_z(b))
}
""")
        rows = invoke("run", "bundled-library")["result"]["distribution"]
        require({tuple(row["bits"]) for row in rows}
                == {(False, False), (False, True), (True, False), (True, True)}
                and len(rows) == 4
                and all(math.isclose(row["probability"], 0.25, abs_tol=1e-12, rel_tol=0)
                        for row in rows), "embedded QFT library failed")

        write_project("invalid-ownership", """
use std::quantum::init0;
use std::observe::measure_z;
observe fn main() -> (CBit, CBit) {
    let q = init0();
    (measure_z(q), measure_z(q))
}
""")
        rejected = invoke("check", "invalid-ownership", status=1)
        require(any(d["code"] == "ownership" for d in rejected["diagnostics"]),
                "reuse of a measured owner did not produce an ownership diagnostic")
    return {"package": package["name"], "version": package["version"],
            "binary": str(binary), "readmes": "matching Bell source and version",
            "registry_links": "absolute; current targets exist locally; retired contracts use reviewed immutable refs",
            "historical_registry_links_pending_live_check": historical,
            "checks": ["Bell check/run/sample in text and JSON", "embedded qft2",
                       "reject measured-owner reuse"],
            "execution": "temporary directory; empty helper-tool PATH",
            "publication": "not performed"}


def main():
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("binary", type=Path)
    parser.add_argument("--root", type=Path, default=Path(__file__).resolve().parents[1])
    args = parser.parse_args()
    try:
        print(json.dumps(check(args.root.resolve(), args.binary.resolve()), indent=2))
    except (ValueError, OSError, subprocess.TimeoutExpired) as error:
        parser.exit(1, f"installation check failed: {error}\n")


if __name__ == "__main__":
    main()