# https://github.com/yantrikos/yantrikdb-server Project Manual Generated at: 2026-07-17 21:57:06 UTC ## Table of Contents - [Overview & Quick Start](#page-1) - [Workspace, Crates & Process Internals](#page-2) - [HTTP Gateway, Wire Protocol & Memory API](#page-3) - [Cluster, HA, Replication & Operations](#page-4) ## Overview & Quick Start ### Related Pages Related topics: [Workspace, Crates & Process Internals](#page-2), [HTTP Gateway, Wire Protocol & Memory API](#page-3), [Cluster, HA, Replication & Operations](#page-4)
Related Source Files The following source files were used to generate this page: - [README.md](https://github.com/yantrikos/yantrikdb-server/blob/main/README.md) - [SERVER_README.md](https://github.com/yantrikos/yantrikdb-server/blob/main/SERVER_README.md) - [CHANGELOG.md](https://github.com/yantrikos/yantrikdb-server/blob/main/CHANGELOG.md) - [ROADMAP.md](https://github.com/yantrikos/yantrikdb-server/blob/main/ROADMAP.md) - [DESIGN.md](https://github.com/yantrikos/yantrikdb-server/blob/main/DESIGN.md) - [pyproject.toml](https://github.com/yantrikos/yantrikdb-server/blob/main/pyproject.toml)
# Overview & Quick Start ## Purpose & Scope **yantrikdb-server** is the HTTP gateway component of the yantrikdb ecosystem. It wraps the memory engine — implemented in Rust and linked through PyO3 — and exposes its storage primitives (`remember`, `remember_batch`, `memories`, `memory`) over a versioned REST surface so that external clients (including `yantrikdb-mcp` and `yantrikdb-hermes-plugin`) can interact with the engine without taking a direct dependency on the core crate. The server targets the **v1** API family; all routes are namespaced under `/v1/` and token-gated. As of the latest published release (**v0.10.0**), the server pins the engine at the v0.10 line and ships the oplog at wire-format `v2`. The server is intentionally thin: it owns *transport*, *authentication*, and *tenant routing*; durability, indexing, embedding, and hygiene policy live in the engine. Source: [CHANGELOG.md:1-40]() ## Quick Start The server is distributed as a Python wheel (the engine is linked through PyO3 at install time), which is the supported install path described in the project metadata. Source: [pyproject.toml:1-60]() ```bash # Install (pinned tag recommended) pip3 install "yantrikdb-server @ git+https://github.com/yantrikos/yantrikdb-server@v0.10.0" # Run in single-node mode yantrikdb-server --config ./server.toml # Verify it is up curl -sS -H "Authorization: Bearer $YANTRIKDB_MASTER_TOKEN" \ http://127.0.0.1:8080/v1/memories?kind=text&drive_id=demo ``` A minimal first request — write one memory item and then read it back: ```bash # Write curl -sS -X POST http://127.0.0.1:8080/v1/remember \ -H "Authorization: Bearer $YANTRIKDB_MASTER_TOKEN" \ -H "Content-Type: application/json" \ -d '{"drive_id":"demo","kind":"text","payload":{"text":"hello"}}' # Read back (current value; superseded items hidden by default) curl -sS -H "Authorization: Bearer $YANTRIKDB_MASTER_TOKEN" \ "http://127.0.0.1:8080/v1/memory?drive_id=demo&kind=text" ``` > **Python compatibility note.** Issue #43 documents that Python 3.14 is currently incompatible with the shipped PyO3 version (0.23.5, which supports interpreters up to 3.13). Stay on Python 3.11–3.13 until upstream PyO3 advances. Source: [README.md:1-40]() ## Core v1 Endpoints The v1 surface is small and stable across the v0.8.x → v0.10.0 line: - `POST /v1/remember` — Write a single memory item. Engine-side WriteAdmission rules apply. - `POST /v1/remember_batch` — Write many items in one request; each item is resolved against its own tenant namespace. - `GET /v1/memory` — Read the **current value** for a `(drive_id, kind)` pair (RFC 027 pillar: known-unknowns semantics). - `GET /v1/memories` — Structural query primitive with `kind`, `drive_id`, `cursor`, and `order` parameters. - `* /admin/...` — Administrative surface for the autonomous hygiene worker introduced in v0.8.24. The `remember` family carries an optional `idempotency_key` field on the wire, but the MCP and Hermes consumers currently **refuse** to forward it in HTTP mode — per ecosystem agreement #6, refusing beats forwarding a field the gateway would silently drop. That field is the design home of issue #58 and is not yet activated end-to-end. Treat it as advisory, not authoritative. Source: [DESIGN.md:1-80]() ## Architecture at a Glance ```mermaid flowchart LR C["HTTP client
(yantrikdb-mcp / hermes / curl)"] -->|v1 routes| G[yantrikdb-server] G -->|token + tenant routing| E["yantrikdb-core engine
(WriteAdmission, embeddings, hygiene)"] E -->|oplog v2| S[(Local or clustered store)] G -->|peers · SYNC| N[Other yantrikdb-server nodes] ``` - **Auth / routing layer.** Every v1 route is gated by either a master token or a per-tenant token; write paths route through tenant-namespace resolution before reaching the engine. Source: [SERVER_README.md:1-60]() - **Engine layer.** The server pins a specific engine version per release. WriteAdmission, embedding-on-wire, and `include_superseded` are engine v0.10 capabilities surfaced through the same v1 routes. Source: [CHANGELOG.md:1-60]() - **Peer-sync layer.** Cluster-mode replication streams oplog entries between nodes. Issue #53 documents a known gap: `OPLOG_FORMAT_VERSION` is stamped at write time but **not yet validated** by readers, with no reader-side gate and no migration registry. The fix is deferred by design and tracked under capability-exchange work. Source: [ROADMAP.md:1-40]() ## Operational Notes Releases follow semver with deliberate minor-bump alignment to the engine: - **v0.8.x** — autonomous-hygiene worker + admin surface (v0.8.24), session lifecycle + boot-digest capture (v0.8.25), `/v1/memories` structural query (v0.8.23), master-token routing fix for `/v1/memory` and `/v1/memories` (v0.8.22), write-side tenant-namespace fix in `remember` and `remember_batch` (v0.8.21). Source: [CHANGELOG.md:60-120]() - **v0.10.0** — oplog wire format `v2` carrying embedding bytes, engine v0.10.0 adoption, server version realignment. Source: [CHANGELOG.md:120-180]() - **Cluster-mode startup** had a transient regression in v0.8.18 fixed in v0.8.19; deployments pinned to older tags should upgrade past v0.8.19. Source: [CHANGELOG.md:180-220]() ### Where to go next - For write- and read-side semantics (WriteAdmission rules, superseded handling, current-value reads), see the engine contract section of `SERVER_README.md`. - For protocol-level details (embedding bytes on the oplog, idempotency-key design home), see `DESIGN.md` and issue #58. - For upgrade notes between minors and known in-flight gaps (`OPLOG_FORMAT_VERSION` validation, issue #53), see `CHANGELOG.md` and `ROADMAP.md`. Until issue #58 lands, do **not** rely on `idempotency_key` for at-most-once semantics — pin a release tag, document the engine version it carries, and treat the gateway as a faithful, but not yet deduplicating, proxy to the engine. --- ## Workspace, Crates & Process Internals ### Related Pages Related topics: [Overview & Quick Start](#page-1), [HTTP Gateway, Wire Protocol & Memory API](#page-3), [Cluster, HA, Replication & Operations](#page-4)
Related Source Files The following source files were used to generate this page: - [Cargo.toml](https://github.com/yantrikos/yantrikdb-server/blob/main/Cargo.toml) - [crates/yantrikdb-protocol/Cargo.toml](https://github.com/yantrikos/yantrikdb-server/blob/main/crates/yantrikdb-protocol/Cargo.toml) - [crates/yantrikdb-protocol/src/lib.rs](https://github.com/yantrikos/yantrikdb-server/blob/main/crates/yantrikdb-protocol/src/lib.rs) - [crates/yantrikdb-server/Cargo.toml](https://github.com/yantrikos/yantrikdb-server/blob/main/crates/yantrikdb-server/Cargo.toml) - [crates/yantrikdb-server/src/main.rs](https://github.com/yantrikos/yantrikdb-server/blob/main/crates/yantrikdb-server/src/main.rs) - [crates/yantrikdb-server/src/runtime.rs](https://github.com/yantrikos/yantrikdb-server/blob/main/crates/yantrikdb-server/src/runtime.rs) - [crates/yantrikdb-server/src/server.rs](https://github.com/yantrikos/yantrikdb-server/src/server.rs)
# Workspace, Crates & Process Internals `yantrikdb-server` is a Cargo workspace that ships the HTTP gateway in front of the `yantrikdb-core` storage engine. The repository is intentionally split into a thin protocol crate and a heavier server crate so that the on-wire formats (oplog entries, capability flags, embedding bytes) can evolve independently of the request-handling binary. ## Workspace layout The root manifest declares a multi-crate workspace and pins a single resolver. The `members` array limits the workspace to the two in-tree crates, and a `[workspace.dependencies]` block centralises version pins that both crates share. Source: [Cargo.toml:1-30]() | Crate | Path | Role | | --- | --- | --- | | `yantrikdb-protocol` | `crates/yantrikdb-protocol/` | Pure-Rust data model for oplog entries, capability flags, and `OPLOG_FORMAT_VERSION`. No I/O, no engine dependency. | | `yantrikdb-server` | `crates/yantrikdb-server/` | Async HTTP gateway, runtime lifecycle, CLI entry point. Depends on `yantrikdb-protocol` and the upstream engine. | The split was finalised in v0.8.20 when pre-split scaffolding was removed (PR #44, closes issue #43). Source: [Cargo.toml:1-15]() ## The `yantrikdb-protocol` crate The protocol crate is the *wire* half of the system. Its `Cargo.toml` declares it as `edition = "2021"` with `yantrikdb-core = { ... }` as an optional dependency, and exposes a `lib.rs` that re-exports the engine's protocol types plus its own `OPLOG_FORMAT_VERSION` constant. Source: [crates/yantrikdb-protocol/Cargo.toml:1-25]() Key responsibilities, anchored to the manifest and `lib.rs`: - Re-export `MemoryItem`, `Entry`, and `EntryKind` from the engine so the server does not duplicate type definitions. - Define `OPLOG_FORMAT_VERSION` and `entry_to_wire` / `entry_from_wire` helpers. As of v0.10.0 the v2 wire format carries embedding bytes on the wire (PR #52). - Provide the `OPLOG_FORMAT_VERSION` constant that is stamped but, per issue #53, currently has **no reader-side gate** — a known gap tracked for a follow-up. Source: [crates/yantrikdb-protocol/src/lib.rs:1-80]() ## The `yantrikdb-server` crate The server crate owns the binary, the runtime, and the request surface. Its manifest declares both `yantrikdb-protocol` and `yantrikdb-core` as dependencies and lists the features (`async`, `tls`, `admin`, `hygiene`) that gate optional subsystems added across the 0.8.x series. Source: [crates/yantrikdb-server/Cargo.toml:1-45]() ### Binary entry — `main.rs` `main.rs` is intentionally small: it parses CLI arguments, loads configuration, and hands off to `runtime::bootstrap`. No business logic lives here. The function `fn main() -> Result<(), BootError>` is the only public surface. Source: [crates/yantrikdb-server/src/main.rs:1-60]() ### Runtime lifecycle — `runtime.rs` `runtime.rs` is where the process becomes a server. It is responsible for: 1. **Boot digest capture** (added in v0.8.25, RFC 027 pillar 2) — the runtime computes a deterministic digest of the on-disk state at start-up so peers can detect divergence. 2. **Engine initialisation** — opens the `yantrikdb-core` storage with the pinned engine version. The pin moved from v0.9.0 → v0.9.4 in v0.8.26 (PR #50) and to v0.10.0 in v0.10.0 (PR #54). 3. **Hygiene worker spawn** — the autonomous worker from v0.8.24 / RFC 027 is started here as a background tokio task. 4. **Signal handling** — `tokio::signal::ctrl_c` and `SIGTERM` drive graceful shutdown, flushing the oplog before exit. Source: [crates/yantrikdb-server/src/runtime.rs:1-180]() ### Request surface — `server.rs` `server.rs` mounts the axum/hyper router and binds it to the configured listener. It wires the engine handle that `runtime.rs` produced into the per-route handlers. Notable routes mounted here, cross-referenced against the release history: - `POST /v1/remember` and `POST /v1/remember_batch` — write-side entry points. v0.8.21 fixed tenant-namespace routing on these (PR #45). Issue #58 is the design home for an `idempotency_key=` parameter that two downstream consumers currently refuse to forward. - `GET /v1/memory` and `GET /v1/memories` — read-side. v0.8.22 fixed master-token routing (PR #46); v0.8.23 added structural query primitives `kind`, `drive_id`, `cursor`, `order` (PR #47); v0.8.27 added current-value reads (PR #51). - `GET /v1/admin/*` — admin surface from v0.8.24 (RFC 027). Source: [crates/yantrikdb-server/src/server.rs:1-220]() ## Process boot sequence ```mermaid flowchart TD A["main.rs: parse CLI + config"] --> B["runtime::bootstrap"] B --> C["Open yantrikdb-core storage (pinned engine)"] C --> D["Compute boot digest (RFC 027)"] D --> E["Spawn hygiene worker (background)"] E --> F["server::serve: bind listener + mount router"] F --> G["Await SIGINT / SIGTERM"] G --> H["Flush oplog + graceful shutdown"] ``` Source: [crates/yantrikdb-server/src/main.rs:1-60](), [crates/yantrikdb-server/src/runtime.rs:1-180](), [crates/yantrikdb-server/src/server.rs:1-220]() ## Engine pinning policy Because the server consumes a separately versioned engine, the workspace uses an *engine pin*: a single `Cargo.toml` line that locks `yantrikdb-core` to an exact tagged release. The pin has moved at every minor release in the 0.8.x series (v0.9.0 → v0.9.4 → v0.10.0) and is the mechanism that lets the server ship known-unknowns (RFC 027) without breaking older storage layouts. Source: [Cargo.toml:1-15](), [crates/yantrikdb-server/Cargo.toml:1-45]() ## Known gaps carried by the process layer - **Python 3.14 is unsupported** because PyO3 0.23.5 caps at 3.13. The path forward is `PYO3_USE_ABI3_FORWARD_COMPAT` once a newer PyO3 ships — tracked in issue #43. Source: [Cargo.toml:1-15]() - **Op-log format-version downgrade path is unwritten.** `OPLOG_FORMAT_VERSION` is stamped in `entry_to_wire` but never validated on read; a reader-side gate and migration registry are tracked in issue #53. Source: [crates/yantrikdb-protocol/src/lib.rs:1-80]() - **Cluster-mode startup regression** was fixed in v0.8.19 (PR #42) after v0.8.18 introduced it — a reminder that `runtime.rs` is the most regression-sensitive file in the workspace. Source: [crates/yantrikdb-server/src/runtime.rs:1-180]() --- ## HTTP Gateway, Wire Protocol & Memory API ### Related Pages Related topics: [Overview & Quick Start](#page-1), [Workspace, Crates & Process Internals](#page-2), [Cluster, HA, Replication & Operations](#page-4)
Related Source Files The following source files were used to generate this page: - [crates/yantrikdb-server/src/http_gateway.rs](https://github.com/yantrikos/yantrikdb-server/blob/main/crates/yantrikdb-server/src/http_gateway.rs) - [crates/yantrikdb-server/src/api/mod.rs](https://github.com/yantrikos/yantrikdb-server/blob/main/crates/yantrikdb-server/src/api/mod.rs) - [crates/yantrikdb-server/src/api/access.rs](https://github.com/yantrikos/yantrikdb-server/blob/main/crates/yantrikdb-server/src/api/access.rs) - [crates/yantrikdb-server/src/api/errors.rs](https://github.com/yantrikos/yantrikdb-server/blob/main/crates/yantrikdb-server/src/api/errors.rs) - [crates/yantrikdb-server/src/version/mod.rs](https://github.com/yantrikos/yantrikdb-server/blob/main/crates/yantrikdb-server/src/version/mod.rs) - [crates/yantrikdb-server/src/version/wire.rs](https://github.com/yantrikos/yantrikdb-server/blob/main/crates/yantrikdb-server/src/version/wire.rs)
# HTTP Gateway, Wire Protocol & Memory API ## Purpose and Scope The HTTP Gateway is the external surface of `yantrikdb-server`: it converts HTTP requests from MCP/CLI/Hermes consumers into engine-level memory operations and serializes responses back as JSON. It binds together three concerns — request routing under access control, a typed memory API (`/v1/remember`, `/v1/memories`, `/v1/memory`, `/v1/recall`), and a versioned wire protocol used for peer-to-peer oplog replication. The gateway never embeds the storage engine directly; it delegates to `yantrikdb-core` through the API layer. Source: [crates/yantrikdb-server/src/http_gateway.rs:1-40]() The wire protocol is logically separate from the HTTP API: it is the format used to ship oplog entries between server instances during peer-sync. `OPLOG_FORMAT_VERSION` is stamped on every entry written, but — as documented in issue #53 — it is not yet validated on read, which is the known gap that motivated the v2 introduction in PR #52. Source: [crates/yantrikdb-server/src/version/wire.rs:1-30]() ## HTTP Gateway & Access Layer The gateway boots as a tower/axum-style service that mounts the API router under a `/v1` prefix and dispatches routes. Each request is funneled through the access layer before reaching a handler. Source: [crates/yantrikdb-server/src/http_gateway.rs:40-120]() The access module is the single chokepoint where master-token vs. drive-token authentication is resolved. It returns a typed `AccessContext` consumed by handlers; routing failures (missing token, wrong tenant) are converted into structured error responses rather than raw panics. Source: [crates/yantrikdb-server/src/api/access.rs:1-80]() Release v0.8.22 fixed a regression where master-token requests against `/v1/memory` and `/v1/memories` were being routed under a drive-token code path. The fix lives in `access.rs` and ensures the master-token branch is matched before drive-id resolution. Source: [crates/yantrikdb-server/src/api/access.rs:80-140]() Errors produced at any layer are normalized through a single error type so the JSON envelope stays stable across versions. Source: [crates/yantrikdb-server/src/api/errors.rs:1-60]() ## Memory API Endpoints The API module re-exports handler modules grouped by verb family. Source: [crates/yantrikdb-server/src/api/mod.rs:1-25]() | Endpoint | Verb | Purpose | Notable behavior | |----------|------|---------|------------------| | `/v1/remember` | POST | Write a single memory item | Subject to `WriteAdmission` gate (engine v0.10) | | `/v1/remember` (batch) | POST | Write multiple items | Per-item tenant-namespace fix shipped in v0.8.21 | | `/v1/recall` | GET | Read by id or query | Supports `include_superseded` (v0.10.0) | | `/v1/memories` | GET | Structural list (kind/drive_id/cursor/order) | Added in v0.8.23 | | `/v1/memory` | GET | Current-value read | Added in v0.8.27 (RFC 027) | The `idempotency_key` parameter on `/v1/remember` is a known shared-surface gap. Two downstream consumers (`yantrikdb-mcp`, `yantrikdb-hermes-plugin`) currently *refuse* the field in HTTP mode rather than forwarding it, per ecosystem agreement #6 ("refusing beats forwarding a field the gateway would silently drop"). Wiring it end-to-end is tracked in issue #58 as agreement #4. Source: [crates/yantrikdb-server/src/api/mod.rs:25-70]() ```mermaid flowchart LR Client[MCP / CLI / Hermes] -->|HTTPS JSON| GW[http_gateway.rs] GW --> Access[api/access.rs
token resolve] Access --> Handler[api handler
remember / recall / memories] Handler --> Engine[(yantrikdb-core
engine v0.10)] Engine -->|oplog entry v2| Wire[version/wire.rs] Wire -->|peer-sync| Peer[Other node] ``` ## Wire Protocol & Versioning The version module exposes both the runtime server version and the oplog wire format version. Source: [crates/yantrikdb-server/src/version/mod.rs:1-40]() Wire format v2 (introduced in PR #52, shipped in v0.10.0) carries embedding bytes inline on every oplog entry. Previously, embeddings had to be re-derived on the receiving side; v2 removes that round-trip and is required for `WriteAdmission` and `include_superseded` semantics. Source: [crates/yantrikdb-server/src/version/wire.rs:30-90]() `entry_to_wire` is the writer side of the protocol and is the only place that stamps `OPLOG_FORMAT_VERSION`. As noted in issue #53, there is no reader-side gate and no migration registry — a downgrade is currently silent. This is a deliberately deferred follow-up to #52, owned by `yantrikdb-core`. Source: [crates/yantrikdb-server/src/version/wire.rs:90-150]() Cross-version compatibility expectations: nodes speaking wire v2 can read v1 entries (forward compatibility); the reverse path requires the receiver to ignore unknown fields. Any consumer building against the API should pin to the server version reported by the version module rather than relying on oplog versioning. Source: [crates/yantrikdb-server/src/version/mod.rs:40-80]() --- ## Cluster, HA, Replication & Operations ### Related Pages Related topics: [Overview & Quick Start](#page-1), [Workspace, Crates & Process Internals](#page-2), [HTTP Gateway, Wire Protocol & Memory API](#page-3)
Related Source Files The following source files were used to generate this page: - [crates/yantrikdb-server/src/raft/mod.rs](https://github.com/yantrikos/yantrikdb-server/blob/main/crates/yantrikdb-server/src/raft/mod.rs) - [crates/yantrikdb-server/src/raft/assembly.rs](https://github.com/yantrikos/yantrikdb-server/blob/main/crates/yantrikdb-server/src/raft/assembly.rs) - [crates/yantrikdb-server/src/raft/committer.rs](https://github.com/yantrikos/yantrikdb-server/blob/main/crates/yantrikdb-server/src/raft/committer.rs) - [crates/yantrikdb-server/src/raft/log_storage.rs](https://github.com/yantrikos/yantrikdb-server/blob/main/crates/yantrikdb-server/src/raft/log_storage.rs) - [crates/yantrikdb-server/src/raft/state_machine.rs](https://github.com/yantrikos/yantrikdb-server/blob/main/crates/yantrikdb-server/src/raft/state_machine.rs) - [crates/yantrikdb-server/src/raft/http_network.rs](https://github.com/yantrikos/yantrikdb-server/blob/main/crates/yantrikdb-server/src/raft/http_network.rs)
# Cluster, HA, Replication & Operations `yantrikdb-server` ships a Raft-based clustering layer that lives under `crates/yantrikdb-server/src/raft/`. The module provides the consensus, replication, and operational primitives that turn a single in-process engine into a coordinated multi-node deployment. The codebase splits these concerns across five focused files, each owning one stage of the Raft pipeline. ## Module Layout The Raft subsystem is declared as a Rust module and re-exports its public surface for the rest of the server to consume. - `mod.rs` declares the module tree, wires the submodules together, and exposes the public types that callers (HTTP handlers, bootstrap, admin endpoints) interact with. - `assembly.rs` is responsible for assembling a Raft node — picking the network factory, log storage backend, and state machine, then handing the configured `Raft` handle back to the server entry point. - `committer.rs` owns the commit-application loop: it takes committed log entries from Raft and dispatches them to the state machine. - `log_storage.rs` implements the durable log backend used by Raft for replication and recovery. - `state_machine.rs` defines the state machine that applies committed entries to the in-memory engine. - `http_network.rs` implements Raft's inter-node transport using HTTP so cluster traffic reuses the same port and stack as the public API. Source: [crates/yantrikdb-server/src/raft/mod.rs]() ## Assembly & Bootstrap `assembly.rs` centralizes node construction so the rest of the codebase can request a ready-to-use Raft instance without knowing the wiring details. The assembly stage is where operational concerns such as peer URLs, node ID, snapshot policy, and log backend are resolved and bound. Because the network layer is implemented over HTTP (see below), assembly also routes peer-to-peer traffic through the same listener that serves the public `/v1/*` API, avoiding a second socket per node. Source: [crates/yantrikdb-server/src/raft/assembly.rs]() Cluster-mode startup has historically been a source of regressions in this server. Release v0.8.19 was a hotfix specifically described as a "cluster-mode startup regression in v0.8.18," indicating that the assembly path is delicate and tightly coupled to engine version pins. Source: v0.8.19 release notes (`release: hotfix: v0.8.19 — cluster-mode startup regression in v0.8.18`) ## Log Storage & State Machine `log_storage.rs` backs Raft's replicated log. It is responsible for appending entries durably, returning them on replay, truncating followers that diverge, and supporting snapshot install/purge operations that Raft issues on membership changes or compaction. `state_machine.rs` defines what it means for an entry to be "applied." Once Raft commits an entry, the committer hands its payload to the state machine, which projects the change onto the embedded engine. Because the engine itself owns the memory model (memories, drives, embeddings, current-value semantics), the state machine is intentionally thin: it deserializes the entry, routes it to the appropriate engine call, and surfaces results back to Raft. Source: [crates/yantrikdb-server/src/raft/log_storage.rs]() Source: [crates/yantrikdb-server/src/raft/state_machine.rs]() A known gap in this area is oplog format-version validation. The community tracked issue #53 observes that `OPLOG_FORMAT_VERSION` is stamped into wire entries by `entry_to_wire` but is never validated by readers, so format-version downgrades during peer sync are not yet enforced. Source: issue #53 — "Peer-sync capability exchange: make oplog format-version downgrades explicit (follow-up to #52)" ## Committer & HTTP Network `committer.rs` runs the commit-side loop. It receives committed entries from Raft (typically driven from the `RawNode` advance loop on the server's main tick), deserializes each entry into a typed request, and forwards it to the state machine in commit order. Errors are recorded against the entry so retries and observability can attribute failures precisely. Source: [crates/yantrikdb-server/src/raft/committer.rs]() `http_network.rs` implements Raft's network layer (vote, append-entries, install-snapshot, heartbeat) over HTTP. This choice lets a single binary expose both the public API and the cluster protocol on one port, and it keeps deployment simple for operators who already front the server with an HTTP load balancer. Peer URLs are the same scheme/host/port that serve `/v1/remember`, `/v1/memories`, and friends. Source: [crates/yantrikdb-server/src/raft/http_network.rs]() ## Operational Notes A few operational characteristics follow directly from the layout above: - Single-port operation. Cluster and public traffic share one HTTP listener, so firewall rules and reverse-proxy configuration treat the server as a single endpoint. - Engine-version coupling. The state machine binds to a specific embedded-engine version; releases v0.8.20, v0.8.26, and v0.8.28 all carried engine bumps (`v0.7.20`, `v0.9.0 → v0.9.4`, `v0.10.0`) that the Raft layer had to absorb without breaking cluster compatibility. - Idempotency plumbing. The community is currently designing `idempotency_key` on `/v1/remember` (issue #58). Once wired, the committer and state machine will be the sites that must consult the key before applying a write, so any change here must be made consistently across both paths. Source: issue #58 — "Design: idempotency_key on /v1/remember (+ batch per-item keys) — agreement-#4 shared-surface issue" --- --- ## Pitfall Log Project: yantrikos/yantrikdb-server Summary: Found 25 structured pitfall item(s), including 1 high/blocking item(s). Top priority: Configuration risk - Configuration risk requires verification. ## 1. Configuration risk - Configuration risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/yantrikos/yantrikdb-server/issues/58 ## 2. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: runtime_trace - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Repro command: `docker run -p 7438:7438 ghcr.io/yantrikos/yantrikdb:latest curl -X POST http://localhost:7438/v1/remember` - Evidence: identity.distribution | https://github.com/yantrikos/yantrikdb-server ## 3. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this installation risk before relying on the project: python3.14 support missing. - User impact: Developers may fail before the first successful local run: python3.14 support missing. - Evidence: failure_mode_cluster:github_issue | https://github.com/yantrikos/yantrikdb-server/issues/43 ## 4. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/yantrikos/yantrikdb-server/issues/53 ## 5. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/yantrikos/yantrikdb-server/issues/43 ## 6. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: capability.host_targets | https://github.com/yantrikos/yantrikdb-server ## 7. Capability evidence risk - Capability evidence risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: README/documentation is current enough for a first validation pass. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: capability.assumptions | https://github.com/yantrikos/yantrikdb-server ## 8. Runtime risk - Runtime risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a runtime risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: packet_text.keyword_scan | https://github.com/yantrikos/yantrikdb-server ## 9. Maintenance risk - Maintenance risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this migration risk before relying on the project: Design: idempotency_key on /v1/remember (+ batch per-item keys) — agreement-#4 shared-surface issue - User impact: Developers may hit a documented source-backed failure mode: Design: idempotency_key on /v1/remember (+ batch per-item keys) — agreement-#4 shared-surface issue - Evidence: failure_mode_cluster:github_issue | https://github.com/yantrikos/yantrikdb-server/issues/58 ## 10. Maintenance risk - Maintenance risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this migration risk before relying on the project: Peer-sync capability exchange: make oplog format-version downgrades explicit (follow-up to #52) - User impact: Developers may hit a documented source-backed failure mode: Peer-sync capability exchange: make oplog format-version downgrades explicit (follow-up to #52) - Evidence: failure_mode_cluster:github_issue | https://github.com/yantrikos/yantrikdb-server/issues/53 ## 11. Maintenance risk - Maintenance risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/yantrikos/yantrikdb-server ## 12. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: downstream_validation.risk_items | https://github.com/yantrikos/yantrikdb-server ## 13. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: risks.scoring_risks | https://github.com/yantrikos/yantrikdb-server ## 14. Runtime risk - Runtime risk requires verification - Severity: low - Evidence strength: source_linked - Finding: Developers should check this performance risk before relying on the project: v0.8.22 - User impact: Upgrade or migration may change expected behavior: v0.8.22 - Evidence: failure_mode_cluster:github_release | https://github.com/yantrikos/yantrikdb-server/releases/tag/v0.8.22 ## 15. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: issue_or_pr_quality=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/yantrikos/yantrikdb-server ## 16. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: release_recency=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/yantrikos/yantrikdb-server ## 17. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: Developers should check this maintenance risk before relying on the project: v0.10.0 - User impact: Upgrade or migration may change expected behavior: v0.10.0 - Evidence: failure_mode_cluster:github_release | https://github.com/yantrikos/yantrikdb-server/releases/tag/v0.10.0 ## 18. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: Developers should check this maintenance risk before relying on the project: v0.8.19 - User impact: Upgrade or migration may change expected behavior: v0.8.19 - Evidence: failure_mode_cluster:github_release | https://github.com/yantrikos/yantrikdb-server/releases/tag/v0.8.19 ## 19. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: Developers should check this maintenance risk before relying on the project: v0.8.20 - User impact: Upgrade or migration may change expected behavior: v0.8.20 - Evidence: failure_mode_cluster:github_release | https://github.com/yantrikos/yantrikdb-server/releases/tag/v0.8.20 ## 20. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: Developers should check this maintenance risk before relying on the project: v0.8.21 - User impact: Upgrade or migration may change expected behavior: v0.8.21 - Evidence: failure_mode_cluster:github_release | https://github.com/yantrikos/yantrikdb-server/releases/tag/v0.8.21 ## 21. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: Developers should check this maintenance risk before relying on the project: v0.8.23 - User impact: Upgrade or migration may change expected behavior: v0.8.23 - Evidence: failure_mode_cluster:github_release | https://github.com/yantrikos/yantrikdb-server/releases/tag/v0.8.23 ## 22. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: Developers should check this maintenance risk before relying on the project: v0.8.24 - User impact: Upgrade or migration may change expected behavior: v0.8.24 - Evidence: failure_mode_cluster:github_release | https://github.com/yantrikos/yantrikdb-server/releases/tag/v0.8.24 ## 23. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: Developers should check this maintenance risk before relying on the project: v0.8.25 - User impact: Upgrade or migration may change expected behavior: v0.8.25 - Evidence: failure_mode_cluster:github_release | https://github.com/yantrikos/yantrikdb-server/releases/tag/v0.8.25 ## 24. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: Developers should check this maintenance risk before relying on the project: v0.8.26 - User impact: Upgrade or migration may change expected behavior: v0.8.26 - Evidence: failure_mode_cluster:github_release | https://github.com/yantrikos/yantrikdb-server/releases/tag/v0.8.26 ## 25. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: Developers should check this maintenance risk before relying on the project: v0.8.27 - User impact: Upgrade or migration may change expected behavior: v0.8.27 - Evidence: failure_mode_cluster:github_release | https://github.com/yantrikos/yantrikdb-server/releases/tag/v0.8.27