ijima_core/
palace.rs

1// Copyright (C) 2026 Industrial Algebra
2// SPDX-License-Identifier: Apache-2.0
3
4//! Palace organization types — the navigational views over a namespace's
5//! memory palace (Phase 3.1 + 3.2).
6//!
7//! These are pure aggregations over stored memories' `project` and `topic`
8//! fields. No new storage; they let an agent *browse* the shape of its own
9//! palace: which rooms (topics) exist, how projects are taxonomized, and which
10//! projects connect via shared topics (tunnels).
11
12use crate::Memory;
13
14/// A room is a single `(project, topic)` cell with its memory count.
15///
16/// Mirrors pi-mempalace's "room" concept: a topic within a project.
17#[derive(Debug, Clone, PartialEq, Eq)]
18#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
19pub struct Room {
20    /// The project this room lives under.
21    pub project: String,
22    /// The topic (room name).
23    pub topic: String,
24    /// Memories in this room.
25    pub count: usize,
26}
27
28/// One project's taxonomy: its rooms (topics) with counts, plus a total.
29#[derive(Debug, Clone, PartialEq, Eq)]
30#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
31pub struct ProjectTaxon {
32    /// The project name.
33    pub project: String,
34    /// Rooms under this project, ordered by count desc then topic.
35    pub rooms: Vec<Room>,
36    /// Total memories across this project's rooms.
37    pub total: usize,
38}
39
40/// A topic tunnel connecting two projects.
41///
42/// A tunnel exists when two distinct projects both have memories tagged
43/// with the same topic — the topic is the shared concern that connects
44/// them (e.g. `auth`, `database`, `architecture`).
45#[derive(Debug, Clone, PartialEq, Eq)]
46#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
47pub struct Tunnel {
48    /// The shared topic forming the tunnel.
49    pub topic: String,
50    /// First project.
51    pub project_a: String,
52    /// Second project.
53    pub project_b: String,
54    /// Memory count in `project_a` on this topic.
55    pub count_a: usize,
56    /// Memory count in `project_b` on this topic.
57    pub count_b: usize,
58}
59
60/// The palace graph: projects as nodes, shared-topic tunnels as edges.
61///
62/// Powers `getPalaceGraph` — *"what connects these projects?"*
63#[derive(Debug, Clone, Default, PartialEq, Eq)]
64#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
65pub struct PalaceGraph {
66    /// Distinct project names (graph nodes).
67    pub projects: Vec<String>,
68    /// Topic tunnels between projects (graph edges).
69    pub tunnels: Vec<Tunnel>,
70}
71
72/// The result of traversing a tunnel between two projects via a shared
73/// topic: the actual memories from both sides, so the caller can see what
74/// connects them.
75#[derive(Debug, Clone, PartialEq)]
76#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
77pub struct TunnelTraversal {
78    /// The traversed topic.
79    pub topic: String,
80    /// First project.
81    pub project_a: String,
82    /// Second project.
83    pub project_b: String,
84    /// Memories in `project_a` on this topic (importance-ranked).
85    pub memories_a: Vec<Memory>,
86    /// Memories in `project_b` on this topic (importance-ranked).
87    pub memories_b: Vec<Memory>,
88}
ijima_core/palace.rs

ijima_core/
palace.rs
