Replace read_blob with descriptor-first read_blob_at facade

[ragnorc]

The blob read path gets the correct-by-design shape ahead of the HTTP
blob endpoint:

• New public Omnigraph::read_blob_at(target, type, id, prop) resolves one
  pinned snapshot of any ReadTarget (capture_read_view), classifies the
  cell from its persisted blob-v2 descriptor BEFORE any payload API, and
  returns an engine-owned BlobRead: internal blobs stream through a
  bounded, range-capable BlobReader; External references return their
  absolute URI with ZERO server-side store resolution (Lance 9.0.0-rc.1's
  take_blobs eagerly builds a store client for external URIs and issues a
  remote HEAD when the recorded size is zero). BlobVersionTag carries the
  identity tuple (stable_table_id, incarnation_id, table_version, row_id)
  for rename-stable, drop/re-add-safe cache validators.
• lance::dataset::BlobFile no longer leaks through the public API (the
  SnapshotScanner boundary shape); the old current-branch-only read_blob
  is removed and every caller migrated.
• Blob-v2 descriptor decoding is extracted into one shared
  crate::blob_descriptor decoder used by both the read facade and the
  merge/rewrite null-check, and its field shape (kind, position, size,
  blob_id, blob_uri) plus BlobKind discriminants are pinned by surface
  guard 21.
• Row lookup uses a typed exact-id predicate (first_row_id_for_id,
  scanner.filter_expr) instead of SQL-text flattening of the caller's id;
  blob errors are typed (unknown type/row and null cell are NotFound, a
  non-Blob property is BadRequest) instead of uniform bad-requests.
• The filtered BlobsDescriptions probe is pinned green: the upstream
  projection assertion that motivated /query's blob-column exclusion is
  fixed on the rc.1 pin. The null-column /query response is retained as
  shipped contract; the exec/query.rs comment now says so.

forbidden_apis: read_blob_at classified read-only, .into_arc() moved to
blob_read.rs, storage_layer .dataset() forwarding count 25 -> 26.

Co-Authored-By: Claude Fable 5 noreply@anthropic.com
Claude-Session: https://claude.ai/code/session_0149LrcotcFUeveBZBA4ww5T

---

Note

Medium Risk
Touches read paths, streaming HTTP semantics, and ingest validation for blob columns; behavior is heavily tested but external-reference and range/conditional handling are user-visible contract.

Overview
Adds end-to-end Blob property access on top of a redesigned engine read path: read_blob_at replaces read_blob, pins reads to branch/snapshot, decodes blob-v2 descriptors first (internal streaming vs external URI with no server-side fetch), and exposes BlobReader / BlobVersionTag instead of Lance’s BlobFile.

Server & CLI: GET/HEAD /graphs/{id}/blob streams internal payloads with ETag, ranges (206/416), 304, and 302 for external refs; omnigraph blob get / blob stat mirror that for embedded and remote graphs (no redirect follow on external URIs). Shared blob_etag lives in omnigraph-api-types.

Ingest hardening: create/overwrite validates canonical {data, uri} blob input and probes readable external URIs at load time so later keyed writes don’t break on schema drift.

Tests, parity matrix rows, OpenAPI, and user docs are updated accordingly.

^{Reviewed by Cursor Bugbot for commit f6123ce. Bugbot is set up for automated code reviews on this repo. Configure here.}

Greptile Summary

This PR replaces the blob read API with a descriptor-first, snapshot-pinned facade. The main changes are:

• Adds bounded internal blob streaming and external-reference classification.
• Adds authenticated GET and HEAD blob routes with ranges and cache validators.
• Adds embedded and remote blob get and blob stat CLI commands.
• Centralizes blob descriptor decoding and ETag generation.
• Updates tests, OpenAPI output, and user documentation.

Confidence Score: 5/5

The latest fixes look safe to merge.

• The validator fix handles comma-separated and weak entity tags.
• No additional qualifying production issue was found in the descriptor compatibility path.

Important Files Changed

Filename	Overview
crates/omnigraph-server/src/handlers.rs	Adds authenticated blob GET and HEAD handling with streaming, ranges, redirects, and cache validators.
crates/omnigraph/src/db/omnigraph/blob_read.rs	Adds the snapshot-pinned descriptor-first blob read facade and bounded reader.
crates/omnigraph/src/blob_descriptor.rs	Centralizes decoding of persisted blob descriptors.
crates/omnigraph-cli/src/client.rs	Adds embedded and remote blob retrieval and metadata operations.

_{Reviews (9): Last reviewed commit: "Merge remote-tracking branch 'origin/mai..." | Re-trigger Greptile}

Context used:

• Context used - AGENTS.md (source)
• Context used - CLAUDE.md (source)

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e5f7ec6a90

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

There are 2 total unresolved issues (including 1 from previous review).

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit f823be0. Configure here.}