Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
//! A process-shared pointer to the project the user is currently active in.
//!
//! ## Why this exists (issue #2)
//!
//! The MCP protocol carries no working-directory context: a `memory_query`
//! call arrives with its arguments and nothing else, so a tool handler has
//! no way to know which project the agent is sitting in. The lifecycle hooks
//! *do* know — lifecycle `/hook` events carry the agent's `cwd`, and the hook
//! router resolves it to the correct per-cwd `(workspace_id, project_id)`.
//!
//! In HTTP mode the `/hook` ingress and the `/mcp` endpoint live in the same
//! process, so the hook router can publish "the project the user is currently
//! active in" to this shared pointer when work starts or advances, and the MCP
//! tools can read it as their default instead of falling back to the server's
//! static `--project` (which defaults to `scratch` and made the read tools
//! return empty memory even when the hooks were correctly populating a real
//! project). Completion events refresh exact actor-scoped entries only; a
//! delayed tail from an older session must not redirect a shared fallback.
//!
//! ## Isolation modes
//!
//! The `Single` mode keeps the pre-v1.39 behaviour — one process-wide slot,
//! last-write-wins. That is right for a single operator running
//! one project at a time, but collapses parallel sessions on shared installs:
//! a hook firing from `~/repo-A` overwrites the slot a concurrent
//! `memory_query` (with no explicit project) in `~/repo-B` was about to read.
//!
//! The `PerActor` (default) and `PerSession` isolation modes keep a per-key
//! map alongside the single slot:
//!
//! - `PerSession` keys by `session_id` — isolates concurrent agent runs of
//! the same operator (one person with several Claude Code / Codex windows
//! in different repos at once).
//! - `PerActor` keys by `(user, session_id)` when both coordinates are present
//! and also keeps a user-only slot for requests that truly have no session
//! coordinate. That isolates across operators while preserving per-session
//! isolation for clients/bridges that do forward one. Pairs with multi-user
//! mode (rung 2): `user` comes from the `users` row that owns the bearer
//! token.
//!
//! When the caller has no actor identity at all (anonymous request without a
//! session, or a code path the migration has not threaded yet), every mode
//! falls back to the single slot for backward compatibility. That is a legacy
//! convenience, not isolation. If a request provides a usable actor coordinate
//! and the keyed lookup misses, `get_for` returns `None` instead of falling
//! through to another session's latest project; callers then use their baked
//! default or an explicit workspace/project. The single slot is also what the
//! historical `set` / `get` / `clear` API touches, so existing callers compile
//! unchanged and admin ops like `move-project` still invalidate the pointer
//! correctly.
//!
//! ## Memory bound
//!
//! Per-key entries carry an [`Instant`] insertion timestamp and are evicted
//! on read or write once they exceed the configured TTL (default 1 hour).
//! A hard `max_entries` cap (default 4096) drops the oldest entries when
//! exceeded, so an adversarial / runaway client cannot grow the map without
//! bound. Both knobs are exposed via the CLI's `[auto_scope]` config block.
//!
//! ## Locking
//!
//! Locks are held only for the microseconds it takes to copy a small tuple
//! or do a single hash lookup; callers never `.await` while holding them, so
//! plain `std::sync::RwLock` is the right primitive (no async lock needed).
use std::collections::HashMap;
use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::{Arc, RwLock};
use std::time::{Duration, Instant};
use serde::{Deserialize, Serialize};
use crate::ids::{ProjectId, WorkspaceId};
/// Default TTL for per-key entries in the `PerActor` and `PerSession`
/// isolation modes.
pub const DEFAULT_PER_KEY_TTL: Duration = Duration::from_secs(60 * 60);
/// Default upper bound on per-key entries, to keep memory finite on shared
/// installs where many short-lived sessions may come and go.
pub const DEFAULT_MAX_ENTRIES: usize = 4096;
/// Selects how the hook router and the MCP tools share the "currently active
/// project" pointer.
///
/// `PerActor` is the default: it keys the pointer by whatever coordinate the
/// caller actually has, so parallel harnesses and multiple operators stay
/// separated without configuration. A caller carrying no coordinate at all
/// still reads the shared slot, which is what keeps a single-harness install
/// behaving exactly as it always has.
///
/// `Single` remains available for installs that want the historical
/// process-wide slot explicitly.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ActiveProjectMode {
/// Process-wide slot, last-write-wins. The historical behaviour, now opt-in.
Single,
/// Keyed by `session_id`. Isolates concurrent agent runs of the same
/// operator from each other.
PerSession,
/// Keyed by `(user, session_id)`, with an identity-only slot alongside.
/// Isolates parallel harnesses and separate operators. The default.
#[default]
PerActor,
}
/// Selects how the hook router attributes MID-SESSION events whose cwd has
/// moved since the session started. Set under `[routing] mid_session`.
///
/// Distinct from [`ActiveProjectMode`], which namespaces the in-process
/// "current project" pointer: this decides the DURABLE project written on
/// observations, and it never affects session-CREATING events — opening a
/// session always resolves from its own cwd.
///
/// `FollowCwd` is the default and preserves the historical behavior exactly:
/// every mid-session event re-resolves from its own cwd, so `cd`-ing into a
/// sibling checkout routes those observations to that checkout's project.
///
/// `Sticky` treats mid-session navigation as navigation: the session's project
/// stays the source of truth wherever the agent wanders. This matches the
/// product's own model — `sessions.project_id` holds exactly one value, and
/// consolidation writes one page in the session's project — so following the
/// cwd splits a session's raw record across projects while its page lands in
/// only one. A `.ai-memory.toml` marker still wins in both modes: naming a
/// project is a deliberate rescope, not drift (#394).
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum MidSessionRouting {
/// Re-resolve every mid-session event from its own cwd. Historical
/// behavior, and the default.
#[default]
#[serde(alias = "follow_cwd")]
FollowCwd,
/// Inherit the session's project for every mid-session event, overruling
/// a host-derived repo-root override but never a marker-declared one.
Sticky,
}
impl MidSessionRouting {
/// Whether this mode lets an established session overrule a
/// non-deliberate (host-derived) project override.
#[must_use]
pub const fn overrules_derived_override(self) -> bool {
matches!(self, Self::Sticky)
}
/// Stable config/log representation.
#[must_use]
pub const fn as_str(self) -> &'static str {
match self {
Self::FollowCwd => "follow-cwd",
Self::Sticky => "sticky",
}
}
}
/// Composite identity used to key per-actor entries.
/// This cache key namespaces active-project pointers only; it does not
/// namespace durable hook `SessionId` records.
///
/// - `PerSession` mode populates only `session_id`.
/// - `PerActor` mode populates both (`user` holds the qualified identity key:
/// `user:<name>` or an issuer-qualified OIDC subject).
///
/// An [`ActorKey`] with both fields `None` is treated the same as "no actor"
/// — the request falls back to the single slot. That keeps anonymous /
/// pre-identity callers working without a special branch at every call site.
#[derive(Debug, Clone, Default, PartialEq, Eq, Hash)]
pub struct ActorKey {
/// Qualified stable identity when the request was authenticated as a known
/// user. The field name is retained for API compatibility; values are
/// produced by `ActorContext::identity_key`, not copied from raw headers.
pub user: Option<String>,
/// Per-agent-run session identifier published by the lifecycle hooks
/// (Claude Code, Codex, OpenCode, …). `None` when the call site has no
/// session context (e.g. an ad-hoc MCP probe with no hook history).
pub session_id: Option<String>,
}
/// Outcome of resolving the active-project pointer for one actor.
///
/// Distinguishes the two cases [`ActiveProject::get_for`] returns `None` for,
/// which callers that *write* need to tell apart.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ActiveProjectLookup {
/// The pointer resolved to a concrete workspace/project.
Resolved(WorkspaceId, ProjectId),
/// The actor carries a coordinate, this install's pointer is live, and
/// nothing matched it. Answering from the shared slot or the server default
/// would route the call somewhere the caller did not mean.
Mismatch,
/// No pointer information exists anywhere for this caller — an anonymous or
/// legacy call site, or an install with no lifecycle hooks feeding the
/// pointer. The configured default is the best and only answer.
Unset,
}
/// Outcome of [`ActiveProject::read_pointer`]: the read-path answer and the
/// source that gave it.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ReadPointer {
/// The caller's own keyed entry.
Session(WorkspaceId, ProjectId),
/// The process-wide slot — whichever project published last. What a
/// caller with no coordinate reads, and every caller in `single` mode.
SharedSlot(WorkspaceId, ProjectId),
/// The startup seed (#678), standing in until the first hook event.
StartupSeed(WorkspaceId, ProjectId),
/// The caller carries a coordinate that matched no live hook session.
Mismatch,
/// No pointer information exists for this caller.
Unset,
}
impl ReadPointer {
/// The resolved ids, if any source gave one.
#[must_use]
pub fn ids(self) -> Option<(WorkspaceId, ProjectId)> {
match self {
Self::Session(workspace_id, project_id)
| Self::SharedSlot(workspace_id, project_id)
| Self::StartupSeed(workspace_id, project_id) => Some((workspace_id, project_id)),
Self::Mismatch | Self::Unset => None,
}
}
}
impl ActiveProjectLookup {
fn from_single(slot: Option<(WorkspaceId, ProjectId)>) -> Self {
match slot {
Some((workspace_id, project_id)) => Self::Resolved(workspace_id, project_id),
None => Self::Unset,
}
}
}
impl ActorKey {
/// `true` when neither identity coordinate is present — used to short-
/// circuit the per-key map and fall back to the single slot.
#[must_use]
pub fn is_empty(&self) -> bool {
self.user.is_none() && self.session_id.is_none()
}
}
/// One per-actor slot: the resolved project plus the actor's opted-in
/// `default_global` recall preference and the insertion time (for TTL).
#[derive(Debug, Clone, Copy)]
struct Entry {
ws: WorkspaceId,
proj: ProjectId,
default_global: bool,
inserted: Instant,
}
#[derive(Debug)]
struct PerActorMap {
entries: HashMap<ActorKey, Entry>,
ttl: Duration,
max_entries: usize,
}
impl PerActorMap {
fn new(ttl: Duration, max_entries: usize) -> Self {
Self {
entries: HashMap::new(),
ttl: if ttl.is_zero() {
DEFAULT_PER_KEY_TTL
} else {
ttl
},
max_entries: max_entries.max(1),
}
}
/// Drop expired entries. Run on every read + write so a stale key never
/// surfaces to a tool handler and the cap below sees an accurate size.
fn purge_expired(&mut self, now: Instant) {
self.entries
.retain(|_, e| now.saturating_duration_since(e.inserted) < self.ttl);
}
/// Cap the map at `max_entries`, dropping the oldest insertions first.
/// O(n log n) when over the cap; called only at insertion time, so the
/// amortised cost is well below the hash insertion itself.
fn enforce_cap(&mut self) {
if self.entries.len() <= self.max_entries {
return;
}
let excess = self.entries.len() - self.max_entries;
let mut by_age: Vec<(ActorKey, Instant)> = self
.entries
.iter()
.map(|(k, e)| (k.clone(), e.inserted))
.collect();
by_age.sort_by_key(|(_, inserted)| *inserted);
for (k, _) in by_age.into_iter().take(excess) {
self.entries.remove(&k);
}
}
fn insert(
&mut self,
key: ActorKey,
ws: WorkspaceId,
proj: ProjectId,
default_global: bool,
now: Instant,
) {
self.purge_expired(now);
self.entries.insert(
key,
Entry {
ws,
proj,
default_global,
inserted: now,
},
);
self.enforce_cap();
}
fn get(&mut self, key: &ActorKey, now: Instant) -> Option<(WorkspaceId, ProjectId)> {
self.purge_expired(now);
self.entries.get(key).map(|e| (e.ws, e.proj))
}
/// The actor's opted-in `default_global` preference, or `false` when no
/// live entry exists for the key.
fn get_default_global(&mut self, key: &ActorKey, now: Instant) -> bool {
self.purge_expired(now);
self.entries.get(key).is_some_and(|e| e.default_global)
}
fn retarget_project(&mut self, project_id: ProjectId, workspace_id: WorkspaceId, now: Instant) {
self.purge_expired(now);
for e in self.entries.values_mut() {
if e.proj == project_id {
e.ws = workspace_id;
}
}
}
fn clear_project(&mut self, project_id: ProjectId, now: Instant) {
self.purge_expired(now);
self.entries.retain(|_, e| e.proj != project_id);
}
fn clear_workspace(&mut self, workspace_id: WorkspaceId, now: Instant) {
self.purge_expired(now);
self.entries.retain(|_, e| e.ws != workspace_id);
}
fn contains_project(&mut self, project_id: ProjectId, now: Instant) -> bool {
self.purge_expired(now);
self.entries.values().any(|e| e.proj == project_id)
}
fn contains_workspace(&mut self, workspace_id: WorkspaceId, now: Instant) -> bool {
self.purge_expired(now);
self.entries.values().any(|e| e.ws == workspace_id)
}
/// Test-only: live row count in the backing HashMap. Counts all
/// rows, including ones whose TTL has elapsed (those are dropped
/// by `purge_expired` on the next read/write). The randomised cap
/// test uses this to verify `enforce_cap` keeps the storage bounded
/// at every step regardless of when expiry sweeps run.
#[cfg(test)]
fn raw_len(&self) -> usize {
self.entries.len()
}
}
/// Cheap, cloneable handle to the shared "currently active project" pointer.
///
/// Clones share the same underlying state. Starts empty; the hook router
/// fills it as events arrive.
#[derive(Clone)]
pub struct ActiveProject {
mode: ActiveProjectMode,
single: Arc<RwLock<Option<(WorkspaceId, ProjectId)>>>,
/// `default_global` for the single/fallback slot (Single mode or an actor
/// with no usable coordinate). Kept beside `single` rather than inside the
/// tuple so the legacy `set`/`get` API and every existing caller stay
/// byte-for-byte unchanged.
single_default_global: Arc<RwLock<bool>>,
per_actor: Arc<RwLock<PerActorMap>>,
/// Whether any keyed entry has ever been published on this process.
///
/// Distinguishes "this install has no lifecycle hooks, so nothing was ever
/// keyed" from "hooks are running and this key simply does not match".
/// The first deserves the shared fallback — there is no better information
/// anywhere — while the second is a mismatch that must fail closed rather
/// than answer for whichever project published last.
///
/// Never reset: an install that once had hook activity is not hookless
/// again just because entries aged out of the TTL map.
ever_keyed: Arc<AtomicBool>,
/// A startup reconstruction of the shared slot, consulted by READS only.
///
/// The pointer is process memory, so a restart mid-session empties it and
/// unscoped reads answered for the baked default scope — zero counts for a
/// project full of observations, through the success path (#678). `serve`
/// fills this slot at startup from the most recently active project on
/// disk so those reads degrade to real data instead.
///
/// It is deliberately NOT the single slot. A seeded value is a
/// reconstruction, not an observed publish: writing it to `single` would
/// make [`Self::lookup_for`] answer `Resolved` for every caller until the
/// first hook event lands, including one whose coordinate matches nothing
/// — and an unscoped write would then be attributed to a project the
/// caller never named, possibly another operator's. That is exactly the
/// misfiling the `Mismatch`/`Unset` split exists to prevent, so the write
/// path never sees this slot.
seeded: Arc<RwLock<Option<(WorkspaceId, ProjectId)>>>,
}
impl Default for ActiveProject {
fn default() -> Self {
Self::with_config(
ActiveProjectMode::default(),
DEFAULT_PER_KEY_TTL,
DEFAULT_MAX_ENTRIES,
)
}
}
impl ActiveProject {
/// Create an empty pointer in the shipped default mode
/// ([`ActiveProjectMode::PerActor`]).
///
/// Was `Single` before v1.39. Call [`Self::with_mode`] explicitly for the
/// historical process-wide slot.
#[must_use]
pub fn new() -> Self {
Self::default()
}
/// Create an empty pointer in the given mode, using the default TTL +
/// cap for the per-key backing map.
#[must_use]
pub fn with_mode(mode: ActiveProjectMode) -> Self {
Self::with_config(mode, DEFAULT_PER_KEY_TTL, DEFAULT_MAX_ENTRIES)
}
/// Full-fidelity constructor used by the CLI's `serve` wiring and by
/// unit tests that need to exercise eviction.
#[must_use]
pub fn with_config(mode: ActiveProjectMode, ttl: Duration, max_entries: usize) -> Self {
Self {
mode,
single: Arc::new(RwLock::new(None)),
single_default_global: Arc::new(RwLock::new(false)),
per_actor: Arc::new(RwLock::new(PerActorMap::new(ttl, max_entries))),
ever_keyed: Arc::new(AtomicBool::new(false)),
seeded: Arc::new(RwLock::new(None)),
}
}
/// The mode this handle was built with. Mostly useful for tests and for
/// observability (the `serve` startup log records it once).
#[must_use]
pub fn mode(&self) -> ActiveProjectMode {
self.mode
}
/// The effective TTL of a per-key entry, after the zero-means-default
/// normalization the backing map applies.
///
/// `serve` uses it as the recency bound when it seeds the single-slot
/// fallback from disk at startup (#678): activity older than this would
/// have aged out of the live pointer anyway, so it must not come back
/// through the restart path either.
#[must_use]
pub fn per_key_ttl(&self) -> Duration {
self.per_actor.read().unwrap_or_else(|e| e.into_inner()).ttl
}
/// Publish the project the agent is currently active in. Called by the
/// hook router after it resolves an event's `cwd` to a real project.
///
/// The actor's identity steers which slot is updated:
/// - In `Single` mode, the process-wide slot is overwritten.
/// - In `PerSession` / `PerActor`, the entry keyed by the actor is set
/// *and* the single slot is updated as well, so callers that have no
/// actor identity (anonymous probes, legacy code paths) still see the
/// latest project rather than an empty pointer.
/// - In `PerActor`, a user-only entry is also set when `user` is present.
/// Requests that carry that user but no session id can still resolve to
/// the user's latest project without falling through to the global slot.
pub fn set_for(
&self,
actor: &ActorKey,
workspace_id: WorkspaceId,
project_id: ProjectId,
default_global: bool,
) {
self.write_single(workspace_id, project_id);
self.write_single_default_global(default_global);
if self.mode == ActiveProjectMode::Single || actor.is_empty() {
return;
}
let scoped = self.scoped_key(actor);
if scoped.is_empty() {
return;
}
let mut guard = self.per_actor.write().unwrap_or_else(|e| e.into_inner());
self.ever_keyed.store(true, Ordering::Relaxed);
if self.mode == ActiveProjectMode::PerActor
&& actor.user.is_some()
&& actor.session_id.is_some()
{
guard.insert(
ActorKey {
user: actor.user.clone(),
session_id: None,
},
workspace_id,
project_id,
default_global,
Instant::now(),
);
}
guard.insert(
scoped,
workspace_id,
project_id,
default_global,
Instant::now(),
);
}
/// Refresh only the exact actor-scoped entry without advancing either
/// fallback slot.
///
/// Hook completion events use this path so an exact `per_session` or
/// `per_actor` caller keeps a fresh mapping, while a delayed tail from an
/// older session cannot redirect the process-wide single slot or the
/// identity-only fallback used by a caller with no session coordinate.
/// `Single` mode and actors without a usable coordinate are no-ops.
pub fn set_scoped_for(
&self,
actor: &ActorKey,
workspace_id: WorkspaceId,
project_id: ProjectId,
default_global: bool,
) {
if self.mode == ActiveProjectMode::Single || actor.is_empty() {
return;
}
let scoped = self.scoped_key(actor);
if scoped.is_empty() {
return;
}
let mut guard = self.per_actor.write().unwrap_or_else(|e| e.into_inner());
guard.insert(
scoped,
workspace_id,
project_id,
default_global,
Instant::now(),
);
}
/// Read the currently active project for the given actor, if any has
/// been published yet. Falls back to the single slot only when:
/// - the mode is `Single`, or
/// - the actor is empty, or has no coordinate usable by the selected mode.
///
/// When a request provides a usable session/user coordinate and that keyed
/// entry is absent, return `None`. Falling through to the user/global latest
/// slot would route a remote MCP request with a mismatched session id into
/// whichever project published hook activity last.
#[must_use]
pub fn get_for(&self, actor: &ActorKey) -> Option<(WorkspaceId, ProjectId)> {
match self.lookup_for(actor) {
ActiveProjectLookup::Resolved(workspace_id, project_id) => {
Some((workspace_id, project_id))
}
ActiveProjectLookup::Mismatch | ActiveProjectLookup::Unset => None,
}
}
/// Read-path resolution: [`Self::get_for`], plus the startup seed for a
/// caller the pointer holds no information about.
///
/// Only [`ActiveProjectLookup::Unset`] consults the seed — the state a
/// fresh process is in before the first hook event lands, which is
/// precisely the restart window that made `memory_status` answer an empty
/// default (#678). A [`ActiveProjectLookup::Mismatch`] still resolves to
/// nothing: hooks are live there and this coordinate matched none of them,
/// so the caller's own default is the honest answer.
///
/// Reads only. The write path stays on [`Self::lookup_for`] so an unscoped
/// write from an unrecognized caller keeps failing closed instead of being
/// attributed to a project reconstructed from someone else's history.
#[must_use]
pub fn get_for_read(&self, actor: &ActorKey) -> Option<(WorkspaceId, ProjectId)> {
self.read_pointer(actor).ids()
}
/// Read-path resolution with its provenance: the same answer as
/// [`Self::get_for_read`], plus which of the pointer's sources gave it.
///
/// A keyed entry is evidence about *this* caller; the shared slot and the
/// startup seed are not — they hold whichever project published last, or
/// was active last on disk. Reporting that difference is what lets a caller
/// see it was answered about someone else's project (#757).
#[must_use]
pub fn read_pointer(&self, actor: &ActorKey) -> ReadPointer {
match self.lookup_traced(actor) {
(ActiveProjectLookup::Resolved(workspace_id, project_id), true) => {
ReadPointer::Session(workspace_id, project_id)
}
(ActiveProjectLookup::Resolved(workspace_id, project_id), false) => {
ReadPointer::SharedSlot(workspace_id, project_id)
}
(ActiveProjectLookup::Unset, _) => match self.read_seeded() {
Some((workspace_id, project_id)) => {
ReadPointer::StartupSeed(workspace_id, project_id)
}
None => ReadPointer::Unset,
},
(ActiveProjectLookup::Mismatch, _) => ReadPointer::Mismatch,
}
}
/// Same resolution as [`Self::get_for`], but says *why* it failed.
///
/// `get_for` collapses two very different outcomes into `None`, which is fine
/// for a read (both mean "use your configured default") and wrong for a write.
/// A [`ActiveProjectLookup::Mismatch`] is a caller that carries a coordinate on
/// an install whose pointer is live — writing it to the default silently misfiles
/// a real page. [`ActiveProjectLookup::Unset`] is an install with no pointer
/// information at all, which has always used the default and must keep doing so.
#[must_use]
pub fn lookup_for(&self, actor: &ActorKey) -> ActiveProjectLookup {
self.lookup_traced(actor).0
}
/// [`Self::lookup_for`], plus whether a `Resolved` answer came from the
/// caller's own keyed entry (`true`) or from the shared slot (`false`).
fn lookup_traced(&self, actor: &ActorKey) -> (ActiveProjectLookup, bool) {
let shared = |slot| (ActiveProjectLookup::from_single(slot), false);
if self.mode == ActiveProjectMode::Single || actor.is_empty() {
return shared(self.read_single());
}
let scoped = self.scoped_key(actor);
if scoped.is_empty() {
return shared(self.read_single());
}
let now = Instant::now();
let mut guard = self.per_actor.write().unwrap_or_else(|e| e.into_inner());
if let Some((workspace_id, project_id)) = guard.get(&scoped, now) {
return (
ActiveProjectLookup::Resolved(workspace_id, project_id),
true,
);
}
// A keyed miss means one of two very different things.
//
// If this identity has published before — or anything on this process
// has — then hooks are running and this coordinate simply does not
// match one. That is a mismatch, and answering from the shared slot
// would route the request into whichever project published last,
// possibly another operator's. Fail closed and let the caller fall
// back to its configured default.
//
// If nothing has *ever* been keyed, this install has no lifecycle
// hooks feeding the pointer at all (MCP-only). There is no better
// information anywhere, and the shared slot is exactly what such an
// install has always used, so keep answering from it.
if self.mode == ActiveProjectMode::PerActor && actor.user.is_some() {
let identity_only = ActorKey {
user: actor.user.clone(),
session_id: None,
};
if guard.get(&identity_only, now).is_some() {
return (ActiveProjectLookup::Mismatch, false);
}
}
drop(guard);
if self.ever_keyed.load(Ordering::Relaxed) {
return (ActiveProjectLookup::Mismatch, false);
}
shared(self.read_single())
}
/// Whether the actor opted this session into `default_global` recall (via
/// the repo's `[recall] default_global` marker, published by the hook).
/// Uses the SAME slot-selection as [`Self::get_for`], so the flag tracks
/// the project pointer it was published alongside. Defaults to `false`
/// (unchanged behaviour) for any actor/slot that never opted in.
#[must_use]
pub fn default_global_for(&self, actor: &ActorKey) -> bool {
if self.mode == ActiveProjectMode::Single || actor.is_empty() {
return self.read_single_default_global();
}
let scoped = self.scoped_key(actor);
if scoped.is_empty() {
return self.read_single_default_global();
}
let mut guard = self.per_actor.write().unwrap_or_else(|e| e.into_inner());
guard.get_default_global(&scoped, Instant::now())
}
/// Project the actor's identity onto only the coordinates the current
/// mode uses: `PerSession` keeps `session_id`, `PerActor` keeps both.
fn scoped_key(&self, actor: &ActorKey) -> ActorKey {
match self.mode {
ActiveProjectMode::Single => ActorKey {
user: None,
session_id: None,
},
ActiveProjectMode::PerSession => ActorKey {
user: None,
session_id: actor.session_id.clone(),
},
ActiveProjectMode::PerActor => actor.clone(),
}
}
fn write_single(&self, ws: WorkspaceId, proj: ProjectId) {
let mut guard = self.single.write().unwrap_or_else(|e| e.into_inner());
*guard = Some((ws, proj));
}
fn read_single(&self) -> Option<(WorkspaceId, ProjectId)> {
let guard = self.single.read().unwrap_or_else(|e| e.into_inner());
*guard
}
fn read_seeded(&self) -> Option<(WorkspaceId, ProjectId)> {
let guard = self.seeded.read().unwrap_or_else(|e| e.into_inner());
*guard
}
fn write_single_default_global(&self, value: bool) {
let mut guard = self
.single_default_global
.write()
.unwrap_or_else(|e| e.into_inner());
*guard = value;
}
fn read_single_default_global(&self) -> bool {
let guard = self
.single_default_global
.read()
.unwrap_or_else(|e| e.into_inner());
*guard
}
/// Legacy single-slot setter — used by tests and by call sites that
/// have no actor context yet. Touches the single slot only; the per-key
/// map is untouched.
pub fn set(&self, workspace_id: WorkspaceId, project_id: ProjectId) {
self.write_single(workspace_id, project_id);
}
/// Legacy single-slot getter — same contract as [`Self::set`].
#[must_use]
pub fn get(&self) -> Option<(WorkspaceId, ProjectId)> {
self.read_single()
}
/// Publish the read-side startup seed (#678). Called once by `serve`,
/// from the project the database says was active most recently.
///
/// Touches neither the single slot nor the per-key map, so it cannot make
/// an unscoped write resolve anywhere new; see the `seeded` field for why
/// that separation is load-bearing. A real publish supersedes it for every
/// caller the moment the first hook event arrives.
pub fn seed_read_fallback(&self, workspace_id: WorkspaceId, project_id: ProjectId) {
let mut guard = self.seeded.write().unwrap_or_else(|e| e.into_inner());
*guard = Some((workspace_id, project_id));
}
/// The startup seed, if one was published.
#[must_use]
pub fn seeded(&self) -> Option<(WorkspaceId, ProjectId)> {
self.read_seeded()
}
/// Forget the active project. Called after an admin operation invalidates
/// the published pointer (e.g. a `move-project` whose copy-purge path
/// gives the project a NEW id, so the old pointer no longer resolves).
/// Clears both the single slot AND the per-key map, since the project
/// id is gone for every caller.
pub fn clear(&self) {
{
let mut guard = self.single.write().unwrap_or_else(|e| e.into_inner());
*guard = None;
}
{
let mut guard = self.seeded.write().unwrap_or_else(|e| e.into_inner());
*guard = None;
}
let mut guard = self.per_actor.write().unwrap_or_else(|e| e.into_inner());
guard.entries.clear();
}
/// Retarget every active entry for `project_id` to `workspace_id`, preserving
/// the project id. Used after a lossless cross-workspace move where the
/// project row survives and only its workspace changes.
pub fn retarget_project_workspace(&self, project_id: ProjectId, workspace_id: WorkspaceId) {
for slot in [&self.single, &self.seeded] {
let mut guard = slot.write().unwrap_or_else(|e| e.into_inner());
if let Some((ws, proj)) = guard.as_mut()
&& *proj == project_id
{
*ws = workspace_id;
}
}
let mut guard = self.per_actor.write().unwrap_or_else(|e| e.into_inner());
guard.retarget_project(project_id, workspace_id, Instant::now());
}
/// Clear every active entry whose project id matches `project_id`.
pub fn clear_project(&self, project_id: ProjectId) {
for slot in [&self.single, &self.seeded] {
let mut guard = slot.write().unwrap_or_else(|e| e.into_inner());
if guard.map(|(_, proj)| proj) == Some(project_id) {
*guard = None;
}
}
let mut guard = self.per_actor.write().unwrap_or_else(|e| e.into_inner());
guard.clear_project(project_id, Instant::now());
}
/// Clear every active entry whose workspace id matches `workspace_id`.
pub fn clear_workspace(&self, workspace_id: WorkspaceId) {
for slot in [&self.single, &self.seeded] {
let mut guard = slot.write().unwrap_or_else(|e| e.into_inner());
if guard.map(|(ws, _)| ws) == Some(workspace_id) {
*guard = None;
}
}
let mut guard = self.per_actor.write().unwrap_or_else(|e| e.into_inner());
guard.clear_workspace(workspace_id, Instant::now());
}
/// Whether any live active entry references `project_id`.
#[must_use]
pub fn contains_project(&self, project_id: ProjectId) -> bool {
if self.read_single().map(|(_, proj)| proj) == Some(project_id)
|| self.read_seeded().map(|(_, proj)| proj) == Some(project_id)
{
return true;
}
let mut guard = self.per_actor.write().unwrap_or_else(|e| e.into_inner());
guard.contains_project(project_id, Instant::now())
}
/// Whether any live active entry references `workspace_id`.
#[must_use]
pub fn contains_workspace(&self, workspace_id: WorkspaceId) -> bool {
if self.read_single().map(|(ws, _)| ws) == Some(workspace_id)
|| self.read_seeded().map(|(ws, _)| ws) == Some(workspace_id)
{
return true;
}
let mut guard = self.per_actor.write().unwrap_or_else(|e| e.into_inner());
guard.contains_workspace(workspace_id, Instant::now())
}
/// Test-only: look up only the per-key backing store. Used to prove
/// eviction in tests without depending on the public fallback semantics.
#[cfg(test)]
fn keyed_only_get(&self, actor: &ActorKey) -> Option<(WorkspaceId, ProjectId)> {
if self.mode == ActiveProjectMode::Single || actor.is_empty() {
return None;
}
let scoped = self.scoped_key(actor);
if scoped.is_empty() {
return None;
}
let mut guard = self.per_actor.write().unwrap_or_else(|e| e.into_inner());
guard.get(&scoped, Instant::now())
}
/// Test-only: live count of keyed entries in the per-actor backing
/// store, after any pending TTL expiry. Used by the randomised
/// invariant tests to pin `count <= max_entries` after every
/// operation. Counts both still-fresh and stale entries because
/// pre-expiry sweeping is a `get`-time concern; this helper
/// inspects raw storage so the cap test catches a cap violation
/// regardless of when expiry sweeps run.
#[cfg(test)]
fn keyed_entry_count_for_test(&self) -> usize {
let guard = self.per_actor.read().unwrap_or_else(|e| e.into_inner());
guard.raw_len()
}
}
#[cfg(test)]
mod tests {
use super::*;
fn key_session(s: &str) -> ActorKey {
ActorKey {
user: None,
session_id: Some(s.to_string()),
}
}
fn key_actor(user: &str, session: &str) -> ActorKey {
ActorKey {
user: Some(user.to_string()),
session_id: Some(session.to_string()),
}
}
fn empty_actor() -> ActorKey {
ActorKey {
user: None,
session_id: None,
}
}
fn per_actor() -> ActiveProject {
ActiveProject::with_config(
ActiveProjectMode::PerActor,
DEFAULT_PER_KEY_TTL,
DEFAULT_MAX_ENTRIES,
)
}
fn ids(_n: u8) -> (WorkspaceId, ProjectId) {
(WorkspaceId::new(), ProjectId::new())
}
/// #678: the startup seed serves reads, and ONLY reads.
///
/// Seeding the single slot instead would make this same lookup answer
/// `Resolved` for an actor that never published — `ever_keyed` is false for
/// the whole window between a restart and the first hook event — and
/// `resolve_write_args` consumes `Resolved` directly. A foreign caller's
/// unscoped write would then be attributed to whichever project the
/// database remembered, which is the misfiling #564 closed.
#[test]
fn a_seeded_fallback_serves_reads_without_placing_a_foreign_actor() {
let ap = per_actor();
let (ws, proj) = ids(1);
ap.seed_read_fallback(ws, proj);
let stranger = key_actor("bob", "s-bob-never-published");
assert_eq!(
ap.lookup_for(&stranger),
ActiveProjectLookup::Unset,
"the write path must still see no pointer for this caller"
);
assert_eq!(
ap.get_for(&stranger),
None,
"the seed is not a publish, so `get_for` must not report one"
);
assert_eq!(
ap.get_for_read(&stranger),
Some((ws, proj)),
"the read path degrades to the seed instead of an empty default"
);
assert_eq!(
ap.get(),
None,
"the shared publish slot stays empty until a hook fills it"
);
}
/// A keyed hit outranks the seed, and a real publish supersedes it for
/// every caller — the seed is only ever the answer of last resort.
#[test]
fn a_published_pointer_outranks_the_seed() {
let ap = per_actor();
let (ws, seeded_proj) = ids(1);
let (_, own_proj) = ids(2);
ap.seed_read_fallback(ws, seeded_proj);
let alice = key_actor("alice", "s-alice");
ap.set_for(&alice, ws, own_proj, false);
assert_eq!(ap.get_for_read(&alice), Some((ws, own_proj)));
// And once anything is keyed, a stranger is a mismatch again: hooks are
// live, so the honest answer is the caller's own default, not the seed.
let stranger = key_actor("bob", "s-bob");
assert_eq!(ap.lookup_for(&stranger), ActiveProjectLookup::Mismatch);
assert_eq!(ap.get_for_read(&stranger), None);
}
/// An admin op that invalidates the pointer must reach the seed too, or a
/// purged project keeps answering reads from a slot nothing can clear.
#[test]
fn invalidations_reach_the_seed() {
let (ws, proj) = ids(1);
let (other_ws, _) = ids(2);
let stranger = key_actor("bob", "s-bob");
let ap = per_actor();
ap.seed_read_fallback(ws, proj);
assert!(ap.contains_project(proj));
assert!(ap.contains_workspace(ws));
ap.clear_project(proj);
assert_eq!(ap.get_for_read(&stranger), None);
let ap = per_actor();
ap.seed_read_fallback(ws, proj);
ap.clear_workspace(ws);
assert_eq!(ap.get_for_read(&stranger), None);
let ap = per_actor();
ap.seed_read_fallback(ws, proj);
ap.clear();
assert_eq!(ap.get_for_read(&stranger), None);
// A lossless cross-workspace move keeps the project and moves it.
let ap = per_actor();
ap.seed_read_fallback(ws, proj);
ap.retarget_project_workspace(proj, other_ws);
assert_eq!(ap.get_for_read(&stranger), Some((other_ws, proj)));
}
/// The scenario the default must not break: one operator, one harness, and
/// an MCP-only install with no lifecycle hooks feeding the pointer.
///
/// Nothing is ever keyed, so a request carrying a session id has no keyed
/// entry to match. That is not a mismatch — there is no better information
/// anywhere — so it must keep reading the shared slot, exactly as it did
/// before `PerActor` became the default.
#[test]
fn a_hookless_install_still_reads_the_shared_slot() {
let ap = per_actor();
let (ws, proj) = ids(1);
ap.set(ws, proj);
assert_eq!(
ap.get_for(&key_actor("alice", "session-never-published")),
Some((ws, proj)),
"with no keyed activity anywhere, the shared slot is the only answer"
);
}
/// Once hooks *are* publishing, a session id that matches nothing is a
/// mismatch rather than a hookless install. Answering from the shared slot
/// would hand back whichever project published last — on a shared server,
/// somebody else's. Fail closed instead.
#[test]
fn a_session_mismatch_fails_closed_once_anything_has_been_keyed() {
let ap = per_actor();
let (ws_a, proj_a) = ids(1);
ap.set_for(&key_actor("alice", "s-alice"), ws_a, proj_a, false);
assert_eq!(
ap.get_for(&key_actor("alice", "some-other-session")),
None,
"alice has published, so an unmatched session of hers is a mismatch"
);
assert_eq!(
ap.get_for(&key_actor("carol", "s-carol")),
None,
"and another operator must not inherit alice's pointer"
);
}
/// Scenario: one user, two harnesses open in the same project at once.
/// Each must keep its own pointer; neither may overwrite the other.
#[test]
fn parallel_harnesses_of_one_user_keep_separate_pointers() {
let ap = per_actor();
let (ws_1, proj_1) = ids(1);
let (ws_2, proj_2) = ids(2);
ap.set_for(&key_actor("alice", "harness-a"), ws_1, proj_1, false);
ap.set_for(&key_actor("alice", "harness-b"), ws_2, proj_2, false);
assert_eq!(
ap.get_for(&key_actor("alice", "harness-a")),
Some((ws_1, proj_1))
);
assert_eq!(
ap.get_for(&key_actor("alice", "harness-b")),
Some((ws_2, proj_2)),
"the second harness must not have clobbered the first"
);
}
/// Scenario: two operators on one server. Neither may read the other's
/// pointer, in either direction.
#[test]
fn two_operators_never_read_each_others_pointer() {
let ap = per_actor();
let (ws_a, proj_a) = ids(1);
let (ws_c, proj_c) = ids(2);
ap.set_for(&key_actor("alice", "s-a"), ws_a, proj_a, false);
ap.set_for(&key_actor("carol", "s-c"), ws_c, proj_c, false);
assert_eq!(ap.get_for(&key_actor("alice", "s-a")), Some((ws_a, proj_a)));
assert_eq!(ap.get_for(&key_actor("carol", "s-c")), Some((ws_c, proj_c)));
}
/// The commonest authenticated upgrade path: lifecycle hooks publish with
/// both a user and a session, while a *static* MCP client (no session-aware
/// bridge) sends only its bearer.
///
/// That client keys to the identity-only slot, which `set_for` publishes
/// alongside the session slot precisely so this works. Without it, every
/// static MCP client on an authenticated install would fail closed after
/// the default changed — which would be a broken upgrade, not a safer one.
#[test]
fn a_static_mcp_client_reads_the_identity_only_slot() {
let ap = per_actor();
let (ws, proj) = ids(1);
ap.set_for(&key_actor("alice", "hook-session"), ws, proj, false);
let static_client = ActorKey {
user: Some("alice".to_string()),
session_id: None,
};
assert_eq!(
ap.get_for(&static_client),
Some((ws, proj)),
"a bearer with no session must still resolve to that user's project"
);
}
/// A caller with no coordinate at all — an anonymous probe, or a client
/// that cannot forward identity — still reads the shared slot. This is what
/// keeps the single-harness install unchanged under the new default.
#[test]
fn an_actorless_caller_still_reads_the_shared_slot_after_keying() {
let ap = per_actor();
let (ws_a, proj_a) = ids(1);
ap.set_for(&key_actor("alice", "s-a"), ws_a, proj_a, false);
assert_eq!(
ap.get_for(&empty_actor()),
Some((ws_a, proj_a)),
"an empty actor has no coordinate to mismatch on"
);
}
#[test]
fn starts_empty() {
assert!(ActiveProject::new().get().is_none());
}
#[test]
fn set_then_get_round_trips_legacy_api() {
let ap = ActiveProject::new();
let ws = WorkspaceId::new();
let proj = ProjectId::new();
ap.set(ws, proj);
assert_eq!(ap.get(), Some((ws, proj)));
}
#[test]
fn set_overwrites_previous_legacy_api() {
let ap = ActiveProject::new();
ap.set(WorkspaceId::new(), ProjectId::new());
let ws2 = WorkspaceId::new();
let proj2 = ProjectId::new();
ap.set(ws2, proj2);
assert_eq!(ap.get(), Some((ws2, proj2)));
}
#[test]
fn clones_share_one_slot() {
let a = ActiveProject::new();
let b = a.clone();
let ws = WorkspaceId::new();
let proj = ProjectId::new();
a.set(ws, proj);
assert_eq!(b.get(), Some((ws, proj)), "clone must see the same slot");
}
#[test]
fn clear_drops_single_and_per_actor() {
let ap = ActiveProject::with_mode(ActiveProjectMode::PerActor);
let alice = key_actor("alice", "sA");
let ws = WorkspaceId::new();
let proj = ProjectId::new();
ap.set_for(&alice, ws, proj, false);
assert_eq!(ap.get_for(&alice), Some((ws, proj)));
ap.clear();
assert!(ap.get_for(&alice).is_none(), "per-actor entry must be gone");
assert!(ap.get().is_none(), "single slot must be gone");
}
#[test]
fn retarget_project_workspace_updates_single_and_keyed_entries() {
let ap = ActiveProject::with_mode(ActiveProjectMode::PerActor);
let alice = key_actor("alice", "sA");
let bob = key_actor("bob", "sB");
let old_ws = WorkspaceId::new();
let new_ws = WorkspaceId::new();
let moved = ProjectId::new();
let other = ProjectId::new();
ap.set_for(&alice, old_ws, moved, false);
ap.set_for(&bob, old_ws, other, false);
ap.set(old_ws, moved);
ap.retarget_project_workspace(moved, new_ws);
assert_eq!(ap.get(), Some((new_ws, moved)));
assert_eq!(ap.get_for(&alice), Some((new_ws, moved)));
assert_eq!(ap.get_for(&bob), Some((old_ws, other)));
assert!(ap.contains_project(moved));
assert!(ap.contains_workspace(new_ws));
}
#[test]
fn clear_project_drops_matching_single_and_keyed_entries_only() {
let ap = ActiveProject::with_mode(ActiveProjectMode::PerActor);
let alice = key_actor("alice", "sA");
let bob = key_actor("bob", "sB");
let ws = WorkspaceId::new();
let doomed = ProjectId::new();
let kept = ProjectId::new();
ap.set_for(&alice, ws, doomed, false);
ap.set_for(&bob, ws, kept, false);
ap.set(ws, doomed);
ap.clear_project(doomed);
assert!(ap.get().is_none());
assert!(ap.get_for(&alice).is_none());
assert_eq!(ap.get_for(&bob), Some((ws, kept)));
assert!(!ap.contains_project(doomed));
assert!(ap.contains_project(kept));
}
#[test]
fn clear_workspace_drops_matching_single_and_keyed_entries_only() {
let ap = ActiveProject::with_mode(ActiveProjectMode::PerActor);
let alice = key_actor("alice", "sA");
let bob = key_actor("bob", "sB");
let doomed_ws = WorkspaceId::new();
let kept_ws = WorkspaceId::new();
let p1 = ProjectId::new();
let p2 = ProjectId::new();
ap.set_for(&alice, doomed_ws, p1, false);
ap.set_for(&bob, kept_ws, p2, false);
ap.set(doomed_ws, p1);
ap.clear_workspace(doomed_ws);
assert!(ap.get().is_none());
assert!(ap.get_for(&alice).is_none());
assert_eq!(ap.get_for(&bob), Some((kept_ws, p2)));
assert!(!ap.contains_workspace(doomed_ws));
assert!(ap.contains_workspace(kept_ws));
}
#[test]
fn single_mode_ignores_actor_coordinates() {
// Explicit: `Single` is opt-in since v1.39, so this pins the mode
// rather than relying on whatever the default happens to be.
let ap = ActiveProject::with_mode(ActiveProjectMode::Single);
let alice = key_actor("alice", "sA");
let bob = key_actor("bob", "sB");
let ws = WorkspaceId::new();
let p_alice = ProjectId::new();
let p_bob = ProjectId::new();
ap.set_for(&alice, ws, p_alice, false);
ap.set_for(&bob, ws, p_bob, false);
// Both reads see the last write; that's the legacy contract.
assert_eq!(ap.get_for(&alice), Some((ws, p_bob)));
assert_eq!(ap.get_for(&bob), Some((ws, p_bob)));
assert_eq!(ap.get(), Some((ws, p_bob)));
}
#[test]
fn per_session_isolates_by_session_id() {
let ap = ActiveProject::with_mode(ActiveProjectMode::PerSession);
let sess_a = key_session("sA");
let sess_b = key_session("sB");
let ws = WorkspaceId::new();
let p_a = ProjectId::new();
let p_b = ProjectId::new();
ap.set_for(&sess_a, ws, p_a, false);
ap.set_for(&sess_b, ws, p_b, false);
assert_eq!(ap.get_for(&sess_a), Some((ws, p_a)));
assert_eq!(ap.get_for(&sess_b), Some((ws, p_b)));
}
#[test]
fn scoped_refresh_does_not_advance_single_fallback() {
let ap = ActiveProject::with_mode(ActiveProjectMode::PerSession);
let ws = WorkspaceId::new();
let foreground = key_session("foreground");
let stale = key_session("stale");
let foreground_project = ProjectId::new();
let stale_project = ProjectId::new();
ap.set_for(&foreground, ws, foreground_project, true);
ap.set_scoped_for(&stale, ws, stale_project, false);
assert_eq!(ap.get(), Some((ws, foreground_project)));
assert_eq!(ap.get_for(&foreground), Some((ws, foreground_project)));
assert_eq!(ap.get_for(&stale), Some((ws, stale_project)));
assert!(ap.default_global_for(&foreground));
assert!(!ap.default_global_for(&stale));
}
#[test]
fn scoped_refresh_does_not_advance_per_actor_identity_fallback() {
let ap = ActiveProject::with_mode(ActiveProjectMode::PerActor);
let ws = WorkspaceId::new();
let foreground = key_actor("alice", "foreground");
let stale = key_actor("alice", "stale");
let foreground_project = ProjectId::new();
let stale_project = ProjectId::new();
ap.set_for(&foreground, ws, foreground_project, true);
ap.set_scoped_for(&stale, ws, stale_project, false);
let identity_only = ActorKey {
user: Some("alice".to_string()),
session_id: None,
};
assert_eq!(ap.get(), Some((ws, foreground_project)));
assert_eq!(ap.get_for(&identity_only), Some((ws, foreground_project)));
assert_eq!(ap.get_for(&stale), Some((ws, stale_project)));
assert!(ap.default_global_for(&identity_only));
assert!(!ap.default_global_for(&stale));
}
#[test]
fn per_session_ignores_user_field() {
let ap = ActiveProject::with_mode(ActiveProjectMode::PerSession);
let ws = WorkspaceId::new();
let p = ProjectId::new();
let alice = key_actor("alice", "shared-session");
let bob = key_actor("bob", "shared-session");
ap.set_for(&alice, ws, p, false);
let p_bob = ProjectId::new();
ap.set_for(&bob, ws, p_bob, false);
// Same session_id, different users → still collapses to one entry
// (intentional: per_session is the right mode for single-operator,
// multi-cwd installs; per_actor is the mode for multi-operator).
assert_eq!(ap.get_for(&alice), Some((ws, p_bob)));
}
#[test]
fn per_actor_isolates_by_user_and_session() {
let ap = ActiveProject::with_mode(ActiveProjectMode::PerActor);
let alice_a = key_actor("alice", "sA");
let alice_b = key_actor("alice", "sB");
let bob_a = key_actor("bob", "sA");
let ws = WorkspaceId::new();
let p1 = ProjectId::new();
let p2 = ProjectId::new();
let p3 = ProjectId::new();
ap.set_for(&alice_a, ws, p1, false);
ap.set_for(&alice_b, ws, p2, false);
ap.set_for(&bob_a, ws, p3, false);
assert_eq!(ap.get_for(&alice_a), Some((ws, p1)));
assert_eq!(ap.get_for(&alice_b), Some((ws, p2)));
assert_eq!(ap.get_for(&bob_a), Some((ws, p3)));
}
#[test]
fn per_actor_user_only_lookup_stays_with_that_user() {
let ap = ActiveProject::with_mode(ActiveProjectMode::PerActor);
let alice_a = key_actor("alice", "sA");
let bob_a = key_actor("bob", "sA");
let ws = WorkspaceId::new();
let p_alice = ProjectId::new();
let p_bob = ProjectId::new();
ap.set_for(&alice_a, ws, p_alice, false);
ap.set_for(&bob_a, ws, p_bob, false);
assert_eq!(
ap.get_for(&ActorKey {
user: Some("alice".into()),
session_id: None,
}),
Some((ws, p_alice)),
"missing session id must not fall through to Bob's global slot"
);
}
#[test]
fn per_actor_unknown_session_does_not_fall_back_to_user_or_single_slot() {
let ap = ActiveProject::with_mode(ActiveProjectMode::PerActor);
let alice_a = key_actor("alice", "hook-session");
let bob_a = key_actor("bob", "hook-session");
let ws = WorkspaceId::new();
let p_alice = ProjectId::new();
let p_bob = ProjectId::new();
ap.set_for(&alice_a, ws, p_alice, false);
ap.set_for(&bob_a, ws, p_bob, false);
assert_eq!(
ap.get_for(&ActorKey {
user: Some("alice".into()),
session_id: Some("different-mcp-session".into()),
}),
None,
"mismatched session id must not degrade to Alice's latest slot or the global slot"
);
assert_eq!(
ap.get(),
Some((ws, p_bob)),
"legacy single slot remains populated for actorless callers only"
);
}
#[test]
fn per_actor_falls_back_to_single_when_actor_is_empty() {
let ap = ActiveProject::with_mode(ActiveProjectMode::PerActor);
let ws = WorkspaceId::new();
let proj = ProjectId::new();
ap.set(ws, proj);
assert_eq!(ap.get_for(&empty_actor()), Some((ws, proj)));
}
#[test]
fn per_actor_set_also_updates_single_slot() {
// Legacy callers (anonymous probes, code paths the migration has not
// touched yet) keep seeing a fresh pointer via `get()`.
let ap = ActiveProject::with_mode(ActiveProjectMode::PerActor);
let alice = key_actor("alice", "sA");
let ws = WorkspaceId::new();
let proj = ProjectId::new();
ap.set_for(&alice, ws, proj, false);
assert_eq!(ap.get(), Some((ws, proj)));
}
#[test]
fn default_global_round_trips_per_actor_and_defaults_false() {
let ap = ActiveProject::with_mode(ActiveProjectMode::PerActor);
let alice = key_actor("alice", "sA");
let bob = key_actor("bob", "sB");
let ws = WorkspaceId::new();
let (pa, pb) = (ProjectId::new(), ProjectId::new());
ap.set_for(&alice, ws, pa, true); // alice opted in
ap.set_for(&bob, ws, pb, false); // bob did not
assert!(ap.default_global_for(&alice), "alice opted in");
assert!(!ap.default_global_for(&bob), "bob did not");
// The project-pointer resolution is unaffected by the recall flag.
assert_eq!(ap.get_for(&alice), Some((ws, pa)));
assert_eq!(ap.get_for(&bob), Some((ws, pb)));
// An actor that never published defaults to false (unchanged behaviour).
assert!(!ap.default_global_for(&key_actor("carol", "sC")));
}
#[test]
fn default_global_single_slot_tracks_last_publish() {
let ap = ActiveProject::with_mode(ActiveProjectMode::Single);
let ws = WorkspaceId::new();
let proj = ProjectId::new();
ap.set_for(&empty_actor(), ws, proj, true);
assert!(ap.default_global_for(&empty_actor()));
// A later publish without the flag clears it — the pointer and its
// preference move together.
ap.set_for(&empty_actor(), ws, proj, false);
assert!(!ap.default_global_for(&empty_actor()));
}
#[test]
fn per_actor_max_entries_evicts_oldest() {
let ap = ActiveProject::with_config(ActiveProjectMode::PerActor, DEFAULT_PER_KEY_TTL, 2);
let ws = WorkspaceId::new();
let p1 = ProjectId::new();
let p2 = ProjectId::new();
let p3 = ProjectId::new();
let k1 = key_session("s1");
let k2 = key_session("s2");
let k3 = key_session("s3");
ap.set_for(&k1, ws, p1, false);
std::thread::sleep(Duration::from_millis(2));
ap.set_for(&k2, ws, p2, false);
std::thread::sleep(Duration::from_millis(2));
ap.set_for(&k3, ws, p3, false);
// Use the test-only keyed-only getter so the cap assertion targets
// the backing map directly.
assert!(ap.keyed_only_get(&k1).is_none(), "k1 must be evicted");
assert_eq!(ap.keyed_only_get(&k2), Some((ws, p2)));
assert_eq!(ap.keyed_only_get(&k3), Some((ws, p3)));
}
#[test]
fn per_actor_ttl_expires_entries() {
let ap = ActiveProject::with_config(
ActiveProjectMode::PerActor,
Duration::from_millis(20),
DEFAULT_MAX_ENTRIES,
);
let k = key_session("s");
let ws = WorkspaceId::new();
let proj = ProjectId::new();
ap.set_for(&k, ws, proj, false);
assert_eq!(ap.get_for(&k), Some((ws, proj)));
std::thread::sleep(Duration::from_millis(40));
// The per-actor entry must be gone; identified callers with expired
// keyed entries must not fall through to a stale latest-project slot.
assert!(ap.get_for(&k).is_none());
}
// ────────────────────────────────────────────────────────────────────
// Randomised invariant tests.
//
// Each `prop_*` test runs a long sequence of operations driven by a
// tiny xorshift RNG with a fixed seed (printed on failure for
// repro). We assert universal invariants that must hold AFTER every
// operation — not just at one cherry-picked moment — so a bug in
// eviction order or TTL expiry that the fixed scenarios miss
// surfaces here.
//
// No external dep: workspace deliberately curates its dev-deps and
// adding `proptest` for one module is more cost than signal. The
// randomized fuzzing below covers the same ground for the
// invariants we care about; if a future regression motivates true
// shrinking, swap in proptest then.
// ────────────────────────────────────────────────────────────────────
/// Minimal xorshift64* — deterministic, ~4 cycles/step, no deps.
struct Rng(u64);
impl Rng {
fn new(seed: u64) -> Self {
// Avoid the all-zero degenerate state.
Self(if seed == 0 {
0x9e37_79b9_7f4a_7c15
} else {
seed
})
}
fn next(&mut self) -> u64 {
let mut x = self.0;
x ^= x << 13;
x ^= x >> 7;
x ^= x << 17;
self.0 = x;
x
}
fn pick<T: Copy>(&mut self, slice: &[T]) -> T {
slice[(self.next() as usize) % slice.len()]
}
}
/// One operation in the randomised harness.
#[derive(Debug, Clone, Copy)]
enum Op {
Set(usize), // set_for(actor_pool[idx], ws, fresh proj)
Get(usize), // get_for(actor_pool[idx])
ClearAll, // clear() — single + keyed
SetSingle, // set(ws, fresh proj) — legacy single-slot path
GetSingle, // get() — legacy single-slot path
}
fn run_seeded<F: FnMut(usize, &Op, &ActiveProject)>(
ap: &ActiveProject,
seed: u64,
steps: usize,
actor_pool_size: usize,
ws: WorkspaceId,
mut on_step: F,
) {
let mut rng = Rng::new(seed);
let actors: Vec<ActorKey> = (0..actor_pool_size)
.map(|i| ActorKey {
user: Some(format!("user-{i}")),
session_id: Some(format!("sess-{i}")),
})
.collect();
let op_table = [
Op::Set(0),
Op::Get(0),
Op::ClearAll,
Op::SetSingle,
Op::GetSingle,
];
for step in 0..steps {
let mut op = rng.pick(&op_table);
if let Op::Set(_) = op {
op = Op::Set((rng.next() as usize) % actor_pool_size);
} else if let Op::Get(_) = op {
op = Op::Get((rng.next() as usize) % actor_pool_size);
}
match op {
Op::Set(i) => {
let proj = ProjectId::new();
ap.set_for(&actors[i], ws, proj, false);
}
Op::Get(i) => {
let _ = ap.get_for(&actors[i]);
}
Op::ClearAll => ap.clear(),
Op::SetSingle => {
let proj = ProjectId::new();
ap.set(ws, proj);
}
Op::GetSingle => {
let _ = ap.get();
}
}
on_step(step, &op, ap);
}
}
/// Property: at every moment, the count of `keyed` entries must be
/// `<= max_entries`. The LRU evictor is the only thing keeping the
/// map bounded; a race that lets it grow past the cap would surface
/// here within a few thousand random ops.
#[test]
fn prop_keyed_entries_never_exceed_max() {
let ws = WorkspaceId::new();
for seed in [1, 42, 1337, 0xdead_beef, 0xfeed_face] {
let cap = 8;
let ap =
ActiveProject::with_config(ActiveProjectMode::PerActor, DEFAULT_PER_KEY_TTL, cap);
// Pool larger than cap so eviction is exercised continuously.
run_seeded(&ap, seed, 2_000, cap * 4, ws, |step, op, ap| {
let count = ap.keyed_entry_count_for_test();
assert!(
count <= cap,
"seed={seed:#x} step={step}: cap violated, count={count} > {cap} after {op:?}"
);
});
}
}
/// Property: an entry's projection through `set_for(k, _, p)` must
/// be observable by `keyed_only_get(k) == Some(_, p)` until either
/// (a) another `set_for(k, _, p')` overrides it, (b) eviction
/// kicks it out (only possible if cap was exceeded between writes),
/// or (c) the TTL passes.
///
/// This is the "fresh write is durable" contract — the foundation
/// every read tool depends on.
#[test]
fn prop_fresh_write_round_trips_until_overwrite_or_evict() {
let ws = WorkspaceId::new();
for seed in [1, 99, 12_345, 0xc0ffee_u64] {
let cap = 16;
let pool_size = cap * 2;
let ap = ActiveProject::with_config(
ActiveProjectMode::PerActor,
Duration::from_secs(60), // long TTL — eviction stays cap-driven
cap,
);
let mut rng = Rng::new(seed);
let actors: Vec<ActorKey> = (0..pool_size)
.map(|i| ActorKey {
user: Some(format!("user-{i}")),
session_id: Some(format!("sess-{i}")),
})
.collect();
// Walk: each step picks an actor, writes a fresh project id,
// immediately reads back, asserts the read sees THAT id.
// Whether other actors' entries were evicted is fine; the
// write we JUST did MUST be readable.
for step in 0..1_000 {
let i = (rng.next() as usize) % pool_size;
let proj = ProjectId::new();
ap.set_for(&actors[i], ws, proj, false);
let got = ap.keyed_only_get(&actors[i]);
assert_eq!(
got,
Some((ws, proj)),
"seed={seed:#x} step={step}: fresh write for actor {i} not readable; got {got:?}"
);
}
}
}
/// Property: `clear()` must wipe BOTH the single slot and every
/// keyed entry. Operators rely on this for tests / admin-driven
/// reset; a partial clear would leak stale routing.
#[test]
fn prop_clear_wipes_all_slots() {
let ws = WorkspaceId::new();
for seed in [1_u64, 7, 314_159, 271_828, 161_803] {
let ap =
ActiveProject::with_config(ActiveProjectMode::PerActor, DEFAULT_PER_KEY_TTL, 64);
run_seeded(&ap, seed, 500, 8, ws, |_step, _op, _ap| {});
// After arbitrary ops, clear and assert emptiness from every
// angle. Use a fresh actor key not seen in the run.
ap.clear();
assert!(
ap.get().is_none(),
"seed={seed:#x}: single slot not cleared"
);
assert!(
ap.keyed_only_get(&ActorKey {
user: Some("post-clear-probe".into()),
session_id: Some("post-clear".into()),
})
.is_none(),
"seed={seed:#x}: keyed lookup after clear must be None"
);
assert_eq!(
ap.keyed_entry_count_for_test(),
0,
"seed={seed:#x}: keyed_entry_count after clear must be 0"
);
}
}
/// Property: TTL is monotonic in time — once an entry has expired
/// (the per-key TTL has elapsed since its last `set_for`), no
/// `get_for` lookup should ever see it again via the *keyed* path.
#[test]
fn prop_expired_entry_is_not_resurrected_via_keyed_path() {
let ws = WorkspaceId::new();
for seed in [1_u64, 11, 222, 3_333] {
let ttl = Duration::from_millis(40);
let ap = ActiveProject::with_config(ActiveProjectMode::PerActor, ttl, 32);
let mut rng = Rng::new(seed);
let actors: Vec<ActorKey> = (0..8)
.map(|i| ActorKey {
user: Some(format!("u-{i}")),
session_id: Some(format!("s-{i}")),
})
.collect();
// Pre-populate every actor; record the write time relative
// to the run start.
for actor in &actors {
ap.set_for(actor, ws, ProjectId::new(), false);
}
// Wait for TTL plus a margin so every pre-populated entry
// is logically expired.
std::thread::sleep(ttl + Duration::from_millis(30));
// Now hit each actor with `keyed_only_get`. None of them
// should resurrect.
for (idx, actor) in actors.iter().enumerate() {
assert!(
ap.keyed_only_get(actor).is_none(),
"seed={seed:#x} idx={idx}: expired keyed entry resurrected"
);
}
// Cross-check that fresh writes still work after expiry —
// the map shouldn't go into an unrecoverable state.
let i = (rng.next() as usize) % actors.len();
let proj = ProjectId::new();
ap.set_for(&actors[i], ws, proj, false);
assert_eq!(
ap.keyed_only_get(&actors[i]),
Some((ws, proj)),
"seed={seed:#x}: fresh post-expiry write must round-trip"
);
}
}
/// #757: `read_pointer` answers exactly what `get_for_read` does, and says
/// which source answered — a keyed hit is about this caller, the shared
/// slot and the seed are not.
#[test]
fn read_pointer_reports_the_source_of_each_answer() {
let (ws, seeded_proj) = ids(1);
let (_, own_proj) = ids(2);
let alice = key_actor("alice", "s-alice");
let stranger = key_actor("bob", "s-bob");
let ap = per_actor();
assert_eq!(ap.read_pointer(&stranger), ReadPointer::Unset);
ap.seed_read_fallback(ws, seeded_proj);
assert_eq!(
ap.read_pointer(&stranger),
ReadPointer::StartupSeed(ws, seeded_proj)
);
ap.set_for(&alice, ws, own_proj, false);
assert_eq!(ap.read_pointer(&alice), ReadPointer::Session(ws, own_proj));
assert_eq!(ap.read_pointer(&stranger), ReadPointer::Mismatch);
assert_eq!(
ap.read_pointer(&empty_actor()),
ReadPointer::SharedSlot(ws, own_proj),
"a caller with no coordinate reads whichever project published last"
);
for actor in [&alice, &stranger, &empty_actor()] {
assert_eq!(ap.read_pointer(actor).ids(), ap.get_for_read(actor));
}
let single = ActiveProject::with_mode(ActiveProjectMode::Single);
single.set_for(&alice, ws, own_proj, false);
assert_eq!(
single.read_pointer(&alice),
ReadPointer::SharedSlot(ws, own_proj),
"single mode has no keyed entries, even for the publisher"
);
}
}