zipzi 0.1.0a2__tar.gz

zipzi-0.1.0a2/LICENSE-MIT

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zipzi 2D Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

zipzi-0.1.0a2/PKG-INFO

@@ -0,0 +1,40 @@
+Metadata-Version: 2.4
+Name: zipzi
+Version: 0.1.0a2
+Summary: Typed Python client for the Zipzi authoring Runtime
+License-Expression: MIT
+License-File: LICENSE-MIT
+License-File: THIRD_PARTY_NOTICES.md
+Requires-Python: >=3.14, <3.15
+Description-Content-Type: text/markdown
+
+# zipzi
+
+Pure Python authoring client for Zipzi. Import it as `zipzi` and use
+`zipzi.connect()` to attach to a resident desktop host. Install `zipzi-native`
+to use the in-process `zipzi.local()` backend.
+
+Use `runtime.sessions.list()` and `sessions.attach(info.id)` to work with an
+existing document. Changes made through an Edit share the Editor's document and
+undo history; saving is separate. Reads return source-bound `Snapshot` or `Batch`
+values. Jobs must be waited or closed to release their resources.
+
+If a response is lost, recover the original call with `OutcomeUnknown.recover()`
+or `zipzi.recover_call(bound_sdk_method, ...)`. A timed-out `job.wait()` does
+not cancel the job. Close an unresolved Runtime only after recovery or with
+`abandon_pending=True`.
+
+The package includes `zipzi/docs/guide.md`, `reference.md` and `recipes.py`;
+`zipzi.describe("zipzi")` works offline. See the [package source](https://github.com/getzipzi/zipzi-2d/tree/main/crates/zipzi-python2)
+for setup, examples and tests.
+
+For an Editor handoff, run:
+
+```sh
+python -I -m zipzi.docs.editor_handoff list
+python -I -m zipzi.docs.editor_handoff rename \
+  --runtime RUNTIME_UUID --session SESSION_SERIAL --mesh MESH_UUID --name "Refined face"
+```
+
+Pass `--endpoint /absolute/path/to/profile.sock` before the subcommand to select
+a particular host.

zipzi-0.1.0a2/README.md

@@ -0,0 +1,30 @@
+# zipzi
+
+Pure Python authoring client for Zipzi. Import it as `zipzi` and use
+`zipzi.connect()` to attach to a resident desktop host. Install `zipzi-native`
+to use the in-process `zipzi.local()` backend.
+
+Use `runtime.sessions.list()` and `sessions.attach(info.id)` to work with an
+existing document. Changes made through an Edit share the Editor's document and
+undo history; saving is separate. Reads return source-bound `Snapshot` or `Batch`
+values. Jobs must be waited or closed to release their resources.
+
+If a response is lost, recover the original call with `OutcomeUnknown.recover()`
+or `zipzi.recover_call(bound_sdk_method, ...)`. A timed-out `job.wait()` does
+not cancel the job. Close an unresolved Runtime only after recovery or with
+`abandon_pending=True`.
+
+The package includes `zipzi/docs/guide.md`, `reference.md` and `recipes.py`;
+`zipzi.describe("zipzi")` works offline. See the [package source](https://github.com/getzipzi/zipzi-2d/tree/main/crates/zipzi-python2)
+for setup, examples and tests.
+
+For an Editor handoff, run:
+
+```sh
+python -I -m zipzi.docs.editor_handoff list
+python -I -m zipzi.docs.editor_handoff rename \
+  --runtime RUNTIME_UUID --session SESSION_SERIAL --mesh MESH_UUID --name "Refined face"
+```
+
+Pass `--endpoint /absolute/path/to/profile.sock` before the subcommand to select
+a particular host.

zipzi-0.1.0a2/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,33 @@
+# Third-party notices
+
+The repository-level MIT License applies only where a file, directory,
+dependency, or submodule does not carry a different notice. The following
+upstream works retain their original copyrights and license terms.
+
+
+## PurismCore
+
+`third_party/purism-core` is a forked Git submodule of
+[PurismCore](https://github.com/SakuraMotion/PurismCore).
+
+Copyright (c) 2026 Sakura Motion Project.
+
+PurismCore is distributed under the MIT License included in that submodule.
+
+## Imported Editor and patched dependencies
+
+Editor-owned source and assets retain GPL-3.0-only; see [LICENSING](LICENSING.md)
+and the full [GPL text](LICENSE-GPL-3.0). Patched GPUI sources now live in `vendor/`;
+their original notices and [dependency/patch record](vendor/README.md#dependencies)
+remain authoritative. Directory flattening does not relicense third-party code.
+
+## PSD2Live adaptive mesh generator
+
+`crates/zipzi-editor-core/src/adaptive_mesh/` is a Rust adaptation of the automatic
+mesh-generation code in [PSD2Live](https://github.com/tsunehimatoi/psd2live),
+revision `692986728e2b7b9254a41a22bdce1656bc0c12f9`, by the PSD2Live contributors.
+It retains **GPL-3.0-only**, including its derived synthetic reference outputs in
+`fixtures/mesh-generation/psd2live.json`. The original and adapted file mapping and
+numerical substitutions are documented in that module's README. These sources
+are part of the GPL Editor, not the MIT SDK. The full license is included in
+`LICENSE-GPL-3.0`.

zipzi-0.1.0a2/pyproject.toml

@@ -0,0 +1,16 @@
+[build-system]
+requires = ["uv_build==0.10.7"]
+build-backend = "uv_build"
+
+[project]
+name = "zipzi"
+version = "0.1.0a2"
+requires-python = ">=3.14,<3.15"
+description = "Typed Python client for the Zipzi authoring Runtime"
+license = "MIT"
+license-files = ["LICENSE-MIT", "THIRD_PARTY_NOTICES.md"]
+readme = "README.md"
+
+[tool.uv.build-backend]
+module-name = "zipzi"
+module-root = "python"

zipzi-0.1.0a2/python/zipzi/__init__.py

@@ -0,0 +1,69 @@
+"""Typed Python authoring API backed by the Zipzi Runtime."""
+from pathlib import Path
+from . import modeling as modeling, bindings, sampling, events, meshes, ops, parameters, resources, scene, references, animation, spatial, observation, inspection
+from ._plans import Plan
+from ._generated.plan_values import PlanCost, PlanReport
+from .resources import PreparedImage
+from .buffers import Buffer
+from ._errors import Busy, JobTimeout, OutcomeUnknown, PendingRequest, RecoveryAction, SdkFailure
+from ._lifecycle import Edit, EditState, Job, JobState, Runtime, Session
+from ._calls import recover_call as recover_call
+from ._results import Batch, Page, PageCursor, Snapshot
+from ._values import ConnectionInfo, ConnectionLimits, Receipt, SaveReceipt, SessionId, SessionInfo, Source, Version, WriteResult
+
+def local() -> Runtime:
+    'Explicitly create an owned in-process Runtime with the paired optional native wheel. Importing zipzi alone does not start it. Use as a context manager; close releases its sessions without saving or connecting to another host.'
+    from .backends.local import LocalBackend
+    return Runtime(LocalBackend())
+
+def connect(*, endpoint: Path | None = None, start: bool = False, host: Path | None = None,
+    timeout: float = 10., startup_timeout: float = 15., sdk_build: str | None = None) -> Runtime:
+    """Connect to an explicit/discovered host and return an owned Runtime client.
+
+    endpoint is an absolute private Unix socket path or a local Windows Named
+    Pipe name; None discovers it from ZIPZI_RUNTIME_DIR/ZIPZI_RUNTIME_PROFILE.
+    On Windows, start=True requires the discovered endpoint (or None).
+    start=False never launches a
+    process. With start=True, host is an absolute executable, or discovery uses
+    ZIPZI_EDITOR_HOST and the supported app locations. host requires start=True.
+    timeout is the positive finite per-request transport timeout in seconds;
+    startup_timeout is the positive finite total startup/handshake budget.
+    sdk_build=None accepts the compatible host build; an explicit string also
+    requires an exact build match. Protocol and required capabilities always
+    match strictly; installing native never changes the selected execution host.
+
+    This blocks for connection/startup, raising ValueError for invalid options,
+    PermissionError for unsafe endpoint ownership, OS connection errors when
+    no host is listening, or SdkFailure for pairing/startup refusal. Runtime
+    resources are bounded by host limits. Close the returned client or use with;
+    this releases its leases while formal Connected sessions remain resident.
+    A request that later becomes unknown must recover on this original Runtime;
+    calling connect again does not replay or resolve that request.
+
+    Example: with zipzi.connect(endpoint=absolute_socket_path) as runtime: ...
+    """
+    from ._endpoint import connect_backend
+    return Runtime(connect_backend(endpoint, start=start, host=host, timeout=timeout,
+        startup_timeout=startup_timeout, sdk_build=sdk_build))
+
+__all__ = ["local", "connect", "Runtime", "Session", "Edit", "Job", "SdkFailure", "Busy", "OutcomeUnknown",
+    "PendingRequest", "Version", "Source", "Receipt", "SaveReceipt", "SessionId", "SessionInfo", "ConnectionInfo", "ConnectionLimits", "WriteResult", "modeling", "bindings", "sampling", "events", "meshes", "ops", "parameters", "resources", "scene", "references", "Plan", "PreparedImage", "Buffer"]
+__all__ += ["animation", "spatial", "observation", "inspection"]
+
+__all__ += ["recover_call", "EditState", "JobState", "JobTimeout", "RecoveryAction"]
+
+from ._request_methods import register as _register_requests
+_register_requests()
+
+__all__ += ["Snapshot", "Batch", "Page", "PageCursor"]
+
+__all__ += ["PlanCost", "PlanReport"]
+
+from ._generated.discovery import RuntimeCapabilities, RuntimeLimits, ObjectSummary
+__all__ += ["RuntimeCapabilities", "RuntimeLimits", "ObjectSummary"]
+
+from ._documentation import ApiDescription, describe
+__all__ += ["ApiDescription", "describe"]
+
+from . import mesh_generation as mesh_generation
+__all__ += ["mesh_generation"]

zipzi-0.1.0a2/python/zipzi/_backend_types.py

@@ -0,0 +1,3 @@
+"""Finite internal task discriminators; no domain imports."""
+from typing import Literal
+JobKind = Literal["published", "saved", "opened", "sampled", "planned", "project", "image", "preview", "spatial", "observation"]

zipzi-0.1.0a2/python/zipzi/_calls.py

@@ -0,0 +1,119 @@
+"""One complete public return contract across request and transfer recovery."""
+from __future__ import annotations
+
+from collections.abc import Callable
+from types import MethodType
+from typing import Generic, Never, ParamSpec, TypeVar, cast
+from ._errors import OutcomeUnknown, PendingRequest, SdkFailure
+
+T = TypeVar("T", covariant=True)
+U = TypeVar("U")
+P = ParamSpec("P")
+
+
+def _resolved_call(*_: object) -> Never:
+    raise SdkFailure("NO_PENDING_REQUEST", "This public call has already been resolved")
+
+
+class Call(Generic[T]):
+    """Retain owned inputs, raw continuation and the complete return projection.
+
+    The backend owns the immutable wire bytes and transfer stage. A Call never
+    invokes its original execute closure during recovery. The same decoder is
+    applied once after either normal execution or raw continuation succeeds.
+    """
+    def __init__(self, operation: str, execute: Callable[[], object], decode: Callable[[object], T], *,
+                 resume: Callable[[], object] | None = None, inputs: tuple[object, ...] = (),
+                 on_unknown: Callable[[OutcomeUnknown], None] | None = None,
+                 on_error: Callable[[BaseException], None] | None = None):
+        self.operation, self.inputs = operation, inputs
+        self._execute, self._decode, self._resume = execute, decode, resume
+        self._explicit_resume = resume is not None
+        self._on_unknown, self._on_error = on_unknown, on_error
+        self.phase = "prepared"
+        self.pending_request: PendingRequest | None = None
+        self._bound_resume: Callable[[], object] | None = None
+
+    def run(self) -> T:
+        if self.phase != "prepared":
+            raise SdkFailure("NO_PENDING_REQUEST", "This public call has already started")
+        return self._invoke(self._execute)
+
+    def recover(self, expected: PendingRequest) -> T:
+        if self.phase != "unknown" or self.pending_request != expected or self._resume is None:
+            raise SdkFailure("NO_PENDING_REQUEST", "This public call has already been resolved")
+        return self._invoke(self._resume)
+
+    def _finish(self, phase: str) -> None:
+        self.phase, self.pending_request = phase, None
+        self._execute, self._resume, self._decode = _resolved_call, None, _resolved_call
+        self._bound_resume = self._on_unknown = self._on_error = None
+        self.inputs = ()
+
+    def _invoke(self, action: Callable[[], object]) -> T:
+        self.phase = "request"
+        try:
+            value = self._decode(action())
+        except OutcomeUnknown as error:
+            # An outer public projection captures the inner Call continuation
+            # before replacing the exception callback with its own full result.
+            if not self._explicit_resume and error._resume is not self._bound_resume and error._resume is not None:
+                self._resume = error._resume
+            self.phase, self.pending_request = "unknown", error.pending
+            expected = error.pending
+            self._bound_resume = lambda: self.recover(expected)
+            error._resume = self._bound_resume
+            if self._on_unknown is not None:
+                self._on_unknown(error)
+            raise
+        except BaseException as error:
+            callback = self._on_error
+            self._finish("failed")
+            if callback is not None:
+                callback(error)
+            raise
+        self._finish("resolved")
+        return value
+
+
+def known(execute: Callable[[], U], resume: Callable[[], U]) -> U:
+    """Adapter for existing complete decoders while facades move to generation."""
+    operation = execute.__qualname__.split(".<locals>", 1)[0]
+    return Call(operation, execute, lambda value: cast(U, value), resume=resume).run()
+
+
+def project(execute: Callable[[], U], projection: Callable[[U], T], *, operation: str,
+            inputs: tuple[object, ...] = ()) -> T:
+    return Call(operation, execute, lambda value: projection(cast(U, value)), inputs=inputs).run()
+
+
+def single_id(result: object) -> str:
+    from ._values import WriteResult
+    if not isinstance(result, WriteResult) or len(result.ids) != 1:
+        raise SdkFailure("INVALID_RESULT", "A create operation must return exactly one ID")
+    return result.ids[0]
+
+
+_REQUEST_METHODS: set[object] = set()
+
+
+def register_request(method: object) -> None:
+    """Only library-owned public method implementations enter this directory."""
+    _REQUEST_METHODS.add(getattr(method, "__func__", method))
+
+
+def recover_call(method: Callable[P, U], /, *args: P.args, **kwargs: P.kwargs) -> U:
+    """Call a registered SDK request method once and recover its Call once.
+
+    Parameters exactly match the bound SDK method, preserving its return type.
+    Arbitrary functions, lambdas and unregistered wrappers raise TypeError before
+    execution. Busy, ordinary failures, budgets and JobTimeout are propagated.
+    If recovery is still unknown, retain that exception and its owner to resume
+    later; this helper never replays a user function or loops on recovery.
+    """
+    if not isinstance(method, MethodType) or method.__func__ not in _REQUEST_METHODS:
+        raise TypeError("recover_call requires a registered bound SDK request method")
+    try:
+        return method(*args, **kwargs)
+    except OutcomeUnknown as error:
+        return cast(U, error.recover())

zipzi-0.1.0a2/python/zipzi/_documentation.py

@@ -0,0 +1,49 @@
+"""Offline public API descriptions; importing or describing never starts a host."""
+from dataclasses import dataclass
+from ._presentation import CompactValue
+
+@dataclass(frozen=True,repr=False)
+class ApiDescription(CompactValue):
+    'One installed offline API entry; it describes the client package rather than probing host support.\n\nFields:\npath: Canonical public API path under zipzi.\nkind: Directory entry category such as module, type, callable or value.\nsignature: Rendered public signature; empty for entries without a callable/type signature.\ndocumentation: Semantic docstring for this installed entry.\nfields: Ordered pairs of public field name and semantic description; empty when no value fields are declared.\nchildren: Canonical child entry paths for further bounded describe queries.\nexample: Package-relative workflow/example reference; empty when no example is assigned.'
+    __module__='zipzi'
+    path:str
+    kind:str
+    signature:str
+    documentation:str
+    fields:tuple[tuple[str,str],...]=()
+    children:tuple[str,...]=()
+    example:str=''
+
+    def format(self) -> str:
+        """Return complete help text without truncation or IO.
+
+        Use print(description.format()) for full help. repr, str and summary
+        remain bounded previews; formatting does not recursively query children.
+        """
+        lines=[self.path+' ('+self.kind+')']
+        if self.signature:lines.extend(('',self.signature))
+        if self.documentation:lines.extend(('',self.documentation))
+        if self.fields:
+            lines.extend(('', 'Fields:'))
+            lines.extend(name+': '+text for name,text in self.fields)
+        if self.children:
+            lines.extend(('', 'Children:', *self.children))
+        if self.example:lines.extend(('', 'Example: '+self.example))
+        return '\n'.join(lines)
+
+
+def describe(path:str)->ApiDescription:
+    """Look up an exact public path, e.g. Session.meshes.list, without IO or eval.
+
+    Unknown paths raise KeyError. Short paths are normalized under zipzi.
+    The root description links the bundled short guide and executable recipes.
+    Use print(describe(path).format()) for complete help; direct printing is a
+    bounded preview. Fields and child paths are also available individually.
+    This describes the installed API, while runtime.capabilities() describes
+    the connected host. No resource is constructed or RPC sent by this query.
+    """
+    from ._generated.catalog import CATALOG
+    if not isinstance(path,str):raise TypeError('Expected a public API path')
+    key=path if path=='zipzi' or path.startswith('zipzi.') else 'zipzi.'+path
+    raw=CATALOG[key]
+    return ApiDescription(key,raw['kind'],raw.get('signature',''),raw.get('documentation',''),tuple(raw.get('fields',())),tuple(raw.get('children',())),raw.get('example',''))

zipzi-0.1.0a2/python/zipzi/_dto_support.py

@@ -0,0 +1,61 @@
+"""Primitive ownership/shape conversions shared by generated DTO projections."""
+from collections.abc import Callable, Mapping, Sequence
+from typing import TypeVar, cast
+from uuid import UUID
+import math
+from ._values import SessionId
+
+T = TypeVar('T')
+
+def get(value: object, key: str) -> object:
+    if isinstance(value, Mapping): return cast(Mapping[str, object], value)[key]
+    return cast(object, getattr(value, key))
+
+def text(value: object) -> str:
+    if not isinstance(value, str): raise TypeError('Expected text')
+    return value
+
+def numeric(value: object, kind: str = 'f32') -> float:
+    if isinstance(value, bool) or not isinstance(value, (int, float)): raise TypeError('Expected a real number')
+    if not math.isfinite(value) or kind == 'f32' and abs(value) > 3.4028234663852886e38: raise ValueError('Expected finite '+kind)
+    return float(value)
+
+def whole(value: object, kind: str) -> int:
+    if type(value) is not int: raise ValueError('Expected '+kind)
+    bits = {'u8':8, 'u16':16, 'u32':32, 'u64':64, 'i32':32, 'i64':64, 'usize':64}[kind]
+    low, high = (-(1 << (bits-1)), 1 << (bits-1)) if kind.startswith('i') else (0, 1 << bits)
+    if not low <= value < high: raise ValueError('Expected '+kind)
+    return value
+
+def flag(value: object) -> bool:
+    if type(value) is not bool: raise TypeError('Expected bool')
+    return value
+
+def point(value: object) -> tuple[float, float]:
+    if isinstance(value, (tuple, list)):
+        values=cast(Sequence[object], value)
+        if len(values)!=2: raise ValueError('Expected point pair')
+        return numeric(values[0]), numeric(values[1])
+    return numeric(get(value,'x')), numeric(get(value,'y'))
+
+def items(value: object) -> Sequence[object]:
+    if not isinstance(value, (list, tuple)): raise TypeError('Expected immutable array input')
+    return cast(Sequence[object], value)
+
+def array(value: Sequence[T], length: int) -> tuple[T, ...]:
+    if len(value)!=length: raise ValueError('Invalid fixed array length')
+    return tuple(value)
+
+def mapping(value: object) -> Mapping[str, object]:
+    if not isinstance(value, Mapping): raise TypeError('Expected mapping')
+    result=cast(Mapping[object, object], value)
+    if any(not isinstance(key,str) for key in result): raise TypeError('Expected text keys')
+    return cast(Mapping[str, object], result)
+
+def cursor_guard(runtime: str, session: SessionId | None, sequence: int) -> None:
+    if str(UUID(runtime))!=runtime or type(sequence) is not int or not 0<=sequence<1<<64: raise ValueError('Invalid event cursor')
+    if session is not None and session.runtime!=runtime: raise ValueError('Cursor mixes Runtime identities')
+
+
+def external(value: object, cls: type[T], decode: Callable[[object], T]) -> T:
+    return value if isinstance(value, cls) else decode(value)

zipzi-0.1.0a2/python/zipzi/_endpoint.py

@@ -0,0 +1,148 @@
+"""Unix endpoint discovery and ownership transfer to the desktop host."""
+import errno
+import math
+import os
+from pathlib import Path
+import re
+import stat
+import subprocess
+import sys
+import threading
+import time
+from ._errors import SdkFailure
+from .backends.connected import ConnectedBackend
+
+
+def _private(metadata: os.stat_result, directory: bool) -> None:
+    if sys.platform == "win32":
+        raise RuntimeError("Unix permission check on Windows")
+    valid_kind = stat.S_ISDIR(metadata.st_mode) if directory else stat.S_ISREG(metadata.st_mode)
+    if not valid_kind or metadata.st_uid != os.getuid() or metadata.st_mode & 0o077:
+        raise PermissionError("Runtime directory/lock must be private, owned by this user and not a symlink")
+
+
+def _endpoint(path: Path | None, start: bool) -> Path:
+    if sys.platform == "win32":
+        raise SdkFailure("HOST_UNAVAILABLE", "Local host connections currently require Unix")
+    if path is None:
+        directory = Path(os.environ.get("ZIPZI_RUNTIME_DIR", f"/tmp/zipzi-runtime-{os.getuid()}"))
+        profile = os.environ.get("ZIPZI_RUNTIME_PROFILE", "default")
+        path = directory / f"{profile}.sock"
+    else:
+        directory = path.parent
+        profile = path.stem
+    if not path.is_absolute() or path.suffix != ".sock" or not re.fullmatch(r"[a-z0-9_-]{1,24}", profile):
+        raise ValueError("Endpoint must be an absolute <profile>.sock path with a valid profile")
+    if len(os.fsencode(path)) >= 104:
+        raise ValueError("Runtime socket path is too long")
+    if start:
+        try:
+            directory.mkdir(mode=0o700)
+        except FileExistsError:
+            pass
+    _private(directory.lstat(), True)
+    return path
+
+
+def _socket(path: Path) -> None:
+    if sys.platform == "win32":
+        raise RuntimeError("Unix socket check on Windows")
+    try:
+        metadata = path.lstat()
+    except FileNotFoundError:
+        return
+    if not stat.S_ISSOCK(metadata.st_mode) or metadata.st_uid != os.getuid() or metadata.st_mode & 0o077:
+        raise PermissionError("Runtime endpoint must be a private socket owned by this user")
+
+
+def _host(explicit: Path | None) -> Path:
+    configured = os.environ.get("ZIPZI_EDITOR_HOST")
+    if explicit is not None or configured:
+        candidates = [explicit if explicit is not None else Path(configured or "")]
+    elif sys.platform == "darwin":
+        candidates = [base / "Zipzi Editor.app/Contents/MacOS/zipzi-editor"
+            for base in (Path.home() / "Applications", Path("/Applications"))]
+    else:
+        candidates = []
+    for candidate in candidates:
+        if not candidate.is_absolute():
+            raise ValueError("Host executable must be absolute")
+        if candidate.is_file() and os.access(candidate, os.X_OK):
+            return candidate
+    raise SdkFailure("HOST_NOT_FOUND", "Set ZIPZI_EDITOR_HOST or pass an absolute host executable")
+
+
+def _claim(path: Path) -> int | None:
+    if sys.platform == "win32":
+        raise RuntimeError("Unix ownership claim on Windows")
+    import fcntl
+    descriptor = os.open(path.with_suffix(".lock"), os.O_RDWR | os.O_CREAT | os.O_NOFOLLOW | os.O_CLOEXEC, 0o600)
+    try:
+        _private(os.fstat(descriptor), False)
+        try:
+            fcntl.flock(descriptor, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except OSError as error:
+            if error.errno in (errno.EAGAIN, errno.EWOULDBLOCK):
+                os.close(descriptor)
+                return None
+            raise
+        return descriptor
+    except BaseException:
+        os.close(descriptor)
+        raise
+
+
+def connect_backend(endpoint: Path | None, *, start: bool, host: Path | None,
+    timeout: float, startup_timeout: float, sdk_build: str | None) -> ConnectedBackend:
+    for value in (timeout, startup_timeout):
+        if isinstance(value, bool) or not math.isfinite(value) or value <= 0:
+            raise ValueError("Connection and startup timeouts must be finite and positive")
+    if host is not None and not start:
+        raise ValueError("A host executable requires start=True")
+    if os.name == "nt":
+        from ._windows_endpoint import connect
+        return connect(endpoint, start=start, host=host, timeout=timeout,
+            startup_timeout=startup_timeout, sdk_build=sdk_build)
+    path = _endpoint(endpoint, start)
+    deadline = time.monotonic() + startup_timeout
+    child: subprocess.Popen[bytes] | None = None
+
+    def attempt() -> ConnectedBackend:
+        _socket(path)
+        remaining = max(.001, deadline - time.monotonic()) if start else timeout
+        return ConnectedBackend(path, timeout, sdk_build=sdk_build, handshake_timeout=min(timeout, remaining))
+
+    while True:
+        try:
+            return attempt()
+        except (FileNotFoundError, ConnectionRefusedError):
+            if not start:
+                raise
+        if child is not None and child.poll() is not None:
+            raise SdkFailure("HOST_START_FAILED", f"Host exited with status {child.returncode} before handshake")
+        if time.monotonic() >= deadline:
+            raise TimeoutError("Host startup timed out; endpoint ownership is retained by any running host")
+        if child is None:
+            descriptor = _claim(path)
+            if descriptor is not None:
+                try:
+                    # Recheck after winning arbitration, before choosing a host.
+                    try:
+                        return attempt()
+                    except (FileNotFoundError, ConnectionRefusedError):
+                        pass
+                    executable = _host(host)
+                    environment = dict(os.environ, ZIPZI_RUNTIME_DIR=str(path.parent), ZIPZI_RUNTIME_PROFILE=path.stem,
+                        ZIPZI_RUNTIME_OWNER_FD=str(descriptor))
+                    # Development session/readiness files belong to their launcher.
+                    for name in ("ZIPZI_DEV_SESSION_DIR", "ZIPZI_DEV_READY_FILE", "ZIPZI_DEV_PID_FILE"):
+                        environment.pop(name, None)
+                    child = subprocess.Popen([str(executable), "--no-window"], env=environment,
+                        pass_fds=(descriptor,), start_new_session=True, stdin=subprocess.DEVNULL,
+                        stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+                    # Reap without tying the host's lifetime to this client.
+                    threading.Thread(target=child.wait, name="zipzi-host-reaper", daemon=True).start()
+                finally:
+                    # Never LOCK_UN: the child inherits the same open description.
+                    os.close(descriptor)
+        time.sleep(min(.025, max(0., deadline - time.monotonic())))