Skip to content

Commit 50fbc08

Browse files
nirajgeorgiannirajgeorgian
committed
protocol: reorganize brain-protocol by business domain, drop requests/responses split
The wire-direction folder split (requests/ + responses/) was a leaky taxonomy — working on a feature meant jumping between two mirror files, and the audit found that requests/entity.rs reached backward into responses/entity.rs while EvidenceRefWire lived under statement on the request side but was imported by relation on both sides. The crate is now organized by capability. Each business domain owns one file with its request, response, and view types side by side. Wire plumbing, the dispatch enum, error taxonomy, connection-lifecycle ops, and cross-cutting shared types each live in their own focused module. Final layout (36 files down from 49): crates/brain-protocol/src/ ├── lib.rs crate root + flat re-exports ├── error.rs ErrorCategory / ErrorCode / ProtocolError ├── codec/ bytes-on-the-wire plumbing │ ├── header.rs 32-byte frame header │ ├── frame.rs Frame envelope (encode/decode) │ ├── crc.rs CRC32C helpers │ ├── rkyv.rs rkyv pipeline (was rkyv_codec.rs) │ └── opcode.rs Opcode enum + namespace helpers ├── envelope/ dispatch + ERROR frame + conversions │ ├── request.rs RequestBody + WireUuid/MemoryId/ContextId │ ├── response.rs ResponseBody │ ├── error.rs ErrorResponse + ErrorDetails (was responses/error.rs) │ └── convert.rs MemoryKind/EdgeKind ↔ wire bridges ├── connection/ connection-lifecycle ops │ ├── handshake.rs HELLO/WELCOME/AUTH/AUTH_OK + negotiate │ └── stream.rs CANCEL_STREAM / PING / PONG / SERVER_PING / BYE ├── shared/ cross-cutting wire types │ ├── primitives.rs MemoryKindWire, EdgeKindWire, PlanStrategy, PlanState, ForgetMode (was requests/types.rs) │ └── enums.rs EventType, StageKind, RetrieverNameWire, ErrorCodeWire, etc. (was responses/types.rs) ├── schema/ schema DSL parser + wire ops in one module │ ├── ast.rs, parser.rs, validator.rs, parse_error.rs (unchanged) │ └── ops.rs SCHEMA_UPLOAD/GET/LIST/VALIDATE req+resp └── ops/ per-domain wire ops ├── memory.rs ENCODE/RECALL/PLAN/REASON/FORGET/LINK/UNLINK/ENCODE_VECTOR_DIRECT ├── procedural.rs MATERIALIZE_PROCEDURAL ├── subscribe.rs SUBSCRIBE/UNSUBSCRIBE + SubscriptionEvent + KnowledgeEventPayload ├── txn.rs TXN_BEGIN/COMMIT/ABORT ├── admin.rs substrate admin ops ├── entity.rs typed-graph entity ops + EntityView ├── statement.rs typed-graph statement ops + StatementView + EvidenceRefWire family ├── relation.rs typed-graph relation ops + RelationView + TraversalPathWire ├── query.rs hybrid query ops + TimeRangeWire/RetrieverWire/FusionConfigWire └── extractor.rs EXTRACTOR_LIST/DISABLE/ENABLE Moves preserved git history via `git mv` (21 renames in this commit's status). The requests/ + responses/ directories are gone. Public API surface: every name reachable as `brain_protocol::X` before is reachable as `brain_protocol::X` now. lib.rs uses `pub use crate:: ops::<module>::*;` plus targeted re-exports for codec/envelope/ connection/shared/schema items. Downstream caller updates (per-crate count of edited import lines): - brain-ops, brain-server, brain-workers, brain-metadata, brain-extractors, brain-planner (glommio-dependent; not buildable on macOS but source updated and the rewrite passes ran) - brain-sdk-rust, brain-shell, brain-explore, brain-cli, brain-llm, brain-http, brain-embed, brain-core, brain-protocol (all pass `cargo check` on macOS) Cross-ref sweeps applied: - `brain_protocol::requests::X::Y` → flat `brain_protocol::Y` - `brain_protocol::responses::X::Y` → flat `brain_protocol::Y` - `brain_protocol::responses::types::EventType` → `brain_protocol::EventType` (and similar for RetrieverNameWire, ErrorCodeWire, InferenceKind, TransitionKind, StageKind) - `brain_protocol::requests::statement::EvidenceRefWire` → `brain_protocol::EvidenceRefWire` - `brain_protocol::responses::error::ErrorResponse` → `brain_protocol::ErrorResponse` - Internal `use crate::header::` / `frame::` / `crc::` / etc. → `use crate::codec::` - `use crate::handshake::` → `use crate::connection::handshake::` - `use crate::request::`/`response::` → `use crate::envelope::*::` - `use crate::requests::*` / `use crate::responses::*` → `use crate::ops::*::` Test + clippy results: - cargo test -p brain-protocol --lib → 205 passed (no change) - cargo test -p brain-protocol --test '*' → 37 passed (no change) - cargo clippy -p brain-protocol -- -D warnings → clean - Per-crate macOS-buildable check: clean Three deviations from the plan, all benign: - envelope/{request,response}.rs use bulk `pub use crate::ops::<mod>::*` instead of the plan's enumerated lists. Equivalent surface, less churn. - Three merged files (procedural, query, statement) had a test module in both halves. Renamed to `tests_req` + `tests_resp` so both run. - Downstream callers used singular `brain_protocol::request::` / `::response::` / `::header::` / `::handshake::` / `::opcode::` paths in addition to the deep nested ones. Added these to the sweep map so callers stay compiling. Zero hits on `brain_protocol::(requests|responses)::` across the workspace. The reorg is complete.
1 parent 0434935 commit 50fbc08

197 files changed

Lines changed: 2377 additions & 2386 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎crates/brain-cli/src/commands/extract/mod.rs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ pub enum ExtractAction {
3030
Backfill(BackfillKind),
3131
}
3232

33-
/// Mirrors `brain_protocol::requests::admin::BackfillSelector` but
33+
/// Mirrors `brain_protocol::BackfillSelector` but
3434
/// without the protocol-crate dep — the CLI only renders + transports.
3535
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
3636
pub enum BackfillKind {

‎crates/brain-core/src/nodes/statement.rs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -320,7 +320,7 @@ impl TombstoneReason {
320320
/// Pure value type. The brain-metadata storage layer holds the rkyv-
321321
/// archived form (`brain_metadata::tables::statement::StatementMetadata`);
322322
/// the wire layer holds the rkyv-archived view
323-
/// (`brain_protocol::responses::statement::StatementView`).
323+
/// (`brain_protocol::ops::statement::StatementView`).
324324
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
325325
pub struct Statement {
326326
pub id: StatementId,

‎crates/brain-explore/src/render/encode.rs‎

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@
2727
2828
use std::io::{self, Write};
2929

30-
use brain_protocol::response::EncodeResponse;
30+
use brain_protocol::envelope::response::EncodeResponse;
3131
use serde_json::{json, Value};
3232

3333
use crate::render::{
@@ -105,7 +105,7 @@ pub struct StageResult {
105105
pub summary: String,
106106
}
107107

108-
/// Stage discriminator. Mirrors `brain_protocol::responses::StageKind`
108+
/// Stage discriminator. Mirrors `brain_protocol::StageKind`
109109
/// but kept as a free enum here so the brain-explore crate doesn't
110110
/// re-export the protocol's wire type into its public surface.
111111
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
@@ -637,7 +637,7 @@ fn augment_extractor_summary(
637637
fn write_stages_row(
638638
w: &mut dyn Write,
639639
ctx: &RenderCtx,
640-
pending: &[brain_protocol::responses::StageKind],
640+
pending: &[brain_protocol::StageKind],
641641
) -> io::Result<()> {
642642
let theme = &ctx.theme;
643643
let policy = ctx.policy;
@@ -653,9 +653,9 @@ fn write_stages_row(
653653
let names: Vec<&'static str> = pending
654654
.iter()
655655
.map(|s| match s {
656-
brain_protocol::responses::StageKind::AutoEdge => "auto_edge",
657-
brain_protocol::responses::StageKind::TemporalEdge => "temporal_edge",
658-
brain_protocol::responses::StageKind::Extractor => "extractor",
656+
brain_protocol::StageKind::AutoEdge => "auto_edge",
657+
brain_protocol::StageKind::TemporalEdge => "temporal_edge",
658+
brain_protocol::StageKind::Extractor => "extractor",
659659
})
660660
.collect();
661661
let joined = names.join(" · ");
@@ -720,11 +720,11 @@ fn write_type_row(w: &mut dyn Write, ctx: &RenderCtx, r: &EncodeResponse) -> io:
720720
}
721721

722722
/// Wire variant → canonical lower-case string used in the table view.
723-
fn kind_label(k: brain_protocol::request::MemoryKindWire) -> &'static str {
723+
fn kind_label(k: brain_protocol::envelope::request::MemoryKindWire) -> &'static str {
724724
match k {
725-
brain_protocol::request::MemoryKindWire::Episodic => "episodic",
726-
brain_protocol::request::MemoryKindWire::Semantic => "semantic",
727-
brain_protocol::request::MemoryKindWire::Consolidated => "consolidated",
725+
brain_protocol::envelope::request::MemoryKindWire::Episodic => "episodic",
726+
brain_protocol::envelope::request::MemoryKindWire::Semantic => "semantic",
727+
brain_protocol::envelope::request::MemoryKindWire::Consolidated => "consolidated",
728728
}
729729
}
730730

@@ -735,7 +735,7 @@ mod tests {
735735
use crate::theme::Theme;
736736
use crate::TermPolicy;
737737
use brain_core::MemoryId;
738-
use brain_protocol::request::MemoryKindWire;
738+
use brain_protocol::envelope::request::MemoryKindWire;
739739

740740
/// Build a baseline rendered encode. Tests override the fields
741741
/// they care about so a new field never silently bypasses
@@ -1376,7 +1376,7 @@ mod tests {
13761376
// name plus a `(N pending)` count suffix.
13771377
#[test]
13781378
fn render_stages_row_lists_pending_stages() {
1379-
use brain_protocol::responses::StageKind;
1379+
use brain_protocol::StageKind;
13801380
let mut r = sample();
13811381
r.response.pending_stages = vec![
13821382
StageKind::AutoEdge,

‎crates/brain-explore/src/render/forget.rs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
33
use std::io::{self, Write};
44

5-
use brain_protocol::response::ForgetResponse;
5+
use brain_protocol::envelope::response::ForgetResponse;
66
use serde_json::{json, Value};
77

88
use crate::render::fmt_id;

‎crates/brain-explore/src/render/link.rs‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
33
use std::io::{self, Write};
44

5-
use brain_protocol::response::{LinkResponse, UnlinkResponse};
5+
use brain_protocol::envelope::response::{LinkResponse, UnlinkResponse};
66
use serde_json::{json, Value};
77

88
use crate::render::{fmt_edge_kind, fmt_id};
@@ -78,7 +78,7 @@ mod tests {
7878
use crate::format::OutputFormat;
7979
use crate::theme::Theme;
8080
use crate::TermPolicy;
81-
use brain_protocol::request::EdgeKindWire;
81+
use brain_protocol::envelope::request::EdgeKindWire;
8282

8383
fn ctx() -> RenderCtx {
8484
RenderCtx {

‎crates/brain-explore/src/render/memory.rs‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77
88
use std::io::{self, Write};
99

10-
use brain_protocol::response::MemoryResult;
10+
use brain_protocol::envelope::response::MemoryResult;
1111
use serde_json::{json, Value};
1212

1313
use crate::render::{fmt_hex_16, fmt_id, fmt_kind, fmt_short_id};
@@ -251,7 +251,7 @@ mod tests {
251251
use crate::theme::Theme;
252252
use crate::TermPolicy;
253253
use brain_core::MemoryId;
254-
use brain_protocol::request::MemoryKindWire;
254+
use brain_protocol::envelope::request::MemoryKindWire;
255255

256256
fn make_hit(text: &str, score: f32) -> MemoryResult {
257257
MemoryResult {
@@ -353,7 +353,7 @@ mod tests {
353353
// Non-empty contributing_retrievers → retrievers=N column.
354354
// A single-retriever hit (count=1) is the signal that a row
355355
// only matched one of the routed retrievers.
356-
use brain_protocol::responses::types::RetrieverNameWire;
356+
use brain_protocol::RetrieverNameWire;
357357
let mut hit = make_hit("hybrid hit", 0.9);
358358
hit.contributing_retrievers = vec![RetrieverNameWire::Semantic];
359359
let r = RecallResults(vec![hit]);

‎crates/brain-explore/src/render/mod.rs‎

Lines changed: 14 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,7 @@ use crate::util::humanize::humanize_age;
5757

5858
// ─── id formatters shared across renderers ──────────────────────
5959

60-
/// Full `0x` + 32 hex form of a [`brain_protocol::request::WireMemoryId`].
60+
/// Full `0x` + 32 hex form of a [`brain_protocol::envelope::request::WireMemoryId`].
6161
/// Used in JSON output where a tool wants the canonical id.
6262
#[must_use]
6363
pub fn fmt_id(raw: u128) -> String {
@@ -127,25 +127,25 @@ pub fn fmt_uuid(bytes: &[u8; 16]) -> String {
127127
}
128128

129129
#[must_use]
130-
pub fn fmt_kind(k: brain_protocol::request::MemoryKindWire) -> &'static str {
130+
pub fn fmt_kind(k: brain_protocol::envelope::request::MemoryKindWire) -> &'static str {
131131
match k {
132-
brain_protocol::request::MemoryKindWire::Episodic => "episodic",
133-
brain_protocol::request::MemoryKindWire::Semantic => "semantic",
134-
brain_protocol::request::MemoryKindWire::Consolidated => "consolidated",
132+
brain_protocol::envelope::request::MemoryKindWire::Episodic => "episodic",
133+
brain_protocol::envelope::request::MemoryKindWire::Semantic => "semantic",
134+
brain_protocol::envelope::request::MemoryKindWire::Consolidated => "consolidated",
135135
}
136136
}
137137

138138
#[must_use]
139-
pub fn fmt_edge_kind(k: brain_protocol::request::EdgeKindWire) -> &'static str {
139+
pub fn fmt_edge_kind(k: brain_protocol::envelope::request::EdgeKindWire) -> &'static str {
140140
match k {
141-
brain_protocol::request::EdgeKindWire::Caused => "Caused",
142-
brain_protocol::request::EdgeKindWire::FollowedBy => "FollowedBy",
143-
brain_protocol::request::EdgeKindWire::DerivedFrom => "DerivedFrom",
144-
brain_protocol::request::EdgeKindWire::SimilarTo => "SimilarTo",
145-
brain_protocol::request::EdgeKindWire::Contradicts => "Contradicts",
146-
brain_protocol::request::EdgeKindWire::Supports => "Supports",
147-
brain_protocol::request::EdgeKindWire::References => "References",
148-
brain_protocol::request::EdgeKindWire::PartOf => "PartOf",
141+
brain_protocol::envelope::request::EdgeKindWire::Caused => "Caused",
142+
brain_protocol::envelope::request::EdgeKindWire::FollowedBy => "FollowedBy",
143+
brain_protocol::envelope::request::EdgeKindWire::DerivedFrom => "DerivedFrom",
144+
brain_protocol::envelope::request::EdgeKindWire::SimilarTo => "SimilarTo",
145+
brain_protocol::envelope::request::EdgeKindWire::Contradicts => "Contradicts",
146+
brain_protocol::envelope::request::EdgeKindWire::Supports => "Supports",
147+
brain_protocol::envelope::request::EdgeKindWire::References => "References",
148+
brain_protocol::envelope::request::EdgeKindWire::PartOf => "PartOf",
149149
}
150150
}
151151

‎crates/brain-explore/src/render/plan.rs‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
99
use std::io::{self, Write};
1010

11-
use brain_protocol::response::{PlanStatus, PlanStep};
11+
use brain_protocol::envelope::response::{PlanStatus, PlanStep};
1212
use comfy_table::{Cell, Row};
1313
use serde_json::{json, Value};
1414

@@ -121,7 +121,7 @@ mod tests {
121121
use crate::format::OutputFormat;
122122
use crate::theme::Theme;
123123
use crate::TermPolicy;
124-
use brain_protocol::response::types::TransitionKind;
124+
use brain_protocol::shared::enums::TransitionKind;
125125

126126
fn ctx() -> RenderCtx {
127127
RenderCtx {

‎crates/brain-explore/src/render/reason.rs‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
33
use std::io::{self, Write};
44

5-
use brain_protocol::response::InferenceStep;
5+
use brain_protocol::envelope::response::InferenceStep;
66
use comfy_table::Cell;
77
use serde_json::{json, Value};
88

@@ -65,7 +65,7 @@ mod tests {
6565
use crate::format::OutputFormat;
6666
use crate::theme::Theme;
6767
use crate::TermPolicy;
68-
use brain_protocol::response::types::InferenceKind;
68+
use brain_protocol::shared::enums::InferenceKind;
6969

7070
fn ctx() -> RenderCtx {
7171
RenderCtx {

‎crates/brain-explore/src/render/subscribe.rs‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -7,10 +7,10 @@
77
88
use std::io::{self, Write};
99

10-
use brain_protocol::response::types::{
10+
use brain_protocol::shared::enums::{
1111
EventType, StageAuditStatus, StageExtractorPayload, StageKind, StagePayload,
1212
};
13-
use brain_protocol::response::SubscriptionEvent;
13+
use brain_protocol::envelope::response::SubscriptionEvent;
1414
use comfy_table::Cell;
1515
use serde_json::{json, Value};
1616

@@ -208,8 +208,8 @@ mod tests {
208208
use crate::theme::Theme;
209209
use crate::TermPolicy;
210210
use brain_core::MemoryId;
211-
use brain_protocol::request::MemoryKindWire;
212-
use brain_protocol::response::types::EventType;
211+
use brain_protocol::envelope::request::MemoryKindWire;
212+
use brain_protocol::shared::enums::EventType;
213213

214214
fn ctx() -> RenderCtx {
215215
RenderCtx {
@@ -250,7 +250,7 @@ mod tests {
250250

251251
#[test]
252252
fn stage_completed_extractor_renders_counts_and_status() {
253-
use brain_protocol::response::types::{
253+
use brain_protocol::shared::enums::{
254254
StageAuditStatus, StageExtractorPayload, StageKind, StageOutcome, StagePayload,
255255
};
256256

0 commit comments

Comments
 (0)