atdata 0.3.0b1__py3-none-any.whl → 0.3.2b1__py3-none-any.whl

atdata/{local → index}/_index.py

@@ -7,8 +7,8 @@ from atdata import (
 )
 from atdata._protocols import AbstractDataStore, Packable
 
-from atdata.local._entry import LocalDatasetEntry
-from atdata.local._schema import (
+from atdata.index._entry import LocalDatasetEntry
+from atdata.index._schema import (
     SchemaNamespace,
     LocalSchemaRecord,
     _schema_ref_from_type,
@@ -21,15 +21,17 @@ from atdata.local._schema import (
 from pathlib import Path
 from typing import (
     Any,
+    Iterable,
     Type,
     TypeVar,
     Generator,
     TYPE_CHECKING,
 )
-from redis import Redis
 import json
 
 if TYPE_CHECKING:
+    from redis import Redis
+
     from atdata.providers._base import IndexProvider
     from atdata.repository import Repository, _AtmosphereBackend
     from atdata._protocols import IndexEntry
@@ -37,12 +39,42 @@ if TYPE_CHECKING:
 T = TypeVar("T", bound=Packable)
 
 
+def _is_local_path(url: str) -> bool:
+    """Check if a URL points to the local filesystem."""
+    return (
+        url.startswith("/")
+        or url.startswith("file://")
+        or (len(url) > 1 and url[1] == ":")
+    )
+
+
+def _is_credentialed_source(ds: Dataset) -> bool:
+    """Check if a Dataset uses a credentialed source (e.g. S3Source with keys)."""
+    from atdata._sources import S3Source
+
+    return isinstance(ds.source, S3Source)
+
+
+def _estimate_dataset_bytes(ds: Dataset) -> int:
+    """Best-effort total size estimate from local shard files.
+
+    Returns 0 when size cannot be determined (e.g. remote URLs).
+    """
+    total = 0
+    for shard_url in ds.list_shards():
+        if _is_local_path(shard_url):
+            p = Path(shard_url.removeprefix("file://"))
+            if p.exists():
+                total += p.stat().st_size
+    return total
+
+
 class Index:
     """Unified index for tracking datasets across multiple repositories.
 
     Implements the AbstractIndex protocol. Maintains a registry of
-    dataset entries across a built-in ``"local"`` repository, optional
-    named repositories, and an optional atmosphere (ATProto) backend.
+    dataset entries across named repositories (always including a built-in
+    ``"local"`` repository) and an optional atmosphere (ATProto) backend.
 
     The ``"local"`` repository is always present and uses the storage backend
     determined by the ``provider`` argument. When no provider is given, defaults
@@ -52,14 +84,12 @@ class Index:
     Additional named repositories can be mounted via the ``repos`` parameter,
     each pairing an IndexProvider with an optional data store.
 
-    An AtmosphereClient is available by default for anonymous read-only
+    An Atmosphere is available by default for anonymous read-only
     resolution of ``@handle/dataset`` paths. Pass an authenticated client
     for write operations, or ``atmosphere=None`` to disable.
 
     Attributes:
-        _provider: IndexProvider for the built-in ``"local"`` repository.
-        _data_store: Optional AbstractDataStore for the local repository.
-        _repos: Named repositories beyond ``"local"``.
+        _repos: All repositories keyed by name. ``"local"`` is always present.
         _atmosphere: Optional atmosphere backend for ATProto operations.
     """
 
@@ -105,7 +135,7 @@ class Index:
             atmosphere: ATProto client for distributed network operations.
                 - Default (sentinel): creates an anonymous read-only client
                   lazily on first access.
-                - ``AtmosphereClient`` instance: uses that client directly.
+                - ``Atmosphere`` instance: uses that client directly.
                 - ``None``: disables atmosphere backend entirely.
             auto_stubs: If True, automatically generate .pyi stub files when
                 schemas are accessed via get_schema() or decode_schema().
@@ -146,12 +176,13 @@ class Index:
         ##
 
         from atdata.providers._base import IndexProvider as _IP
+        from atdata.repository import Repository as _Repo
 
+        # Resolve the local provider
         if isinstance(provider, str):
-            # String-based provider selection
             from atdata.providers._factory import create_provider
 
-            self._provider: _IP = create_provider(
+            local_provider: _IP = create_provider(
                 provider, path=path, dsn=dsn, redis=redis, **kwargs
             )
         elif provider is not None:
@@ -160,27 +191,25 @@ class Index:
                     f"provider must be an IndexProvider or backend name string, "
                     f"got {type(provider).__name__}"
                 )
-            self._provider = provider
+            local_provider = provider
         elif redis is not None:
-            # Explicit Redis connection provided
             from atdata.providers._redis import RedisProvider
 
-            self._provider = RedisProvider(redis)
+            local_provider = RedisProvider(redis)
         elif kwargs:
-            # kwargs provided — assume Redis constructor args for compat
+            from redis import Redis as _Redis
             from atdata.providers._redis import RedisProvider
 
-            self._provider = RedisProvider(Redis(**kwargs))
+            local_provider = RedisProvider(_Redis(**kwargs))
         else:
-            # Default: zero-dependency SQLite
             from atdata.providers._sqlite import SqliteProvider
 
-            self._provider = SqliteProvider()
-
-        self._data_store = data_store
+            local_provider = SqliteProvider()
 
-        # Validate and store named repositories
-        from atdata.repository import Repository as _Repo
+        # Build the unified repos dict with "local" always present
+        self._repos: dict[str, _Repo] = {
+            "local": _Repo(provider=local_provider, data_store=data_store),
+        }
 
         if repos is not None:
             if "local" in repos:
@@ -194,9 +223,7 @@ class Index:
                         f"repos[{name!r}] must be a Repository, "
                         f"got {type(repo).__name__}"
                     )
-            self._repos: dict[str, _Repo] = dict(repos)
-        else:
-            self._repos = {}
+            self._repos.update(repos)
 
         # Atmosphere backend (lazy or explicit)
         from atdata.repository import _AtmosphereBackend
@@ -230,10 +257,10 @@ class Index:
         """Get the atmosphere backend, lazily creating anonymous client if needed."""
         if self._atmosphere_deferred and self._atmosphere is None:
             try:
-                from atdata.atmosphere.client import AtmosphereClient
+                from atdata.atmosphere.client import Atmosphere
                 from atdata.repository import _AtmosphereBackend
 
-                client = AtmosphereClient()
+                client = Atmosphere()
                 self._atmosphere = _AtmosphereBackend(client)
             except ImportError:
                 # atproto package not installed -- atmosphere unavailable
@@ -289,13 +316,13 @@ class Index:
         return ("local", ref, None)
 
     @property
-    def repos(self) -> dict[str, Repository]:
-        """Named repositories mounted on this index (excluding ``"local"``)."""
+    def repos(self) -> dict[str, "Repository"]:
+        """All repositories mounted on this index (including ``"local"``)."""
         return dict(self._repos)
 
     @property
     def atmosphere(self) -> Any:
-        """The AtmosphereClient for this index, or None if disabled.
+        """The Atmosphere for this index, or None if disabled.
 
         Returns the underlying client (not the internal backend wrapper).
         """
@@ -304,10 +331,15 @@ class Index:
             return backend.client
         return None
 
+    @property
+    def _provider(self) -> "IndexProvider":  # noqa: F821
+        """IndexProvider for the ``"local"`` repository (backward compat)."""
+        return self._repos["local"].provider
+
     @property
     def provider(self) -> "IndexProvider":  # noqa: F821
-        """The storage provider backing this index."""
-        return self._provider
+        """The storage provider backing the ``"local"`` repository."""
+        return self._repos["local"].provider
 
     @property
     def _redis(self) -> Redis:
@@ -318,17 +350,23 @@ class Index:
         """
         from atdata.providers._redis import RedisProvider
 
-        if isinstance(self._provider, RedisProvider):
-            return self._provider.redis
+        prov = self._repos["local"].provider
+        if isinstance(prov, RedisProvider):
+            return prov.redis
         raise AttributeError(
             "Index._redis is only available with a Redis provider. "
             "Use index.provider instead."
         )
 
+    @property
+    def _data_store(self) -> AbstractDataStore | None:
+        """Data store for the ``"local"`` repository (backward compat)."""
+        return self._repos["local"].data_store
+
     @property
     def data_store(self) -> AbstractDataStore | None:
         """The data store for writing shards, or None if index-only."""
-        return self._data_store
+        return self._repos["local"].data_store
 
     @property
     def stub_dir(self) -> Path | None:
@@ -351,7 +389,7 @@ class Index:
         as attributes on this namespace.
 
         Examples:
-            >>> index.load_schema("atdata://local/sampleSchema/MySample@1.0.0")
+            >>> index.load_schema("atdata://local/schema/MySample@1.0.0")
             >>> MyType = index.types.MySample
             >>> sample = MyType(name="hello", value=42)
 
@@ -368,7 +406,7 @@ class Index:
         in the :attr:`types` namespace for easy access.
 
         Args:
-            ref: Schema reference string (atdata://local/sampleSchema/... or
+            ref: Schema reference string (atdata://local/schema/... or
                 legacy local://schemas/...).
 
         Returns:
@@ -381,11 +419,11 @@ class Index:
 
         Examples:
             >>> # Load and use immediately
-            >>> MyType = index.load_schema("atdata://local/sampleSchema/MySample@1.0.0")
+            >>> MyType = index.load_schema("atdata://local/schema/MySample@1.0.0")
             >>> sample = MyType(field1="hello", field2=42)
             >>>
             >>> # Or access later via namespace
-            >>> index.load_schema("atdata://local/sampleSchema/OtherType@1.0.0")
+            >>> index.load_schema("atdata://local/schema/OtherType@1.0.0")
             >>> other = index.types.OtherType(data="test")
         """
         # Decode the schema (uses generated module if auto_stubs enabled)
@@ -465,6 +503,9 @@ class Index:
     ) -> LocalDatasetEntry:
         """Add a dataset to the local repository index.
 
+        .. deprecated::
+            Use :meth:`insert_dataset` instead.
+
         Args:
             ds: The dataset to add to the index.
             name: Human-readable name for the dataset.
@@ -474,6 +515,13 @@ class Index:
         Returns:
             The created LocalDatasetEntry object.
         """
+        import warnings
+
+        warnings.warn(
+            "Index.add_entry() is deprecated, use Index.insert_dataset()",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         return self._insert_dataset_to_provider(
             ds,
             name=name,
@@ -513,6 +561,23 @@ class Index:
 
     # AbstractIndex protocol methods
 
+    @staticmethod
+    def _ensure_schema_stored(
+        schema_ref: str,
+        sample_type: type,
+        provider: "IndexProvider",  # noqa: F821
+    ) -> None:
+        """Persist the schema definition if not already stored.
+
+        Called during dataset insertion so that ``decode_schema()`` can
+        reconstruct the type later without the caller needing to publish
+        the schema separately.
+        """
+        schema_name, version = _parse_schema_ref(schema_ref)
+        if provider.get_schema_json(schema_name, version) is None:
+            record = _build_schema_record(sample_type, version=version)
+            provider.store_schema(schema_name, version, json.dumps(record))
+
     def _insert_dataset_to_provider(
         self,
         ds: Dataset,
@@ -528,21 +593,36 @@ class Index:
         This is the internal implementation shared by all local and named
         repository inserts.
         """
+        from atdata._logging import get_logger
+
+        log = get_logger()
         metadata = kwargs.get("metadata")
 
         if store is not None:
             prefix = kwargs.get("prefix", name)
             cache_local = kwargs.get("cache_local", False)
+            log.debug(
+                "_insert_dataset_to_provider: name=%s, store=%s",
+                name,
+                type(store).__name__,
+            )
 
             written_urls = store.write_shards(
                 ds,
                 prefix=prefix,
                 cache_local=cache_local,
             )
+            log.info(
+                "_insert_dataset_to_provider: %d shard(s) written for %s",
+                len(written_urls),
+                name,
+            )
 
             if schema_ref is None:
                 schema_ref = _schema_ref_from_type(ds.sample_type, version="1.0.0")
 
+            self._ensure_schema_stored(schema_ref, ds.sample_type, provider)
+
             entry_metadata = metadata if metadata is not None else ds._metadata
             entry = LocalDatasetEntry(
                 name=name,
@@ -551,12 +631,15 @@ class Index:
                 metadata=entry_metadata,
             )
             provider.store_entry(entry)
+            log.debug("_insert_dataset_to_provider: entry stored for %s", name)
             return entry
 
         # No data store - just index the existing URL
         if schema_ref is None:
             schema_ref = _schema_ref_from_type(ds.sample_type, version="1.0.0")
 
+        self._ensure_schema_stored(schema_ref, ds.sample_type, provider)
+
         data_urls = [ds.url]
         entry_metadata = metadata if metadata is not None else ds._metadata
 
@@ -567,6 +650,7 @@ class Index:
             metadata=entry_metadata,
         )
         provider.store_entry(entry)
+        log.debug("_insert_dataset_to_provider: entry stored for %s", name)
         return entry
 
     def insert_dataset(
@@ -575,66 +659,379 @@ class Index:
         *,
         name: str,
         schema_ref: str | None = None,
+        description: str | None = None,
+        tags: list[str] | None = None,
+        license: str | None = None,
+        data_store: AbstractDataStore | None = None,
+        force: bool = False,
+        copy: bool = False,
+        metadata: dict | None = None,
+        _data_urls: list[str] | None = None,
+        _blob_refs: list[dict] | None = None,
         **kwargs,
     ) -> "IndexEntry":
-        """Insert a dataset into the index (AbstractIndex protocol).
+        """Insert a dataset into the index.
 
         The target repository is determined by a prefix in the ``name``
         argument (e.g. ``"lab/mnist"``). If no prefix is given, or the
         prefix is ``"local"``, the built-in local repository is used.
 
-        If the target repository has a data_store, shards are written to
-        storage first, then indexed. Otherwise, the dataset's existing URL
-        is indexed directly.
+        For atmosphere targets:
+
+        - **Local sources** are uploaded via *data_store* (defaults to
+          ``PDSBlobStore``).
+        - **Public remote sources** (http/https) are referenced as
+          external URLs unless *copy* is ``True``.
+        - **Credentialed sources** (e.g. ``S3Source``) raise an error
+          unless *copy* is ``True`` or *data_store* is provided, to
+          prevent leaking private endpoints.
 
         Args:
             ds: The Dataset to register.
             name: Human-readable name for the dataset, optionally prefixed
                 with a repository name (e.g. ``"lab/mnist"``).
             schema_ref: Optional schema reference.
-            **kwargs: Additional options:
-                - metadata: Optional metadata dict
-                - prefix: Storage prefix (default: dataset name)
-                - cache_local: If True, cache writes locally first
+            description: Optional dataset description (atmosphere only).
+            tags: Optional tags for discovery (atmosphere only).
+            license: Optional license identifier (atmosphere only).
+            data_store: Explicit data store for shard storage. When
+                provided, data is always copied through this store.
+            force: If True, bypass PDS size limits (50 MB per shard,
+                1 GB total). Default: ``False``.
+            copy: If True, copy data to the destination store even for
+                remote sources. Required for credentialed sources
+                targeting the atmosphere. Default: ``False``.
+            metadata: Optional metadata dict.
 
         Returns:
             IndexEntry for the inserted dataset.
+
+        Raises:
+            ValueError: If atmosphere limits are exceeded (when
+                *force* is ``False``), or if a credentialed source
+                targets the atmosphere without *copy*.
         """
+        from atdata.atmosphere.store import PDS_TOTAL_DATASET_LIMIT_BYTES
+
         backend_key, resolved_name, handle_or_did = self._resolve_prefix(name)
+        is_atmosphere = backend_key == "_atmosphere"
 
-        if backend_key == "_atmosphere":
+        if is_atmosphere:
             atmo = self._get_atmosphere()
             if atmo is None:
                 raise ValueError(
                     f"Atmosphere backend required for name {name!r} but not available."
                 )
-            return atmo.insert_dataset(
-                ds, name=resolved_name, schema_ref=schema_ref, **kwargs
-            )
 
-        if backend_key == "local":
-            return self._insert_dataset_to_provider(
+            # Providing an explicit data_store implies copy behaviour
+            needs_copy = copy or data_store is not None
+
+            # Credentialed source guard
+            if _is_credentialed_source(ds) and not needs_copy:
+                raise ValueError(
+                    "Dataset uses a credentialed source. Referencing "
+                    "these URLs in a public atmosphere record would "
+                    "leak private endpoints. Pass copy=True to copy "
+                    "data to the destination store (default: PDS blobs)."
+                )
+
+            # If we already have pre-written URLs (from write_samples),
+            # go straight to publish.
+            if _data_urls is not None:
+                return atmo.insert_dataset(
+                    ds,
+                    name=resolved_name,
+                    schema_ref=schema_ref,
+                    data_urls=_data_urls,
+                    blob_refs=_blob_refs,
+                    description=description,
+                    tags=tags,
+                    license=license,
+                    metadata=metadata,
+                    **kwargs,
+                )
+
+            # Determine whether data must be copied
+            source_is_local = _is_local_path(ds.url)
+
+            if source_is_local or needs_copy:
+                # Resolve effective store
+                if data_store is not None:
+                    effective_store = data_store
+                else:
+                    from atdata.atmosphere.store import PDSBlobStore
+
+                    effective_store = PDSBlobStore(atmo.client)
+
+                # Size guard
+                if not force:
+                    total_bytes = _estimate_dataset_bytes(ds)
+                    if total_bytes > PDS_TOTAL_DATASET_LIMIT_BYTES:
+                        raise ValueError(
+                            f"Total dataset size ({total_bytes} bytes) "
+                            f"exceeds atmosphere limit "
+                            f"({PDS_TOTAL_DATASET_LIMIT_BYTES} bytes). "
+                            f"Pass force=True to bypass."
+                        )
+
+                result = effective_store.write_shards(ds, prefix=resolved_name)
+
+                # ShardUploadResult carries blob_refs; plain list does not
+                blob_refs = getattr(result, "blob_refs", None) or None
+
+                return atmo.insert_dataset(
+                    ds,
+                    name=resolved_name,
+                    schema_ref=schema_ref,
+                    data_urls=list(result),
+                    blob_refs=blob_refs,
+                    description=description,
+                    tags=tags,
+                    license=license,
+                    metadata=metadata,
+                    **kwargs,
+                )
+
+            # Public remote source — reference existing URLs
+            data_urls = ds.list_shards()
+            return atmo.insert_dataset(
                 ds,
                 name=resolved_name,
                 schema_ref=schema_ref,
-                provider=self._provider,
-                store=self._data_store,
+                data_urls=data_urls,
+                description=description,
+                tags=tags,
+                license=license,
+                metadata=metadata,
                 **kwargs,
             )
 
-        # Named repository
+        # --- Local / named repo path ---
         repo = self._repos.get(backend_key)
         if repo is None:
             raise KeyError(f"Unknown repository {backend_key!r} in name {name!r}")
+
+        effective_store = data_store or repo.data_store
         return self._insert_dataset_to_provider(
             ds,
             name=resolved_name,
             schema_ref=schema_ref,
             provider=repo.provider,
-            store=repo.data_store,
+            store=effective_store,
+            metadata=metadata,
             **kwargs,
         )
 
+    def write_samples(
+        self,
+        samples: Iterable,
+        *,
+        name: str,
+        schema_ref: str | None = None,
+        description: str | None = None,
+        tags: list[str] | None = None,
+        license: str | None = None,
+        maxcount: int = 10_000,
+        maxsize: int | None = None,
+        metadata: dict | None = None,
+        manifest: bool = False,
+        data_store: AbstractDataStore | None = None,
+        force: bool = False,
+    ) -> "IndexEntry":
+        """Write samples and create an index entry in one step.
+
+        This is the primary method for publishing data. It serializes
+        samples to WebDataset tar files, stores them via the appropriate
+        backend, and creates an index entry.
+
+        The target backend is determined by the *name* prefix:
+
+        - Bare name (e.g., ``"mnist"``): writes to the local repository.
+        - ``"@handle/name"``: writes and publishes to the atmosphere.
+        - ``"repo/name"``: writes to a named repository.
+
+        For atmosphere targets, data is uploaded as PDS blobs by default.
+        Shard size is capped at 50 MB and total dataset size at 1 GB
+        unless *force* is ``True``.
+
+        When the local backend has no ``data_store`` configured, a
+        ``LocalDiskStore`` is created automatically at
+        ``~/.atdata/data/`` so that samples have persistent storage.
+
+        Args:
+            samples: Iterable of ``Packable`` samples. Must be non-empty.
+            name: Dataset name, optionally prefixed with target.
+            schema_ref: Optional schema reference. Auto-generated if ``None``.
+            description: Optional dataset description (atmosphere only).
+            tags: Optional tags for discovery (atmosphere only).
+            license: Optional license identifier (atmosphere only).
+            maxcount: Max samples per shard. Default: 10,000.
+            maxsize: Max bytes per shard. For atmosphere targets defaults
+                to 50 MB (PDS blob limit). For local targets defaults to
+                ``None`` (unlimited).
+            metadata: Optional metadata dict stored with the entry.
+            manifest: If True, write per-shard manifest sidecar files
+                alongside each tar. Default: ``False``.
+            data_store: Explicit data store for shard storage. Overrides
+                the repository's default store. For atmosphere targets
+                defaults to ``PDSBlobStore``.
+            force: If True, bypass PDS size limits (50 MB per shard,
+                1 GB total dataset). Default: ``False``.
+
+        Returns:
+            IndexEntry for the created dataset.
+
+        Raises:
+            ValueError: If *samples* is empty, or if atmosphere size
+                limits are exceeded (when *force* is ``False``).
+
+        Examples:
+            >>> index = Index()
+            >>> samples = [MySample(key="0", text="hello")]
+            >>> entry = index.write_samples(samples, name="my-dataset")
+        """
+        import tempfile
+
+        from atdata.dataset import write_samples as _write_samples
+        from atdata.atmosphere.store import (
+            PDS_BLOB_LIMIT_BYTES,
+            PDS_TOTAL_DATASET_LIMIT_BYTES,
+        )
+        from atdata._logging import log_operation
+
+        backend_key, resolved_name, _ = self._resolve_prefix(name)
+        is_atmosphere = backend_key == "_atmosphere"
+
+        with log_operation("Index.write_samples", name=name):
+            # --- Atmosphere size guards ---
+            if is_atmosphere and not force:
+                if maxsize is not None and maxsize > PDS_BLOB_LIMIT_BYTES:
+                    raise ValueError(
+                        f"maxsize={maxsize} exceeds PDS blob limit "
+                        f"({PDS_BLOB_LIMIT_BYTES} bytes). "
+                        f"Pass force=True to bypass."
+                    )
+
+            # Default maxsize for atmosphere targets
+            effective_maxsize = maxsize
+            if is_atmosphere and effective_maxsize is None:
+                effective_maxsize = PDS_BLOB_LIMIT_BYTES
+
+            # Resolve the effective data store
+            if is_atmosphere:
+                atmo = self._get_atmosphere()
+                if atmo is None:
+                    raise ValueError(
+                        f"Atmosphere backend required for name {name!r} but not available."
+                    )
+                if data_store is None:
+                    from atdata.atmosphere.store import PDSBlobStore
+
+                    effective_store: AbstractDataStore | None = PDSBlobStore(
+                        atmo.client
+                    )
+                else:
+                    effective_store = data_store
+            else:
+                repo = self._repos.get(backend_key)
+                effective_store = data_store or (
+                    repo.data_store if repo is not None else None
+                )
+                needs_auto_store = repo is not None and effective_store is None
+                if needs_auto_store:
+                    from atdata.stores._disk import LocalDiskStore
+
+                    effective_store = LocalDiskStore()
+
+            with tempfile.TemporaryDirectory() as tmp_dir:
+                tmp_path = Path(tmp_dir) / "data.tar"
+                ds = _write_samples(
+                    samples,
+                    tmp_path,
+                    maxcount=maxcount,
+                    maxsize=effective_maxsize,
+                    manifest=manifest,
+                )
+
+                # Atmosphere total-size guard (after writing so we can measure)
+                if is_atmosphere and not force:
+                    total_bytes = _estimate_dataset_bytes(ds)
+                    if total_bytes > PDS_TOTAL_DATASET_LIMIT_BYTES:
+                        raise ValueError(
+                            f"Total dataset size ({total_bytes} bytes) exceeds "
+                            f"atmosphere limit ({PDS_TOTAL_DATASET_LIMIT_BYTES} "
+                            f"bytes). Pass force=True to bypass."
+                        )
+
+                if is_atmosphere:
+                    # Write shards through the store, then publish record
+                    # with the resulting URLs (not the temp paths).
+                    written_urls = effective_store.write_shards(
+                        ds, prefix=resolved_name
+                    )
+
+                    # If write_shards returned blob refs (e.g. ShardUploadResult),
+                    # use storageBlobs so the PDS retains the uploaded blobs.
+                    # Fall back to storageExternal with AT URIs otherwise.
+                    blob_refs = getattr(written_urls, "blob_refs", None) or None
+
+                    return self.insert_dataset(
+                        ds,
+                        name=name,
+                        schema_ref=schema_ref,
+                        metadata=metadata,
+                        description=description,
+                        tags=tags,
+                        license=license,
+                        data_store=data_store,
+                        force=force,
+                        _data_urls=written_urls,
+                        _blob_refs=blob_refs,
+                    )
+
+                # Local / named repo path
+                repo = self._repos.get(backend_key)
+                if repo is not None and effective_store is not None:
+                    return self._insert_dataset_to_provider(
+                        ds,
+                        name=resolved_name,
+                        schema_ref=schema_ref,
+                        provider=repo.provider,
+                        store=effective_store,
+                        metadata=metadata,
+                    )
+
+                return self.insert_dataset(
+                    ds,
+                    name=name,
+                    schema_ref=schema_ref,
+                    metadata=metadata,
+                    description=description,
+                    tags=tags,
+                    license=license,
+                )
+
+    def write(
+        self,
+        samples: Iterable,
+        *,
+        name: str,
+        **kwargs: Any,
+    ) -> "IndexEntry":
+        """Write samples and create an index entry.
+
+        .. deprecated::
+            Use :meth:`write_samples` instead.
+        """
+        import warnings
+
+        warnings.warn(
+            "Index.write() is deprecated, use Index.write_samples()",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.write_samples(samples, name=name, **kwargs)
+
     def get_dataset(self, ref: str) -> "IndexEntry":
         """Get a dataset entry by name or prefixed reference.
 
@@ -659,14 +1056,10 @@ class Index:
             if atmo is None:
                 raise ValueError(
                     f"Atmosphere backend required for path {ref!r} but not available. "
-                    "Install 'atproto' or pass an AtmosphereClient."
+                    "Install 'atproto' or pass an Atmosphere."
                 )
             return atmo.get_dataset(resolved_ref)
 
-        if backend_key == "local":
-            return self._provider.get_entry_by_name(resolved_ref)
-
-        # Named repository
         repo = self._repos.get(backend_key)
         if repo is None:
             raise KeyError(f"Unknown repository {backend_key!r} in ref {ref!r}")
@@ -676,14 +1069,13 @@ class Index:
     def datasets(self) -> Generator["IndexEntry", None, None]:
         """Lazily iterate over all dataset entries across local repositories.
 
-        Yields entries from the ``"local"`` repository and all named
-        repositories. Atmosphere entries are not included (use
+        Yields entries from all mounted repositories (``"local"`` and named).
+        Atmosphere entries are not included (use
         ``list_datasets(repo="_atmosphere")`` for those).
 
         Yields:
             IndexEntry for each dataset.
         """
-        yield from self._provider.iter_entries()
         for repo in self._repos.values():
             yield from repo.provider.iter_entries()
 
@@ -702,9 +1094,6 @@ class Index:
         if repo is None:
             return list(self.datasets)
 
-        if repo == "local":
-            return self.list_entries()
-
         if repo == "_atmosphere":
             atmo = self._get_atmosphere()
             if atmo is None:
@@ -740,7 +1129,7 @@ class Index:
                 the class docstring.
 
         Returns:
-            Schema reference string: 'atdata://local/sampleSchema/{name}@{version}'.
+            Schema reference string: 'atdata://local/schema/{name}@{version}'.
 
         Raises:
             ValueError: If sample_type is not a dataclass.
@@ -794,7 +1183,7 @@ class Index:
 
         Args:
             ref: Schema reference string. Supports both new format
-                (atdata://local/sampleSchema/{name}@{version}) and legacy
+                (atdata://local/schema/{name}@{version}) and legacy
                 format (local://schemas/{module.Class}@{version}).
 
         Returns:
@@ -871,7 +1260,7 @@ class Index:
         The returned class has proper type information that IDEs can understand.
 
         Args:
-            ref: Schema reference string (atdata://local/sampleSchema/... or
+            ref: Schema reference string (atdata://local/schema/... or
                 legacy local://schemas/...).
 
         Returns:
@@ -938,3 +1327,159 @@ class Index:
         if self._stub_manager is not None:
             return self._stub_manager.clear_stubs()
         return 0
+
+    # -- Atmosphere promotion --
+
+    def promote_entry(
+        self,
+        entry_name: str,
+        *,
+        name: str | None = None,
+        description: str | None = None,
+        tags: list[str] | None = None,
+        license: str | None = None,
+    ) -> str:
+        """Promote a locally-indexed dataset to the atmosphere.
+
+        .. deprecated::
+            Use :meth:`insert_dataset` instead.
+
+        Args:
+            entry_name: Name of the local dataset entry to promote.
+            name: Override name for the atmosphere record. Defaults to
+                the local entry name.
+            description: Optional description for the dataset.
+            tags: Optional tags for discovery.
+            license: Optional license identifier.
+
+        Returns:
+            AT URI of the created atmosphere dataset record.
+
+        Raises:
+            ValueError: If atmosphere backend is not available, or
+                the local entry has no data URLs.
+            KeyError: If the entry or its schema is not found.
+
+        Examples:
+            >>> index = Index(atmosphere=client)
+            >>> uri = index.promote_entry("mnist-train")
+        """
+        import warnings
+
+        warnings.warn(
+            "Index.promote_entry() is deprecated, use Index.insert_dataset()",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        from atdata.promote import _find_or_publish_schema
+        from atdata.atmosphere import DatasetPublisher
+        from atdata._schema_codec import schema_to_type
+        from atdata._logging import log_operation
+
+        atmo = self._get_atmosphere()
+        if atmo is None:
+            raise ValueError("Atmosphere backend required but not available.")
+
+        with log_operation("Index.promote_entry", entry_name=entry_name):
+            entry = self.get_entry_by_name(entry_name)
+            if not entry.data_urls:
+                raise ValueError(f"Local entry {entry_name!r} has no data URLs")
+
+            schema_record = self.get_schema(entry.schema_ref)
+            sample_type = schema_to_type(schema_record)
+            schema_version = schema_record.get("version", "1.0.0")
+
+            atmosphere_schema_uri = _find_or_publish_schema(
+                sample_type,
+                schema_version,
+                atmo.client,
+                description=schema_record.get("description"),
+            )
+
+            publisher = DatasetPublisher(atmo.client)
+            uri = publisher.publish_with_urls(
+                urls=entry.data_urls,
+                schema_uri=atmosphere_schema_uri,
+                name=name or entry.name,
+                description=description,
+                tags=tags,
+                license=license,
+                metadata=entry.metadata,
+            )
+            return str(uri)
+
+    def promote_dataset(
+        self,
+        dataset: Dataset,
+        *,
+        name: str,
+        sample_type: type | None = None,
+        schema_version: str = "1.0.0",
+        description: str | None = None,
+        tags: list[str] | None = None,
+        license: str | None = None,
+    ) -> str:
+        """Publish a Dataset directly to the atmosphere.
+
+        .. deprecated::
+            Use :meth:`insert_dataset` instead.
+
+        Args:
+            dataset: The Dataset to publish.
+            name: Name for the atmosphere dataset record.
+            sample_type: Sample type for schema publishing. Inferred from
+                ``dataset.sample_type`` if not provided.
+            schema_version: Semantic version for the schema. Default: ``"1.0.0"``.
+            description: Optional description for the dataset.
+            tags: Optional tags for discovery.
+            license: Optional license identifier.
+
+        Returns:
+            AT URI of the created atmosphere dataset record.
+
+        Raises:
+            ValueError: If atmosphere backend is not available.
+
+        Examples:
+            >>> index = Index(atmosphere=client)
+            >>> ds = atdata.load_dataset("./data.tar", MySample, split="train")
+            >>> uri = index.promote_dataset(ds, name="my-dataset")
+        """
+        import warnings
+
+        warnings.warn(
+            "Index.promote_dataset() is deprecated, use Index.insert_dataset()",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        from atdata.promote import _find_or_publish_schema
+        from atdata.atmosphere import DatasetPublisher
+        from atdata._logging import log_operation
+
+        atmo = self._get_atmosphere()
+        if atmo is None:
+            raise ValueError("Atmosphere backend required but not available.")
+
+        with log_operation("Index.promote_dataset", name=name):
+            st = sample_type or dataset.sample_type
+
+            atmosphere_schema_uri = _find_or_publish_schema(
+                st,
+                schema_version,
+                atmo.client,
+                description=description,
+            )
+
+            data_urls = dataset.list_shards()
+
+            publisher = DatasetPublisher(atmo.client)
+            uri = publisher.publish_with_urls(
+                urls=data_urls,
+                schema_uri=atmosphere_schema_uri,
+                name=name,
+                description=description,
+                tags=tags,
+                license=license,
+                metadata=dataset._metadata,
+            )
+            return str(uri)