Merge pull request #482 from ModernRelay/codex/blob-http-delivery

feat(blob): add bounded HTTP delivery

Author: aaltshuler

AGENTS.md

@@ -268,7 +268,7 @@ omnigraph policy explain --cluster ./company-brain --graph knowledge --actor act
 |---|---|---|
 | Columnar storage on object store | ✅ Arrow/Lance | URI normalization, S3 env-var plumbing |
 | Per-dataset versioning + time travel | ✅ | `snapshot_at_version`, `entity_at`, snapshot-pinned reads across many tables |
-| Blob-v2 cell access | ✅ Blob-v2 descriptors and range readers | `read_blob_at` selects one logical node/edge Blob cell at an exact branch or snapshot without exposing Lance placement. Managed readers are bounded and snapshot-pinned; external values are descriptor-only. Identity ambiguity and malformed state fail closed. See [RFC-033](docs/rfcs/0033-blob-management.md) and [execution internals](docs/dev/execution.md). |
+| Blob-v2 cell access | ✅ Blob-v2 descriptors and range readers | `read_blob_at` selects one logical node/edge Blob cell at an exact branch or snapshot without exposing Lance placement. Managed readers are bounded and snapshot-pinned; HTTP GET/explicit HEAD adds ranges, conditionals, and a two-chunk backpressure envelope, while whole-object external values redirect without target-object I/O. Identity ambiguity, ranged external delivery, and malformed state fail closed. See [RFC-033](docs/rfcs/0033-blob-management.md) and [execution internals](docs/dev/execution.md). |
 | Stable schema + table identity | — | Persisted accepted SchemaIR v2 owns one graph identity domain and a shared monotonic no-reuse allocator for nonzero type, property, and table-incarnation IDs. Internal manifest schema v5 introduced identity-keyed registration, version, tombstone, OCC, recovery ownership, and identity-derived node/edge paths; v6 preserves that contract and adds exact non-null `id` fencing. `table_key` is a mutable alias: rename preserves identity/path/history, while drop/re-add mints a new lifetime. This binary serves exactly v6; released v4 graphs rebuild by export/init/load, and abandoned unreleased v7-v19 roots are refused as future formats. |
 | Per-dataset branches | ✅ | **Graph-level** refs are logically atomic through authoritative `__manifest` `BranchContents`; native create/delete crash gaps are classified and reclaimed under a single-writer-process boundary; live names are path-prefix-disjoint; data-table forks are lazy; system branches are filtered |
 | Atomic single-dataset commits | ✅ | **Multi-table publication has three layers:** each participant's Lance effect, one identity-aware `__manifest` CAS for graph visibility, and ordinary recovery-v9 for the gap. Mutation/Load, SchemaApply, BranchMerge, EnsureIndices, and Optimize arm identity-bearing sidecars before their first durable effect. Every pin, effect, registration, rename, tombstone, and output carries stable table/incarnation identity. Writers pre-mint exact Lance transactions where available, confirm complete outcomes before publication, and fail closed on ambiguous or foreign effects. Completed recovery is audited in `_graph_commit_recoveries.lance`. |

Cargo.lock

@@ -371,6 +371,35 @@ pub struct QueryRequest {
     pub snapshot: Option<String>,
 }
 
+/// Logical graph entity selected by the Blob delivery surface.
+///
+/// This is intentionally graph vocabulary. The wire contract never exposes a
+/// Lance dataset, table key, stable row id, or per-table lane.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, ToSchema)]
+#[serde(rename_all = "snake_case")]
+pub enum BlobEntityKind {
+    Node,
+    Edge,
+}
+
+/// Query parameters shared by `GET` and `HEAD /graphs/{graph_id}/blob`.
+#[derive(Debug, Clone, Serialize, Deserialize, IntoParams)]
+#[into_params(parameter_in = Query)]
+pub struct BlobReadQuery {
+    /// Select a logical node or edge cell.
+    pub entity: BlobEntityKind,
+    /// Accepted-schema node or edge type name.
+    pub r#type: String,
+    /// Logical entity id within the selected type.
+    pub id: String,
+    /// Accepted-schema Blob property name.
+    pub property: String,
+    /// Branch to read. Mutually exclusive with `snapshot`; defaults to `main`.
+    pub branch: Option<String>,
+    /// Immutable graph snapshot id. Mutually exclusive with `branch`.
+    pub snapshot: Option<String>,
+}
+
 #[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
 pub struct ChangeRequest {
     /// GQ mutation source containing `insert`, `update`, or `delete` statements.
@@ -700,6 +729,17 @@ pub struct ResourceLimitOutput {
     pub actual: u64,
 }
 
+/// Normalized half-open range details for an unsatisfiable managed Blob read.
+///
+/// HTTP also returns `Content-Range: bytes */N`; these fields let SDKs inspect
+/// the failure without parsing either that header or the human-readable text.
+#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
+pub struct BlobRangeOutput {
+    pub start: u64,
+    pub end: u64,
+    pub length: u64,
+}
+
 /// Structured details for an allowed external Blob source that could not be
 /// probed or read. The top-level `code` remains optional so this additive
 /// detail can roll out without extending the closed [`ErrorCode`] enum.
@@ -753,6 +793,10 @@ pub struct ErrorOutput {
     /// rejected attempt has no durable sidecar and no table effect.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub resource_limit: Option<ResourceLimitOutput>,
+    /// Set with HTTP 416 for a valid but unsatisfiable managed Blob byte range.
+    /// `start..end` is half-open and `length` is the selected Blob length.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub blob_range: Option<BlobRangeOutput>,
     /// Set with HTTP 424 when an external Blob URI passed admission policy but
     /// its source could not be probed or read. This optional detail is the
     /// rolling-safe machine-readable discriminator; `code` is omitted because

crates/omnigraph-api-types/src/lib.rs

@@ -455,6 +455,7 @@ pub(crate) fn precondition_failed_cli(
             read_set_conflict: None,
             key_conflict: None,
             resource_limit: None,
+            blob_range: None,
             external_blob_source: None,
             recovery_required: None,
             precondition_failure: Some(omnigraph_api_types::PreconditionFailureOutput {

crates/omnigraph-cli/src/helpers.rs

@@ -36,6 +36,7 @@ tracing-subscriber = { workspace = true }
 tower-http = { workspace = true }
 utoipa = { workspace = true }
 futures = { workspace = true }
+headers = "0.4.1"
 sha2 = { workspace = true }
 subtle = { workspace = true }
 async-trait = { workspace = true }