Struct MemoryService 

pub struct MemoryService { /* private fields */ }

Wraps AppState and exposes one async method per logical operation.

Why: see module docs. Lets HTTP handlers stay thin and lets non-HTTP callers (chat tool dispatch, RPC bridges) reuse the same code paths. What: Clone (cheap — only the inner AppState is shared); construct with MemoryService::new(state). Test: every method is covered by the corresponding handler test in web::tests.

Implementations

impl MemoryService

pub fn new(state: AppState) -> Self

Construct a new service wrapper.

Why: handlers cheaply re-wrap their AppState on every request; the cost is just an Arc clone, so we don’t bother caching the wrapper. What: stores the AppState for later method calls. Test: trivial — covered indirectly by every handler test.

pub fn state(&self) -> &AppState

Borrow the inner AppState.

Why: some handlers still need direct access (SSE broadcaster, session store, etc.) while we incrementally extract code into the service. What: returns a borrowed reference to the wrapped AppState. Test: not directly tested; surface-level accessor.

pub async fn status(&self) -> StatusPayload

Build the aggregate /api/v1/status payload.

Why: dashboard widgets and the MCP get_status tool need the same roll-up; centralising avoids drift between the two surfaces. What: walks every persisted palace for palace_count, then sums drawer/vector/triple counts across the cache-resident subset and returns the StatusPayload. Why (issue #4637): this used to open every persisted palace to sum those three counts. With 5,794 palaces on disk against a 64-slot LRU that is ~5,730 cold opens of ~1s each — the endpoint measurably never responded. palace_count still reflects the true on-disk total (the directory walk is cheap and now runs on the blocking pool); the totals cover only cache-resident palaces and say so via cached_palace_count. Test: status_endpoint_returns_payload, status_does_not_open_uncached_palaces.

pub fn aggregate_status_event(&self) -> DaemonEvent

Compute the aggregate StatusChanged event used by SSE consumers.

Why: mutating handlers — and the periodic status ticker — push a refreshed status snapshot so dashboards stay in sync without an extra /api/v1/status request. Why (issue #228): this used to call PalaceRegistry::list_palaces (a synchronous disk walk) + open_palace (more disk I/O on first call) for every palace on every emit. Since every persisted palace is already loaded into the in-memory registry by AppState::load_palaces_from_disk at startup (and every create_palace keeps it in sync), iterating the in-memory registry returns the same counts without touching disk. What: iterates state.registry.list() (a DashMap snapshot) and sums the live handle stats via [collect_palace_stats]. Returns a DaemonEvent::StatusChanged. Palaces that fail to resolve in the registry (race during shutdown) are silently skipped — the next emit will catch them. Test: indirectly via SSE integration tests; the math is identical to the disk-walk implementation and the status_endpoint_returns_payload test still passes against status() (which keeps the disk view for the dedicated endpoint).

pub async fn list_palaces(&self) -> ServiceResult<Vec<PalaceInfo>>

List every palace on disk, enriched with live handle stats.

Why: shared between the HTTP handler and the chat tool dispatcher; both want the same PalaceInfo shape. Issue #185 added the reserved-prefix filter so internal “system” palaces (e.g. the __health_probe__ palace used by /health) never surface in the admin UI, TUI, or any user-facing roster. What: walks the registry, drops any palace whose id starts with the reserved __ prefix, and builds a PalaceInfo per remaining row. Why (issue #4637): this used to call open_palace per row purely to enrich it with counts. At 5,794 palaces against a 64-slot LRU that is ~90 minutes of cold, blocking disk I/O inline on the async executor — and it evicted the entire working set on every call. Rows now come from PalaceRegistry::peek (zero I/O, no LRU promotion, mirroring the #1924 fix in console_metrics.rs). Uncached rows carry cached: false and zero counts; a client that needs live counts for one palace should fetch GET /api/v1/palaces/{id}, which still opens it. Test: palace_list_includes_richer_counts, palace_list_includes_graph_counts, health_probe_palace_is_invisible (in web::tests), list_palaces_does_not_open_uncached_palaces.

pub async fn create_palace( &self, body: CreatePalaceBody, source: ActivitySource, ) -> ServiceResult<String>

Create a new palace and emit the corresponding activity event.

Why: trims duplicated work between the HTTP handler and any future non-HTTP creation flow. What: validates the name, builds the Palace row, calls PalaceRegistry::create_palace, and emits PalaceCreated. Returns the new palace id. Test: covered indirectly by palace_list_includes_richer_counts (which posts a palace through the HTTP layer then reads it back).

pub async fn delete_palace( &self, palace_id: &str, force: bool, ) -> ServiceResult<()>

Delete a palace from disk, optionally rejecting non-empty palaces.

Why: Issue #180 — operators need a way to drop an entire palace without going through drawer-by-drawer deletion. Defaulting to a “must be empty” guard prevents fat-finger destruction of populated palaces; force=true is the explicit opt-in to the destructive path. What: 1) confirms the palace exists on disk (else NotFound), 2) when !force, lists drawers via the live handle and returns BadRequest("Palace has drawers; pass force=true to delete") if the palace is non-empty, 3) drops the in-memory registry entry so future opens hit the (now-missing) disk state, 4) removes <data_root>/<palace_id>/ recursively via tokio::fs::remove_dir_all, and 5) emits an aggregate StatusChanged so dashboards refresh. Test: delete_palace_removes_dir_when_empty, delete_palace_refuses_when_drawers_present, delete_palace_force_removes_populated_palace, delete_palace_returns_not_found_for_missing_id in web::tests.

pub async fn update_palace_name( &self, palace_id: &str, name: &str, ) -> Result<Value>

Rename a palace’s display name without touching its data.

Why: Operators need to fix typos and rebrand palaces without dropping the underlying drawers / vectors / KG. The palace id (the directory name on disk) is immutable — only the human-readable name field in palace.json changes — so cached PalaceHandles stay valid and no registry invalidation is required. What: 1) loads the palace via PalaceStore::load_palace (404 when the directory or palace.json is genuinely missing; a probe that cannot determine whether it is there is a 500, not a 404 — #5549), 2) trims the new name and returns BadRequest when empty, 3) mutates palace.name and writes the metadata back through the atomic PalaceStore::save_palace (tmp file + rename), 4) emits an aggregate StatusChanged so dashboards re-render the relabelled palace, 5) returns the updated palace as JSON (enriched with the live handle stats, so callers see drawer/vector/KG counts in the same shape as GET /palaces/{id}). Test: update_palace_name_renames_palace, update_palace_name_rejects_empty_name, update_palace_name_returns_not_found_for_missing_id in web::tests.

pub async fn update_palace_name_typed( &self, palace_id: &str, name: &str, ) -> ServiceResult<Value>

Typed variant of Self::update_palace_name used by the HTTP handler.

Why: HTTP needs to distinguish 400 (empty name) from 404 (missing palace) so the right status code is emitted; the chat / MCP tool only cares about a Result<Value> because both errors are surfaced as opaque MCP error strings. Keeping a typed variant alongside the untyped one keeps the wire shape correct on both surfaces without asking either caller to parse error strings. What: same as Self::update_palace_name but returns ServiceError::BadRequest for empty names and ServiceError::NotFound for palace metadata that is genuinely absent. Metadata whose presence cannot be determined — a denied or transient stat — is ServiceError::Internal: a 404 would tell the client the palace does not exist when nobody established that (#5549, ADR-0045). Test: update_palace_name_renames_palace, update_palace_name_rejects_empty_name, update_palace_name_returns_not_found_for_missing_id, update_palace_name_reports_an_unstattable_palace_as_internal.

pub async fn get_palace(&self, id: &str) -> ServiceResult<PalaceInfo>

Look up a single palace by id and enrich with live handle stats.

Why: distinct 404 vs. 500 path is needed by both HTTP and chat callers. What: returns NotFound when the id is unknown, otherwise a fully populated PalaceInfo. Test: indirectly via health_endpoint_round_trip_with_palace_is_ok.

pub async fn list_drawers( &self, id: &str, q: ListDrawersQuery, ) -> ServiceResult<Value>

List drawers in a palace with optional room/tag filters and pagination.

Why: deduplicates the open-handle + listing path between HTTP and chat, and (issue #184) lets the TUI activity panel page through drawers in creation-date order without breaking the importance-sorted default the legacy callers rely on. What: opens the palace handle, fetches a window of drawers, optionally re-sorts by created_at descending when sort = "created_desc" (leaving the importance-desc default untouched), then drops the leading offset rows and keeps limit. For created_desc the window must cover the full filtered set (otherwise the importance pre-sort hides truly-recent low-importance drawers), so the window is widened to a sane ceiling (MAX_DRAWER_WINDOW); the default importance path keeps a tight limit+offset window. Returns the serialised JSON array. Test: service::tests::list_drawers_creates_desc_paginates.

pub async fn create_drawer( &self, id: &str, body: CreateDrawerBody, creator: CreatorInfo, source: ActivitySource, ) -> ServiceResult<Uuid>

Store a new drawer and emit the matching activity events.

Why: HTTP and chat both need the auto-KG-extraction follow-up; this method keeps that side-effect chain in one place. What: opens the palace, stores the drawer via PalaceHandle::remember_with_options (issue #3225: body.force threads through as RememberOptions::force, letting a caller bypass the QUALITY gates only — allow_secret_like is left at its default false, so secret detection always still runs, force or not), emits DrawerAdded + StatusChanged, then triggers tools::auto_extract_and_assert. Returns the new drawer id. Test: http_create_drawer_runs_auto_kg_extraction, create_drawer_rejects_json_content_without_force, create_drawer_force_bypasses_quality_gate_for_json_content.

pub async fn delete_drawer( &self, id: &str, drawer_id: &str, source: ActivitySource, ) -> ServiceResult<()>

Forget (delete) a drawer and emit the matching events.

Why: same dedup story as create_drawer. #5231: DELETE on a drawer id that was never stored used to answer 204 No Content, the same as a real delete — this now 404s, matching delete_palace. What: parses the drawer UUID, calls PalaceHandle::forget, deletes the drawer’s BM25 document, maps ForgetOutcome::NotFound to ServiceError::not_found, and emits DrawerDeleted only when a drawer was actually removed. #5053: the lexical delete runs on this path for the same reason it runs on the MCP one — HTTP DELETE and memory_forget remove the same drawer, and the backfill indexes it whichever way it was written, so a lexical copy left here is the same stale document. Test: delete_drawer_404s_for_an_unknown_drawer_id; tests/bm25_forget_delete.rs covers the deletion contract itself.

pub async fn recall( &self, id: &str, query: &str, top_k: usize, deep: bool, ) -> ServiceResult<Value>

Per-palace recall (semantic search), optionally with deep retrieval.

Why: HTTP and chat tools both perform the same fan-out logic. What: opens the palace handle and dispatches to the shallow or deep recall helper. Returns a JSON array of flattened drawer rows (the recall_entry_json shape from issue #69). Test: recall_entry_json_hoists_drawer_fields.

pub async fn recall_all(&self, query: &str, top_k: usize, deep: bool) -> Value

Cross-palace recall.

Why: shared between /api/v1/recall and the memory_recall_all chat tool. Encapsulating the open-everything-fanout-merge dance avoids drift. What: lists every palace, opens handles (skipping failures with a tracing::warn!), delegates to recall_across_palaces_with_default_embedder. Returns a JSON array. Why (issue #4637): unlike list_palaces/status, this route is NOT converted to peek(). A cross-palace recall that answered from cache-resident palaces only would silently omit ~98.9% of the corpus — a wrong answer that looks like a right one, which is strictly worse than a slow correct one. The open loop keeps opening every palace; it just no longer does so inline on a tokio worker thread. Making this route actually fast needs a different design (a shared cross-palace index, or an explicit palace-scoped query), not a cache-only read. Test: indirectly via recall_across_palaces_merges_results and the MCP memory_recall_all integration paths; open_palaces_blocking_opens_every_palace pins that uncached palaces are still searched.

impl MemoryService

pub async fn kg_query( &self, id: &str, subject: &str, ) -> ServiceResult<Vec<Triple>>

Query the KG for all active triples whose subject matches.

pub async fn kg_assert(&self, id: &str, body: KgAssertBody) -> ServiceResult<()>

Assert a triple in the KG.

Assert a triple through POST /api/v1/palaces/{id}/kg.

Why: #4888 — this accepts an arbitrary predicate, so it can write a hot one and must carry the same Tier S gate as the MCP tool. Not a hypothetical path: trusty-mpm’s provisioner seeds its identity fact through exactly this endpoint. #5524 — it also owed the prompt-cache rebuild and never ran it, so a hot fact written here was stored and then invisible to every later turn until some unrelated write rebuilt the cache. What: delegates the whole admission → assert → refresh sequence to crate::kg_write::assert_triple. The variant split is what lets this keep answering 400 for a refused write and 500 for a failed one. Test: http_kg_assert_endpoint_refreshes_prompt_cache, http_kg_assert_endpoint_rejects_over_long_tier_s_object in web::tests::prompt_tests.

pub async fn kg_retract_triple( &self, id: &str, subject: &str, predicate: &str, object: &str, ) -> ServiceResult<usize>

Close the one active triple (subject, predicate, object), leaving every sibling object at that pair active. Returns the rows closed.

Why: Issue #278 — the DELETE /kg/triples/<id> HTTP endpoint needs a service-layer method so the HTTP handler stays a thin adapter. It took no object and called the pair-level KnowledgeGraph::retract, whose meaning is “close every active row at this pair”, so a caller deleting one triple lost the siblings it never named. Retraction is a soft close — close_active_row copies the row to a hist: key first — so the damage was recoverable, not silent data loss. What: Opens the palace handle and calls trusty_common::memory_core::store::kg::KnowledgeGraph::retract_triple, which keys on all three fields. Returns the closed count so the caller can tell a retraction (1) from a miss (0); a miss is a genuine no-op, which makes the call idempotent. Rebuilds the prompt cache when a hot-predicate row was actually closed — otherwise a retracted Tier S fact keeps being injected until the next write. This mirrors the kg_retract_triple MCP tool so both surfaces agree. Test: kg_delete_triple_closes_one_object_and_keeps_siblings, kg_delete_triple_returns_404_for_missing, kg_delete_triple_rebuilds_prompt_cache_for_hot_predicate in web::tests. Only the third reaches the cache rebuild — the other two retract under the predicate is, which is not hot.

pub async fn kg_list_subjects( &self, id: &str, limit: usize, ) -> ServiceResult<Vec<String>>

List distinct subjects in the KG.

pub async fn kg_list_subjects_with_counts( &self, id: &str, limit: usize, ) -> ServiceResult<Vec<(String, u64)>>

List distinct subjects in the KG paired with their active-triple count.

pub async fn kg_list_all( &self, id: &str, limit: usize, offset: usize, ) -> ServiceResult<Vec<Triple>>

Page through every active triple.

pub async fn kg_count(&self, id: &str) -> ServiceResult<usize>

Return the count of currently-active triples.

#5384: a failed count read is a 500, not {"active": 0} — the badge this feeds cannot tell those apart.

pub async fn kg_graph(&self, id: &str) -> ServiceResult<KgGraphPayload>

Build the per-palace visual graph payload.

Why (issue #4670): the node_count / edge_count / community_count here are computed over the FULL adjacency while triples is capped at [KG_GRAPH_MAX_TRIPLES]. That mismatch used to be invisible — the UI rendered 5,000 triples under a “9,311 nodes” badge — and because list_active orders by valid_from DESC the dropped triples were silently the oldest. The payload now reports what it actually returned alongside what exists, so truncation is machine-detectable. What: unchanged query; adds returned_triple_count, active_triple_count, and the derived truncated flag. Test: kg_graph_signals_truncation, kg_graph_returns_active_triples.

pub async fn kg_graph_with_cap( &self, id: &str, max_triples: usize, ) -> ServiceResult<KgGraphPayload>

Self::kg_graph with an explicit triple cap.

Why (issue #4670): the truncation-signalling branch is only reachable above KG_GRAPH_MAX_TRIPLES (5,000), and seeding 5,001 triples costs ~90 s of test time — expensive enough that the branch would in practice go untested. Taking the cap as a parameter makes it provable with five triples and a cap of three, at no cost to the production call path. What: the real implementation; kg_graph is a thin wrapper that passes the production constant. Test: kg_graph_signals_truncation.

pub async fn kg_graph_seed( &self, id: &str, limit: usize, ) -> ServiceResult<KgSeedPayload>

Top-limit nodes by degree plus the edges among them (issue #4670).

Why: first paint must show the graph’s skeleton, not 9,311 nodes in an O(n²) layout. Measured on the live 8,266-triple palace, 90.2% of nodes are degree-1 leaves and only 7.2% have degree >= 5, so a top-degree slice carries essentially all of the visible structure and everything else stays one click away. What: runs KnowledgeGraph::top_degree_subgraph over the resident adjacency (O(V log V + E), no disk I/O) and pairs the result with the palace-wide totals the header needs to report honestly. Test: kg_graph_seed_ranks_by_degree, kg_graph_seed_clamps_limit.

pub async fn kg_neighbors( &self, id: &str, node: &str, direction: ExpandDirection, max_hops: usize, ) -> ServiceResult<KgNeighborsPayload>

Direction-aware, hop-bounded expansion around one node (issue #4670).

Why: click-to-expand needs “what points AT this node”, which no HTTP endpoint could answer — kg_query is a subject prefix scan. Bounding the hops keeps one click on a hub from pulling the whole palace. What: delegates to KnowledgeGraph::expand_neighbors. direction and max_hops are already validated/clamped by the HTTP layer; they are echoed back so the client can see what actually ran. Test: kg_neighbors_returns_incoming_edges, kg_neighbors_clamps_max_hops.

pub async fn dream_status_aggregate(&self) -> DreamStatusPayload

Aggregate dream stats across every persisted palace.

pub async fn dream_status_for_palace( &self, id: &str, ) -> ServiceResult<DreamStatusPayload>

Per-palace dream stats snapshot.

pub async fn dream_run(&self) -> ServiceResult<DreamStatusPayload>

Run a dream cycle across every palace.

Why (issue #4637): like recall_all, this route is deliberately NOT converted to PalaceRegistry::peek. Dreaming is a maintenance pass — consolidating only the 64 palaces that happen to be cache-resident would silently stop maintaining the other ~5,730, which is a worse failure than a slow run because nothing reports it. Opening every palace stays correct; what changes is that the blocking open no longer runs inline on a tokio worker thread. A long dream run is expected — this is an explicitly-triggered POST, not a page load. What: lists palaces on the blocking pool, then per palace hops to spawn_blocking for the open before awaiting the async dream cycle. Test: dream_run_aggregates_stats.

pub async fn list_activity( &self, filter: ActivityFilter, limit: usize, offset: usize, ) -> ServiceResult<(Vec<ActivityEntry>, u64)>

Paginated activity-log read.

pub fn open_handle(&self, id: &str) -> ServiceResult<Arc<PalaceHandle>>

Open the named palace.

Why (#5549, ADR-0045): this mapped every open_palace failure to NotFound, which the HTTP layer renders as 404. A denied or transient read of palace.json, undecodable metadata, an open-queue timeout, or a redb write-lock conflict then all reported that the palace does not exist — erasing at the caller the distinction load_palace draws, and across a much wider surface than the two rename paths: every /api/v1/palaces/{id}/kg* endpoint, the drawer CRUD routes, and per-palace recall reach this one helper. What: returns ServiceError::NotFound only when PalaceRegistry::open_error_is_absent confirms the palace is genuinely not there, and ServiceError::Internal (500) otherwise. Test: unreadable_palace_is_500_not_404_at_the_service_open_handle, unstattable_palace_is_500_not_404_at_the_service_open_handle, absent_palace_is_still_404_at_both_open_handles.

Trait Implementations

impl Clone for MemoryService

fn clone(&self) -> MemoryService

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.