hyperstudy-perception 0.1.0__py3-none-any.whl

perception/estimates.py

@@ -0,0 +1,68 @@
+"""How long a node will take, from how long it took here: seconds per minute of video, per node and place, measured
+from this store's finished runs. A node that has not run on this machine in that place gets no estimate, not a guess.
+
+The video's length comes from a run's media.v1 artifact (decode writes it), or for a run being planned, from its
+cached decode or the file itself, read with PyAV as decode reads it (no ffprobe on the machine: an app started from
+the Finder has none on its PATH).
+"""
+
+from __future__ import annotations
+
+import json
+import statistics
+from pathlib import Path
+
+from .store import Artifact, Store
+
+
+def media_seconds(outputs: dict) -> float | None:
+    """The video length in a media.v1 output, if these outputs hold one."""
+    for a in outputs.values():
+        art = Artifact.from_json(a)
+        if art.type == "media.v1" and art.path.is_file():
+            duration = json.loads(art.path.read_text()).get("duration")
+            if duration:
+                return float(duration)
+    return None
+
+
+def run_seconds(store: Store, run_id: str) -> float | None:
+    for t in store.db.execute("SELECT outputs FROM tasks WHERE run_id=? AND outputs IS NOT NULL", (run_id,)):
+        seconds = media_seconds(json.loads(t["outputs"]))
+        if seconds:
+            return seconds
+    return None
+
+
+def probe_seconds(video: Path) -> float | None:
+    """A video's length, as decode's media.v1 will say it (the container's duration), when no decode output says it
+    yet; None for a file that is not a video."""
+    import av
+
+    if not video.is_file():
+        return None
+    try:
+        with av.open(str(video)) as container:
+            return container.duration / av.time_base if container.duration else None
+    except av.FFmpegError:
+        return None
+
+
+def estimate(store: Store, ref: str, place: str, video_seconds: float | None) -> tuple[float | None, str]:
+    """Seconds this node should take here on a video this long, and what that rests on."""
+    rows = store.db.execute(
+        """SELECT t.run_id, t.usage FROM tasks t JOIN cache c ON c.key = t.cache_key
+           WHERE t.state = 'succeeded' AND c.node = ? AND t.runner = ?""", (ref, place)).fetchall()
+    rates = []
+    for r in rows:
+        # the seconds the node itself ran (the SDK reports them), not the coordinator's clock: a node that finished
+        # while no coordinator watched would otherwise count that time too
+        ran = json.loads(r["usage"] or "{}").get("seconds")
+        seconds = run_seconds(store, r["run_id"])
+        if ran and seconds:
+            rates.append(ran / (seconds / 60))
+    if not rates:
+        return None, f"no runs of {ref} on {place} here yet"
+    if not video_seconds:
+        return None, f"the video's length is not known yet ({len(rates)} runs of {ref} on {place} here)"
+    return round(statistics.median(rates) * video_seconds / 60, 1), f"median of {len(rates)} runs of {ref} on {place} here"

perception/export.py

@@ -0,0 +1,100 @@
+"""Publishing a run as a track bundle (schema/bundle-0.1): the view the annotator and HyperStudy read.
+
+A bundle is not a second copy of the truth. Its layers are the run's committed `bundle.<layer>@0.1` artifacts, copied
+byte for byte, and its manifest records their checksums, the video (from the run's `media.v1` artifact) and each
+layer's licence mode: the strictest of its node's models and of every node upstream of it.
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+import time
+from pathlib import Path
+
+from . import artifacts
+from .release import release
+from .scheduler import Coordinator, LICENCE_ORDER
+
+SCHEMA_VERSION = "0.1.0"
+
+
+def _git_commit() -> str | None:
+    if r := release():
+        return r["commit"][:7]
+    out = subprocess.run(["git", "-C", str(Path(__file__).parent), "rev-parse", "--short", "HEAD"], capture_output=True, text=True)
+    return out.stdout.strip() or None
+
+
+def bundle(coord: Coordinator, run_id: str, out: Path) -> Path:
+    graph = coord.graph_of(run_id)
+    tasks = coord._tasks(run_id)
+    not_done = [i for i, t in tasks.items() if t["state"] not in ("succeeded", "cached")]
+    if not_done:
+        raise SystemExit(f"run {run_id} has unfinished nodes: {', '.join(not_done)}")
+    if (out / "manifest.json").exists():
+        raise SystemExit(f"{out} already holds a bundle")
+
+    own = {i: max([x.licence_mode for x in n.manifest.models] or ["commercial-ok"], key=LICENCE_ORDER.index) for i, n in graph.nodes.items()}
+    effective: dict[str, str] = {}
+
+    def licence(i: str) -> str:
+        if i not in effective:
+            effective[i] = max([own[i], *(licence(u) for u in graph.nodes[i].upstream)], key=LICENCE_ORDER.index)
+        return effective[i]
+
+    media, layers, asset_trees, writers = None, {}, [], {}
+    for node_id, t in tasks.items():
+        for name, a in json.loads(t["outputs"]).items():
+            kind = artifacts.get(a["type"])
+            if a["type"] == "assets.v1":
+                asset_trees.append(Path(a["path"]))
+            elif a["type"] == "media.v1":
+                media = json.loads(Path(a["path"]).read_text())
+            elif kind.layer:
+                writers.setdefault(kind.layer, []).append((node_id, Path(a["path"])))
+    for layer_name, ws in writers.items():
+        # a node that refines an upstream node's layer (captions on the shots layer) supersedes it; two unrelated
+        # writers of one layer are a graph error
+        last = [w for w in ws if not any(o[0] in graph.descendants(w[0]) for o in ws)]   # no other writer downstream
+        if len(last) != 1 or any(o is not last[0] and last[0][0] not in graph.descendants(o[0]) for o in ws):
+            raise SystemExit(f"the {layer_name} layer is written by unrelated nodes: {', '.join(w[0] for w in ws)}")
+        layers[layer_name] = last[0]
+    if media is None:
+        raise SystemExit("the run has no media.v1 artifact (a decode node): the bundle cannot name its video")
+
+    (out / "layers").mkdir(parents=True)
+    entries = {}
+    for name, (node_id, path) in layers.items():
+        dest = out / "layers" / f"{name}.json"
+        # stored layers carry no run time or timings (they would defeat the cache); the bundle gets them from the run
+        # that produced the layer, which for a cache hit is the original run
+        usage = json.loads(tasks[node_id]["usage"] or "{}")
+        doc = json.loads(path.read_text())
+        doc["producer"]["run_at"] = usage.get("finished_at")
+        doc["producer"]["timings"] = {**usage.get("timings", {}), "seconds": usage.get("seconds")}
+        dest.write_text(json.dumps(doc, separators=(",", ":")))
+        entries[name] = {"file": f"layers/{name}.json", "sha256": artifacts.sha256_file(dest), "bytes": dest.stat().st_size,
+                         "licence_mode": licence(node_id), "stage": graph.nodes[node_id].manifest.stage or graph.nodes[node_id].manifest.id}
+    assets = []
+    for tree in asset_trees:   # each node's assets tree merges into assets/; layers refer to "assets/<path>"
+        for src in sorted(p for p in tree.rglob("*") if p.is_file()):
+            rel = src.relative_to(tree).as_posix()
+            dest = out / "assets" / rel
+            if dest.exists():
+                raise SystemExit(f"two nodes write assets/{rel}")
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copyfile(src, dest)
+            dest.chmod(0o644)
+            assets.append({"file": f"assets/{rel}", "sha256": artifacts.sha256_file(dest), "bytes": dest.stat().st_size})
+    manifest = {
+        "format": "hyperstudy-perception-bundle", "schema_version": SCHEMA_VERSION,
+        "created_at": time.strftime("%Y-%m-%dT%H:%M:%S+00:00", time.gmtime()),
+        "video": {k: media[k] for k in ("sha256", "duration", "fps", "width", "height")} | ({"filename": media["filename"]} if media.get("filename") else {}),
+        "pipeline": {"name": "hyperstudy-perception", "version": "0.1.0", "git_commit": _git_commit(), "source": f"perception run {run_id}"},
+        "layers": entries,
+        "assets": assets,
+    }
+    (out / "manifest.json").write_text(json.dumps(manifest, indent=1))
+    return out

perception/hosts.py

@@ -0,0 +1,201 @@
+"""Other machines nodes can run on: lab servers reached over SSH (`perception hosts add NAME DEST`).
+
+A host is probed when it is added (and by `hosts check`): its platform, cores, memory, GPU and tools are recorded in
+$PERCEPTION_HOME/hosts.json, so planning never waits on the network. SSH runs in batch mode with the user's own keys
+and ~/.ssh/config: nothing here asks for or stores a password. Connections are shared (ControlMaster), so the many short
+commands a remote node needs cost one handshake.
+
+On the host everything lives under its root (default ~/.cache/hyperstudy-perception), which is private: created 0700, and
+refused if someone else owns it, so the code, inputs and markers kept there can be trusted and are not readable by others:
+    code/<hash>/         the files git tracks for the node, its uv project and the node SDK, by content
+    objects/<sha256>/data   inputs, by content: the video is sent once per host (each attempt links it under its name)
+    work/<run>/<node>/<attempt>/   the request, out/, response.json, log.txt and pid of one attempt: removed after it,
+                         or by the host's watchdog when no driver has asked about it for a while (a finished node's
+                         results wait a day for its driver)
+An attempt's unfinished uploads (objects/.incoming-*, code/.incoming-*) are removed when it ends.
+`perception hosts clean NAME` removes the root's inputs and code (what stays on the host between runs), unless a node
+is running there or the root is not marked as perception's. A host with a node running there is not removed either: that node could no longer be stopped.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import subprocess
+import time
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+from .backends.base import Capabilities
+
+NAME = re.compile(r"^[a-z0-9][a-z0-9-]{0,30}$")
+# an ssh destination: user@host, a host, or a ~/.ssh/config alias; never an option
+DEST = re.compile(r"^[A-Za-z0-9_][A-Za-z0-9_.@%+:\[\]-]*$")
+# a path on the host: plain characters, no `..`; relative ones are under the host's home
+ROOT = re.compile(r"^[A-Za-z0-9_./~-]+$")
+DEFAULT_ROOT = ".cache/hyperstudy-perception"
+RESERVED = {"native", "self", "cloud", "runpod", "local"}
+
+# What the host has, as key=value lines. POSIX sh: Linux servers and Macs, no Python needed. Tools are looked for on the
+# PATH a login shell would add too (~/.local/bin is where uv installs itself), since ssh commands get a minimal PATH.
+PROBE = r"""
+PATH="$HOME/.local/bin:$HOME/.cargo/bin:/opt/homebrew/bin:/usr/local/bin:$PATH"
+echo "home=$HOME"
+echo "system=$(uname -s)"
+echo "machine=$(uname -m)"
+echo "cores=$(getconf _NPROCESSORS_ONLN 2>/dev/null || sysctl -n hw.ncpu)"
+if [ -r /proc/meminfo ]; then echo "memory_kb=$(awk '/^MemTotal:/{print $2}' /proc/meminfo)"
+else echo "memory_kb=$(( $(sysctl -n hw.memsize) / 1024 ))"; fi
+for t in uv ffmpeg ffprobe; do echo "tool_$t=$(command -v $t || true)"; done
+if command -v nvidia-smi >/dev/null 2>&1; then
+  echo "vram_mib=$(nvidia-smi --query-gpu=memory.total --format=csv,noheader,nounits 2>/dev/null | sort -n | tail -1)"
+fi
+"""
+
+
+class HostError(RuntimeError):
+    pass
+
+
+@dataclass
+class Host:
+    name: str
+    dest: str
+    root: str                  # absolute, on the host
+    caps: Capabilities
+    probed_at: float
+
+    def to_json(self) -> dict:
+        d = asdict(self)
+        d["caps"]["accelerators"] = sorted(self.caps.accelerators)
+        return d
+
+    @classmethod
+    def from_json(cls, d: dict) -> "Host":
+        caps = Capabilities(**{**d["caps"], "accelerators": set(d["caps"]["accelerators"])})
+        return cls(d["name"], d["dest"], d["root"], caps, d["probed_at"])
+
+
+def ssh_command() -> list[str]:
+    """ssh with the options every remote command uses. PERCEPTION_SSH replaces the ssh program (the tests use a
+    stand-in that runs commands on this machine)."""
+    control = Path(f"/tmp/perception-ssh-{os.getuid()}")   # short: a socket path must fit in 104 bytes on macOS
+    control.mkdir(mode=0o700, exist_ok=True)
+    st = control.stat()
+    if st.st_uid != os.getuid() or st.st_mode & 0o077:
+        raise HostError(f"{control} must be a directory only you can use")
+    return [os.environ.get("PERCEPTION_SSH", "ssh"), "-o", "BatchMode=yes", "-o", "ConnectTimeout=15",
+            "-o", "ServerAliveInterval=15", "-o", "ServerAliveCountMax=4",
+            "-o", "ControlMaster=auto", "-o", f"ControlPath={control}/%C", "-o", "ControlPersist=120"]
+
+
+def check_names(name: str, dest: str, root: str):
+    if not NAME.match(name) or name in RESERVED:
+        raise HostError(f"a host's name is lower-case letters, digits and -, and not {', '.join(sorted(RESERVED))}: {name!r}")
+    if not DEST.match(dest):
+        raise HostError(f"not an ssh destination: {dest!r}")
+    parts = [x for x in root.removeprefix("~/").split("/") if x not in ("", ".")]
+    if not ROOT.match(root) or ".." in parts or "~" in root.removeprefix("~/") or not parts:
+        raise HostError(f"a host's root is a plain path below / or ~ (its own folder: `hosts clean` empties it): {root!r}")
+
+
+# The root is perception's own and private. It is used only if it is missing, empty or already marked as perception's
+# (MARKER): a folder of the user's own given by mistake is never changed or cleaned. It is created 0700, and refused if
+# someone else owns it: only the user can then write the code, inputs and completion markers kept there, so they are
+# trusted across runs, and others on a shared server cannot read the inputs.
+MARKER = ".hyperstudy-perception"
+PRIVATE_ROOT = r"""
+umask 077
+# the contents first, then the marker: perception writes there only after the marker exists, and never removes it, so
+# a root that another attempt is setting up at this moment is never taken for someone else's
+if [ -d "$root" ] && [ -n "$(ls -A "$root")" ] && [ ! -e "$root/.hyperstudy-perception" ]; then
+  echo "$root already holds other files: give perception a folder of its own (--root)" >&2; exit 3
+fi
+mkdir -p "$root"
+if [ "$(ls -ldn "$root" | awk '{print $3}')" != "$(id -u)" ]; then echo "$root belongs to someone else" >&2; exit 3; fi
+chmod 700 "$root"
+touch "$root/.hyperstudy-perception"
+"""
+
+
+def private_root_script(root: str) -> str:
+    """sh that makes `root` (absolute, or under the home) the user's own private folder, or fails."""
+    import shlex
+    path = shlex.quote(root) if root.startswith("/") else '"$HOME"/' + shlex.quote(root.removeprefix("~/"))
+    return f"root={path}\n" + PRIVATE_ROOT
+
+
+def probe(dest: str, root: str = DEFAULT_ROOT, ssh: list[str] | None = None) -> tuple[Capabilities, str]:
+    """What the host has, and its root as an absolute path (made private there, or refused: PRIVATE_ROOT). `ssh`: the
+    command to reach it, when it needs options of its own (a RunPod pod's key and port)."""
+    out = subprocess.run([*(ssh or ssh_command()), dest, "sh -s"], input=private_root_script(root) + PROBE, capture_output=True,
+                         text=True, timeout=120)
+    if out.returncode:
+        raise HostError(f"could not reach {dest} (ssh exit {out.returncode}): {out.stderr.strip()[-500:]}")
+    facts = dict(line.split("=", 1) for line in out.stdout.splitlines() if "=" in line)
+    try:
+        system = {"Linux": "linux", "Darwin": "darwin"}[facts["system"]]
+        arch = {"x86_64": "amd64", "amd64": "amd64", "arm64": "arm64", "aarch64": "arm64"}[facts["machine"]]
+        memory = int(facts["memory_kb"]) / 2**20
+        cores = int(facts["cores"])
+    except (KeyError, ValueError) as e:
+        raise HostError(f"{dest} answered, but not as expected ({e}): {out.stdout[-500:]}")
+    accelerators, vram = {"cpu"}, 0.0
+    if facts.get("vram_mib", "").strip().isdigit():
+        accelerators.add("cuda")
+        vram = int(facts["vram_mib"]) / 1024
+    if (system, arch) == ("darwin", "arm64"):
+        accelerators.add("mps")
+        vram = vram or memory   # unified memory
+    caps = Capabilities(platform=f"{system}/{arch}", cpu_cores=cores, memory_gb=round(memory, 1), accelerators=accelerators,
+                        vram_gb=round(vram, 1), tools={t: facts.get(f"tool_{t}") or None for t in ("uv", "ffmpeg", "ffprobe")})
+    home = facts["home"]
+    absolute = (root if root.startswith("/") else f"{home}/{root.removeprefix('~/')}").rstrip("/")
+    # plain characters in the whole path, the host's home too: rsync passes remote paths through the host's shell
+    if not ROOT.match(absolute):
+        raise HostError(f"{dest}'s folder for perception would be {absolute!r}, which is not a plain path (spaces?): give --root /a/plain/path")
+    return caps, absolute
+
+
+class Hosts:
+    """hosts.json in the store's home."""
+
+    def __init__(self, home: Path):
+        self.path = home / "hosts.json"
+
+    def load(self) -> dict[str, Host]:
+        if not self.path.exists():
+            return {}
+        return {name: Host.from_json(d) for name, d in json.loads(self.path.read_text()).items()}
+
+    def save(self, hosts: dict[str, Host]):
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = self.path.with_suffix(".tmp")
+        tmp.write_text(json.dumps({n: h.to_json() for n, h in sorted(hosts.items())}, indent=1))
+        os.replace(tmp, self.path)
+
+    def add(self, name: str, dest: str, root: str = DEFAULT_ROOT) -> Host:
+        check_names(name, dest, root)
+        caps, absolute = probe(dest, root)
+        host = Host(name, dest, absolute, caps, time.time())
+        hosts = self.load()
+        hosts[name] = host
+        self.save(hosts)
+        return host
+
+    def check(self, name: str) -> Host:
+        hosts = self.load()
+        if name not in hosts:
+            raise HostError(f"no host {name!r} (perception hosts list)")
+        old = hosts[name]
+        caps, _ = probe(old.dest, old.root)
+        hosts[name] = Host(name, old.dest, old.root, caps, time.time())
+        self.save(hosts)
+        return hosts[name]
+
+    def remove(self, name: str):
+        hosts = self.load()
+        if hosts.pop(name, None) is None:
+            raise HostError(f"no host {name!r}")
+        self.save(hosts)

perception/ir.py

@@ -0,0 +1,245 @@
+"""Graph files: parse, check against the node manifests, and compile into an ordered graph.
+
+    schema_version: 1
+    pipeline: perception-mvp
+    inputs:
+      video: {type: video.v1, uri: 'file:///data/clip.mp4'}
+    policy: {privacy: local-only, max_cost_usd: 0, retries: 2}
+    nodes:
+      - id: decode
+        uses: core.decode@1.0.0
+        inputs: {video: $inputs.video}
+      - id: faces
+        uses: vision.face-track@1.0.0
+        inputs: {video: $inputs.video, shots: $nodes.decode.shots}
+        config: {fps: 8}
+
+References are `$inputs.<name>` or `$nodes.<node id>.<output name>`. Compilation checks that every reference
+exists, that its artifact type is the one the consuming node's manifest declares, that every declared input is
+supplied, that config keys are known and valid, and that the graph has no cycles. The privacy policy is checked here
+too, so a graph that would upload what it may not never starts.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Literal
+from urllib.parse import unquote, urlparse
+
+import yaml
+from jsonschema import Draft202012Validator
+from pydantic import BaseModel, ConfigDict, Field, ValidationError
+
+from . import artifacts
+from .manifests import Manifest, Registry
+
+REF = re.compile(r"^\$(inputs)\.([A-Za-z0-9_-]+)$|^\$nodes\.([A-Za-z0-9_-]+)\.([A-Za-z0-9_-]+)$")
+
+
+class GraphError(Exception):
+    def __init__(self, problems: list[str]):
+        super().__init__("\n".join(problems))
+        self.problems = problems
+
+
+class Strict(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+
+class InputSpec(Strict):
+    type: str
+    uri: str
+
+
+UploadKind = Literal["video", "audio", "frames", "faces", "transcript", "embeddings"]
+UPLOAD_KINDS = UploadKind.__args__
+
+
+class Policy(Strict):
+    placement: Literal["local", "hybrid", "remote"] = "local"
+    # local-only: nothing leaves the machine. Otherwise a node may send out only the kinds of data allow_upload names
+    # (spec: video, audio, frames, faces, transcripts and embeddings are permitted separately).
+    privacy: Literal["local-only", "local-preferred", "allow-external"] = "local-only"
+    allow_upload: list[UploadKind] = Field(default_factory=list)
+    max_cost_usd: float = 0.0
+    retries: int = Field(default=2, ge=0, le=10)
+
+
+class NodeSpec(Strict):
+    id: str = Field(pattern=r"^[A-Za-z0-9_-]+$")
+    uses: str = Field(pattern=r"^[a-z0-9_.-]+@\d+\.\d+\.\d+$")
+    inputs: dict[str, str] = Field(default_factory=dict)
+    config: dict = Field(default_factory=dict)
+    backend: Literal["auto", "native", "self"] = "auto"
+    # where it runs, among the places it can run (`perception plan` lists them): native:mps, native:cpu, ssh-gpu1:cuda...
+    place: str | None = Field(default=None, pattern=r"^[a-z][a-z0-9-]*:[a-z]+$")
+
+
+class GraphSpec(Strict):
+    schema_version: Literal[1]
+    pipeline: str
+    inputs: dict[str, InputSpec]
+    outputs: dict[str, str] = Field(default_factory=dict)
+    policy: Policy = Field(default_factory=Policy)
+    nodes: list[NodeSpec]
+
+
+@dataclass
+class Ref:
+    node: str | None      # None: a graph input
+    name: str
+
+    def __str__(self):
+        return f"$inputs.{self.name}" if self.node is None else f"$nodes.{self.node}.{self.name}"
+
+
+@dataclass
+class CompiledNode:
+    spec: NodeSpec
+    manifest: Manifest
+    inputs: dict[str, Ref]
+    config: dict                              # manifest defaults + the graph's values
+    upstream: set[str] = field(default_factory=set)
+
+    @property
+    def id(self) -> str:
+        return self.spec.id
+
+
+@dataclass
+class Graph:
+    spec: GraphSpec
+    nodes: dict[str, CompiledNode]            # in topological order
+    source: Path | None = None
+
+    def input_path(self, name: str) -> Path:
+        uri = self.spec.inputs[name].uri
+        parsed = urlparse(uri)
+        if parsed.scheme not in ("file", ""):
+            raise GraphError([f"input {name}: only file:// inputs are supported locally ({uri})"])
+        path = Path(unquote(parsed.path)) if parsed.scheme else Path(uri)
+        if not path.is_absolute() and self.source:
+            path = self.source.parent / path
+        return path
+
+    def descendants(self, node_id: str) -> set[str]:
+        out, frontier = set(), {node_id}
+        while frontier:
+            frontier = {n.id for n in self.nodes.values() if n.upstream & frontier} - out
+            out |= frontier
+        return out
+
+
+def parse_ref(text: str) -> Ref | None:
+    m = REF.match(text)
+    if not m:
+        return None
+    return Ref(None, m.group(2)) if m.group(1) else Ref(m.group(3), m.group(4))
+
+
+def load(path: Path, registry: Registry) -> Graph:
+    doc = yaml.safe_load(path.read_text())
+    graph = compile_graph(doc, registry)
+    graph.source = path.resolve()
+    return graph
+
+
+def compile_graph(doc: dict, registry: Registry) -> Graph:
+    try:
+        spec = GraphSpec.model_validate(doc)
+    except ValidationError as e:
+        raise GraphError([f"{'.'.join(map(str, err['loc']))}: {err['msg']}" for err in e.errors()]) from None
+
+    problems: list[str] = []
+    for name, inp in spec.inputs.items():
+        if inp.type not in artifacts.TYPES:
+            problems.append(f"input {name}: unknown artifact type {inp.type}")
+    ids = [n.id for n in spec.nodes]
+    for dup in {i for i in ids if ids.count(i) > 1}:
+        problems.append(f"node id {dup} is used twice")
+
+    manifests: dict[str, Manifest] = {}
+    for n in spec.nodes:
+        try:
+            manifests[n.id] = registry.get(n.uses)
+        except KeyError as e:
+            problems.append(f"node {n.id}: {e.args[0]}")
+
+    compiled: dict[str, CompiledNode] = {}
+    for n in spec.nodes:
+        m = manifests.get(n.id)
+        if m is None:
+            continue
+        refs: dict[str, Ref] = {}
+        for name in n.inputs.keys() - m.inputs.keys():
+            problems.append(f"node {n.id}: {m.ref} has no input {name!r} (inputs: {', '.join(m.inputs) or 'none'})")
+        for name, want in m.inputs.items():
+            text = n.inputs.get(name)
+            if text is None:
+                problems.append(f"node {n.id}: input {name!r} ({want}) is not connected")
+                continue
+            ref = parse_ref(text)
+            if ref is None:
+                problems.append(f"node {n.id}: input {name}: {text!r} is not $inputs.<name> or $nodes.<id>.<output>")
+                continue
+            if ref.node is None:
+                got = spec.inputs[ref.name].type if ref.name in spec.inputs else None
+                if got is None:
+                    problems.append(f"node {n.id}: input {name}: graph has no input {ref.name!r}")
+            else:
+                src = manifests.get(ref.node)
+                if ref.node not in ids:
+                    problems.append(f"node {n.id}: input {name}: no node {ref.node!r}")
+                    continue
+                if src is None:
+                    continue
+                got = src.outputs.get(ref.name)
+                if got is None:
+                    problems.append(f"node {n.id}: input {name}: {src.ref} has no output {ref.name!r} (outputs: {', '.join(src.outputs)})")
+            if got is not None and got != want:
+                problems.append(f"node {n.id}: input {name} wants {want} but {text} is {got}")
+            refs[name] = ref
+
+        for key in n.config.keys() - m.config.keys():
+            problems.append(f"node {n.id}: {m.ref} has no config {key!r} (config: {', '.join(m.config) or 'none'})")
+        config = {**m.defaults(), **{k: v for k, v in n.config.items() if k in m.config}}
+        for key, value in config.items():
+            for err in Draft202012Validator(m.config[key]).iter_errors(value):
+                problems.append(f"node {n.id}: config {key}: {err.message}")
+
+        if spec.policy.privacy == "local-only" and m.privacy.external_upload:
+            problems.append(f"node {n.id}: {m.ref} uploads {', '.join(m.privacy.external_upload)}, but the graph's privacy policy is local-only")
+        elif not_allowed := [k for k in m.privacy.external_upload if k not in spec.policy.allow_upload]:
+            problems.append(f"node {n.id}: {m.ref} uploads {', '.join(not_allowed)}, which policy.allow_upload does not permit")
+
+        compiled[n.id] = CompiledNode(n, m, refs, config, {r.node for r in refs.values() if r.node})
+
+    order = _topological(compiled, problems)
+    if problems:
+        raise GraphError(problems)
+    return Graph(spec, {i: compiled[i] for i in order})
+
+
+def _topological(nodes: dict[str, CompiledNode], problems: list[str]) -> list[str]:
+    order, done, visiting = [], set(), []
+
+    def visit(i: str):
+        if i in done:
+            return
+        if i in visiting:
+            cycle = visiting[visiting.index(i):] + [i]
+            problems.append(f"cycle: {' -> '.join(cycle)}")
+            return
+        visiting.append(i)
+        for up in sorted(nodes[i].upstream):
+            if up in nodes:
+                visit(up)
+        visiting.pop()
+        done.add(i)
+        order.append(i)
+
+    for i in nodes:
+        visit(i)
+    return order