crit 0.10.0__py3-none-any.whl

crit/__init__.py

@@ -0,0 +1,2 @@
+"""crit: run records, Kernels, Eval dispatch and the serving API's command line."""
+__version__ = "0.10.0"

crit/cli.py

@@ -0,0 +1,55 @@
+"""Small product CLI; implementation code is never imported by navigation."""
+import argparse
+from pathlib import Path
+import sys
+
+ROOT = Path(__file__).resolve().parents[2]
+
+
+def main(argv=None):
+    # Route subcommands with their own parsers before the maintenance parser.
+    arguments = list(sys.argv[1:] if argv is None else argv)
+    if arguments and arguments[0] == "run":
+        from .run.cli import main as run_main
+        return run_main(arguments[1:])
+    if arguments and arguments[0] == "serve":
+        from crit_api.cli import main as serve_main
+        return serve_main(arguments[1:])
+    if arguments and arguments[0] == "kernels":
+        from crit_kernels import main as kernels_main
+        return kernels_main(arguments[1:])
+    if arguments and arguments[0] == "models":
+        from crit_models import main as models_main
+        return models_main(arguments[1:])
+    if arguments and arguments[0] == "eval":
+        try:
+            from crit_eval.cli import main as eval_main
+        except ImportError:
+            raise SystemExit("crit eval needs crit Eval (https://github.com/crit-labs/crit-eval): install it with "
+                             "python -m pip install -e ../crit-eval beside this checkout") from None
+        return eval_main(arguments[1:])
+    parser = argparse.ArgumentParser(description="crit Core, Inference, Kernels, Models, Eval, run records and the serving API")
+    from . import __version__
+    parser.add_argument("--version", action="version", version="crit " + __version__)
+    subs = parser.add_subparsers(dest="command", required=True)
+    subs.add_parser("contracts", help="Print native core contract locations")
+    subs.add_parser("kernels", help="Inspect kernel applicability and retain verified dependency bytes")
+    subs.add_parser("models", help="Transform model weights (PTQ) and record how; use crit models --help")
+    subs.add_parser("serve", help="Serve a sealed candidate as an OpenAI-compatible API; use crit serve --help")
+    subs.add_parser("run", help="Publish retained run/candidate records; use crit run --help")
+    subs.add_parser("eval", help="Run the common speed, quality and exactness suite (crit Eval); use crit eval --help")
+    sub = subs.add_parser("inference", help="Query or check the inference techniques")
+    sub.add_argument("arguments", nargs=argparse.REMAINDER)
+    args = parser.parse_args(arguments)
+    repository = ROOT if (ROOT / "core/include/crit/core.h").is_file() else Path.cwd()
+    if not (repository / "core/include/crit/core.h").is_file():
+        parser.error("Run repository maintenance commands from the crit repository")
+    if args.command == "inference":
+        from . import inference
+        return inference.main(args.arguments, repository)
+    print("core/include/crit/core.h\ncore/include/crit/cuda.h\ncore/contracts/README.md")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

crit/inference.py

@@ -0,0 +1,153 @@
+"""Query/check the crit inference techniques; never import implementation code."""
+import argparse
+import json
+from pathlib import Path, PurePosixPath
+import sys
+
+ROOT = Path(__file__).resolve().parents[2]
+GUIDANCE_TEXT = ("use_when", "avoid_when")
+GUIDANCE_LISTS = ("provides", "engine_supplies", "preserve", "adapt")
+# Navigation metadata, not folders: every entry names one category; `list` groups by it in this order.
+CATEGORIES = ("attention", "projections", "experts", "speculation", "sampling-and-constraints",
+              "execution", "memory-and-loading")
+
+
+def under(root, relative):
+    if not isinstance(relative, str) or not relative or "\\" in relative or ":" in relative:
+        raise ValueError("canonical repository-relative path required")
+    path = PurePosixPath(relative)
+    if path.is_absolute() or any(p in {"", ".", ".."} for p in relative.split("/")):
+        raise ValueError("canonical repository-relative path required")
+    target = (root / relative).resolve()
+    if not target.is_relative_to(root.resolve()):
+        raise ValueError("path escapes the repository")
+    return target
+
+
+def load(root=ROOT):
+    """Read authored entries directly, without generated files or code imports."""
+    entries = [json.loads(p.read_text(encoding="utf-8")) for p in sorted((root / "inference").glob("*/entry.json"))]
+    return {"schema_version": 3, "collection_name": "crit Inference", "entries": entries}
+
+
+def check(root=ROOT):
+    errors = []
+    store = load(root)
+    ids = set()
+    if not store["entries"]:
+        errors.append("Inference contains no techniques")
+    for entry in store["entries"]:
+        ident = entry["id"]
+        under(root, "inference/" + ident)
+        if ident in ids:
+            errors.append("duplicate technique ID")
+        ids.add(ident)
+        if any(field in entry for field in ("donors", "origin_path", "source_bundle_path", "code_locations")):
+            errors.append(f"{ident}: external source-bundle metadata is not a crit technique")
+        if entry.get("category") not in CATEGORIES:
+            errors.append(f"{ident}: category must be one of " + ", ".join(CATEGORIES))
+        if not entry["summary"] or not entry["implementation_scope"] or not entry["code_files"]:
+            errors.append(f"{ident}: description and actual implementation required")
+        if entry.get("implementation_status") not in {"reference", "native_source"}:
+            errors.append(f"{ident}: explicit reference/native-source scope required")
+        if any(not entry.get("validation", {}).get(field) for field in ("host", "native", "performance")):
+            errors.append(f"{ident}: host/native/performance status must be explicit")
+        guidance = entry.get("agent_guidance")
+        if not isinstance(guidance, dict):
+            errors.append(f"{ident}: agent selection, implementation and adaptation guidance required")
+        else:
+            for field in GUIDANCE_TEXT:
+                value = guidance.get(field)
+                if not isinstance(value, str) or not value.strip():
+                    errors.append(f"{ident}: agent_guidance.{field} must be nonempty text")
+            for field in GUIDANCE_LISTS:
+                value = guidance.get(field)
+                if not isinstance(value, list) or not value or any(not isinstance(item, str) or not item.strip() for item in value):
+                    errors.append(f"{ident}: agent_guidance.{field} must list concrete responsibilities or choices")
+        if entry["code_path"] != f"inference/{ident}/code" or entry["path"] != f"inference/{ident}/README.md":
+            errors.append(f"{ident}: technique-local description/code required")
+        if not under(root, entry["path"]).is_file():
+            errors.append(f"{ident}: description missing")
+        for field in ("input", "output", "ownership", "failure", "core_boundary"):
+            if not entry["contract"].get(field):
+                errors.append(f"{ident}: missing {field} contract")
+        for field in ("hardware", "model", "workload"):
+            if not entry["requires"].get(field):
+                errors.append(f"{ident}: missing {field} requirement")
+        actual = False
+        listed = set()
+        for code in entry["code_files"]:
+            path = under(root, code["path"])
+            if not path.is_relative_to(under(root, entry["code_path"])) or not path.is_file():
+                errors.append(f"{ident}: actual code must be inside the feature")
+            elif path.suffix in {".py", ".cpp", ".cu", ".h"} and path.stat().st_size:
+                actual = True
+            listed.add(path)
+        if not actual:
+            errors.append(f"{ident}: code folder contains no actual implementation")
+        for path in under(root, entry["code_path"]).rglob("*"):
+            if path.is_file() and path.suffix in {".py", ".cpp", ".cu", ".h"} and path.resolve() not in listed:
+                errors.append(f"{ident}: implementation file missing from metadata")
+    return errors
+
+
+def main(argv=None, root=ROOT):
+    parser = argparse.ArgumentParser(description=__doc__)
+    subs = parser.add_subparsers(dest="command", required=True)
+    for name in ("list", "search", "show"):
+        sub = subs.add_parser(name)
+        if name != "list":
+            sub.add_argument("query")
+        sub.add_argument("--json", action="store_true")
+    subs.add_parser("check")
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "check":
+            errors = check(root)
+            if errors:
+                raise ValueError("\n".join(errors))
+            print("crit Inference passed: actual technique code and authored metadata.")
+        else:
+            entries = load(root)["entries"]
+            if args.command == "show":
+                entries = [e for e in entries if e["id"] == args.query]
+                if not entries:
+                    raise ValueError("unknown technique")
+            elif args.command == "search":
+                words = args.query.casefold().split()
+                entries = [e for e in entries if all(w in json.dumps(e).casefold() for w in words)]
+            if args.json:
+                print(json.dumps(entries[0] if args.command == "show" else entries, indent=2))
+            elif args.command == "list":
+                for category in CATEGORIES + tuple(sorted({e.get("category") or "" for e in entries} - set(CATEGORIES))):
+                    group = [e for e in entries if (e.get("category") or "") == category]
+                    if group:
+                        print((category or "uncategorized") + ":")
+                        for entry in group:
+                            print("  " + entry["id"] + ": " + entry["summary"])
+            else:
+                for entry in entries:
+                    print(entry["id"] + ": " + entry["summary"])
+                    if args.command == "show":
+                        print("Category: " + str(entry.get("category")))
+                        print("Scope: " + entry["implementation_scope"])
+                        guidance = entry["agent_guidance"]
+                        print("Use when: " + guidance["use_when"])
+                        print("Consider another approach when: " + guidance["avoid_when"])
+                        for title, field in (("Supplied here", "provides"), ("Engine supplies", "engine_supplies"),
+                                             ("Preserve", "preserve"), ("Adapt", "adapt")):
+                            print(title + ":")
+                            for item in guidance[field]:
+                                print("  - " + item)
+                        print("Description and worked example: " + entry["path"])
+                        print("Code:")
+                        for code in entry["code_files"]:
+                            print("  " + code["path"])
+        return 0
+    except (ValueError, OSError, KeyError, TypeError) as exc:
+        print("ERROR: " + str(exc), file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

crit/process/guardian.py

@@ -0,0 +1,63 @@
+"""Launch gate and parent-death monitor, inside the supervisor's process tree."""
+from pathlib import Path
+import os
+import signal
+import subprocess
+import sys
+import time
+
+if __package__ in {None, ""}:
+    sys.path.insert(0, str(Path(__file__).resolve().parents[2]))
+from crit.process.ownership import process_identity, read_ownership
+from crit.run.records import read_json, write_json
+
+
+def main():
+    launch = read_json(Path(sys.argv[1]))
+    owner_path = Path(launch["owner_path"])
+    owner = read_ownership(owner_path)
+    identity = process_identity(os.getpid())
+    if (identity in {None, "unknown"} or owner["token"] != launch["token"] or
+            process_identity(owner["owner_pid"]) != owner["owner_identity"]):
+        return 125
+    # A Windows virtual-environment launcher is a different process from the
+    # interpreter running this file. Report the actual guardian before the
+    # supervisor verifies containment and grants permission to start the engine.
+    write_json(Path(sys.argv[1]).with_suffix(".ready.json"),
+               {"token": launch["token"], "pid": os.getpid(), "identity": identity}, immutable=True)
+    end = time.monotonic() + 10
+    while True:
+        owner = read_ownership(owner_path)
+        if owner["token"] != launch["token"] or process_identity(owner["owner_pid"]) != owner["owner_identity"]:
+            return 125
+        child = owner.get("process")
+        if child and child["pid"] == os.getpid() and child["identity"] == process_identity(os.getpid()):
+            break
+        if time.monotonic() >= end:
+            return 125
+        time.sleep(.02)
+    # Inherit the guardian's POSIX process group / Windows Job Object.
+    try:
+        engine = subprocess.Popen(launch["command"], cwd=launch["cwd"], stdin=subprocess.DEVNULL)
+    except OSError as exc:
+        write_json(Path(sys.argv[1]).with_suffix(".error.json"), {"error": str(exc)}, immutable=True)
+        return 125
+    while engine.poll() is None:
+        try:
+            owner = read_ownership(owner_path)
+            alive = owner["token"] == launch["token"] and process_identity(owner["owner_pid"]) == owner["owner_identity"]
+        except (OSError, ValueError, KeyError) as exc:
+            print("Launch guardian could not read ownership: " + str(exc), file=sys.stderr, flush=True)
+            alive = False
+        if not alive:
+            if os.name != "nt":
+                os.killpg(os.getpgrp(), signal.SIGKILL)
+            engine.kill()  # Windows job also closes when its owner exits.
+            engine.wait(timeout=5)
+            return 125
+        time.sleep(.05)
+    return engine.returncode
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

crit/process/ownership.py

@@ -0,0 +1,270 @@
+"""Durable per-user runtime ownership; stale/failed cleanup never grants admission."""
+import getpass
+import hashlib
+import os
+from pathlib import Path
+import signal
+import re
+import shutil
+import tempfile
+import time
+import uuid
+
+from crit.run.records import keys, now, number, read_json, safe_path, write_json
+from crit.run.store import lease
+
+
+def process_identity(pid):
+    if not isinstance(pid, int) or pid <= 0:
+        return None
+    if os.name == "nt":
+        import ctypes as c
+        from ctypes import wintypes as w
+        api = c.WinDLL("kernel32", use_last_error=True)
+        api.OpenProcess.argtypes, api.OpenProcess.restype = [w.DWORD, w.BOOL, w.DWORD], w.HANDLE
+        api.GetProcessTimes.argtypes = [w.HANDLE] + [c.POINTER(w.FILETIME)] * 4
+        api.CloseHandle.argtypes = [w.HANDLE]
+        api.GetExitCodeProcess.argtypes = [w.HANDLE, c.POINTER(w.DWORD)]
+        handle = api.OpenProcess(0x1000, False, pid)
+        if not handle:
+            return None if c.get_last_error() in {87, 1168} else "unknown"
+        try:
+            code = w.DWORD()
+            if not api.GetExitCodeProcess(handle, c.byref(code)):
+                return "unknown"
+            if code.value != 259:
+                return None
+            values = [w.FILETIME() for _ in range(4)]
+            if not api.GetProcessTimes(handle, *(c.byref(v) for v in values)):
+                return "unknown"
+            return str((values[0].dwHighDateTime << 32) | values[0].dwLowDateTime)
+        finally:
+            api.CloseHandle(handle)
+    try:
+        fields = Path(f"/proc/{pid}/stat").read_text().rsplit(")", 1)[1].split()
+        if fields[0] in {"Z", "X"}:
+            return None
+        boot = Path("/proc/sys/kernel/random/boot_id").read_text().strip()
+        return boot + ":" + fields[19]
+    except FileNotFoundError:
+        if Path("/proc").is_dir():
+            return None
+    except (OSError, IndexError):
+        return "unknown"
+    try:
+        os.kill(pid, 0)
+        return "unknown"
+    except ProcessLookupError:
+        return None
+    except PermissionError:
+        return "unknown"
+
+
+def group_alive(pgid):
+    if Path("/proc/self/stat").exists():
+        for path in Path("/proc").glob("[0-9]*/stat"):
+            try:
+                fields = path.read_text().rsplit(")", 1)[1].split()
+                if int(fields[2]) == pgid and fields[0] not in {"Z", "X"}:
+                    return True
+            except FileNotFoundError:
+                continue
+            except (OSError, ValueError, IndexError):
+                return True  # An unobservable member cannot prove settlement.
+        return False
+    try:
+        os.killpg(pgid, 0)
+        return True
+    except ProcessLookupError:
+        return False
+
+
+def windows_job_settled(name):
+    import ctypes as c
+    from ctypes import wintypes as w
+    if not name:
+        raise ValueError("No retained Windows job identity; cleanup cannot be proven")
+    api = c.WinDLL("kernel32", use_last_error=True)
+    api.OpenJobObjectW.argtypes, api.OpenJobObjectW.restype = [w.DWORD, w.BOOL, w.LPCWSTR], w.HANDLE
+    api.QueryInformationJobObject.argtypes = [w.HANDLE, c.c_int, c.c_void_p, w.DWORD, c.c_void_p]
+    api.CloseHandle.argtypes = [w.HANDLE]
+    handle = api.OpenJobObjectW(4, False, name)  # JOB_OBJECT_QUERY
+    if not handle:
+        if c.get_last_error() == 2:  # Destroyed only after the owned processes exit.
+            return True
+        raise c.WinError(c.get_last_error())
+    try:
+        class Accounting(c.Structure):
+            _fields_ = [("times", c.c_int64 * 4), ("faults", w.DWORD), ("total", w.DWORD),
+                        ("active", w.DWORD), ("terminated", w.DWORD)]
+        value = Accounting()
+        if not api.QueryInformationJobObject(handle, 1, c.byref(value), c.sizeof(value), None):
+            raise c.WinError(c.get_last_error())
+        return value.active == 0
+    finally:
+        api.CloseHandle(handle)
+
+
+# How long a killed process tree may take to exit before cleanup counts as failed. Exit is not immediate: a process
+# that pinned tens of GB of host memory or holds a GPU context releases it after SIGKILL (several seconds here).
+RETIREMENT_SECONDS = 60
+
+
+def read_ownership(path):
+    """Read fresh ownership after bounded sharing-denial retries; never infer ownership from cached data.
+
+    Both supervisor and guardian need this: Windows atomic replacement can briefly deny an open even while
+    the owner remains alive. Missing/malformed records and an expired retry still fail closed.
+    """
+    deadline = time.monotonic() + .25
+    while True:
+        try:
+            return read_json(path)
+        except PermissionError:
+            if time.monotonic() >= deadline:
+                raise
+            time.sleep(.005)
+
+
+def default_directory():
+    user = str(os.getuid()) if hasattr(os, "getuid") else hashlib.sha256(getpass.getuser().encode()).hexdigest()[:16]
+    return Path(os.environ.get("CRIT_RUNTIME_DIRECTORY", str(Path(tempfile.gettempdir()) / ("crit-runtime-" + user))))
+
+
+def clean_snapshots(directory, runtime_id):
+    """Remove a settled owner's private model snapshots."""
+    if runtime_id is None:
+        return
+    if not isinstance(runtime_id, str) or not re.fullmatch(r"[0-9a-f]{32}", runtime_id):
+        raise ValueError("Invalid private runtime identity")
+    root = safe_path(directory, "runtimes/" + runtime_id + "/models")
+    if root.exists():
+        for path in root.rglob("*"):
+            safe_path(root, path.relative_to(root).as_posix())
+            if path.is_file():
+                path.chmod(0o600)
+        # Job retirement can precede release of a mapped file's Windows handle.
+        # Retry only transient sharing/permission errors on this checked private
+        # directory; persistent failure must retain runtime ownership.
+        deadline = time.monotonic() + .25
+        while True:
+            try:
+                shutil.rmtree(root)
+                break
+            except PermissionError as exc:
+                if getattr(exc, "winerror", None) not in {5, 32, 33} or time.monotonic() >= deadline:
+                    raise
+                time.sleep(.005)
+
+
+class RuntimeOwnership:
+    def __init__(self, directory=None):
+        self.directory = (Path(directory) if directory is not None else default_directory()).expanduser().absolute()
+        self.path = safe_path(self.directory, "owner.json")
+        self.token = None
+        self.failed_tree = None
+        self.launch_settled = True  # In-process proof for failed guarded launches.
+        self.blocked = ""
+
+    def acquire(self):
+        if self.token:
+            value = self.read_owned()
+            if self.blocked or value["state"] == "blocked":
+                raise ValueError("Runtime cleanup is unresolved. Unload/recover it before another request.")
+            return
+        self.directory.mkdir(parents=True, exist_ok=True, mode=0o700)
+        token = uuid.uuid4().hex
+        value = {"schema_version": 1, "token": token, "owner_pid": os.getpid(),
+                 "owner_identity": process_identity(os.getpid()), "process": None,
+                 "state": "reserved", "updated_at": now(), "error": None}
+        try:
+            write_json(self.path, value, immutable=True)
+        except FileExistsError:
+            raise ValueError("Another CRIT runtime owns execution or left unresolved cleanup. Unload it or run crit serve --recover-runtime.") from None
+        self.token = token
+
+    def read_owned(self):
+        value = read_ownership(self.path)
+        if not self.token or value.get("token") != self.token:
+            raise ValueError("Runtime ownership changed")
+        return value
+
+    def update(self, **changes):
+        value = self.read_owned()
+        write_json(self.path, value | changes | {"updated_at": now()})
+
+    def bind(self, tree):
+        if not tree.guardian or process_identity(tree.guardian["pid"]) != tree.guardian["identity"]:
+            raise ValueError("Launch guardian identity must be verified before binding")
+        self.update(process=tree.guardian | {"job_name": tree.job_name}, state="running")
+
+    def block(self, error):
+        if self.token:
+            self.blocked = str(error) or "Unresolved runtime cleanup"
+            try:
+                self.update(state="blocked", error=self.blocked)
+            except (ValueError, OSError) as exc:
+                # The existing exclusive guard still blocks other clients. Keep
+                # local quarantine even if the diagnostic update cannot persist.
+                self.blocked += "; could not record cleanup failure: " + str(exc)
+
+    def release(self, settled=False):
+        if self.token:
+            value = self.read_owned()
+            if not settled and (self.blocked or value["state"] == "blocked"):
+                raise ValueError("Prove runtime cleanup before releasing ownership")
+            self.path.unlink()
+            self.token = None
+            self.blocked = ""
+
+    def recover(self):
+        """Explicit dead-owner recovery; live owners and PID reuse block it."""
+        self.directory.mkdir(parents=True, exist_ok=True, mode=0o700)
+        with lease(self.directory):
+            if not self.path.exists():
+                return {"status": "idle"}
+            value = read_json(self.path)
+            keys(value, {"schema_version", "token", "owner_pid", "owner_identity", "process", "state", "updated_at", "error"}, {"runtime_id"})
+            if value["schema_version"] != 1 or value["state"] not in {"reserved", "running", "blocked"}:
+                raise ValueError("Invalid runtime ownership record")
+            number(value["owner_pid"], "runtime owner PID", 1, 2 ** 32, integer=True)
+            if not isinstance(value["token"], str) or not re.fullmatch(r"[0-9a-f]{32}", value["token"]):
+                raise ValueError("Invalid runtime ownership token")
+            if value["process"] is not None:
+                keys(value["process"], {"pid", "identity"}, {"job_name"})
+                number(value["process"]["pid"], "runtime process PID", 1, 2 ** 32, integer=True)
+            owner = process_identity(value["owner_pid"])
+            if owner is not None and (owner == "unknown" or owner == value["owner_identity"]):
+                raise ValueError("The runtime owner is still alive; use its Unload action")
+            child = value.get("process")
+            if child:
+                current = process_identity(child["pid"])
+                if current is not None and current != child["identity"]:
+                    raise ValueError("Process identity changed; refusing ambiguous cleanup")
+                if os.name == "nt":
+                    # Windows job ownership closes on owner death. Do not kill an
+                    # arbitrary process outside that job or infer that it settled.
+                    if current is not None or not windows_job_settled(child.get("job_name")):
+                        raise ValueError("Owned Windows job has not finished closing; retry recovery after settlement")
+                else:
+                    if child["identity"] in {None, "unknown"}:
+                        raise ValueError("Process birth identity is unavailable; refusing ambiguous recovery")
+                    boot_path = Path("/proc/sys/kernel/random/boot_id")
+                    if boot_path.exists() and not child["identity"].startswith(boot_path.read_text().strip() + ":"):
+                        raise ValueError("Runtime belongs to a different boot; verify and archive its stale guard explicitly")
+                    if current is None and group_alive(child["pid"]):
+                        raise ValueError("Live group has no matching birth-identified guardian; refusing ambiguous recovery")
+                    if group_alive(child["pid"]):
+                        os.killpg(child["pid"], signal.SIGKILL)
+                    end = time.monotonic() + RETIREMENT_SECONDS
+                    while group_alive(child["pid"]) and time.monotonic() < end:
+                        time.sleep(.02)
+                    if group_alive(child["pid"]):
+                        raise ValueError("Owned process group has not settled")
+            clean_snapshots(self.directory, value.get("runtime_id"))
+            # Before bind, the guardian cannot launch engine code. After bind,
+            # recovery has checked the recorded private process group/job.
+            recovery = value | {"recovered_at": now(), "recovery": "dead owner; owned process settlement verified"}
+            write_json(self.directory / ("recovery-" + uuid.uuid4().hex + ".json"), recovery, immutable=True)
+            self.path.unlink()
+            return {"status": "recovered"}