envloop-envhub 1.23.0__tar.gz

envloop_envhub-1.23.0/NOTICE

@@ -0,0 +1,7 @@
+EnvLoop EnvHub implementation
+Source repository: https://github.com/EnvLoop/EnvHub
+
+This distribution preserves the implementation's source and attribution.
+No implementation LICENSE exists in the source baseline; this packaging change
+adds no license grant. Dataset and other content licenses are not repurposed.
+Dataset, Recipe, Runner and environment assets are excluded from this package.

envloop_envhub-1.23.0/PKG-INFO

@@ -0,0 +1,34 @@
+Metadata-Version: 2.5
+Name: envloop-envhub
+Version: 1.23.0
+Summary: Dependency-free ANS protocol and verified downloads
+License-File: NOTICE
+Requires-Python: >=3.12
+Provides-Extra: default
+Description-Content-Type: text/markdown
+
+# EnvLoop ANS core
+
+`envloop-envhub==1.23.0` provides dependency-free ANS references, URI parsing,
+content manifest validation and verified atomic downloads for Python 3.12+.
+
+```python
+from envhub.ans.proto import DatasetRef, parse_uri
+from envhub.ans.client import download_directory
+```
+
+Bare and `[default]` installs have identical files and no runtime dependencies.
+HTTPS uses Python's system CA trust and verifies certificates and hostnames;
+the Python installation must have a working trusted CA store. Download plans
+come from the caller's authorized API; this library does not issue credentials.
+
+Only the ANS client/protocol implementation is distributed. Registry services,
+databases, storage drivers, publishing tools, datasets and Runner/Recipe assets
+are excluded. Internal EnvHub applications require a separately provided private
+companion; installing this core does not provide those applications.
+
+The import name is `envhub`; the distribution name is `envloop-envhub`.
+Source: https://github.com/EnvLoop/EnvHub
+
+The source baseline declares no implementation license. This packaging change
+adds no license grant; excluded content licenses do not apply. See NOTICE.

envloop_envhub-1.23.0/README.pypi.md

@@ -0,0 +1,25 @@
+# EnvLoop ANS core
+
+`envloop-envhub==1.23.0` provides dependency-free ANS references, URI parsing,
+content manifest validation and verified atomic downloads for Python 3.12+.
+
+```python
+from envhub.ans.proto import DatasetRef, parse_uri
+from envhub.ans.client import download_directory
+```
+
+Bare and `[default]` installs have identical files and no runtime dependencies.
+HTTPS uses Python's system CA trust and verifies certificates and hostnames;
+the Python installation must have a working trusted CA store. Download plans
+come from the caller's authorized API; this library does not issue credentials.
+
+Only the ANS client/protocol implementation is distributed. Registry services,
+databases, storage drivers, publishing tools, datasets and Runner/Recipe assets
+are excluded. Internal EnvHub applications require a separately provided private
+companion; installing this core does not provide those applications.
+
+The import name is `envhub`; the distribution name is `envloop-envhub`.
+Source: https://github.com/EnvLoop/EnvHub
+
+The source baseline declares no implementation license. This packaging change
+adds no license grant; excluded content licenses do not apply. See NOTICE.

envloop_envhub-1.23.0/envhub/__init__.py

@@ -0,0 +1,3 @@
+"""Public, dependency-free ANS core."""
+from .ans import *  # noqa: F403
+from .ans import __all__ as __all__

envloop_envhub-1.23.0/envhub/ans/__init__.py

@@ -0,0 +1,5 @@
+"""Public ANS protocol and download facade."""
+from .client import download_directory, materialize_manifest, validate_download_plan
+from .proto import *  # noqa: F403
+
+__all__ = ['ArtifactIdRef', 'ArtifactRef', 'AssetReference', 'CheckpointRef', 'DatasetRef', 'JobCheckpointRef', 'ModelRef', 'RecipeRef', 'RevisionRunnerRef', 'RewardSetRef', 'RunnerRef', 'RunnerRevision', 'TemplateRef', 'parse_uri', 'ANSError', 'Conflict', 'InvalidCommand', 'InvalidRecord', 'InvalidURI', 'NotFound', 'RepositoryError', 'InvalidManifest', "download_directory", "validate_download_plan", "materialize_manifest"]

envloop_envhub-1.23.0/envhub/ans/client/__init__.py

@@ -0,0 +1,5 @@
+"""Authorized download and atomic materialization."""
+from .download import download_directory, validate_download_plan
+from .materialize import materialize_manifest
+
+__all__ = ["download_directory", "validate_download_plan", "materialize_manifest"]

envloop_envhub-1.23.0/envhub/ans/client/download.py

@@ -0,0 +1,83 @@
+"""Materialize one ANS directory from temporary provider URLs."""
+
+import re
+from collections.abc import Callable, Iterable, Iterator
+from pathlib import Path
+from typing import Any, override
+from urllib.parse import urlsplit
+
+from envhub.ans.client.materialize import materialize_manifest
+from envhub.ans.proto import manifests as artifacts
+from envhub.ans.proto.errors import InvalidRecord
+from envhub.ans.proto.uri import parse_uri
+
+
+def validate_download_plan(plan: Any, *, uri: str, split: str | None = None,
+                           content_digest: str | None = None) -> tuple[dict[str, Any], dict[str, str], dict[str, int]]:
+    """Validate identity, pins and URLs before issuing any provider request."""
+    try:
+        reference = parse_uri(uri)
+        if (not isinstance(plan, dict) or set(plan) != {'uri', 'content_digest', 'split', 'expires_in', 'files'}
+                or reference.uri != uri or plan['uri'] != uri or plan['split'] != split
+                or not re.fullmatch('[a-f0-9]{64}', plan['content_digest'])
+                or content_digest is not None and plan['content_digest'] != content_digest
+                or type(plan['expires_in']) is not int or not 1 <= plan['expires_in'] <= 300):
+            raise InvalidRecord('download plan does not match the requested ANS identity')
+        entries: list[dict[str, Any]] = []
+        urls: dict[str, str] = {}
+        modes: dict[str, int] = {}
+        for entry in plan['files']:
+            if (set(entry) != {'path', 'size', 'sha256', 'mode', 'url'}
+                    or type(entry['mode']) is not int or entry['mode'] not in (0o100644, 0o100755)):
+                raise InvalidRecord('invalid download file metadata')
+            url = urlsplit(entry['url'])
+            if (url.scheme != 'https' or not url.hostname or url.username is not None
+                    or url.password is not None or url.fragment):
+                raise InvalidRecord('download requires a credential-free HTTPS origin')
+            entries.append({key: entry[key] for key in ('path', 'size', 'sha256')})
+            urls[entry['path']], modes[entry['path']] = entry['url'], entry['mode']
+        manifest = artifacts.validate_manifest({'schema': artifacts.SCHEMA, 'kind': 'directory', 'files': entries})
+    except (KeyError, TypeError, ValueError) as error:
+        raise InvalidRecord('invalid ANS download plan') from error
+
+    return manifest, urls, modes
+
+
+def download_directory(plan: Any, destination: Path, *, uri: str, split: str | None = None,
+                       content_digest: str | None = None,
+                       read_url: Callable[[str], Iterable[bytes]] | None = None) -> Path:
+    """Verify a complete directory and publish it atomically, without API credentials.
+
+    The default reader uses one dedicated client, with no ambient authentication,
+    cookies or redirect support. Temporary URLs never enter the saved directory.
+    """
+    manifest, urls, modes = validate_download_plan(plan, uri=uri, split=split, content_digest=content_digest)
+    if read_url is not None:
+        def read_custom(path: str) -> Iterable[bytes]:
+            return read_url(urls[path])
+        return materialize_manifest(manifest, destination, read_custom, modes=modes)
+    import ssl
+    from urllib.error import URLError
+    from urllib.request import (
+        HTTPRedirectHandler,
+        HTTPSHandler,
+        ProxyHandler,
+        build_opener,
+    )
+
+    class NoRedirect(HTTPRedirectHandler):
+        @override
+        def redirect_request(self, *args: Any, **kwargs: Any) -> None:
+            return None
+
+    client = build_opener(ProxyHandler({}), NoRedirect(), HTTPSHandler(context=ssl.create_default_context()))
+    def read(path: str) -> Iterator[bytes]:
+        try:
+            with client.open(urls[path], timeout=60) as response:
+                if response.status != 200:
+                    raise InvalidRecord('repository download failed')
+                while chunk := response.read(1024 * 1024):
+                    yield chunk
+        except URLError:
+            raise InvalidRecord('repository download failed') from None
+    return materialize_manifest(manifest, destination, read, modes=modes)

envloop_envhub-1.23.0/envhub/ans/client/materialize.py

@@ -0,0 +1,64 @@
+"""Verify bytes and atomically materialize ANS manifests."""
+import hashlib
+import os
+import shutil
+import tempfile
+from collections.abc import Callable, Iterable
+from pathlib import Path
+from typing import Any
+
+from envhub.ans.proto.errors import InvalidManifest
+from envhub.ans.proto.manifests import validate_manifest
+
+
+def materialize_manifest(
+    manifest: dict[str, Any],
+    destination: Path,
+    read: Callable[[str], bytes | Iterable[bytes]],
+    *,
+    modes: dict[str, int] | None = None,
+) -> Path:
+    """Verify streamed bytes privately, then rename the complete tree into place.
+
+    ``read(relative_path)`` returns bytes or an iterable of byte chunks. Existing
+    destinations and symlink ancestors are rejected; callers own the parent tree.
+    No destination becomes visible on download, size or digest failure.
+    """
+    value = validate_manifest(manifest)
+    if modes is not None and (not isinstance(modes, dict)
+            or set(modes) != {item['path'] for item in value['files']}
+            or any(type(mode) is not int or mode not in (0o100644, 0o100755) for mode in modes.values())):
+        raise InvalidManifest('Invalid artifact executable modes')
+    target = Path(destination)
+    if any(parent.is_symlink() for parent in (target, *target.parents)):
+        raise InvalidManifest('Artifact destination cannot contain symlinks')
+    if target.exists():
+        raise FileExistsError('Artifact destination already exists')
+    staging = Path(tempfile.mkdtemp(prefix='.artifact-', dir=target.parent))
+    try:
+        for item in value['files']:
+            path = staging / item['path']
+            path.parent.mkdir(parents=True, exist_ok=True)
+            content = read(item['path'])
+            chunks = (content,) if isinstance(content, bytes) else content
+            digest, size = hashlib.sha256(), 0
+            with path.open('xb') as output:
+                for chunk in chunks:
+                    if not isinstance(chunk, bytes):
+                        raise InvalidManifest('Artifact reader must return byte chunks')
+                    size += len(chunk)
+                    if size > item['size']:
+                        raise InvalidManifest('Artifact file size mismatch')
+                    digest.update(chunk)
+                    output.write(chunk)
+            if size != item['size'] or digest.hexdigest() != item['sha256']:
+                raise InvalidManifest('Artifact file size or SHA-256 mismatch')
+            if modes is not None:
+                path.chmod(modes[item['path']] & 0o777)
+        if target.exists() or target.is_symlink():
+            raise FileExistsError('Artifact destination already exists')
+        os.rename(staging, target)
+        return target
+    finally:
+        if staging.exists():
+            shutil.rmtree(staging)

envloop_envhub-1.23.0/envhub/ans/proto/__init__.py

@@ -0,0 +1,29 @@
+"""Dependency-free ANS protocol definitions."""
+from .errors import (
+    ANSError,
+    Conflict,
+    InvalidCommand,
+    InvalidManifest,
+    InvalidRecord,
+    InvalidURI,
+    NotFound,
+    RepositoryError,
+)
+from .uri import (
+    ArtifactIdRef,
+    ArtifactRef,
+    AssetReference,
+    CheckpointRef,
+    DatasetRef,
+    JobCheckpointRef,
+    ModelRef,
+    RecipeRef,
+    RevisionRunnerRef,
+    RewardSetRef,
+    RunnerRef,
+    RunnerRevision,
+    TemplateRef,
+    parse_uri,
+)
+
+__all__ = ['ArtifactIdRef', 'ArtifactRef', 'AssetReference', 'CheckpointRef', 'DatasetRef', 'JobCheckpointRef', 'ModelRef', 'RecipeRef', 'RevisionRunnerRef', 'RewardSetRef', 'RunnerRef', 'RunnerRevision', 'TemplateRef', 'parse_uri', 'ANSError', 'Conflict', 'InvalidCommand', 'InvalidRecord', 'InvalidURI', 'NotFound', 'RepositoryError', 'InvalidManifest']

envloop_envhub-1.23.0/envhub/ans/proto/ans.proto

@@ -0,0 +1,99 @@
+syntax = "proto3";
+package envloop.ans.v1;
+
+// Logical identity, never a storage credential or signed download URL.
+message CheckpointRef {
+  string session_id = 1;
+  string checkpoint_id = 2;
+}
+message DatasetRef {
+  string namespace = 1;
+  string name = 2;
+  string version = 3;
+}
+message RunnerRef {
+  string namespace = 1;
+  string name = 2;
+  string version = 3 [deprecated = true]; // Legacy read compatibility only.
+  string revision = 4; // Full 40/64-character Git commit object ID.
+}
+message JobCheckpointRef {
+  string job_id = 1;
+  string checkpoint_id = 2;
+}
+message TemplateRef {
+  string namespace = 1;
+  string name = 2;
+  string revision = 3; // Full 64-character lowercase canonical manifest SHA-256.
+}
+message ModelRef {
+  string namespace = 1;
+  string name = 2;
+  string revision = 3;
+  string checkpoint = 4; // Empty means the model revision itself.
+}
+message ArtifactRef {
+  string namespace = 1;
+  string name = 2;
+  string revision = 3; // Canonical manifest SHA-256.
+}
+message RecipeRef {
+  string namespace = 1;
+  string name = 2;
+  string revision = 3; // Canonical Recipe manifest SHA-256.
+}
+message RewardSetRef {
+  string namespace = 1;
+  string name = 2;
+  string version = 3; // Author version; consumers also pin the manifest SHA-256.
+}
+message AssetReference {
+  oneof resource {
+    CheckpointRef checkpoint = 1;
+    DatasetRef datasets = 2;
+    JobCheckpointRef job_checkpoint = 3;
+    RunnerRef runners = 4;
+    TemplateRef templates = 5;
+    ArtifactRef artifacts = 6;
+    ModelRef model = 7;
+    RecipeRef recipes = 8;
+    RewardSetRef reward_sets = 9;
+  }
+}
+message StorageLocation {
+  string provider_id = 1;
+  string object_key = 2;
+}
+message AssetRecord {
+  AssetReference reference = 1;
+  string manifest_sha256 = 2;
+  StorageLocation location = 3;
+}
+message NormalizeRequest { string uri = 1; }
+message NormalizeResponse {
+  string uri = 1;
+  AssetReference reference = 2;
+}
+message RegisterRequest { AssetRecord record = 1; }
+message ResolveRequest { string uri = 1; }
+message AssetResponse {
+  string uri = 1;
+  AssetRecord record = 2;
+}
+message ListRequest {
+  optional string kind = 1; // checkpoint, datasets, runners, templates, artifacts, recipes, reward-sets or model; omitted means all.
+  optional uint32 limit = 2; // 1..100; omitted defaults to 100.
+  optional string after = 3; // Previous next_cursor, a canonical URI.
+}
+message ListResponse {
+  repeated AssetRecord items = 1;
+  optional string next_cursor = 2;
+}
+// Authenticated Scope is injected by the transport, never accepted in requests.
+// These declarations do not imply a deployed gRPC endpoint.
+service AssetNamespaceService {
+  rpc Normalize(NormalizeRequest) returns (NormalizeResponse);
+  rpc Register(RegisterRequest) returns (AssetResponse);
+  rpc Resolve(ResolveRequest) returns (AssetResponse);
+  rpc List(ListRequest) returns (ListResponse);
+}

envloop_envhub-1.23.0/envhub/ans/proto/errors.py

@@ -0,0 +1,33 @@
+"""Stable ANS protocol errors without provider or record contents."""
+
+
+class ANSError(Exception):
+    code = 'ANS_ERROR'
+
+
+class InvalidURI(ANSError, ValueError):
+    code = 'INVALID_URI'
+
+
+class InvalidRecord(ANSError, ValueError):
+    code = 'INVALID_RECORD'
+
+
+class InvalidCommand(ANSError, ValueError):
+    code = 'INVALID_COMMAND'
+
+
+class NotFound(ANSError):
+    code = 'NOT_FOUND'
+
+
+class Conflict(ANSError):
+    code = 'CONFLICT'
+
+
+class RepositoryError(Exception):
+    """Base error for local repository operations."""
+
+
+class InvalidManifest(RepositoryError):
+    """The author manifest does not conform to the supported schema."""

envloop_envhub-1.23.0/envhub/ans/proto/manifests.py

@@ -0,0 +1,123 @@
+"""Immutable artifact manifests and verified, atomic local materialization.
+
+The caller supplies authorized bytes. Names and content pins never grant access,
+and this module neither discovers storage nor changes retention or durability.
+"""
+
+import hashlib
+import json
+import re
+from typing import Any
+
+from envhub.ans.proto.errors import InvalidManifest, InvalidURI
+from envhub.ans.proto.schemas import canonical_schema
+from envhub.ans.proto.uri import ArtifactRef, parse_uri
+
+SCHEMA = 'envloop.artifact/v1'
+_HASH = re.compile(r'[0-9a-f]{64}')
+_SEGMENT = re.compile(r'[A-Za-z0-9_][A-Za-z0-9._-]*')
+_STATE_FIELDS = {
+    'acl', 'ttl', 'ttl_seconds', 'expires_at', 'delete_requested', 'deleted',
+    'location', 'storage_location', 'credentials', 'signed_url', 'api_key',
+    'access_token', 'secret', 'ready', 'durable',
+}
+_MAX_INTEGER = 2**53 - 1  # Exact JSON integers in Python and JavaScript.
+
+
+def _hash(value: Any) -> None:
+    if not isinstance(value, str) or not _HASH.fullmatch(value):
+        raise InvalidManifest('Invalid artifact SHA-256')
+
+
+def _json(value: Any) -> None:
+    """Strict JSON subset with exact, portable numbers and no implicit coercions."""
+    if value is None or type(value) in (str, bool):
+        if isinstance(value, str):
+            try:
+                value.encode('utf-8')
+            except UnicodeError as exc:
+                raise InvalidManifest('Invalid artifact UTF-8') from exc
+        return
+    if type(value) is int and abs(value) <= _MAX_INTEGER:
+        return
+    if isinstance(value, list):
+        for item in value:
+            _json(item)
+        return
+    if isinstance(value, dict) and all(isinstance(key, str) for key in value):
+        for key, item in value.items():
+            if key.lower() in _STATE_FIELDS:
+                raise InvalidManifest('Artifact manifests cannot carry access, storage or runtime state')
+            _json(key)
+            _json(item)
+        return
+    raise InvalidManifest('Artifact metadata must use portable JSON values and integer numbers')
+
+
+def validate_manifest(value: dict[str, Any]) -> dict[str, Any]:
+    """Return a detached, path-sorted manifest; reject unknown protocol fields."""
+    required = {'schema', 'kind', 'files'}
+    if (not isinstance(value, dict) or not required <= value.keys()
+            or value.keys() - (required | {'metadata', 'producer', 'derived_from'})
+            or canonical_schema(value['schema']) != SCHEMA or value['kind'] not in ('checkpoint', 'file', 'directory')):
+        raise InvalidManifest('Invalid artifact manifest fields, schema or kind')
+    files = value['files']
+    if not isinstance(files, list) or not files or (value['kind'] == 'file' and len(files) != 1):
+        raise InvalidManifest('Invalid artifact files')
+    paths = set()
+    for item in files:
+        if not isinstance(item, dict) or set(item) != {'path', 'size', 'sha256'}:
+            raise InvalidManifest('Invalid artifact file fields')
+        path = item['path']
+        if (not isinstance(path, str) or len(path) > 1024
+                or any(not _SEGMENT.fullmatch(part) for part in path.split('/')) or path in paths):
+            raise InvalidManifest('Unsafe or duplicate artifact path')
+        paths.add(path)
+        if type(item['size']) is not int or not 0 <= item['size'] <= _MAX_INTEGER:
+            raise InvalidManifest('Invalid artifact file size')
+        _hash(item['sha256'])
+    if any('/'.join(path.split('/')[:index]) in paths
+           for path in paths for index in range(1, len(path.split('/')))):
+        raise InvalidManifest('Conflicting artifact file paths')
+    if 'metadata' in value and not isinstance(value['metadata'], dict):
+        raise InvalidManifest('Artifact metadata must be an object')
+    if 'producer' in value:
+        producer = value['producer']
+        if (not isinstance(producer, dict) or 'job_id' not in producer
+                or producer.keys() - {'job_id', 'trial_id'}
+                or any(not isinstance(item, str) or not _SEGMENT.fullmatch(item)
+                       for item in producer.values())):
+            raise InvalidManifest('Invalid artifact producer')
+    if 'derived_from' in value:
+        parents = value['derived_from']
+        if not isinstance(parents, list):
+            raise InvalidManifest('Invalid artifact derived_from')
+        seen = set()
+        for parent in parents:
+            if not isinstance(parent, dict) or set(parent) != {'uri', 'manifest_sha256'}:
+                raise InvalidManifest('Invalid parent artifact fields')
+            _hash(parent['manifest_sha256'])
+            try:
+                reference = parse_uri(parent['uri'])
+            except InvalidURI as exc:
+                raise InvalidManifest('Invalid parent artifact URI') from exc
+            if (reference.kind not in ('checkpoint', 'model', 'artifacts') or reference.uri != parent['uri']
+                    or parent['uri'] in seen or (isinstance(reference, ArtifactRef)
+                    and reference.revision != parent['manifest_sha256'])):
+                raise InvalidManifest('Invalid or mismatched parent artifact')
+            seen.add(parent['uri'])
+    try:
+        _json(value)
+        normalized = json.loads(json.dumps(value, ensure_ascii=False, allow_nan=False))
+    except (RecursionError, ValueError) as exc:
+        raise InvalidManifest('Invalid artifact JSON') from exc
+    entries: list[dict[str, Any]] = normalized['files']
+    entries.sort(key=lambda item: item['path'])
+    return normalized
+
+
+def manifest_digest(value: dict[str, Any]) -> str:
+    """SHA-256 of validated, path-sorted canonical UTF-8 JSON (no whitespace)."""
+    content = json.dumps(validate_manifest(value), ensure_ascii=False, sort_keys=True,
+                         separators=(',', ':'), allow_nan=False).encode('utf-8')
+    return hashlib.sha256(content).hexdigest()

envloop_envhub-1.23.0/envhub/ans/proto/schemas.py

@@ -0,0 +1,14 @@
+"""Schema namespace compatibility for readers; new documents use ``envloop.*``.
+
+Only compare this view with an explicit supported schema/version. Never use it
+as a recursive document rewrite: stored bytes and their digest remain immutable.
+The ``envhub`` Python import/package name is independent of the protocol org.
+"""
+from typing import Any
+
+
+def canonical_schema(value: Any) -> Any:
+    """Map the historical prefix for dispatch without modifying the document."""
+    if isinstance(value, str) and value.startswith('envhub.'):
+        return 'envloop.' + value.removeprefix('envhub.')
+    return value

envloop_envhub-1.23.0/envhub/ans/proto/uri.py

@@ -0,0 +1,395 @@
+"""Backend-independent checkpoint, dataset, runner, template and reward set references."""
+import re
+from dataclasses import dataclass
+from typing import Any
+from unicodedata import category
+from urllib.parse import quote, unquote
+
+from envhub.ans.proto.errors import InvalidURI
+
+_CHECKPOINT = re.compile(r'(?:envloop|tinker)://(tts-[0-9a-f]{12})/([A-Za-z0-9_-][A-Za-z0-9_.-]*)')
+_SEGMENT = re.compile(r'[A-Za-z0-9][A-Za-z0-9._-]*')
+_DATASET = re.compile(r'envloop://datasets/([^/]+)/([^/@]+)@([^/]+)')
+_RUNNER = re.compile(r'envloop://runners/([^/]+)/([^/@]+)@([^/]+)')
+_RECIPE = re.compile(r'envloop://recipes/([^/]+)/([^/@]+)@([^/]+)')
+_REWARD_SET = re.compile(r'envloop://reward-sets/([^/]+)/([^/@]+)@([^/]+)')
+_ARTIFACT = re.compile(r'envloop://artifacts/([^/]+)/([^/@]+)@([^/]+)')
+_TEMPLATE = re.compile(r'envloop://templates/([^/]+)/([^/@]+)@([^/]+)')
+_JOB_CHECKPOINT = re.compile(r'(?:envloop|tinker)://(job_[0-7][0-9A-HJKMNP-TV-Z]{25})/([A-Za-z0-9_-][A-Za-z0-9_.-]*)')
+
+
+@dataclass(frozen=True)
+class CheckpointRef:
+    session_id: str
+    checkpoint_id: str
+
+    def __post_init__(self):
+        if not isinstance(self.session_id, str) or not isinstance(self.checkpoint_id, str):
+            raise InvalidURI('invalid checkpoint reference')
+        if not _CHECKPOINT.fullmatch(f'envloop://{self.session_id}/{self.checkpoint_id}'):
+            raise InvalidURI('invalid checkpoint reference')
+
+    @property
+    def kind(self):
+        return 'checkpoint'
+
+    @property
+    def uri(self):
+        return f'envloop://{self.session_id}/{self.checkpoint_id}'
+
+    def to_dict(self):
+        return {'checkpoint': {'session_id': self.session_id, 'checkpoint_id': self.checkpoint_id}}
+
+
+@dataclass(frozen=True)
+class ModelRef:
+    """Logical model revision and optional single checkpoint segment."""
+
+    namespace: str
+    name: str
+    revision: str
+    checkpoint: str = ''
+
+    def __post_init__(self):
+        if any(not isinstance(value, str) or not _SEGMENT.fullmatch(value) or '..' in value
+               for value in (self.namespace, self.name, self.revision)):
+            raise InvalidURI('invalid model identity')
+        if (not isinstance(self.checkpoint, str) or (self.checkpoint and
+                (not _SEGMENT.fullmatch(self.checkpoint) or '..' in self.checkpoint))):
+            raise InvalidURI('invalid model checkpoint')
+
+    @property
+    def kind(self):
+        return 'model'
+
+    @property
+    def uri(self):
+        suffix = '/' + self.checkpoint if self.checkpoint else ''
+        return f'envloop://model/{self.namespace}/{self.name}@{self.revision}{suffix}'
+
+    def to_dict(self):
+        return {'model': {'namespace': self.namespace, 'name': self.name,
+                          'revision': self.revision, 'checkpoint': self.checkpoint}}
+
+
+@dataclass(frozen=True)
+class DatasetRef:
+    namespace: str
+    name: str
+    version: str
+
+    def __post_init__(self):
+        if any(not isinstance(value, str) or not _SEGMENT.fullmatch(value) or '..' in value
+               for value in (self.namespace, self.name)):
+            raise InvalidURI('invalid dataset name')
+        if (not isinstance(self.version, str) or not self.version.strip() or self.version in {'.', '..'}
+                or any(category(char) == 'Cc' or char in '/\\' for char in self.version)):
+            raise InvalidURI('invalid dataset version')
+        try:
+            self.version.encode('utf-8')
+        except UnicodeError as exc:
+            raise InvalidURI('invalid dataset version') from exc
+
+    @property
+    def kind(self):
+        return 'datasets'
+
+    @property
+    def uri(self):
+        return f'envloop://datasets/{self.namespace}/{self.name}@{quote(self.version, safe="._-")}'
+
+    def to_dict(self):
+        return {'datasets': {'namespace': self.namespace, 'name': self.name, 'version': self.version}}
+
+
+@dataclass(frozen=True)
+class RunnerRef:
+    namespace: str
+    name: str
+    version: str
+
+    def __post_init__(self):
+        if any(not isinstance(value, str) or not _SEGMENT.fullmatch(value) or '..' in value
+               for value in (self.namespace, self.name, self.version)):
+            raise InvalidURI('invalid runner identity')
+
+    @property
+    def kind(self):
+        return 'runners'
+
+    @property
+    def uri(self):
+        return f'envloop://runners/{self.namespace}/{self.name}@{self.version}'
+
+    def to_dict(self):
+        return {'runners': {'namespace': self.namespace, 'name': self.name, 'version': self.version}}
+
+
+@dataclass(frozen=True)
+class RunnerRevision:
+    """ANS logical identity; legacy version identities are a separate protocol."""
+
+    namespace: str
+    name: str
+    revision: str
+
+    def __post_init__(self):
+        if any(not isinstance(value, str) or not _SEGMENT.fullmatch(value) or '..' in value
+               for value in (self.namespace, self.name)):
+            raise InvalidURI('invalid runner name')
+        if not isinstance(self.revision, str) or not re.fullmatch(r'[0-9a-f]{40}|[0-9a-f]{64}', self.revision):
+            raise InvalidURI('runner revision requires a complete Git commit object ID')
+
+    @property
+    def kind(self):
+        return 'runners'
+
+    @property
+    def uri(self):
+        return f'envloop://runners/{self.namespace}/{self.name}@{self.revision}'
+
+    def to_dict(self):
+        return {'runners': {'namespace': self.namespace, 'name': self.name, 'revision': self.revision}}
+
+
+@dataclass(frozen=True)
+class TemplateRef:
+    """Immutable template identity pinned to its canonical manifest SHA-256."""
+
+    namespace: str
+    name: str
+    revision: str
+
+    def __post_init__(self):
+        if any(not isinstance(value, str) or not _SEGMENT.fullmatch(value) or '..' in value
+               for value in (self.namespace, self.name)):
+            raise InvalidURI('invalid template name')
+        if not isinstance(self.revision, str) or not re.fullmatch(r'[0-9a-f]{64}', self.revision):
+            raise InvalidURI('template revision requires a complete manifest SHA-256')
+
+    @property
+    def kind(self):
+        return 'templates'
+
+    @property
+    def uri(self):
+        return f'envloop://templates/{self.namespace}/{self.name}@{self.revision}'
+
+    def to_dict(self):
+        return {'templates': {'namespace': self.namespace, 'name': self.name, 'revision': self.revision}}
+
+
+@dataclass(frozen=True)
+class ArtifactRef:
+    """Immutable artifact identity pinned to its canonical manifest SHA-256."""
+
+    namespace: str
+    name: str
+    revision: str
+
+    def __post_init__(self):
+        if any(not isinstance(value, str) or not _SEGMENT.fullmatch(value) or '..' in value
+               for value in (self.namespace, self.name)):
+            raise InvalidURI('invalid artifact name')
+        if not isinstance(self.revision, str) or not re.fullmatch(r'[0-9a-f]{64}', self.revision):
+            raise InvalidURI('artifact revision requires a complete manifest SHA-256')
+
+    @property
+    def kind(self):
+        return 'artifacts'
+
+    @property
+    def uri(self):
+        return f'envloop://artifacts/{self.namespace}/{self.name}@{self.revision}'
+
+    def to_dict(self):
+        return {'artifacts': {'namespace': self.namespace, 'name': self.name, 'revision': self.revision}}
+
+
+@dataclass(frozen=True)
+class RecipeRef:
+    """Immutable recipe identity pinned to its canonical manifest SHA-256."""
+
+    namespace: str
+    name: str
+    revision: str
+
+    def __post_init__(self):
+        if any(not isinstance(value, str) or not _SEGMENT.fullmatch(value) or '..' in value
+               for value in (self.namespace, self.name)):
+            raise InvalidURI('invalid recipe name')
+        if not isinstance(self.revision, str) or not re.fullmatch(r'[0-9a-f]{64}', self.revision):
+            raise InvalidURI('recipe revision requires a complete manifest SHA-256')
+
+    @property
+    def kind(self):
+        return 'recipes'
+
+    @property
+    def uri(self):
+        return f'envloop://recipes/{self.namespace}/{self.name}@{self.revision}'
+
+    def to_dict(self):
+        return {'recipes': {'namespace': self.namespace, 'name': self.name, 'revision': self.revision}}
+
+
+@dataclass(frozen=True)
+class RewardSetRef:
+    """Author-versioned verifier bundle; consumers pin the version's manifest SHA-256.
+
+    Like a Dataset version, a published version never changes: its first registration binds the
+    manifest digest and a different manifest under the same URI is a conflict.
+    """
+
+    namespace: str
+    name: str
+    version: str
+
+    def __post_init__(self):
+        if any(not isinstance(value, str) or not _SEGMENT.fullmatch(value) or '..' in value
+               for value in (self.namespace, self.name, self.version)):
+            raise InvalidURI('invalid reward set identity')
+
+    @property
+    def kind(self):
+        return 'reward-sets'
+
+    @property
+    def uri(self):
+        return f'envloop://reward-sets/{self.namespace}/{self.name}@{self.version}'
+
+    def to_dict(self):
+        return {'reward_sets': {'namespace': self.namespace, 'name': self.name, 'version': self.version}}
+
+
+@dataclass(frozen=True)
+class RevisionRunnerRef:
+    """Frozen Job reference with both immutable content pins and no storage details."""
+
+    name: str
+    revision: str
+    sha256: str
+    index_sha256: str
+
+    def __post_init__(self):
+        self.identity
+        for value in (self.sha256, self.index_sha256):
+            if not isinstance(value, str) or not re.fullmatch(r'[0-9a-f]{64}', value):
+                raise InvalidURI('invalid Runner content pin')
+
+    @property
+    def identity(self):
+        if not isinstance(self.name, str) or len(self.name.split('/')) != 2:
+            raise InvalidURI('invalid runner name')
+        namespace, name = self.name.split('/')
+        return RunnerRevision(namespace, name, self.revision)
+
+    @property
+    def uri(self):
+        return self.identity.uri
+
+    def to_dict(self):
+        return {'uri': self.uri, 'name': self.name, 'revision': self.revision,
+                'sha256': self.sha256, 'index_sha256': self.index_sha256}
+
+    @classmethod
+    def from_dict(cls, value: Any):
+        if not isinstance(value, dict) or set(value) != {'uri', 'name', 'revision', 'sha256', 'index_sha256'}:
+            raise InvalidURI('invalid RunnerRef fields')
+        reference = cls(**{key: value[key] for key in ('name', 'revision', 'sha256', 'index_sha256')})
+        if value['uri'] != reference.uri:
+            raise InvalidURI('RunnerRef URI does not match its identity')
+        return reference
+
+
+@dataclass(frozen=True)
+class JobCheckpointRef:
+    job_id: str
+    checkpoint_id: str
+
+    def __post_init__(self):
+        if (not isinstance(self.job_id, str) or not isinstance(self.checkpoint_id, str)
+                or not _JOB_CHECKPOINT.fullmatch(f'envloop://{self.job_id}/{self.checkpoint_id}')):
+            raise InvalidURI('invalid job checkpoint reference')
+
+    @property
+    def kind(self):
+        return 'checkpoint'
+
+    @property
+    def uri(self):
+        return f'envloop://{self.job_id}/{self.checkpoint_id}'
+
+    def to_dict(self):
+        return {'job_checkpoint': {'job_id': self.job_id, 'checkpoint_id': self.checkpoint_id}}
+
+
+@dataclass(frozen=True)
+class ArtifactIdRef:
+    """Stable opaque platform Artifact ID, never a path or storage locator."""
+
+    artifact_id: str
+
+    def __post_init__(self):
+        if (not isinstance(self.artifact_id, str) or len(self.artifact_id) > 256
+                or not _SEGMENT.fullmatch(self.artifact_id) or '..' in self.artifact_id):
+            raise InvalidURI('invalid artifact identity')
+
+    @property
+    def kind(self):
+        return 'artifacts'
+
+    @property
+    def uri(self):
+        return f'envloop://artifacts/{self.artifact_id}'
+
+    def to_dict(self):
+        return {'artifacts': {'artifact_id': self.artifact_id}}
+
+
+AssetReference = ArtifactIdRef | CheckpointRef | JobCheckpointRef | DatasetRef | RunnerRef | RunnerRevision | TemplateRef | ModelRef | ArtifactRef | RecipeRef | RewardSetRef
+
+
+def parse_uri(value: str) -> AssetReference:
+    """Strict parsing; legacy checkpoint inputs normalize through ``ref.uri``."""
+    if not isinstance(value, str):
+        raise InvalidURI('asset URI must be a string')
+    if re.fullmatch(r'envloop://artifacts/[^/]+', value):
+        return ArtifactIdRef(value.removeprefix('envloop://artifacts/'))
+    model = re.fullmatch(r'envloop://model/([^/]+)/([^/@]+)@([^/]+)(?:/([^/]+))?', value)
+    if model:
+        namespace, name, revision, checkpoint = model.groups()
+        return ModelRef(namespace, name, revision, checkpoint or '')
+    job_checkpoint = _JOB_CHECKPOINT.fullmatch(value)
+    if job_checkpoint:
+        return JobCheckpointRef(*job_checkpoint.groups())
+    checkpoint = _CHECKPOINT.fullmatch(value)
+    if checkpoint:
+        return CheckpointRef(*checkpoint.groups())
+    recipe = _RECIPE.fullmatch(value)
+    if recipe:
+        return RecipeRef(*recipe.groups())
+    reward_set = _REWARD_SET.fullmatch(value)
+    if reward_set:
+        return RewardSetRef(*reward_set.groups())
+    artifact = _ARTIFACT.fullmatch(value)
+    if artifact:
+        return ArtifactRef(*artifact.groups())
+    template = _TEMPLATE.fullmatch(value)
+    if template:
+        return TemplateRef(*template.groups())
+    runner = _RUNNER.fullmatch(value)
+    if runner:
+        if re.fullmatch(r'[0-9a-f]{40}|[0-9a-f]{64}', runner.group(3)):
+            return RunnerRevision(*runner.groups())
+        return RunnerRef(*runner.groups())
+    dataset = _DATASET.fullmatch(value)
+    if dataset:
+        namespace, name, encoded = dataset.groups()
+        try:
+            reference = DatasetRef(namespace, name, unquote(encoded, errors='strict'))
+        except UnicodeError as exc:
+            raise InvalidURI('invalid dataset version encoding') from exc
+        if reference.uri == value:
+            return reference
+    raise InvalidURI('unsupported or malformed asset URI')

envloop_envhub-1.23.0/hatch_build.py

@@ -0,0 +1,47 @@
+"""Fail closed before either implementation-only artifact is assembled."""
+import stat
+import tempfile
+import tomllib
+from pathlib import Path, PurePosixPath
+
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+
+
+class CustomBuildHook(BuildHookInterface):
+    def initialize(self, version, build_data):
+        root = Path(self.root)
+        config = tomllib.loads((root / 'pyproject.toml').read_text())
+        selected = config['tool']['hatch']['build']['targets'][self.target_name]['only-include']
+        # Hatch otherwise force-includes VCS ignore files in sdists, bypassing selection.
+        build_data['force_include'] = {source: target for source, target in
+            build_data.get('force_include', {}).items() if target in selected}
+        metadata = {'pyproject.toml', 'README.pypi.md', 'NOTICE', 'hatch_build.py'}
+        for name in selected:
+            path = PurePosixPath(name)
+            if (str(path) != name or path.is_absolute() or '..' in path.parts
+                    or '\\' in name or any(part.startswith('.') for part in path.parts)
+                    or not (name in metadata or (path.parts[0] == 'envhub'
+                            and (path.suffix == '.py' or name == 'envhub/ans/proto/ans.proto')))):
+                raise ValueError('DISTRIBUTION_PATH_INVALID: implementation allowlist only')
+            target = root
+            for part in path.parts:
+                target = target / part
+                if target.is_symlink():
+                    raise ValueError('DISTRIBUTION_LINK_FORBIDDEN: source must be ordinary files')
+            mode = target.stat().st_mode
+            if not stat.S_ISREG(mode) or mode & 0o7111:
+                raise ValueError('DISTRIBUTION_MODE_INVALID: ordinary non-executable files only')
+
+        if self.target_name == 'sdist':
+            # Do not expose private workspace/dependency configuration in the public archive.
+            public_config = (root / 'pyproject.toml').read_text().split('# Private development configuration;')[0]
+            self._projection = tempfile.TemporaryDirectory(prefix='envhub-public-build-')
+            projected = Path(self._projection.name) / 'pyproject.toml'
+            projected.write_text(public_config)
+            build_data['force_include'] = {source: target for source, target in
+                build_data['force_include'].items() if target != 'pyproject.toml'}
+            build_data['force_include'][str(projected)] = 'pyproject.toml'
+
+    def finalize(self, version, build_data, artifact_path):
+        if hasattr(self, '_projection'):
+            self._projection.cleanup()

envloop_envhub-1.23.0/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+
+[project]
+name = "envloop-envhub"
+version = "1.23.0"
+description = "Dependency-free ANS protocol and verified downloads"
+readme = "README.pypi.md"
+license-files = ["NOTICE"]
+requires-python = ">=3.12"
+dependencies = []
+
+[project.optional-dependencies]
+default = []
+
+[tool.hatch.build]
+ignore-vcs = true
+
+[tool.hatch.build.hooks.custom]
+path = "hatch_build.py"
+
+[tool.hatch.build.targets.wheel]
+only-include = [
+    "envhub/__init__.py",
+    "envhub/ans/__init__.py",
+    "envhub/ans/client/__init__.py",
+    "envhub/ans/client/download.py",
+    "envhub/ans/client/materialize.py",
+    "envhub/ans/proto/__init__.py",
+    "envhub/ans/proto/uri.py",
+    "envhub/ans/proto/errors.py",
+    "envhub/ans/proto/manifests.py",
+    "envhub/ans/proto/schemas.py",
+    "envhub/ans/proto/ans.proto"
+]
+
+[tool.hatch.build.targets.sdist]
+only-include = [
+    "envhub/__init__.py",
+    "envhub/ans/__init__.py",
+    "envhub/ans/client/__init__.py",
+    "envhub/ans/client/download.py",
+    "envhub/ans/client/materialize.py",
+    "envhub/ans/proto/__init__.py",
+    "envhub/ans/proto/uri.py",
+    "envhub/ans/proto/errors.py",
+    "envhub/ans/proto/manifests.py",
+    "envhub/ans/proto/schemas.py",
+    "envhub/ans/proto/ans.proto",
+    "pyproject.toml",
+    "README.pypi.md",
+    "NOTICE",
+    "hatch_build.py"
+]
+