zipzi 0.1.0a2__py3-none-any.whl

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/_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/_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/_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/_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/_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())))

zipzi/_errors.py

@@ -0,0 +1,131 @@
+"""Backend-independent exceptions. Importing these never imports PyO3."""
+from __future__ import annotations
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Literal
+from ._values import Version, record, sequence, string
+from ._generated.modeling import ProjectReport
+
+RecoveryAction = Literal["retry", "reduce_request", "release_resources", "recover_original",
+                         "restart_edit", "refresh_source", "resync", "wait_job", "stop"]
+
+def _recovery_action(code: str, edit_state: str | None, limit_name: str | None) -> RecoveryAction:
+    if edit_state in {"aborted", "failed"}:
+        return "restart_edit"
+    if code == "OUTCOME_UNKNOWN":
+        return "recover_original"
+    if code == "JOB_TIMEOUT":
+        return "wait_job"
+    if code == "BUSY":
+        return "retry"
+    if code in {"BUDGET_EXCEEDED", "RESOURCE_BUDGET_EXCEEDED"}:
+        return "release_resources" if limit_name in {"jobs_per_client", "jobs_total", "results_per_client", "plans_per_client", "prepared_images_per_client", "references_per_client", "blobs_per_client", "jobs and retained results", "plans", "prepared images", "object references"} else "reduce_request"
+    if code in {"STALE_SOURCE", "STALE_PLAN"}:
+        return "refresh_source"
+    if code == "RESYNC_REQUIRED":
+        return "resync"
+    return "stop"
+
+class SdkFailure(Exception):
+    """Confirmed SDK/host refusal with structured recovery and ownership facts.
+
+    code is the stable discriminator; message is human-readable. operation and
+    object_ids identify the attempted domain action. expected_version,
+    actual_version, field_path and referrers explain stale/invalid references.
+    edit_state distinguishes aborted candidates from confirmed admission refusal.
+    requested/allowed are counts or bytes named by limit_name; None means absent.
+    project_report retains a failed IO report when available. recovery_action
+    recommends a finite next action; it is not permission to replay unknown work.
+    OutcomeUnknown has a separate retained request owner and recover method.
+    This value alone performs no IO and owns no resource lease. Catch outside a
+    failed Edit, inspect code/recovery_action, and start a fresh candidate when
+    required. See docs/guide.md for the error/recovery workflow.
+    """
+    def __init__(self, code: str, message: str, *, operation: str = "", object_ids: tuple[str, ...] = (),
+        expected_version: Version | None = None, actual_version: Version | None = None,
+        field_path: str | None = None, referrers: tuple[str, ...] = (), edit_state: str | None = None, project_report: ProjectReport | None = None,
+        recovery_action: RecoveryAction | None = None, requested: int | None = None,
+        allowed: int | None = None, limit_name: str | None = None):
+        super().__init__(message)
+        self.code, self.operation, self.object_ids = code, operation, object_ids
+        self.expected_version, self.actual_version = expected_version, actual_version
+        self.field_path, self.referrers, self.edit_state = field_path, referrers, edit_state
+        self.project_report = project_report
+        self.requested, self.allowed, self.limit_name = requested, allowed, limit_name
+        self.recovery_action = recovery_action or _recovery_action(code, edit_state, limit_name)
+        self.cleanup: OutcomeUnknown | None = None
+
+class Busy(SdkFailure):
+    """Confirmed refusal before execution; the caller may submit a new request."""
+
+@dataclass(frozen=True)
+class PendingRequest:
+    'Immutable identity of the original request whose outcome is unknown; recover through its owning call.\n\nFields:\nrequest_id: Original client request number; do not allocate a fresh write request to probe the outcome.\ndigest: Digest binding the request identity to its original payload; not the payload itself.\noperation: Original protocol operation name used for diagnostics and recovery ownership.'
+    request_id: int
+    digest: str
+    operation: str
+
+class OutcomeUnknown(SdkFailure):
+    """The original public call has an unconfirmed outcome; retain this exception.
+
+    pending identifies its immutable request, while the owning SDK wrapper keeps
+    the complete result projection. recover returns that original runtime type;
+    use recover_call for exact static typing. Further uncertainty raises another
+    recoverable OutcomeUnknown. Never repeat a write under a new request ID.
+    Recovery is synchronous, bounded by host retention/timeouts; expiration is a
+    structured failure rather than proof the write did not happen.
+    """
+    def __init__(self, pending: PendingRequest, message: str):
+        super().__init__("OUTCOME_UNKNOWN", message, operation=pending.operation)
+        self.pending = pending
+        self._resume: Callable[[], object] | None = None
+
+    def recover(self) -> object:
+        """Recover this complete public call using its original request identity.
+
+        The result has the original method's runtime type. The exception cannot
+        express that method's static type; use zipzi.recover_call for typed code.
+        This never invokes the original method again. Repeated recovery after
+        resolution raises NO_PENDING_REQUEST.
+        """
+        if self._resume is None:
+            raise SdkFailure("NO_RECOVERY_OWNER", "No owning operation is available")
+        return self._resume()
+
+class JobTimeout(SdkFailure):
+    """The accepted Job remains pending; retain it and wait again or cancel.
+
+    This confirmed nonterminal status has no PendingRequest and is distinct
+    from a lost transport reply. A timeout does not cancel the task.
+    """
+    def __init__(self, message: str = "Accepted Job is still pending"):
+        super().__init__("JOB_TIMEOUT", message, operation="job.wait", recovery_action="wait_job")
+
+
+def unwrap(value: object) -> object:
+    r = record(value)
+    if "error" not in r:
+        return r["ok"]
+    e = record(r["error"])
+    code = string(e["code"])
+    def optional(key: str) -> Version | None:
+        return None if e.get(key) is None else Version._read(e[key])
+    report=None
+    if e.get("project_report") is not None:
+        from ._generated.modeling import read_ProjectReport
+        report=read_ProjectReport(e["project_report"])
+    raise (Busy if code == "BUSY" else SdkFailure)(code, string(e["message"]),
+        operation=string(e.get("operation", "")), object_ids=tuple(string(v) for v in sequence(e.get("object_ids", ()))),
+        expected_version=optional("expected_version"), actual_version=optional("actual_version"),
+        field_path=None if e.get("field_path") is None else string(e["field_path"]),
+        referrers=tuple(string(v) for v in sequence(e.get("referrers", ()))),
+        edit_state=None if e.get("edit_state") is None else string(e["edit_state"]), project_report=report,
+        requested=None if e.get("requested") is None else _limit_integer(e["requested"]),
+        allowed=None if e.get("allowed") is None else _limit_integer(e["allowed"]),
+        limit_name=None if e.get("limit_name") is None else string(e["limit_name"]))
+
+
+def _limit_integer(value: object) -> int:
+    if type(value) is not int or value < 0:
+        raise TypeError("Host budget details must be nonnegative integers")
+    return value

zipzi/_extensions.py

@@ -0,0 +1,38 @@
+"""Immutable JSON extensions in canonical document fields only."""
+from collections.abc import Mapping
+from types import MappingProxyType
+from typing import TypeAlias, cast
+import math
+ExtensionValue: TypeAlias = None | bool | int | float | str | tuple['ExtensionValue', ...] | Mapping[str, 'ExtensionValue']
+def freeze(value: ExtensionValue) -> ExtensionValue:
+    if isinstance(value, Mapping):
+        return MappingProxyType({k: freeze(v) for k, v in value.items()})
+    if isinstance(value, (tuple, list)):
+        return tuple(freeze(v) for v in cast(tuple[ExtensionValue, ...], value))
+    return value
+def validate(value: ExtensionValue) -> None:
+    if value is None or isinstance(value, (bool, str)): return
+    if isinstance(value, int):
+        if not -(1 << 63) <= value < (1 << 64): raise ValueError('Extension integer exceeds JSON range')
+        return
+    if isinstance(value, float):
+        if not math.isfinite(value): raise ValueError('Extension number must be finite')
+        return
+    if isinstance(value, Mapping):
+        for k,v in value.items():
+            if not isinstance(k,str): raise TypeError('Extension key must be text')
+            validate(v)
+        return
+    if isinstance(value, tuple):
+        for v in value: validate(v)
+        return
+    raise TypeError('Invalid extension value')
+def encode(value: ExtensionValue) -> object:
+    if isinstance(value, Mapping): return {k: encode(v) for k,v in value.items()}
+    if isinstance(value, tuple): return [encode(v) for v in value]
+    return value
+def read(value: object) -> ExtensionValue:
+    if value is None or isinstance(value, (bool,int,float,str)): return value
+    if isinstance(value, dict): return MappingProxyType({str(k): read(v) for k,v in cast(dict[str,object],value).items()})
+    if isinstance(value, (list,tuple)): return tuple(read(v) for v in cast(tuple[object,...],value))
+    raise TypeError('Invalid JSON extension response')