process-bigraph-lang 0.1.0__py3-none-win_amd64.whl

process_bigraph_lang/v2/interfaces.py

@@ -0,0 +1,236 @@
+"""
+Interface declarations as data: a minimal stage-A `describe` and the registry the normalizer resolves addresses in.
+
+`describe_module` imports a Python module once (the publish-time step; authoring never imports) and turns every
+step/process class it exposes into an `InterfaceDecl`: the address in portable `local:!module.Class` form, the
+`config_schema`, and the ports obtained by calling `inputs()`/`outputs()` with the class standing in for `self`
+(ports that depend on an instance are marked `dynamic_ports`). Types stay in bigraph-schema's own form. The
+`InterfaceRegistry` holds declarations and reads and writes the JSON manifest (`pblang-manifest/0`), which the
+TypeScript checker, printer and binder consume; `render_interfaces` has the CLI print the `.pblang` header file.
+"""
+
+from __future__ import annotations
+
+import importlib
+import inspect
+import json
+import tempfile
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from process_bigraph_lang.v2.types import MISSING, Named, parse_type
+
+MANIFEST_VERSION = "pblang-manifest/0"
+
+
+@dataclass
+class ConfigField:
+    """One entry of a `config_schema`: the type in bigraph-schema form and its default, when it has one."""
+
+    type: Any = None
+    default: Any = MISSING
+
+
+@dataclass
+class InterfaceDecl:
+    """A process/step interface as a manifest entry: address, config fields, ports (bigraph-schema forms)."""
+
+    name: str
+    kind: str  # process | step | adapter
+    address: str | None = None
+    module: str | None = None
+    config: dict[str, ConfigField] = field(default_factory=dict)
+    inputs: dict[str, Any] | None = None
+    outputs: dict[str, Any] | None = None
+    doc: str | None = None
+    dynamic_ports: bool = False  # inputs()/outputs() could not be evaluated without an instance
+
+
+def short_name(address: str) -> str:
+    """`Name` of `local:!pkg.mod.Name`, `local:Name` or `Name`."""
+    data = address.split(":", 1)[1] if ":" in address else address
+    return data.lstrip("!").rsplit(".", 1)[-1]
+
+
+def describe_module(module_name: str) -> list[InterfaceDecl]:
+    """Declarations for the step/process classes a module defines or re-exports (classes of its own package only)."""
+    module = importlib.import_module(module_name)
+    is_package = hasattr(module, "__path__")
+    decls: list[InterfaceDecl] = []
+    for name, cls in inspect.getmembers(module, inspect.isclass):
+        if name.startswith("_") or not _is_edge_class(cls) or not _belongs_to(cls, module_name, is_package):
+            continue
+        decls.append(describe_class(cls, module_name, name))
+    return decls
+
+
+def describe_class(cls: type, module_name: str | None = None, name: str | None = None) -> InterfaceDecl:
+    """The declaration of one step/process class."""
+    module_name = module_name or cls.__module__
+    name = name or cls.__name__
+    inputs, outputs, dynamic = _ports(cls)
+    return InterfaceDecl(
+        name=name,
+        kind=_kind(cls),
+        address=f"local:!{module_name}.{name}",
+        module=module_name,
+        config=_config_fields(getattr(cls, "config_schema", None) or {}),
+        inputs=inputs,
+        outputs=outputs,
+        doc=_doc(cls),
+        dynamic_ports=dynamic,
+    )
+
+
+@dataclass
+class InterfaceRegistry:
+    """Declarations by address: the manifest the CLI reads, and what the normalizer resolves edges in."""
+
+    decls: list[InterfaceDecl] = field(default_factory=list)
+
+    @classmethod
+    def from_modules(cls, *module_names: str) -> InterfaceRegistry:
+        registry = cls()
+        for module_name in module_names:
+            registry.decls.extend(describe_module(module_name))
+        return registry
+
+    @classmethod
+    def from_manifest(cls, manifest: dict[str, Any]) -> InterfaceRegistry:
+        return cls([_decl_from_manifest(entry) for entry in manifest.get("components", [])])
+
+    def to_manifest(self) -> dict[str, Any]:
+        return {"schema_version": MANIFEST_VERSION, "components": [_decl_to_manifest(d) for d in self.decls]}
+
+    def lookup(self, address: str) -> InterfaceDecl | None:
+        """By exact address; else by unique short name (`local:Name`, or a class re-exported from another module)."""
+        wanted = address if ":" in address else f"local:{address}"
+        if not wanted.startswith("local:"):
+            return None
+        exact = [d for d in self.decls if d.address == wanted]
+        if exact:
+            return exact[0]
+        by_name = [d for d in self.decls if d.name == short_name(wanted)]
+        return by_name[0] if len(by_name) == 1 else None
+
+    def write_manifest(self, path: Path) -> Path:
+        path.write_text(json.dumps(self.to_manifest(), indent=2, default=str) + "\n", encoding="utf-8")
+        return path
+
+
+def render_interfaces(decls: list[InterfaceDecl], module_name: str) -> str:
+    """The `.pblang` header file of a module's declarations, as the CLI prints it."""
+    from process_bigraph_lang.v2.langium import run_cli
+
+    with tempfile.TemporaryDirectory() as tmp:
+        manifest = Path(tmp) / "manifest.json"
+        entries = [_decl_to_manifest(d) for d in decls]
+        for entry in entries:
+            entry["module"] = module_name
+        manifest.write_text(json.dumps({"schema_version": MANIFEST_VERSION, "components": entries}, default=str))
+        return run_cli("headers", str(manifest)).stdout
+
+
+# --- describe ----------------------------------------------------------------------------------------------------
+
+
+def _is_edge_class(cls: type) -> bool:
+    return any(base.__name__ == "Edge" for base in cls.__mro__)
+
+
+def _belongs_to(cls: type, module_name: str, is_package: bool) -> bool:
+    """Defined in the module itself, or (for a package) re-exported from one of its submodules."""
+    return cls.__module__ == module_name or (is_package and cls.__module__.startswith(module_name + "."))
+
+
+def _kind(cls: type) -> str:
+    names = [base.__name__ for base in cls.__mro__]
+    if "Process" in names:
+        return "process"
+    return "step"
+
+
+def _ports(cls: type) -> tuple[dict[str, Any] | None, dict[str, Any] | None, bool]:
+    faces: list[dict[str, Any] | None] = []
+    dynamic = False
+    for method_name in ("inputs", "outputs"):
+        method = getattr(cls, method_name, None)
+        if method is None:
+            faces.append(None)
+            continue
+        try:
+            ports = method(cls)  # the class stands in for `self`: works for literal port dicts
+        except Exception:  # noqa: BLE001 - ports depend on an instance (self.config, children, ...)
+            faces.append(None)
+            dynamic = True
+            continue
+        faces.append({str(k): v for k, v in ports.items()} if isinstance(ports, dict) else None)
+    return faces[0], faces[1], dynamic
+
+
+def _config_fields(schema: Any) -> dict[str, ConfigField]:
+    if not isinstance(schema, dict):
+        return {}
+    fields: dict[str, ConfigField] = {}
+    for key, spec in schema.items():
+        default: Any = MISSING
+        try:
+            expr = parse_type(spec)
+            if isinstance(expr, Named):
+                default = expr.default
+        except (TypeError, ValueError):
+            pass
+        fields[str(key)] = ConfigField(spec if isinstance(spec, (str, dict)) else None, default)
+    return fields
+
+
+def _doc(cls: type) -> str | None:
+    text = cls.__dict__.get("__doc__")
+    if not text:
+        return None
+    first = inspect.cleandoc(text).split("\n\n", 1)[0].strip()
+    return first or None
+
+
+# --- manifest ----------------------------------------------------------------------------------------------------
+
+
+def _decl_to_manifest(decl: InterfaceDecl) -> dict[str, Any]:
+    entry: dict[str, Any] = {
+        "name": decl.name,
+        "kind": decl.kind,
+        "address": decl.address,
+        "module": decl.module,
+        "config": {
+            k: {"type": f.type, **({"default": f.default} if f.default is not MISSING else {})}
+            for k, f in decl.config.items()
+        },
+        "inputs": dict(decl.inputs) if decl.inputs is not None else None,
+        "outputs": dict(decl.outputs) if decl.outputs is not None else None,
+        "dynamic_ports": decl.dynamic_ports,
+    }
+    if decl.doc:
+        entry["doc"] = decl.doc
+    return entry
+
+
+def _decl_from_manifest(entry: dict[str, Any]) -> InterfaceDecl:
+    config = {k: ConfigField(f.get("type"), f.get("default", MISSING)) for k, f in (entry.get("config") or {}).items()}
+    return InterfaceDecl(
+        name=entry["name"],
+        kind=entry.get("kind", "process"),
+        address=entry["address"] if entry.get("address") else None,
+        module=entry.get("module"),
+        config=config,
+        inputs=_ports_from_manifest(entry.get("inputs")),
+        outputs=_ports_from_manifest(entry.get("outputs")),
+        doc=entry.get("doc"),
+        dynamic_ports=bool(entry.get("dynamic_ports", False)),
+    )
+
+
+def _ports_from_manifest(ports: Any) -> dict[str, Any] | None:
+    if ports is None:
+        return None
+    return {str(k): v for k, v in ports.items()}

process_bigraph_lang/v2/langium.py

@@ -0,0 +1,38 @@
+"""
+The DSL CLI from Python: `cli-native` (the same binary v1 uses, built once by Deno at wheel-build time) or
+`node dsl/bin/cli.js` in a development checkout. Everything the v2 language does, parsing, checking, compiling,
+decompiling and rendering headers, lives in TypeScript (`dsl/src/language/v2/`); Python only calls it.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+_ROOT = Path(__file__).resolve().parent.parent
+
+
+def langium_cli() -> list[str] | None:
+    """The command that runs the DSL CLI, or None when neither the native binary nor a built checkout exists."""
+    for candidate in (_ROOT / "bin").glob("cli-native*"):
+        return [str(candidate)]
+    script = _ROOT.parent / "dsl" / "bin" / "cli.js"
+    if script.exists() and (_ROOT.parent / "dsl" / "out").exists():
+        return ["node", str(script)]
+    return None
+
+
+def run_cli(*args: str, check: bool = True) -> subprocess.CompletedProcess[str]:
+    """Run a CLI command; raise with its stderr when it fails (unless `check=False`)."""
+    command = langium_cli()
+    if command is None:
+        raise RuntimeError("no Langium CLI: build dsl/ (npm run build) or install the cli-native binary")
+    result = subprocess.run([*command, *args], capture_output=True, text=True, encoding="utf-8", check=False)
+    if check and result.returncode != 0:
+        raise RuntimeError(
+            f"Langium CLI failed ({' '.join(args[:2])}): {result.stderr.strip() or result.stdout.strip()}"
+        )
+    return result
+
+
+__all__ = ["langium_cli", "run_cli"]

process_bigraph_lang/v2/normalize.py

@@ -0,0 +1,384 @@
+"""
+Equivalence of composite documents modulo representation.
+
+Two documents are equivalent when they realize the same composite. `normalize_document` rewrites a document
+into one canonical shape: types are pushed through bigraph-schema (`core.access` + `core.render(defaults=True)`),
+addresses become `protocol:data` strings, wires become lists, tuples and arrays become lists, runtime keys
+(`instance`, `_contract`, the root `global_time`) are dropped, and the edge entries of the schema half are folded
+into the state half. `equivalent` compares two normalized documents; `diff_documents` explains a difference.
+"""
+
+from __future__ import annotations
+
+import difflib
+import json
+import math
+from typing import Any
+
+import numpy as np
+
+from process_bigraph_lang.v2.interfaces import InterfaceRegistry
+from process_bigraph_lang.v2.types import MISSING, Group, Named, Struct, TypeExpr, UnionType, parse_type
+
+EDGE_KINDS = ("process", "step", "shared_process", "shared_process_ref")
+RUNTIME_EDGE_KEYS = ("instance", "_contract")
+COMPOSITE_OPTION_KEYS = (
+    "global_time_precision",
+    "run_steps_on_init",
+    "parallel_steps",
+    "parallel_processes",
+    "parallel_workers",
+    "skip_process_state",
+    "contract_strict",
+)
+
+
+def is_site(value: Any) -> bool:
+    """A template site: `{"_type": "site", "_sort": ..., "_default"?: ...}`."""
+    return isinstance(value, dict) and value.get("_type") == "site"
+
+
+def is_edge_node(value: Any) -> bool:
+    """A step/process node in the state half (its `_type` says so, or it carries an `address`)."""
+    return isinstance(value, dict) and (value.get("_type") in EDGE_KINDS or "address" in value)
+
+
+_EdgeTable = dict[tuple[str, ...], dict[str, Any]]
+
+
+def normalize_document(doc: dict[str, Any], core: Any, registry: InterfaceRegistry | None = None) -> dict[str, Any]:
+    """
+    The canonical shape of a document (see the module docstring). `core` is a bigraph-schema core. With a
+    `registry`, an edge's `_inputs`/`_outputs` that merely repeat its interface's face are dropped (process-bigraph
+    merges them with `interface()`, so they carry no information).
+    """
+    table: _EdgeTable = {}
+    raw_schema = doc.get("schema") or {}
+    schema = _norm_schema(raw_schema, core, (), table)
+    state = _norm_state(doc.get("state") or {}, raw_schema, core, (), table, registry)
+    options = {k: _canon(doc[k], core) for k in COMPOSITE_OPTION_KEYS if k in doc}
+    return {"schema": schema if isinstance(schema, dict) else {}, "state": state, "options": options}
+
+
+def equivalent(a: dict[str, Any], b: dict[str, Any], core: Any, registry: InterfaceRegistry | None = None) -> bool:
+    return deep_equal(normalize_document(a, core, registry), normalize_document(b, core, registry))
+
+
+def diff_documents(
+    a: dict[str, Any], b: dict[str, Any], core: Any, limit: int = 200, registry: InterfaceRegistry | None = None
+) -> str:
+    """A readable account of how two documents differ after normalization (empty when equivalent)."""
+    left, right = normalize_document(a, core, registry), normalize_document(b, core, registry)
+    flat_left, flat_right = _flatten(left), _flatten(right)
+    lines: list[str] = []
+    for key in sorted(set(flat_left) | set(flat_right)):
+        if key not in flat_right:
+            lines.append(f"- {key}: {_show(flat_left[key])}")
+        elif key not in flat_left:
+            lines.append(f"+ {key}: {_show(flat_right[key])}")
+        elif not deep_equal(flat_left[key], flat_right[key]):
+            lines.append(f"~ {key}: {_show(flat_left[key])} -> {_show(flat_right[key])}")
+    if len(lines) > limit:
+        lines = [*lines[:limit], f"... {len(lines) - limit} more"]
+    if not lines and not deep_equal(left, right):
+        dump_left = json.dumps(left, indent=2, sort_keys=True, default=str).splitlines()
+        dump_right = json.dumps(right, indent=2, sort_keys=True, default=str).splitlines()
+        lines = list(difflib.unified_diff(dump_left, dump_right, "a", "b", lineterm=""))
+    return "\n".join(lines)
+
+
+def deep_equal(a: Any, b: Any, *, strict: bool = False, rel_tol: float = 1e-9) -> bool:
+    """
+    Structural equality that tolerates numpy arrays and float noise.
+
+    With `strict=False` (the normalizer's mode) tuples equal lists and ints equal floats; with `strict=True`
+    container types and numeric types must match exactly (the v1 parity tests use this).
+    """
+    if isinstance(a, np.ndarray) or isinstance(b, np.ndarray):
+        if strict and not (isinstance(a, np.ndarray) and isinstance(b, np.ndarray)):
+            return False
+        return deep_equal(_to_list(a), _to_list(b), strict=False, rel_tol=rel_tol)
+    if isinstance(a, dict) and isinstance(b, dict):
+        return set(a) == set(b) and all(deep_equal(a[k], b[k], strict=strict, rel_tol=rel_tol) for k in a)
+    if isinstance(a, (list, tuple)) and isinstance(b, (list, tuple)):
+        if strict and type(a) is not type(b):
+            return False
+        return len(a) == len(b) and all(deep_equal(x, y, strict=strict, rel_tol=rel_tol) for x, y in zip(a, b))
+    if isinstance(a, bool) or isinstance(b, bool):
+        return a is b or (isinstance(a, bool) and isinstance(b, bool) and a == b)
+    if _is_number(a) and _is_number(b):
+        if strict and (isinstance(a, float) != isinstance(b, float)):
+            return False
+        return math.isclose(float(a), float(b), rel_tol=rel_tol, abs_tol=0.0)
+    return bool(a == b)
+
+
+# --- schema half -------------------------------------------------------------------------------------------------
+
+
+def _norm_schema(schema: Any, core: Any, path: tuple[str, ...], table: _EdgeTable) -> Any:
+    if isinstance(schema, dict) and schema.get("_type") in EDGE_KINDS:
+        table[path] = {k: schema[k] for k in ("_type", "_inputs", "_outputs") if k in schema}
+        return None
+    if isinstance(schema, dict) and "_type" not in schema:
+        out: dict[str, Any] = {}
+        for key in sorted(schema, key=str):
+            if not path and key == "global_time":
+                continue
+            value = _norm_schema(schema[key], core, (*path, str(key)), table)
+            if value is not None:
+                out[str(key)] = value
+        return out
+    return _canon_type(schema, core)
+
+
+def _canon_type(spec: Any, core: Any) -> Any:
+    """
+    One canonical shape for every spelling of a type: `float{3.5}` and `{"_type": "float", "_default": 3.5}`,
+    `map[string,float]` and `map[float]`, `a:float|b:float` and `{"a": "float", "b": "float"}`,
+    `array[(2|3),T]` and `{"_type": "array", "_shape": [2, 3], "_data": T}`. The canonical form is built from
+    the parsed type tree, so unknown (custom) type names survive.
+    """
+    try:
+        expr = parse_type(spec)
+    except (TypeError, ValueError, KeyError, IndexError):
+        return _canon(spec, core)
+    return _canon_expr(expr, core)
+
+
+def _canon_expr(expr: TypeExpr, core: Any) -> Any:
+    if isinstance(expr, Named):
+        return _canon_named(expr, core)
+    if isinstance(expr, Struct):
+        return {k: _canon_expr(v, core) for k, v in sorted(expr.fields.items())}
+    if isinstance(expr, UnionType):
+        return {"_type": "union", "_options": [_canon_expr(o, core) for o in expr.options]}
+    if isinstance(expr, Group):
+        return [int(i) if str(i).lstrip("-").isdigit() else i for i in expr.items]
+    out: dict[str, Any] = {}
+    for key, value in sorted(expr.attrs.items(), key=lambda kv: str(kv[0])):
+        if key in ("_inputs", "_outputs"):
+            out[key] = _canon_ports(value, core)
+        elif key in ("_value", "_element", "_data", "_sort", "_key", "_leaf") and isinstance(value, (str, dict)):
+            out[key] = _canon_type(value, core)
+        else:
+            out[key] = _canon(value, core)
+    return out
+
+
+def _canon_named(expr: Named, core: Any) -> Any:
+    name = _TYPE_ALIASES.get(expr.name, expr.name)
+    groups = [a for a in expr.args if isinstance(a, Group)]
+    others = [a for a in expr.args if not isinstance(a, Group)]
+    if name == "map" and len(others) == 2 and isinstance(others[0], Named) and others[0].name == "string":
+        others = others[1:]
+    out: Any
+    numeric = [a for a in others if isinstance(a, Named) and a.name.lstrip("-").isdigit()]
+    if name == "array" or groups or expr.units is not None:
+        dims = _canon_expr(groups[0], core) if groups else [int(a.name) for a in numeric]
+        data = [a for a in others if a not in numeric]
+        out = {"_type": name, "_shape": dims or [1], "_data": _canon_expr(data[-1], core) if data else "float"}
+        if expr.units is not None:
+            out["_units"] = expr.units
+    elif others:
+        out = {"_type": name, "_args": [_canon_expr(a, core) for a in others]}
+    else:
+        out = name
+    if expr.default is not MISSING:
+        out = {"_type": out} if isinstance(out, str) else out
+        out["_default"] = _canon(expr.default, core)
+    return out
+
+
+def _canon_ports(ports: Any, core: Any) -> Any:
+    if isinstance(ports, str):
+        try:
+            parsed = parse_type(ports)
+        except (TypeError, ValueError, KeyError, IndexError):
+            return ports
+        ports = parsed.fields if isinstance(parsed, Struct) else {}
+        return {str(k): _canon_expr(v, core) for k, v in sorted(ports.items())}
+    if isinstance(ports, dict):
+        return {str(k): _canon_type(v, core) for k, v in sorted(ports.items(), key=lambda kv: str(kv[0]))}
+    return _canon(ports, core)
+
+
+_TYPE_ALIASES = {"int": "integer", "bool": "boolean"}
+
+
+# --- state half --------------------------------------------------------------------------------------------------
+
+
+def _norm_state(
+    state: Any,
+    schema: Any,
+    core: Any,
+    path: tuple[str, ...],
+    table: _EdgeTable,
+    registry: InterfaceRegistry | None = None,
+) -> Any:
+    if is_site(state):
+        return _canon_site(state, core)
+    if isinstance(state, dict) and (is_edge_node(state) or path in table):
+        return _canon_edge(state, core, path, table, registry)
+    if isinstance(state, dict) and not (isinstance(schema, dict) and "_type" in schema):
+        out: dict[str, Any] = {}
+        sub_schema = schema if isinstance(schema, dict) else {}
+        keys = set(state) | {k for k in sub_schema if (*path, str(k)) not in table}
+        for key in sorted(keys, key=str):
+            if not path and key == "global_time":
+                continue
+            if key in state:
+                out[str(key)] = _norm_state(state[key], sub_schema.get(key), core, (*path, str(key)), table, registry)
+            else:
+                default = _schema_default(sub_schema[key], core)
+                if default is not None:
+                    out[str(key)] = _norm_state(default, sub_schema[key], core, (*path, str(key)), table, registry)
+        return out
+    return _canon(state, core)
+
+
+def _schema_default(schema: Any, core: Any) -> Any:
+    """What process-bigraph materializes for a schema entry that has no state (a saved document contains it)."""
+    if isinstance(schema, dict) and schema.get("_type") in EDGE_KINDS:
+        return None
+    try:
+        default = core.default(core.access(schema))
+    except Exception:  # noqa: BLE001
+        return None
+    return default[1] if isinstance(default, tuple) and len(default) == 2 else default
+
+
+def _canon_edge(
+    node: dict[str, Any],
+    core: Any,
+    path: tuple[str, ...],
+    table: _EdgeTable,
+    registry: InterfaceRegistry | None = None,
+) -> dict[str, Any]:
+    info = table.get(path, {})
+    out: dict[str, Any] = {"_type": node.get("_type") or info.get("_type")}
+    address = node.get("address")
+    if address is not None:
+        out["address"] = _canon_address(address, core)
+    decl = None
+    if registry is not None and address is not None and not is_site(address):
+        decl = registry.lookup(_canon_address(address, core))
+        if decl is not None and decl.address is not None:
+            out["address"] = decl.address  # `local:Name` and `local:!module.Name` name the same component
+    for key, attr in (("_inputs", "inputs"), ("_outputs", "outputs")):
+        ports = node.get(key, info.get(key))
+        if ports is None:
+            continue
+        canon = _canon_ports(ports, core)
+        declared = getattr(decl, attr) if decl is not None else None
+        if declared is not None and canon == _canon_ports(declared, core):
+            continue  # the node repeats the interface's face: no information
+        out[key] = canon
+    config = node.get("config")
+    if isinstance(config, dict) and _is_composite_address(address):
+        config = dict(config)
+        inner_table: _EdgeTable = {}
+        inner_schema = config.get("schema") or {}
+        config["schema"] = _norm_schema(inner_schema, core, (), inner_table) or {}
+        config["state"] = _norm_state(config.get("state") or {}, inner_schema, core, (), inner_table, registry)
+    if config:
+        out["config"] = _canon(config, core)
+    for key in ("inputs", "outputs", "_triggers"):
+        if node.get(key):
+            out[key] = _canon_wires(node[key])
+    # a process without an interval runs every 1.0: the default is not a difference
+    if (
+        node.get("interval") is not None
+        and not _is_number(node["interval"])
+        or (_is_number(node.get("interval")) and not math.isclose(float(node["interval"]), 1.0))
+    ):
+        out["interval"] = _canon(node["interval"], core)
+    if node.get("priority") is not None:
+        out["priority"] = _canon(node["priority"], core)
+    for key, value in node.items():
+        if key in out or key in RUNTIME_EDGE_KEYS or key in ("_type", "address", "config", "inputs", "outputs"):
+            continue
+        if key in ("_inputs", "_outputs", "_triggers", "interval", "priority"):
+            continue
+        out[str(key)] = _canon(value, core)
+    return out
+
+
+def _is_composite_address(address: Any) -> bool:
+    text = _canon_address(address, None) if address is not None else ""
+    return isinstance(text, str) and text.split(":", 1)[-1].lstrip("!").rsplit(".", 1)[-1] == "Composite"
+
+
+def _canon_address(address: Any, core: Any) -> Any:
+    if is_site(address):
+        return _canon_site(address, core)
+    if isinstance(address, dict) and "protocol" in address:
+        return f"{address['protocol']}:{address.get('data', '')}"
+    if isinstance(address, str) and ":" not in address:
+        return f"local:{address}"
+    return address
+
+
+def _canon_site(site: dict[str, Any], core: Any) -> dict[str, Any]:
+    out: dict[str, Any] = {"_type": "site"}
+    if "_sort" in site:
+        sort = site["_sort"]
+        out["_sort"] = _canon_type(sort, core) if core is not None else _canon(sort, core)
+    if "_default" in site:
+        out["_default"] = _canon(site["_default"], core)
+    return out
+
+
+def _canon_wires(wires: Any) -> Any:
+    if isinstance(wires, dict):
+        return {str(k): _canon_wires(v) for k, v in sorted(wires.items(), key=lambda kv: str(kv[0]))}
+    if isinstance(wires, str):
+        return [wires]
+    if isinstance(wires, (list, tuple)):
+        return [int(s) if isinstance(s, (int, np.integer)) and not isinstance(s, bool) else str(s) for s in wires]
+    return wires
+
+
+# --- values ------------------------------------------------------------------------------------------------------
+
+
+def _canon(value: Any, core: Any) -> Any:
+    if is_site(value):
+        return _canon_site(value, core)
+    if isinstance(value, dict):
+        return {str(k): _canon(v, core) for k, v in sorted(value.items(), key=lambda kv: str(kv[0]))}
+    if isinstance(value, (list, tuple)):
+        return [_canon(v, core) for v in value]
+    if isinstance(value, np.ndarray):
+        return _canon(value.tolist(), core)
+    if isinstance(value, np.generic):
+        return value.item()
+    return value
+
+
+def _to_list(value: Any) -> Any:
+    return value.tolist() if isinstance(value, np.ndarray) else value
+
+
+def _is_number(value: Any) -> bool:
+    return isinstance(value, (int, float, np.integer, np.floating)) and not isinstance(value, bool)
+
+
+def _flatten(tree: Any, prefix: str = "") -> dict[str, Any]:
+    if isinstance(tree, dict) and tree:
+        out: dict[str, Any] = {}
+        for key, value in tree.items():
+            out.update(_flatten(value, f"{prefix}/{key}" if prefix else str(key)))
+        return out
+    if isinstance(tree, list) and tree and any(isinstance(v, (dict, list)) for v in tree):
+        out = {}
+        for index, value in enumerate(tree):
+            out.update(_flatten(value, f"{prefix}[{index}]"))
+        return out
+    return {prefix: tree}
+
+
+def _show(value: Any) -> str:
+    text = json.dumps(value, default=str)
+    return text if len(text) <= 120 else text[:117] + "..."