aloelite 0.1.0__tar.gz

aloelite-0.1.0/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: aloelite
+Version: 0.1.0
+Requires-Python: >=3.11
+Requires-Dist: cryptography
+Requires-Dist: pydantic
+Requires-Dist: pyyaml
+Requires-Dist: msgpack
+Requires-Dist: pyfuse3
+Requires-Dist: trio
+Requires-Dist: flask
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"

aloelite-0.1.0/README.md

@@ -0,0 +1,235 @@
+# aloelite
+
+<div align="center">
+
+<img src="https://raw.githubusercontent.com/Aloecraft-org/xtrshow/main/doc/icon.png" style="height:96px; width:96px;"/>
+
+**AloeLite SQLite Filesystem**
+
+[![PyPI Version](https://img.shields.io/pypi/v/aloelite.svg)](https://pypi.org/project/aloelite/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/aloelite.svg)](https://pypi.org/project/aloelite/)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+
+[![CI Status](https://github.com/Aloecraft-org/aloelite/actions/workflows/main.yml/badge.svg)](https://github.com/Aloecraft-org/aloelite/actions/workflows/main.yml)
+[![Downloads](https://static.pepy.tech/badge/aloelite)](https://pepy.tech/project/aloelite)
+
+</div>
+
+## Overview
+
+AloeLite is a filesystem implemented as a SQLite database. The entire filesystem — files, directories, metadata, and content — lives in a single portable `.sqlite` file that can be copied, versioned, and opened anywhere SQLite runs.
+
+It is designed for situations where you want filesystem semantics (paths, directories, streaming I/O) but need more control than a raw filesystem gives you: portable snapshots, at-rest encryption, content deduplication, and a clean programmatic API. A single file is easier to back up, replicate, and audit than a directory tree.
+
+**What it provides:**
+
+- A Python API for creating and navigating volumes, with full streaming read/write support validated against multi-gigabyte files
+- At-rest encryption per volume (ChaCha20-Poly1305, Argon2id key derivation), with the PIN accepted only at mount time and never stored
+- Content deduplication via a chunk pool — identical data stored once across all files in a volume
+- FUSE integration so any application can use an AloeLite volume as a plain directory, without modification
+- A container-ready volume manager that exposes volumes over HTTP and propagates FUSE mounts to other containers via bind mount — suitable as a lightweight Docker/Podman volume provisioner
+- Export and checkpoint endpoints that produce clean, self-contained SQLite snapshots while the volume remains mounted, enabling simple backup workflows without coordination
+
+**What it is not:** a general-purpose network filesystem, a database replacement, or a POSIX-complete block device. Random-access rewrites on large files fall back to a buffered path. Node metadata (paths, timestamps, directory structure) is stored in plaintext even on encrypted volumes — see [Security Notes](#security-notes).
+
+## Abstract
+
+This document specifies the design of a portable filesystem implemented on top of SQLite. The system models a filesystem as a small set of relational primitives (i.e. nodes, edges, volumes, and mounts) rather than as a fixed on-disk layout, deferring byte packing, page management, and durability to SQLite's mature storage engine. It is deliberately interface-agnostic: it presents a coherent internal model of files, directories, placement, and access without committing to any single external protocol, while remaining structurally amenable to exposing one (WebDAV, FUSE, or others) in the future. The design favors a hierarchical tree as its default arrangement but encodes that hierarchy as a relaxable constraint rather than a structural assumption, leaving a clear path toward a more general graph-shaped namespace. Supporting concerns (e.g. content storage, archival, and verifiable modification) are accommodated as first-class parts of the model even where their full implementation is staged for later.
+
+## Discussion
+
+The motivation for building on SQLite is portability and reach. A filesystem expressed as a SQLite database is a single, self-describing file that can be opened, moved, and inspected anywhere SQLite runs, which is nearly everywhere, and it inherits decades of work on storage layout and transactional integrity for free. The cost of that choice is that the filesystem's structure must be expressed relationally; the contribution of this design is a set of primitives that do so cleanly while keeping future capabilities reachable rather than precluded.
+
+The model separates four concerns that filesystems often conflate. A *node* is an identity: a file (Entry) or a directory (Container), bearing a stable time-ordered identifier and its own name. An *edge* is a placement: a directed, immutable relationship that situates a node beneath a container within a particular volume. A *volume* is an origin: the root to which a coherent tree of placements ultimately refers. A *mount* is an access context: a live, volume-bound session, anchored at a node, through which operation on the filesystem is brokered. Holding these four apart is what gives the design its flexibility. Because a node's name and existence are independent of where it sits, the same node can in principle be reachable from more than one place, which is the seam through which links, mounts, and an eventual graph layout enter without disturbing the core. Because placement lives in immutable edges, every structural change is expressed as the creation of a new edge rather than the mutation of an existing one, which keeps the history of where things have been available and gives later features (e.g. ordering, verification, recovery) a stable substrate to build on. Because origins are modeled explicitly rather than inferred, the boundary of a volume is a real, referenceable thing rather than a convention. And because access is brokered through mounts rather than ambient, the system has a concrete answer to a question filesystems usually answer with the operating system: who holds a handle, who holds a lock, and what to reclaim when a session ends.
+
+File contents are held apart from node metadata, so that traversing and resolving the namespace touches only small, frequently-accessed rows and never drags large payloads along. Reading and writing a whole file is an atomic operation in the ordinary case, with a streaming, descriptor-like access path for large or incremental I/O. That access path is mediated by mounts: because the filesystem has no native notion of a process, a mount stands in as the session identity that holds open handles and locks, and locks are scoped to the mount that acquired them, so that ending a session has a well-defined effect on everything it held. This advisory locking coexists with rather than commandeers SQLite's own transactional concurrency. Archival packs a subtree into a portable serialized form within the safety of a single transaction, so that the act of consolidating data cannot lose it. And the design reserves room for cryptographic verification of modification (e.g. a Merkle structure over the tree) by ensuring that mutations flow through a single, well-defined path where such bookkeeping can later be attached. None of these later-stage capabilities is fully realized in the first iteration; the purpose of the model described here is to make each of them an addition rather than a redesign.
+
+**Implementation Status**
+
+The core model — nodes, edges, volumes, and mounts — is fully realized, including path resolution, structural operations (create, move, rename, copy, remove, pack/unpack), advisory locking, and mount-scoped session management. File content is stored in a content-addressed chunk pool with deduplication, per-version manifests, configurable retention, and bounded-memory streaming I/O for both reads and writes; the streaming descriptor is production-validated against files in the tens of gigabytes. At-rest encryption is implemented at the storage boundary (ChaCha20-Poly1305, Argon2id key derivation, per-volume wrapped key), with convergent-nonce and random-nonce modes and a FUSE front-end that accepts a PIN at mount time. A container manager (`manager/`) exposes volumes as FUSE-mounted directories over a nine-endpoint HTTP API, suitable for use as a Docker/Podman volume provisioner. Reserved but not yet realized: cryptographic verification of the node tree (Merkle structure over content and placement), content-defined chunking, key rotation, graph-shaped namespaces beyond the default hierarchical tree, and node metadata encryption (currently plaintext in the SQLite schema — see [Security Notes](#security-notes)).
+
+---
+
+## Getting Started
+
+```
+pip install aloelite
+```
+
+For FUSE support (Linux only):
+
+```bash
+sudo apt install fuse3 libfuse3-dev
+pip install aloelite[fuse]
+```
+
+### Python API
+
+```python
+from aloelite.aloelite import AloeLite
+from aloelite.types import WriteMode, Whence
+
+with AloeLite("photos.sqlite") as fs:
+    vol = fs.create_volume("photos")
+
+    with fs.mount(vol.id) as m:
+        m.create_container("/2024")
+        m.set_metadata("/2024", {"year": "2024", "album": "trip"})
+        m.create_entry("/2024/caption.txt", b"a sunset")
+
+        with m.open_write("/note.txt") as w:
+            w.write(b"hello ")
+            w.write(b"world")
+
+        print(m.read_all("/note.txt"))   # -> b"hello world"
+
+        with m.open_read("/note.txt") as r:
+            head = r.read(5)
+            r.seek(-5, Whence.END)
+            tail = r.read()
+
+        m.rename("/note.txt", "readme.txt")
+        m.move("/readme.txt", "/2024/readme.txt")
+        m.copy("/2024", "/backup")
+        m.remove_recursive("/backup")
+
+    fs.prune()
+    print(fs.health_check())   # -> [] when consistent
+```
+
+### Encryption
+
+```python
+PIN = b"correct-horse-battery-staple"
+
+with AloeLite("vault.sqlite") as fs:
+    vol = fs.create_volume("vault", pin=PIN)   # Argon2id key derivation, ChaCha20-Poly1305
+
+    with fs.mount(vol.id, pin=PIN) as m:
+        m.create_entry("/secret.txt", b"eyes only")
+        print(m.read_all("/secret.txt"))   # -> b"eyes only"
+
+    # Wrong PIN is rejected at mount time (not at read time)
+    from aloelite import errors
+    try:
+        fs.mount(vol.id, pin=b"wrong")
+    except errors.BadKey:
+        print("wrong PIN rejected ✓")
+```
+
+Encryption is invisible at the `Mount` API level. Use `enc_mode="random"` to trade chunk deduplication for zero equality leakage.
+
+---
+
+## FUSE
+
+Mount an AloeLite volume as a regular directory (Linux, requires `fuse3`):
+
+```bash
+# Plain volume
+aloelite-fuse photos.sqlite photos /mnt/photos
+
+# Encrypted volume — three ways to supply the PIN
+aloelite-fuse vault.sqlite vault /mnt/vault --pin "my secret"
+aloelite-fuse vault.sqlite vault /mnt/vault --pin-file ~/.vaultpin
+aloelite-fuse vault.sqlite vault /mnt/vault --pin-env VAULT_PIN
+
+# Unmount
+fusermount3 -u /mnt/photos
+```
+
+The FUSE driver uses bounded-memory streaming I/O for both reads and writes — a 15 GB copy does not buffer in RAM. Sequential writes flush one chunk at a time; non-sequential access on large files falls back to a buffered path.
+
+---
+
+## Volume Manager
+
+The volume manager is a privileged container that manages multiple AloeLite volumes and exposes each as a FUSE-mounted subdirectory, accessible to other containers via bind mount.
+
+### Run
+
+```bash
+# Host directories (once)
+sudo mkdir -p /aloelite-root /mnt/aloelite
+
+docker run -d --privileged \
+  -v /aloelite-root:/aloelite-root \
+  -v /mnt/aloelite:/mnt:rshared \
+  --device /dev/fuse \
+  -p 8080:8080 \
+  aloecraft/aloelite-manager
+```
+
+`/aloelite-root` holds the backing SQLite files and persists across restarts. `/mnt/aloelite` is the host-visible mount root; FUSE mounts inside the container propagate here via `rshared`. `--privileged` (or at minimum `CAP_SYS_ADMIN`) is required.
+
+### API
+
+| Method | Path | Description |
+|---|---|---|
+| `POST` | `/volumes` | Create a volume |
+| `GET` | `/volumes` | List all volumes |
+| `DELETE` | `/volumes/<id>` | Delete a volume (unmounts first) |
+| `POST` | `/volumes/<id>/mount` | Mount a volume |
+| `DELETE` | `/volumes/<id>/mount` | Unmount a volume |
+| `GET` | `/volumes/<id>/mount` | Mount status |
+| `GET` | `/volumes/<id>/stat` | Backing file metadata (size, mtime) |
+| `GET` | `/volumes/<id>/export` | Checkpoint + stream the SQLite file |
+| `POST` | `/volumes/<id>/checkpoint` | Run `WAL_CHECKPOINT(TRUNCATE)` |
+
+```bash
+# Create and mount
+curl -s -X POST http://localhost:8080/volumes \
+  -H 'Content-Type: application/json' \
+  -d '{"name": "myphotos"}' | tee /tmp/vol.json
+
+VID=$(jq -r .id /tmp/vol.json)
+curl -s -X POST http://localhost:8080/volumes/$VID/mount \
+  -H 'Content-Type: application/json' -d '{}'
+
+# The volume is now a plain directory on the host
+ls /mnt/aloelite/$VID
+
+# Consume from another container
+docker run --rm -v /mnt/aloelite/$VID:/data alpine ls /data
+
+# Backup: poll stat, export on change
+curl -s http://localhost:8080/volumes/$VID/stat | jq
+curl -s http://localhost:8080/volumes/$VID/export -o snapshot.sqlite
+
+# Encrypted volume
+curl -s -X POST http://localhost:8080/volumes \
+  -H 'Content-Type: application/json' \
+  -d '{"name": "vault", "encrypted": true, "pin": "correct-horse"}'
+# Mount with: -d '{"pin": "correct-horse"}'
+```
+
+The export endpoint runs `WAL_CHECKPOINT(TRUNCATE)` before streaming, producing a complete self-contained SQLite file with no accompanying WAL. The volume does not need to be unmounted to export — SQLite's read consistency guarantees a coherent snapshot regardless of active writes.
+
+### Backup sync pattern
+
+```
+loop:
+    poll GET /volumes/<id>/stat
+    if mtime > last_known_mtime:
+        GET /volumes/<id>/export  →  write to temp file  →  rename into place
+        last_known_mtime = mtime
+    sleep(interval)
+```
+
+The rename into place is atomic; a failed export leaves the previous replica intact.
+
+---
+
+## Security Notes
+
+**Chunk data** is encrypted at the storage boundary (ChaCha20-Poly1305, Argon2id key derivation). The SQLite file is opaque without the PIN.
+
+**Node metadata** (paths, timestamps, node IDs, directory structure) is stored in plaintext in the SQLite schema. An observer with access to the file can read the filesystem tree even without the PIN. For sensitive deployments, place the backing file on an encrypted volume (LUKS, encrypted home directory, etc.) or use the `pack` primitive to seal a subtree before transport.
+
+The volume manager API is intended for trusted networks. PINs are transmitted in request bodies and never logged or persisted; the derived key is held only for the duration of the mount session.
+
+---
+
+## License
+
+Apache 2.0. See [LICENSE](LICENSE).

aloelite-0.1.0/aloelite/__init__.py

@@ -0,0 +1,99 @@
+# ./aloelite/__init__.py
+# License: Apache-2.0 (disclaimer at bottom of file)
+"""
+aloefs — Python reference implementation of the SQLite-backed Mount API.
+
+This is the oracle: the implementation the conformance suite is generated from
+and the other three (Rust, JS/WASM, Kotlin) are tested against. It drives the
+shared SQL templates (sql-templates.yaml) rather than hand-written SQL, so it
+stays a true reference for the template-driven implementations.
+
+Layering, bottom to top:
+    schema.sql                      (the SQL floor)
+    db.Db / Db.txn                  (connection, templates, transaction boundary)
+    resolve.resolve / resolve_parent (path -> id, the most-reused logic)
+    [function layer]                (flat Mount API — next session)
+    types / errors / models         (vocabulary, used throughout)
+"""
+
+from . import errors, operations
+from .db import Db, Templates
+from .descriptor import Descriptor
+from .models import (
+    Anomaly,
+    ContentPruneReport,
+    DirEntry,
+    LockInfo,
+    MountInfo,
+    NodeInfo,
+    PruneReport,
+    VolumeInfo,
+)
+from .resolve import Parent, Resolved, resolve, resolve_parent, split_path
+from .types import (
+    EdgeId,
+    FdId,
+    LockId,
+    LockMode,
+    MountId,
+    MountState,
+    NodeId,
+    NodeType,
+    Path,
+    Timestamp,
+    VolumeId,
+    Whence,
+    WriteMode,
+)
+
+__all__ = [
+    # scaffolding
+    "Db",
+    "Templates",
+    # resolve
+    "resolve",
+    "resolve_parent",
+    "split_path",
+    "Resolved",
+    "Parent",
+    # models
+    "VolumeInfo",
+    "NodeInfo",
+    "DirEntry",
+    "MountInfo",
+    "LockInfo",
+    "Anomaly",
+    "PruneReport",
+    "ContentPruneReport",
+    # types
+    "NodeId",
+    "EdgeId",
+    "VolumeId",
+    "MountId",
+    "LockId",
+    "FdId",
+    "Path",
+    "Timestamp",
+    "NodeType",
+    "MountState",
+    "Whence",
+    "WriteMode",
+    "LockMode",
+    # errors module
+    "errors",
+    "operations",
+    "Descriptor",
+]
+# Copyright Michael Godfrey 2026 | aloecraft.org <michael@aloecraft.org>
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.

aloelite-0.1.0/aloelite/aloelite.py

@@ -0,0 +1,237 @@
+# ./aloelite/aloelite.py
+# License: Apache-2.0 (disclaimer at bottom of file)
+"""
+AloeLite — the ergonomic, Pythonic wrapper.
+
+This is the ONLY layer that is allowed object state and sugar. It sits on top of
+the flat function layer (operations.py) and adds nothing to the contract — the
+other three implementations will each grow their own idiomatic wrapper over the
+same operations. Two objects, each owning a resource as a context manager:
+
+  AloeLite  — owns the file / connection (the transient physical attachment).
+              `with AloeLite(path) as fs:` opens it; exit closes the connection.
+              Note a mount is a ROW, not this connection: the connection is
+              disposable, the mount id outlives it.
+
+  Mount     — a handle bound to one mount id. `with fs.mount(vol) as m:` opens a
+              session; exit unmounts it. Every method forwards to operations.*
+              with the mount id already bound, so callers write m.list("/")
+              instead of operations.list(db, mount_id, "/").
+
+The streaming descriptor returned by m.open_read/open_write is itself a context
+manager (its own concern: the lock lifecycle), so it composes:
+    with fs.mount(vol) as m:
+        with m.open_write("/f") as w:
+            w.write(b"...")
+"""
+
+from __future__ import annotations
+
+import builtins
+from pathlib import Path as _FsPath
+from typing import Iterator
+
+from . import operations as ops
+from .db import Db
+from .descriptor import Descriptor
+from .models import (
+    ContentPruneReport,
+    DirEntry,
+    MountInfo,
+    NodeInfo,
+    PruneReport,
+    VolumeInfo,
+)
+from .types import MountId, NodeId, VolumeId, WriteMode
+
+# Default spec locations, resolved relative to this package. Override per call.
+_PKG = _FsPath(__file__).resolve().parent
+_DEFAULT_TEMPLATES = _PKG / "../config/sql-templates.yaml"
+_DEFAULT_SCHEMA = _PKG / "../sql/schema.sql"
+
+
+class AloeLite:
+    """A handle to an AloeLite filesystem file (owns the connection)."""
+
+    def __init__(
+        self,
+        path: str | _FsPath = ":memory:",
+        *,
+        templates_path: str | _FsPath = _DEFAULT_TEMPLATES,
+        schema_path: str | _FsPath | None = _DEFAULT_SCHEMA,
+        ensure_schema: bool = True,
+    ) -> None:
+        # The schema is idempotent (CREATE ... IF NOT EXISTS), so applying it on
+        # open is safe for both new and existing files.
+        self._db = Db.open(
+            path,
+            templates_path,
+            schema_path=schema_path if ensure_schema else None,
+        )
+
+    # -- connection lifecycle (this object's context manager) ----------------
+    def __enter__(self) -> "AloeLite":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._db.close()
+
+    @property
+    def db(self) -> Db:
+        """Escape hatch to the connection wrapper (for advanced/raw use)."""
+        return self._db
+
+    # -- volumes -------------------------------------------------------------
+    def create_volume(
+        self,
+        name: str | None = None,
+        chunk_size: int = 1048576,
+        pin: bytes | None = None,
+        *,
+        enc_mode: str = "convergent",
+    ) -> VolumeInfo:
+        return ops.create_volume(self._db, name, chunk_size, pin, enc_mode=enc_mode)
+
+    def list_volumes(self) -> builtins.list[VolumeInfo]:
+        return ops.list_volumes(self._db)
+
+    # -- mounts --------------------------------------------------------------
+    def mount(
+        self,
+        volume: VolumeId,
+        at: str = "/",
+        ttl_ms: int | None = None,
+        pin: bytes | None = None,
+    ) -> "Mount":
+        mid = ops.mount(self._db, volume, at, ttl_ms, pin)
+        sess = self._db.active_session
+        token = sess["token"] if sess and sess.get("mount_id") == mid else None
+        return Mount(self._db, mid, token=token)
+
+    def attach(self, mount: MountId) -> "Mount":
+        """Re-attach to an existing mount row (e.g. one created elsewhere and
+        resumed on this connection). The mount is validated lazily, per op."""
+        return Mount(self._db, mount)
+
+    # -- maintenance ---------------------------------------------------------
+    def prune(self, volume: VolumeId | None = None) -> PruneReport:
+        return ops.prune(self._db, volume)
+
+    def prune_content(self, volume: VolumeId | None = None) -> ContentPruneReport:
+        return ops.prune_content(self._db, volume)
+
+    def health_check(self) -> builtins.list:
+        return ops.health_check(self._db)
+
+
+class Mount:
+    """A bound mount/session handle. Context manager: exit unmounts."""
+
+    def __init__(
+        self, db: Db, mount_id: MountId, *, token: bytes | None = None
+    ) -> None:
+        self._db = db
+        self.id = mount_id
+        # The per-mount token (encrypted volumes only); None when unencrypted.
+        # Runtime-only handle that, with N_m, stands in for the PIN this session.
+        self.token = token
+
+    # -- the mount's context manager (session lifecycle) ---------------------
+    def __enter__(self) -> "Mount":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.unmount()
+
+    def unmount(self) -> None:
+        ops.unmount(self._db, self.id)
+
+    def info(self) -> MountInfo:
+        return ops.mount_info(self._db, self.id)
+
+    def renew(self, ttl_ms: int | None = None) -> MountInfo:
+        return ops.renew_mount(self._db, self.id, ttl_ms)
+
+    # -- read ----------------------------------------------------------------
+    def stat(self, path: str) -> NodeInfo:
+        return ops.stat(self._db, self.id, path)
+
+    def stat_by_id(self, node: NodeId) -> NodeInfo:
+        return ops.stat_by_id(self._db, self.id, node)
+
+    def exists(self, path: str) -> bool:
+        return ops.exists(self._db, self.id, path)
+
+    def list(self, path: str = "/") -> builtins.list[DirEntry]:
+        return ops.list(self._db, self.id, path)
+
+    def read_all(self, path: str) -> bytes:
+        return ops.read_all(self._db, self.id, path)
+
+    def path_of(self, node: NodeId) -> str:
+        return ops.path_of(self._db, self.id, node)
+
+    # -- structural ----------------------------------------------------------
+    def create_container(self, path: str) -> NodeId:
+        return ops.create_container(self._db, self.id, path)
+
+    def create_entry(self, path: str, data: bytes | None = None) -> NodeId:
+        return ops.create_entry(self._db, self.id, path, data)
+
+    def write_all(self, path: str, data: bytes) -> None:
+        ops.write_all(self._db, self.id, path, data)
+
+    def rename(self, path: str, name: str) -> None:
+        ops.rename(self._db, self.id, path, name)
+
+    def set_metadata(self, path: str, metadata: dict[str, str]) -> None:
+        ops.set_metadata(self._db, self.id, path, metadata)
+
+    def set_retention(self, path: str, keep: int | None) -> None:
+        ops.set_retention(self._db, self.id, path, keep)
+
+    def move(self, src: str, dst: str) -> None:
+        ops.move(self._db, self.id, src, dst)
+
+    def remove(self, path: str) -> None:
+        ops.remove(self._db, self.id, path)
+
+    def remove_recursive(self, path: str) -> None:
+        ops.remove_recursive(self._db, self.id, path)
+
+    def copy(self, src: str, dst: str) -> NodeId:
+        return ops.copy(self._db, self.id, src, dst)
+
+    def pack(self, path: str) -> NodeId:
+        return ops.pack(self._db, self.id, path)
+
+    def unpack(self, path: str) -> None:
+        ops.unpack(self._db, self.id, path)
+
+    # -- streaming -----------------------------------------------------------
+    def open_read(self, path: str) -> Descriptor:
+        return ops.open_read(self._db, self.id, path)
+
+    def open_write(self, path: str, mode: WriteMode = WriteMode.TRUNCATE) -> Descriptor:
+        if not self.exists(path) and mode is not WriteMode.APPEND:
+            ops.create_entry(self._db, self.id, path)
+        return ops.open_write(self._db, self.id, path, mode)
+
+
+__all__ = ["AloeLite", "Mount"]
+# Copyright Michael Godfrey 2026 | aloecraft.org <michael@aloecraft.org>
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.