|
| 1 | +# dn_redis is Redis-protocol EMULATION, not a Redis dependency |
| 2 | + |
| 3 | +## TL;DR |
| 4 | + |
| 5 | +`lance-graph-cognitive::container_bs::dn_redis` is a **protocol/shape adapter** for HHTL-keyed hot lookups. It is NOT a dependency on an external Redis server. Adopters reading the module and the lab-vs-canonical-surface discipline doc correctly identify that `dn_redis` is "protocol-only"; they sometimes incorrectly conclude that an external Redis server is therefore required. |
| 6 | + |
| 7 | +This doc clarifies that **"protocol-only adapter" means the SHAPE is the contract — the backend is open**. Three valid backends: |
| 8 | + |
| 9 | +- (a) an external Redis cluster (traditional hybrid deployment) |
| 10 | +- (b) **in-binary**: an OGIT class view + DataFusion query over the local Lance dataset, projected through the `dn_redis` adapter shape — Redis-protocol responses emitted from your own data, **no Redis service required** |
| 11 | +- (c) anything else that produces the `ada:dn:{hex}` / `ada:spine:{hex}` key shape with the documented operations |
| 12 | + |
| 13 | +## Audience |
| 14 | + |
| 15 | +Anyone reading `lance-graph-cognitive::container_bs::dn_redis` (the 253-line protocol-only adapter) and wondering whether they need to deploy a Redis server. Also anyone reading SPRINT plan docs that reference `dn_redis` as "protocol-only" without further qualification. |
| 16 | + |
| 17 | +## The pattern (FalkorDB / KuzuDB precedent) |
| 18 | + |
| 19 | +[FalkorDB](https://www.falkordb.com/) (formerly RedisGraph) and [KùzuDB](https://kuzudb.com/) both "talk Redis" — they expose the Redis wire protocol — while the storage and execution underneath are completely different. They are NOT Redis; they emulate the wire protocol so existing Redis clients work. |
| 20 | + |
| 21 | +`dn_redis` follows the same pattern. It defines: |
| 22 | + |
| 23 | +- Key conventions: `ada:dn:{hex}` for individual nodes, `ada:spine:{hex}` for spine entries |
| 24 | +- Walk-to-root operation shape (`MGET ada:dn:{ancestor1} ada:dn:{ancestor2} ...`) |
| 25 | +- Children/subtree patterns (`KEYS ada:dn:{prefix}??` for one-level; `KEYS ada:dn:{prefix}*` for subtree) |
| 26 | +- Pipeline operations (`RedisPipeline` + `RedisCommand` enum) |
| 27 | + |
| 28 | +These are **shapes**, not service dependencies. The shape can be served by any backend that produces the right responses. |
| 29 | + |
| 30 | +## Why this matters |
| 31 | + |
| 32 | +Consumers reading the `dn_redis` module + the surrounding lance-graph discipline docs (lab-vs-canonical-surface, the "protocol-only adapter" annotation that appears across the brutal-fix planning material in downstream consumers like `AdaWorldAPI/bardioc`) correctly identify that it is protocol-only. They incorrectly conclude that an external Redis server is therefore required. This doc clarifies that "protocol-only adapter" means the SHAPE is the contract — the backend is open. |
| 33 | + |
| 34 | +For a single-binary deployment (e.g. `bardioc/substrate-b`) the natural backend is option (b): the in-binary OGIT class view + DataFusion query over Lance. This produces Redis-protocol-shaped responses without running a Redis server. The single-binary "zero application-level boundaries" deployment shape (see `docs/APPEND_ONLY_RAFT_DOVETAIL.md` for the broader argument) survives the addition of HHTL-keyed hot lookups precisely because `dn_redis` is emulation, not a service. |
| 35 | + |
| 36 | +For consumers that already operate a Redis cluster, option (a) is fine. For consumers that prefer purpose-built graph engines exposing Redis wire protocol, FalkorDB and KùzuDB demonstrate that the pattern is well-established. |
| 37 | + |
| 38 | +## Recommended consumer pattern |
| 39 | + |
| 40 | +For the in-binary backend (option b): |
| 41 | + |
| 42 | +1. Implement a `dn_redis::Backend` impl (or whatever the trait name resolves to in the adapter's surface) that intercepts the documented operations |
| 43 | +2. Project them through DataFusion queries over the local Lance dataset |
| 44 | +3. Wrap the responses in the Redis-protocol shape the adapter expects |
| 45 | +4. Mount the backend at the same call sites that a Redis client would be mounted |
| 46 | + |
| 47 | +See the bardioc B1 substrate-b reference for a worked example once that consumer's reference-implementation doc lands (separate proposal under upstream-contributions T2.1). |
| 48 | + |
| 49 | +## What this doc does NOT claim |
| 50 | + |
| 51 | +- **It does not claim FalkorDB or KùzuDB use `dn_redis`.** Those are independent products demonstrating the wire-protocol-emulation pattern; `dn_redis` borrows the pattern but is its own thing. |
| 52 | +- **It does not claim option (a) is wrong.** External Redis is a perfectly valid backend for `dn_redis`. The point is that adopters are not LOCKED IN to it. |
| 53 | +- **It does not specify the in-binary backend implementation.** That's consumer code; this doc explains why such consumer code is well-formed, not how to write it. |
| 54 | + |
| 55 | +## Cross-references |
| 56 | + |
| 57 | +- `lance-graph-cognitive::container_bs::dn_redis` — the protocol adapter |
| 58 | +- `lab-vs-canonical-surface.md` — the canonical-vs-lab discipline that frames adapters |
| 59 | +- FalkorDB project (Redis wire protocol emulation precedent) |
| 60 | +- KùzuDB project (similar pattern) |
| 61 | +- `AdaWorldAPI/bardioc` PR #15 conversation thread — where this clarification surfaced |
0 commit comments