Struct WorkspaceManager 

pub struct WorkspaceManager { /* private fields */ }

Owns every loaded workspace plus the admission-accounting state.

Construction spawns the retention reaper task (§G.3). The handle is stored so Drop can abort it cleanly — on daemon shutdown the reaper is aborted, then the admission state drops, dropping every retained Arc<CodeGraph> in one pass. No accounting leak, no dangling Arc.

Implementations

impl WorkspaceManager

pub fn new(config: Arc<DaemonConfig>) -> Arc<Self>

Construct a fresh manager and spawn the retention reaper.

The reaper is spawned on the current Tokio runtime. Callers must therefore construct the manager from a Tokio context (#[tokio::main], an async block driven by Runtime::block_on, etc.). Tests that don’t need the reaper can use Self::new_without_reaper.

pub fn set_hook(&self, hook: SharedHook)

Install a post-publish hook. Task 9’s daemon binary calls this once at startup after constructing the shared QueryDb; unit tests call it to install a recording hook. The old hook is dropped immediately; no retention semantics apply.

pub fn memory_limit_bytes(&self) -> u64

Memory budget in bytes (derived from config.memory_limit_mb).

pub fn lookup(&self, key: &WorkspaceKey) -> Option<Arc<LoadedWorkspace>>

Look up a loaded workspace by key without acquiring rebuild_lane or admission.

Returns Some(Arc<LoadedWorkspace>) if a workspace is currently registered under key, or None otherwise. The workspaces read guard is acquired and released inside the call — callers never observe it nested with any other lock.

Added for the Task 7 crate::rebuild::RebuildDispatcher which needs a cheap handle on Arc<LoadedWorkspace> as a precondition before entering the canonical §J.4 ordered sequence (rebuild_lane → admission). This is not part of the ordered sequence itself — the §J.4 contract only constrains paths that hold more than one lock simultaneously. Here, the workspaces guard is dropped before the caller takes rebuild_lane, so there is no nesting. Shared lookup: returns the Arc<LoadedWorkspace> keyed by key if present. Used by RebuildDispatcher::handle_changes (inside the crate) and by external test harnesses (Task 7 Phase 7b1 rebuild_runner_gate.rs) that need to inspect workspace-level atomics (rebuild_in_flight, rebuild_cancelled) or the rebuild_lane mutex directly.

This is NOT a JSON-RPC surface — the IPC layer should use status() for point-in-time workspace state. Direct lookup access bypasses the LRU touch that status() performs.

pub fn reap_once(&self)

Retention reaper: a single pass over retained_old.

Removes entries whose Arc::strong_count has dropped to 1 — meaning the admission map is the last holder. Emits a one-shot WARN log line when an entry exceeds rebuild_drain_timeout_ms without dropping.

This is the only code path that removes tokens from retained_old. Any other code that mutates the retention map is a violation of §G.3.

pub fn reserve_rebuild( self: &Arc<Self>, for_key: &WorkspaceKey, working_set_estimate: u64, ) -> Result<RebuildReservation, DaemonError>

Amendment 2 §G.1 two-phase reservation protocol.

Phase 1 (workspaces read + admission read):
    project_total + estimate ≤ limit?  → commit
    otherwise                          → pick LRU non-pinned
                                         victims (`for_key` is
                                         exempt — a workspace
                                         cannot evict itself)
Phase 2 (no locks held):
    for each victim: execute_eviction()
Phase 3 (admission alone):
    re-check projected vs limit     → authoritative commit
    reserved_bytes += estimate     → return RebuildReservation

Lock order is workspaces → admission in Phase 1, nothing in Phase 2, admission alone in Phase 3. No nesting of rebuild_lane — Task 7 adds that layer outside this function.

Returns a RebuildReservation RAII guard on success. On Err, the admission state is exactly pre-call — either no eviction happened (headroom already available) or the eviction cleared retained entries but could not fit.

pub fn get_or_load( self: &Arc<Self>, key: &WorkspaceKey, builder: &dyn WorkspaceBuilder, working_set_estimate: u64, ) -> Result<Arc<CodeGraph>, DaemonError>

Load the workspace’s graph, building it via builder if not already present.

Lifecycle gate:

1. Cache-hit fast path — if the workspace is present AND in WorkspaceState::Loaded, touch + return.
2. CAS Unloaded/Evicted/Failed → Loading. Exactly one caller wins. If another caller already holds the gate (Loading/Rebuilding), return an error — Phase 6c / Task 7 will introduce a wait-for-done notify channel.
3. The winner arms a [LoadingGuard] RAII wrapper that transitions the workspace into WorkspaceState::Failed on any non-success exit (Err, early return, or panic). This covers the Codex iter-1 MAJOR that a panic from builder.build() would leave the workspace stuck in Loading.
4. Reserve admission headroom (§G.1 three-phase).
5. Build the graph via the injected builder.
6. Re-check rebuild_cancelled + workspace map membership before publishing. If eviction ran during the build, the reservation refunds via RAII and no graph is published.
7. Publish via publish_and_retain. Disarm the LoadingGuard
   • record success + touch.
8. Release workspaces_guard, THEN dispatch the post-publish SqrydHook. The hook fires outside every outer manager lock so a hook impl is free to call back into unload / get_or_load / set_hook / status without deadlocking against the loader that fired it.

Codex Task 6 Phase 6b iter-1 MAJOR (×2): the pre-fix version clobbered a concurrent eviction’s rebuild_cancelled signal and could publish into a workspace already removed from the map. The CAS + post-build re-check + LoadingGuard together close both holes.

Codex Task 6 Phase 6c iter-2 MAJOR: the pre-fix version dispatched the hook from inside publish_and_retain while the caller still held workspaces.read(), giving a hook impl that needed workspaces.write() (e.g. via unload) a guaranteed re-entrancy deadlock. Splitting publish and hook dispatch into Steps 7 and 8 closes that hole.

Errors

• DaemonError::MemoryBudgetExceeded if Phase 3 cannot admit the reservation even after LRU eviction.
• DaemonError::WorkspaceBuildFailed surfaced from the builder OR synthesised when a concurrent eviction races the load (reason = "workspace evicted mid-load").

pub fn evict_lru(&self) -> Option<WorkspaceKey>

Evict the least-recently-accessed non-pinned workspace, if any. Returns the evicted key on success, None if there are no eligible candidates.

pub fn unload(&self, key: &WorkspaceKey) -> bool

Explicitly unload a workspace. Equivalent to Self::execute_eviction but callable by the IPC daemon/unload method and sqry daemon unload <path> CLI. Returns true if the workspace was present, false if it was already absent.

pub fn find_key_and_workspace_by_path( &self, path: &Path, ) -> Option<(WorkspaceKey, Arc<LoadedWorkspace>)>

Find a loaded workspace by its directory path.

Linear scan over all registered workspaces comparing each workspace’s index_root against path. Callers (e.g. daemon/rebuild) supply a canonicalised path but not the full WorkspaceKey. O(n) in the number of loaded workspaces; in practice n is small.

Returns None if no workspace with a matching root is found.

pub fn status(&self) -> DaemonStatus

Snapshot of daemon-wide status. Point-in-time, non-transactional.

pub fn classify_for_serve( &self, key: &WorkspaceKey, now: SystemTime, ) -> Result<ServeVerdict, DaemonError>

Classify a workspace’s readiness to serve a query.

Task 7 Phase 7c. Used by the Task 8 IPC router on every query dispatch. Pure-read: no mutations, no .await (sync).

Returns

Workspace state	Map present	Result
Loaded or Rebuilding	yes	Ok(ServeVerdict::Fresh { graph, state })
Failed, age < cap (or cap == 0)	yes	Ok(ServeVerdict::Stale { graph, age_hours, last_good_at, last_error })
Failed, age >= cap	yes	Err(WorkspaceStaleExpired { age_hours, cap_hours, last_good_at, last_error }) (→ JSON-RPC -32002)
Failed, no prior good	yes	Err(WorkspaceBuildFailed { reason }) (→ -32001)
Unloaded or Loading	yes	Ok(ServeVerdict::NotReady { state })
Evicted	yes (transient window)	Err(WorkspaceEvicted) (→ -32004)
any	no	Err(WorkspaceEvicted) (→ -32004)

Lock order

Task 7 Phase 7c feat iter-1 Codex BLOCKER fix: takes workspaces.read() across the FULL snapshot — state, graph, last_good, and last_error_text are all captured inside the read critical section. Dropping the read lock before reading the graph would allow execute_eviction (which needs workspaces.write() for the full graph-swap + state-store + map-remove sequence) to interleave, surfacing the empty post-eviction placeholder graph as a Fresh verdict.

Does not acquire admission or rebuild_lane; only workspaces + per-workspace field locks. §J.4 order preserved.

Errors

Returns the variants listed in the table above.

pub fn publish_and_retain( self: &Arc<Self>, reservation: RebuildReservation, workspace: &LoadedWorkspace, new_graph: CodeGraph, ) -> (OldGraphToken, Arc<CodeGraph>)

Consume a RebuildReservation plus a freshly-built CodeGraph and atomically publish it to the workspace.

Implements Amendment 2 §G.2:

• Captures the prior Arc<CodeGraph> and memory_bytes into a [RollbackGuard] before any swap — so a panic at any point before the admission update reverts cleanly.
• Swaps the ArcSwap<CodeGraph> to the new graph.
• Swaps the per-workspace memory_bytes to the new size.
• Under the admission mutex: moves bytes_delta from reserved_bytes into loaded_bytes, inserts a RetainedEntry holding the old Arc until the retention reaper frees it.
• Disarms the [RollbackGuard] on success.

Sync fn. There is no .await between the first swap and the admission insert — tokio task cancellation can only interrupt at .await points, so this sequence is atomic with respect to cancellation per §G.2.

Returns the minted OldGraphToken for tracing / integration tests, together with an Arc<CodeGraph> handle to the freshly published graph. Per Codex Task 6 Phase 6c iter-2 MAJOR the post-publish SqrydHook dispatch is NOT performed here — firing on_publish under the workspaces.read() guard get_or_load holds across this call would nest self.hook.read() inside workspaces, giving hook impls a re-entrancy deadlock hole if they call back into manager methods needing workspaces.write(). The caller is responsible for dispatching the hook after dropping every outer workspaces-lock holder.

Trait Implementations

impl Debug for WorkspaceManager

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for WorkspaceManager

fn drop(&mut self)

Executes the destructor for this type.