lodedb 1.3.1__tar.gz → 2.0.0__tar.gz

{lodedb-1.3.1 → lodedb-2.0.0}/Cargo.toml

@@ -1,15 +1,17 @@
 [workspace]
 members = [
+  "crates/lodedb-cloud-core",
   "crates/lodedb-core",
   "crates/lodedb-ffi",
   "crates/lodedb-gpu",
+  "crates/lodedb-graph",
 ]
 resolver = "2"
 
 [workspace.package]
-version = "1.3.0"
+version = "2.0.0"
 edition = "2021"
-rust-version = "1.70"
+rust-version = "1.88"
 license = "Apache-2.0"
 repository = "https://github.com/Egoist-Machines/LodeDB"
 

{lodedb-1.3.1 → lodedb-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lodedb
-Version: 1.3.1
+Version: 2.0.0
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3 :: Only
@@ -10,6 +10,9 @@ Requires-Dist: numpy>=2.0.0,<3
 Requires-Dist: typer>=0.12.0
 Requires-Dist: pyyaml>=6.0.0
 Requires-Dist: lodedb[embeddings,torch,image,mcp,langchain,llama-index,mem0] ; extra == 'all'
+Requires-Dist: httpx>=0.27 ; extra == 'cloud'
+Requires-Dist: pynacl>=1.5 ; extra == 'cloud'
+Requires-Dist: cryptography>=47 ; extra == 'cloud-sealed'
 Requires-Dist: cognee>=1.1.0,<2 ; python_full_version < '3.15' and extra == 'cognee'
 Requires-Dist: pytest>=8.3.0 ; extra == 'dev'
 Requires-Dist: ruff==0.15.17 ; extra == 'dev'
@@ -25,6 +28,8 @@ Requires-Dist: mem0ai>=2.0.0 ; extra == 'mem0'
 Requires-Dist: optimum[exporters]>=1.23.0,<2.0.0 ; extra == 'onnx-export'
 Requires-Dist: sentence-transformers>=3.0.0,<5 ; extra == 'torch'
 Provides-Extra: all
+Provides-Extra: cloud
+Provides-Extra: cloud-sealed
 Provides-Extra: cognee
 Provides-Extra: dev
 Provides-Extra: embeddings
@@ -388,6 +393,42 @@ db.search("turbine fault", k=5)                                 # nearest cluste
 `ann_clusters` (partitions) defaults to about `sqrt(n)` and `ann_nprobe` (clusters probed per
 query) to about `sqrt(clusters)`. ANN is a create-time choice persisted with the index and works
 for text and bring-your-own-vector indexes alike; keep the exact default for small-to-mid corpora.
+On reopen, `ann_nprobe` is a session-only override, so benchmark handles can change probe breadth
+without rebuilding; the algorithm and partition count remain the persisted configuration.
+
+For large corpora, these are useful starting ranges to measure, not recall or latency promises:
+
+| Knob | Useful range | Trade-off |
+| --- | --- | --- |
+| `ann_nprobe` | 64 to 256 clusters | More probes raise recall and scan work; probing every cluster is exact. |
+| `rescore_oversample` | 2 to 8 times `k` | More candidates improve the chance that fp32 re-ranking repairs compact-code errors, at more sidecar reads. |
+</details>
+
+<details>
+<summary><b>Two-stage rescore (`rescore="original"`)</b></summary>
+
+TurboVec's compact 4-bit scan is fast, but its quantized first-stage ranking can put close
+neighbors in the wrong order. Enable rescore at creation to retain each input vector in a separate
+original-precision sidecar, then re-score the first-stage candidate pool with fp32 dot products:
+
+```python
+db = LodeDB(
+    path="./data",
+    ann="cluster",
+    ann_clusters=1024,
+    rescore="original",
+    rescore_dtype="float16",      # default; about 2 bytes per dimension per vector
+    rescore_oversample=4,
+)
+```
+
+`float16` sidecars add about 2 bytes per dimension per vector (`float32` adds 4; `int8` adds 1).
+They let the final ordering rise above the practical 4-bit ranking ceiling while retaining the
+compact index for candidate generation. Re-scored candidate scores are exact fp32 dots, but the
+overall result can still be approximate when ANN or a too-small candidate pool excludes a true
+neighbor. Rescore is a create-time capture choice: originals are not recoverable after a normal
+store's first ingest, so enabling it later requires a rebuild. On a rescore-enabled reopen,
+`rescore_oversample` is a session-only override; mode and dtype must match the persisted sidecar.
 </details>
 
 ## Multimodal & bring-your-own vectors
@@ -537,6 +578,9 @@ lodedb mcp         # stdio MCP server for agent memory
 lodedb benchmark   # local, metrics-only benchmark
 ```
 
+Use `lodedb serve` as a local OpenAI-compatible embeddings provider; see [LodeDB as a local
+embeddings provider](docs/integrations.md#lodedb-as-a-local-embeddings-provider).
+
 ## Use as an MCP server
 
 LodeDB ships a [Model Context Protocol](https://modelcontextprotocol.io) server, so an agent
@@ -617,6 +661,86 @@ See [`examples/mcp_config.json`](examples/mcp_config.json) for a copy-paste star
 
 </details>
 
+## Managed cloud (OreCloud)
+
+LodeDB stores can live in [OreCloud](https://db.egoistmachines.com), the managed-cloud
+companion: durable sync for local stores, hosted read serving, and a per-user memory
+data plane for agent applications. The client ships as the `[cloud]` extra:
+
+```sh
+pip install "lodedb[cloud]"
+
+lodedb cloud login                        # one browser approval
+lodedb cloud init ./my-store              # link the directory to a managed remote
+lodedb cloud keys ./my-store              # list the directory's index keys
+lodedb cloud sync ./my-store cloud <key>  # mirror the local store to the cloud
+```
+
+A cloud store opens through the same class as a local one, via the
+`LodeDB.cloud` alternate constructor:
+
+```python
+from lodedb import LodeDB
+
+db = LodeDB("./notes")          # local, as always
+db = LodeDB.cloud("user-42")    # managed cloud, same verbs
+db.add("the quick brown fox")   # embedded server-side
+db.search("fox", k=5)
+```
+
+A bare store id is enough. The org/environment half resolves from the
+credential (`token=`, the `ORECLOUD_TOKEN` environment variable, or
+`lodedb cloud login`); pass the full `"org/environment/store"` triple in
+cross-environment scripts. For config-driven code, where one string field (an
+env var, a YAML value) must express either a local path or a cloud store, the
+plain constructor accepts the explicit URL form
+`LodeDB("orecloud://org/environment/store")` and returns the same handle.
+An application serving many end users should hold one `Client` and open
+per-user handles from it (`Client().store(user_id)`); the credential resolves
+once and the handles share one HTTP pool. `from lodedb.cloud import Client`
+works as the import root.
+
+Work locally with `lodedb` exactly as before. The client is first-party code
+in this package (`lodedb.cloud` and the `lodedb cloud` CLI), and push/pull/
+sync run on the same bundled native core as the engine. The extra installs
+only its dependencies (`httpx`, `pynacl`). Everything cloud loads lazily, so
+a plain `import lodedb` stays network-free.
+
+### Sealed stores
+
+OreCloud can host a server-side encrypted store whose 32-byte wrapping key
+remains with your application. Install the additional lazy crypto support,
+keep that material outside source control, and keep a recovery copy: losing
+it makes the store unreadable and the service never persists it.
+
+```sh
+pip install "lodedb[cloud,cloud-sealed]"
+```
+
+```python
+import secrets
+
+from lodedb.cloud import Client
+
+material = secrets.token_bytes(32)
+client = Client()
+client.create_store(
+    "user-42",
+    encrypted=True,
+    key_material=material,
+    mode="cloud_writer",
+    preset="minilm",
+)
+expires_at = client.unseal_store("user-42", material, ttl_seconds=900)
+# Query or write while the grant is live, then remove it when finished.
+client.reseal_store("user-42")
+```
+
+`Client.rotate_store_key("user-42", fresh_material)` replaces the caller-held
+material after the store is unsealed. A sealed data-plane read returns
+`CloudError` with status 423 and a `store_sealed:` detail; applications decide
+when to request an unseal grant.
+
 ## Concurrency & durability
 
 - **Single writer, many readers, per path.** One handle holds the path open for *writing* at
@@ -660,7 +784,7 @@ See [`examples/mcp_config.json`](examples/mcp_config.json) for a copy-paste star
   read-your-writes against an append's returned LSN). On Windows the shared lock degrades to an
   exclusive hold, so appenders serialize there rather than coexisting. A record is a precomputed
   vector plus metadata (with an optional caption, e.g. for an image, retained only when the appender
-  opts into `store_text` -- off by default, so no raw text reaches the WAL); with an embedder
+  opts into `store_text`; it is off by default, so no raw text reaches the WAL); with an embedder
   configured, the appender also ingests full text (chunked by the core, embedded in the binding
   layer, then logged as a post-embedding record) so text writes are multi-producer too, without a
   captured base generation. It requires WAL commit mode. Exposed as the native `CoreAppender`, over

{lodedb-1.3.1 → lodedb-2.0.0}/README.md

@@ -337,6 +337,42 @@ db.search("turbine fault", k=5)                                 # nearest cluste
 `ann_clusters` (partitions) defaults to about `sqrt(n)` and `ann_nprobe` (clusters probed per
 query) to about `sqrt(clusters)`. ANN is a create-time choice persisted with the index and works
 for text and bring-your-own-vector indexes alike; keep the exact default for small-to-mid corpora.
+On reopen, `ann_nprobe` is a session-only override, so benchmark handles can change probe breadth
+without rebuilding; the algorithm and partition count remain the persisted configuration.
+
+For large corpora, these are useful starting ranges to measure, not recall or latency promises:
+
+| Knob | Useful range | Trade-off |
+| --- | --- | --- |
+| `ann_nprobe` | 64 to 256 clusters | More probes raise recall and scan work; probing every cluster is exact. |
+| `rescore_oversample` | 2 to 8 times `k` | More candidates improve the chance that fp32 re-ranking repairs compact-code errors, at more sidecar reads. |
+</details>
+
+<details>
+<summary><b>Two-stage rescore (`rescore="original"`)</b></summary>
+
+TurboVec's compact 4-bit scan is fast, but its quantized first-stage ranking can put close
+neighbors in the wrong order. Enable rescore at creation to retain each input vector in a separate
+original-precision sidecar, then re-score the first-stage candidate pool with fp32 dot products:
+
+```python
+db = LodeDB(
+    path="./data",
+    ann="cluster",
+    ann_clusters=1024,
+    rescore="original",
+    rescore_dtype="float16",      # default; about 2 bytes per dimension per vector
+    rescore_oversample=4,
+)
+```
+
+`float16` sidecars add about 2 bytes per dimension per vector (`float32` adds 4; `int8` adds 1).
+They let the final ordering rise above the practical 4-bit ranking ceiling while retaining the
+compact index for candidate generation. Re-scored candidate scores are exact fp32 dots, but the
+overall result can still be approximate when ANN or a too-small candidate pool excludes a true
+neighbor. Rescore is a create-time capture choice: originals are not recoverable after a normal
+store's first ingest, so enabling it later requires a rebuild. On a rescore-enabled reopen,
+`rescore_oversample` is a session-only override; mode and dtype must match the persisted sidecar.
 </details>
 
 ## Multimodal & bring-your-own vectors
@@ -486,6 +522,9 @@ lodedb mcp         # stdio MCP server for agent memory
 lodedb benchmark   # local, metrics-only benchmark
 ```
 
+Use `lodedb serve` as a local OpenAI-compatible embeddings provider; see [LodeDB as a local
+embeddings provider](docs/integrations.md#lodedb-as-a-local-embeddings-provider).
+
 ## Use as an MCP server
 
 LodeDB ships a [Model Context Protocol](https://modelcontextprotocol.io) server, so an agent
@@ -566,6 +605,86 @@ See [`examples/mcp_config.json`](examples/mcp_config.json) for a copy-paste star
 
 </details>
 
+## Managed cloud (OreCloud)
+
+LodeDB stores can live in [OreCloud](https://db.egoistmachines.com), the managed-cloud
+companion: durable sync for local stores, hosted read serving, and a per-user memory
+data plane for agent applications. The client ships as the `[cloud]` extra:
+
+```sh
+pip install "lodedb[cloud]"
+
+lodedb cloud login                        # one browser approval
+lodedb cloud init ./my-store              # link the directory to a managed remote
+lodedb cloud keys ./my-store              # list the directory's index keys
+lodedb cloud sync ./my-store cloud <key>  # mirror the local store to the cloud
+```
+
+A cloud store opens through the same class as a local one, via the
+`LodeDB.cloud` alternate constructor:
+
+```python
+from lodedb import LodeDB
+
+db = LodeDB("./notes")          # local, as always
+db = LodeDB.cloud("user-42")    # managed cloud, same verbs
+db.add("the quick brown fox")   # embedded server-side
+db.search("fox", k=5)
+```
+
+A bare store id is enough. The org/environment half resolves from the
+credential (`token=`, the `ORECLOUD_TOKEN` environment variable, or
+`lodedb cloud login`); pass the full `"org/environment/store"` triple in
+cross-environment scripts. For config-driven code, where one string field (an
+env var, a YAML value) must express either a local path or a cloud store, the
+plain constructor accepts the explicit URL form
+`LodeDB("orecloud://org/environment/store")` and returns the same handle.
+An application serving many end users should hold one `Client` and open
+per-user handles from it (`Client().store(user_id)`); the credential resolves
+once and the handles share one HTTP pool. `from lodedb.cloud import Client`
+works as the import root.
+
+Work locally with `lodedb` exactly as before. The client is first-party code
+in this package (`lodedb.cloud` and the `lodedb cloud` CLI), and push/pull/
+sync run on the same bundled native core as the engine. The extra installs
+only its dependencies (`httpx`, `pynacl`). Everything cloud loads lazily, so
+a plain `import lodedb` stays network-free.
+
+### Sealed stores
+
+OreCloud can host a server-side encrypted store whose 32-byte wrapping key
+remains with your application. Install the additional lazy crypto support,
+keep that material outside source control, and keep a recovery copy: losing
+it makes the store unreadable and the service never persists it.
+
+```sh
+pip install "lodedb[cloud,cloud-sealed]"
+```
+
+```python
+import secrets
+
+from lodedb.cloud import Client
+
+material = secrets.token_bytes(32)
+client = Client()
+client.create_store(
+    "user-42",
+    encrypted=True,
+    key_material=material,
+    mode="cloud_writer",
+    preset="minilm",
+)
+expires_at = client.unseal_store("user-42", material, ttl_seconds=900)
+# Query or write while the grant is live, then remove it when finished.
+client.reseal_store("user-42")
+```
+
+`Client.rotate_store_key("user-42", fresh_material)` replaces the caller-held
+material after the store is unsealed. A sealed data-plane read returns
+`CloudError` with status 423 and a `store_sealed:` detail; applications decide
+when to request an unseal grant.
+
 ## Concurrency & durability
 
 - **Single writer, many readers, per path.** One handle holds the path open for *writing* at
@@ -609,7 +728,7 @@ See [`examples/mcp_config.json`](examples/mcp_config.json) for a copy-paste star
   read-your-writes against an append's returned LSN). On Windows the shared lock degrades to an
   exclusive hold, so appenders serialize there rather than coexisting. A record is a precomputed
   vector plus metadata (with an optional caption, e.g. for an image, retained only when the appender
-  opts into `store_text` -- off by default, so no raw text reaches the WAL); with an embedder
+  opts into `store_text`; it is off by default, so no raw text reaches the WAL); with an embedder
   configured, the appender also ingests full text (chunked by the core, embedded in the binding
   layer, then logged as a post-embedding record) so text writes are multi-producer too, without a
   captured base generation. It requires WAL commit mode. Exposed as the native `CoreAppender`, over

lodedb-2.0.0/crates/lodedb-cloud-core/Cargo.toml

@@ -0,0 +1,41 @@
+[package]
+name = "lodedb-cloud-core"
+description = "Native transfer core for the LodeDB managed cloud — durable push/pull/sync over the open commit format."
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+repository.workspace = true
+publish = false
+
+[dependencies]
+# The engine core. The cloud transfer plane links its `storage` module directly
+# so the managed cloud and the embedded product share ONE commit-format
+# implementation (schema, layout, checksum, sub-manifests incl. `tvmv`). A path
+# dep now that both live in this workspace — engine changes and the transfer
+# plane move together under one suite.
+lodedb-core = { path = "../lodedb-core" }
+# Object-storage backend (S3/GCS/Azure) behind the same ArtifactStore trait. The
+# `aws` feature adds the S3 builder; the crate's conditional-put API (Create /
+# Update{e_tag}) is what makes the root-pointer compare-and-swap strongly
+# consistent on object storage. Its InMemory backend also drives the tests.
+object_store = { version = "0.12.5", features = ["aws"] }
+serde_json = "1.0"
+sha2 = "0.10"
+# Streaming transfer plumbing: `bytes` for the object-store chunk type and
+# `futures` for driving its download streams chunk-by-chunk from the sync
+# ArtifactStore surface. Both are already in the tree via object_store.
+bytes = "1"
+futures = "0.3"
+# The object_store backends are async; the runtime is enabled with net + time so a
+# real S3 client works (not just the in-memory test backend). ObjectArtifactStore
+# keeps the sync ArtifactStore trait by owning a current-thread runtime.
+tokio = { version = "1.47.5", default-features = false, features = ["rt", "net", "time"] }
+# The pointer serialize/validate round-trip reuses lodedb-core's own
+# write/read_commit_manifest (which operate on file paths) via a scratch file, so
+# object-store pointer documents are byte-identical to on-disk ones. Also used by
+# the test fixtures to build committed generations in throwaway directories.
+tempfile = "3"
+
+[lints]
+workspace = true

lodedb-2.0.0/crates/lodedb-cloud-core/src/artifact_store.rs

@@ -0,0 +1,127 @@
+//! Storage abstraction for committed, generation-addressed artifacts.
+//!
+//! The substrate is the engine's existing on-disk layout: a committed generation
+//! is a set of immutable, sha256-addressed `g<epoch>.*` artifacts under
+//! `<key>.gen/` pinned by an atomic `<key>.commit.json` root pointer. An
+//! [`ArtifactStore`] exposes exactly the operations that layout needs:
+//!
+//! - **names** are store-relative paths mirroring the on-disk layout, e.g.
+//!   `idx.gen/g7.json` or `idx.gen/g7.json.json-delta/delta-00000000.jsd`;
+//! - the **pointer key** is the index key (`idx` -> `idx.commit.json`).
+//!
+//! Implementations treat content artifacts as immutable and content-addressed
+//! (written once, never overwritten), and commit a generation *only* by swapping
+//! the root pointer. [`LocalArtifactStore`](crate::LocalArtifactStore) is the
+//! default; object-storage backends (S3/GCS/Azure) land in later milestones with
+//! the artifact names becoming object keys under a per-tenant prefix and the
+//! pointer swap becoming a conditional write.
+
+use crate::error::Result;
+use serde_json::Value;
+use std::io::Read;
+
+/// Reads/writes immutable artifacts and swaps a root pointer atomically.
+///
+/// The interface is deliberately small: streaming artifact I/O plus a pointer
+/// compare-and-swap. That is everything the generation-addressed commit format
+/// needs as a cloud substrate. Streaming is the primitive. Vector bases run
+/// to gigabytes, so a transfer's peak memory must be a fixed buffer, never a
+/// function of artifact size; the buffered methods are conveniences for the
+/// small payloads (pointer documents) built on top.
+pub trait ArtifactStore {
+    /// Opens one artifact for streaming reads;
+    /// [`ArtifactStoreError::NotFound`] if the name is absent.
+    ///
+    /// [`ArtifactStoreError::NotFound`]: crate::ArtifactStoreError::NotFound
+    fn open_read<'a>(&'a self, name: &str) -> Result<Box<dyn Read + 'a>>;
+
+    /// Returns one artifact's bytes, fully buffered, for small payloads
+    /// only; transfers and verification stream via [`open_read`](Self::open_read).
+    fn read_bytes(&self, name: &str) -> Result<Vec<u8>> {
+        let mut data = Vec::new();
+        self.open_read(name)?.read_to_end(&mut data)?;
+        Ok(data)
+    }
+
+    /// Streams one immutable artifact into the store unless it already
+    /// exists, hashing incrementally as it copies.
+    ///
+    /// `sha256` is the expected lowercase-hex digest of the streamed bytes; a
+    /// mismatch is an integrity error and nothing is stored, so corruption can
+    /// never land, even when the source is another store's live stream. A
+    /// name already present with identical bytes is a no-op (idempotent
+    /// re-push); present with *different* bytes is a conflict. Artifacts are
+    /// immutable and are never overwritten in place. On the already-present
+    /// no-op path the incoming stream may be left partially (or wholly)
+    /// unread and unvalidated: success then attests that the STORED bytes
+    /// match `sha256`, not that the stream did.
+    ///
+    /// `size_hint` is the expected byte count (0 = unknown), advisory only:
+    /// backends use it to pick an upload strategy (the object store's
+    /// conditional-claim path has a provider copy-size ceiling), never to
+    /// trust the stream's length. Transfers pass the manifest-recorded size.
+    fn write_stream_if_absent(
+        &self,
+        name: &str,
+        data: &mut dyn Read,
+        sha256: &str,
+        size_hint: u64,
+    ) -> Result<()>;
+
+    /// Buffered convenience over
+    /// [`write_stream_if_absent`](Self::write_stream_if_absent), for small
+    /// payloads a caller already holds in memory.
+    fn write_bytes_if_absent(&self, name: &str, data: &[u8], sha256: &str) -> Result<()> {
+        let mut cursor = data;
+        self.write_stream_if_absent(name, &mut cursor, sha256, data.len() as u64)
+    }
+
+    /// Whether an artifact named `name` is present, without asserting anything
+    /// about its content.
+    ///
+    /// The default opens the artifact and maps
+    /// [`NotFound`](crate::ArtifactStoreError::NotFound) to `false`; backends
+    /// with a cheap existence primitive (a filesystem stat, an object-store
+    /// HEAD) should override it to avoid opening a stream.
+    fn contains(&self, name: &str) -> Result<bool> {
+        match self.open_read(name) {
+            Ok(_) => Ok(true),
+            Err(crate::ArtifactStoreError::NotFound(_)) => Ok(false),
+            Err(error) => Err(error),
+        }
+    }
+
+    /// Returns the committed root-manifest body for `key`, or `None`.
+    ///
+    /// The body carries the generation number, the base epoch, counts, and the
+    /// per-store sub-manifests that name every artifact in the generation. It is
+    /// the read side that [`compare_and_swap_pointer`](Self::compare_and_swap_pointer)
+    /// and the inventory helpers need to learn the currently-committed generation.
+    fn read_pointer(&self, key: &str) -> Result<Option<Value>>;
+
+    /// Publishes `new_body` as the root pointer iff the currently committed body is
+    /// exactly `old_body` (`None` means the pointer must not yet exist); otherwise
+    /// [`ArtifactStoreError::PointerConflict`]. This swap is the only commit point:
+    /// artifacts are published first, then the pointer flips all-or-nothing.
+    ///
+    /// The precondition is the full committed body, not just its generation number.
+    /// A generation number is not a unique version token (two independent lineages
+    /// can share one with different content), so comparing the whole body is what
+    /// makes this a sound compare-and-swap rather than an ABA-prone check.
+    ///
+    /// [`ArtifactStoreError::PointerConflict`]: crate::ArtifactStoreError::PointerConflict
+    fn compare_and_swap_pointer(
+        &self,
+        key: &str,
+        old_body: Option<&Value>,
+        new_body: &Value,
+    ) -> Result<()>;
+}
+
+/// The generation number recorded in a committed body, if present.
+///
+/// Used only to annotate a [`PointerConflict`](crate::ArtifactStoreError::PointerConflict)
+/// for readability; the swap precondition is the full body, not this number.
+pub(crate) fn body_generation(body: &Value) -> Option<u64> {
+    body.get("generation").and_then(Value::as_u64)
+}

lodedb-2.0.0/crates/lodedb-cloud-core/src/blob_layout.rs

@@ -0,0 +1,119 @@
+//! Content-addressed blob naming for the managed remote layout.
+//!
+//! A managed remote can store artifacts content-addressed
+//! (`blobs/sha256/aa/<sha256>` under a per-tenant prefix) instead of under
+//! their engine path names. Content addressing is what absorbs the
+//! fork-collision case (two branches committing different artifacts under the
+//! same engine name, e.g. `idx.gen/g7.json`, coexist as two blobs), and the
+//! two-level `aa/` fan-out keeps listings and prefix operations tractable.
+//!
+//! These helpers are pure and tested; they pin the naming contract the
+//! transfer plane builds on. The digest is always the lowercase-hex
+//! SHA-256 of the blob's bytes, the same digest the engine records per
+//! artifact and [`ArtifactStore::write_bytes_if_absent`] verifies.
+//!
+//! [`ArtifactStore::write_bytes_if_absent`]: crate::ArtifactStore::write_bytes_if_absent
+
+use crate::error::{ArtifactStoreError, Result};
+
+/// The fixed prefix every blob name lives under.
+const BLOB_PREFIX: &str = "blobs/sha256";
+
+/// Returns the store-relative blob name for a content digest:
+/// `blobs/sha256/aa/<sha256>`, where `aa` is the digest's first two hex chars.
+///
+/// Rejects anything that is not exactly 64 lowercase hex characters. Blob
+/// names participate in authorization paths, so a malformed digest must fail
+/// closed rather than mint a name outside the contract.
+pub fn blob_name(sha256: &str) -> Result<String> {
+    validate_sha256(sha256)?;
+    Ok(format!("{BLOB_PREFIX}/{}/{sha256}", &sha256[..2]))
+}
+
+/// Parses a blob name back to its content digest, the exact inverse of
+/// [`blob_name`]. Rejects any name that deviates from the contract (wrong
+/// prefix, fan-out directory disagreeing with the digest, malformed digest).
+pub fn parse_blob_name(name: &str) -> Result<String> {
+    let malformed = || {
+        ArtifactStoreError::Integrity(format!(
+            "blob name {name:?} does not match {BLOB_PREFIX}/aa/<sha256>"
+        ))
+    };
+    let rest = name.strip_prefix(BLOB_PREFIX).ok_or_else(malformed)?;
+    let rest = rest.strip_prefix('/').ok_or_else(malformed)?;
+    let (fan_out, sha256) = rest.split_once('/').ok_or_else(malformed)?;
+    validate_sha256(sha256).map_err(|_| malformed())?;
+    if fan_out != &sha256[..2] {
+        return Err(malformed());
+    }
+    Ok(sha256.to_string())
+}
+
+/// Requires exactly 64 lowercase hex characters. Also used by the generation
+/// inventory to validate every manifest digest at the trust boundary: digests
+/// become staging file names and object keys, so a non-hex "digest" must fail
+/// closed before it can name a path.
+pub(crate) fn validate_sha256(sha256: &str) -> Result<()> {
+    let valid = sha256.len() == 64
+        && sha256
+            .bytes()
+            .all(|byte| byte.is_ascii_digit() || (b'a'..=b'f').contains(&byte));
+    if valid {
+        Ok(())
+    } else {
+        Err(ArtifactStoreError::Integrity(format!(
+            "{sha256:?} is not a lowercase-hex sha256 digest"
+        )))
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{blob_name, parse_blob_name};
+    use crate::error::ArtifactStoreError;
+
+    const SHA: &str = "aa30b1cc05c10ac8a1f4e6d46f7d4b1a9c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f";
+
+    #[test]
+    fn names_a_blob_under_its_two_char_fan_out() {
+        assert_eq!(blob_name(SHA).unwrap(), format!("blobs/sha256/aa/{SHA}"));
+    }
+
+    #[test]
+    fn parse_inverts_blob_name() {
+        assert_eq!(parse_blob_name(&blob_name(SHA).unwrap()).unwrap(), SHA);
+    }
+
+    #[test]
+    fn rejects_malformed_digests() {
+        for bad in [
+            "",
+            "abc",
+            &SHA[..63],                 // too short
+            &format!("{SHA}0"),         // too long
+            &SHA.to_uppercase(),        // uppercase
+            &format!("g{}", &SHA[1..]), // non-hex
+        ] {
+            assert!(matches!(
+                blob_name(bad).unwrap_err(),
+                ArtifactStoreError::Integrity(_)
+            ));
+        }
+    }
+
+    #[test]
+    fn rejects_names_off_contract() {
+        for bad in [
+            format!("blobs/sha256/{SHA}"),             // no fan-out level
+            format!("blobs/sha256/bb/{SHA}"),          // fan-out disagrees
+            format!("blobs/md5/aa/{SHA}"),             // wrong algorithm segment
+            format!("sha256/aa/{SHA}"),                // wrong prefix
+            format!("blobs/sha256/aa/{}", &SHA[..63]), // malformed digest
+        ] {
+            assert!(matches!(
+                parse_blob_name(&bad).unwrap_err(),
+                ArtifactStoreError::Integrity(_)
+            ));
+        }
+    }
+}