Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
//! Shared workspace/project scope resolution.
//!
//! HTTP admin routes, MCP tools, and the read-only web API all need the same
//! boundary rules: explicit read scopes fail closed, write scopes are the only
//! place that may create projects, and current-project defaults must respect the
//! actor-scoped active-project pointer. Keeping those policies here prevents
//! each surface from growing its own subtly different fallback chain.
use std::collections::HashSet;
use std::fmt;
use ai_memory_core::{
ActiveProject, ActiveProjectLookup, ActorKey, ProjectId, ReadPointer, UserId, WorkspaceId,
};
use crate::error::{AmbiguousProjectHolders, StoreError};
use crate::project_authz::{GrantLevel, ProjectAccess, ProjectPrincipal};
use crate::{ReaderPool, WriterHandle};
/// Canonical error for partial explicit scope arguments.
pub const WORKSPACE_PROJECT_PAIR_REQUIRED: &str = "workspace and project must be provided together";
/// Message for [`ScopeResolutionError::AmbiguousUnscopedWrite`]. Names both fixes,
/// because the caller cannot tell from the failure alone which one applies to them.
pub const AMBIGUOUS_UNSCOPED_WRITE: &str = "cannot resolve a target for this write: the active-project pointer does not match this \
caller. Pass an explicit workspace and project, or install the lifecycle hooks so the \
pointer is populated";
/// Human-readable workspace/project pair supplied by an API caller.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct ScopeName {
/// Workspace name.
pub workspace: String,
/// Project name within the workspace.
pub project: String,
}
impl ScopeName {
/// Build a scope name from any string-like values.
#[must_use]
pub fn new(workspace: impl Into<String>, project: impl Into<String>) -> Self {
Self {
workspace: workspace.into(),
project: project.into(),
}
}
}
/// Resolved database ids for a project scope.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct ResolvedScope {
/// Owning workspace id.
pub workspace_id: WorkspaceId,
/// Project id inside the workspace.
pub project_id: ProjectId,
}
/// Result of write-scope resolution, including a committed name promotion.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ResolvedWriteScope {
/// Stable workspace/project ids selected for the write.
pub scope: ResolvedScope,
/// Previous name when this resolution promoted the row in place.
pub promoted_from: Option<String>,
}
impl ResolvedScope {
/// Return the ids as the tuple used by existing reader/writer APIs.
#[must_use]
pub fn as_tuple(self) -> (WorkspaceId, ProjectId) {
(self.workspace_id, self.project_id)
}
}
/// Where a resolved read scope came from.
///
/// An unscoped read never fails: it degrades through the pointer, the startup
/// seed and the server default. That keeps reads working, and it also means a
/// caller cannot tell a correct answer from one about a different project
/// (#757). Surfaces report this next to the scope they answered from.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum ScopeSource {
/// The caller named the project (with or without its workspace).
Explicit,
/// The caller's own keyed active-project entry — its hook session.
Session,
/// The process-wide slot: whichever project published last. The answer
/// for a caller with no coordinate, and for every caller in `single` mode.
SharedSlot,
/// The startup seed (#678): the most recently active project on disk,
/// standing in until the first hook event after a restart.
StartupSeed,
/// The server default, because no pointer information exists at all.
Default,
/// The server default, because the caller's coordinate matched no hook
/// session — a static MCP client whose transport session id is not a
/// lifecycle-hook session id.
DefaultAfterMismatch,
}
impl ScopeSource {
/// Stable snake_case label for responses and logs.
#[must_use]
pub fn as_str(self) -> &'static str {
match self {
ScopeSource::Explicit => "explicit",
ScopeSource::Session => "session",
ScopeSource::SharedSlot => "shared_slot",
ScopeSource::StartupSeed => "startup_seed",
ScopeSource::Default => "default",
ScopeSource::DefaultAfterMismatch => "default_after_mismatch",
}
}
/// True when the scope is a guess standing in for a caller the server
/// could not identify, rather than information about that caller. The
/// shared slot and the plain default are how pointer-less installs have
/// always worked, so they do not count.
#[must_use]
pub fn is_fallback(self) -> bool {
matches!(
self,
ScopeSource::StartupSeed | ScopeSource::DefaultAfterMismatch
)
}
/// True when the scope was inferred from a pointer or default rather than
/// stated by the caller ([`ScopeSource::Explicit`]) or bound to the
/// caller's own hook session ([`ScopeSource::Session`]).
///
/// Broader than [`Self::is_fallback`] on purpose: it also covers
/// [`ScopeSource::SharedSlot`] (whichever project published last). Two
/// same-operator agents with no session id share that one slot, so a
/// no-scope read can resolve to a *different* project than the caller
/// meant — the on-start inbox notice counted one project's mail but a
/// later no-scope `memory_message_pop` resolved another project's inbox.
/// The message tools therefore refuse an inferred scope for pop, cancel,
/// and send, and name it on every listing.
#[must_use]
pub fn is_inferred(self) -> bool {
!matches!(self, ScopeSource::Explicit | ScopeSource::Session)
}
}
impl fmt::Display for ScopeSource {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str(self.as_str())
}
}
/// Scope-resolution failure, independent of HTTP/MCP response types.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ScopeResolutionError {
/// Only one of workspace/project was provided.
WorkspaceProjectPairRequired,
/// A multi-scope entry had an empty workspace.
ScopeWorkspaceEmpty,
/// A multi-scope entry had an empty project.
ScopeProjectEmpty,
/// The caller supplied more scopes than the surface allows.
TooManyScopes {
/// Maximum number of scopes allowed by the caller surface.
max: usize,
/// Number of scopes the request supplied.
actual: usize,
},
/// A workspace name did not resolve.
WorkspaceNotFound {
/// Workspace name supplied by the caller.
workspace: String,
},
/// A project name did not resolve inside the provided workspace.
ProjectNotFoundInWorkspace {
/// Workspace name supplied by the caller.
workspace: String,
/// Project name supplied by the caller.
project: String,
},
/// A compatibility key matched more than one project in the workspace.
ProjectNameAmbiguous {
/// Workspace name supplied by the caller.
workspace: String,
/// Project name supplied by the caller.
project: String,
/// The projects that answer to the name, when the lookup knows them.
holders: AmbiguousProjectHolders,
},
/// A project-only read did not resolve in either the actor's active
/// workspace or the server's default workspace.
ProjectNotFoundInActiveOrDefault {
/// Project name supplied by the caller.
project: String,
},
/// An unscoped write from a caller whose active-project pointer did not
/// resolve. Writing it to the server default would silently misfile it.
AmbiguousUnscopedWrite,
/// A write-create policy was requested without a writer handle.
WriterRequired,
/// The per-project authorization choke point (#708) refused the caller a
/// `restricted` project. Carries the policy message.
Forbidden(String),
/// Underlying store failure.
Store(String),
}
impl ScopeResolutionError {
/// True when the error is caused by malformed caller input rather than a
/// missing object or an internal store failure.
#[must_use]
pub fn is_bad_request(&self) -> bool {
matches!(
self,
ScopeResolutionError::WorkspaceProjectPairRequired
| ScopeResolutionError::ScopeWorkspaceEmpty
| ScopeResolutionError::ScopeProjectEmpty
| ScopeResolutionError::TooManyScopes { .. }
| ScopeResolutionError::ProjectNameAmbiguous { .. }
| ScopeResolutionError::AmbiguousUnscopedWrite
)
}
/// True when the caller named a scope that does not exist.
#[must_use]
pub fn is_not_found(&self) -> bool {
matches!(
self,
ScopeResolutionError::WorkspaceNotFound { .. }
| ScopeResolutionError::ProjectNotFoundInWorkspace { .. }
| ScopeResolutionError::ProjectNotFoundInActiveOrDefault { .. }
)
}
/// True when the per-project authorization choke point (#708) refused the
/// caller. Surfaces map this to a 403/permission error.
#[must_use]
pub fn is_forbidden(&self) -> bool {
matches!(self, ScopeResolutionError::Forbidden(_))
}
}
impl fmt::Display for ScopeResolutionError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
ScopeResolutionError::WorkspaceProjectPairRequired => {
f.write_str(WORKSPACE_PROJECT_PAIR_REQUIRED)
}
ScopeResolutionError::ScopeWorkspaceEmpty => {
f.write_str("scope workspace cannot be empty")
}
ScopeResolutionError::ScopeProjectEmpty => f.write_str("scope project cannot be empty"),
ScopeResolutionError::AmbiguousUnscopedWrite => f.write_str(AMBIGUOUS_UNSCOPED_WRITE),
ScopeResolutionError::TooManyScopes { max, .. } => {
write!(f, "at most {max} scopes are allowed")
}
ScopeResolutionError::WorkspaceNotFound { workspace } => {
write!(f, "workspace '{workspace}' not found")
}
ScopeResolutionError::ProjectNotFoundInWorkspace { workspace, project } => {
write!(
f,
"project '{project}' not found in workspace '{workspace}'"
)?;
// A project name never contains '/', so this is a
// `workspace/project` label passed as the project (#1152).
if let Some((ws, proj)) = project.split_once('/')
&& !ws.is_empty()
&& !proj.is_empty()
&& !proj.contains('/')
{
write!(
f,
"; project names never contain '/': pass workspace \"{ws}\" and \
project \"{proj}\" as separate arguments"
)?;
}
Ok(())
}
ScopeResolutionError::ProjectNameAmbiguous {
workspace,
project,
holders,
} => {
write!(
f,
"project '{project}' is ambiguous in workspace '{workspace}'{holders}"
)
}
ScopeResolutionError::ProjectNotFoundInActiveOrDefault { project } => {
write!(
f,
"project '{project}' not found in the active or default workspace"
)
}
ScopeResolutionError::WriterRequired => {
f.write_str("scope resolver requires a writer for create-on-write resolution")
}
ScopeResolutionError::Forbidden(msg) => f.write_str(msg),
ScopeResolutionError::Store(msg) => f.write_str(msg),
}
}
}
impl std::error::Error for ScopeResolutionError {}
impl From<StoreError> for ScopeResolutionError {
fn from(value: StoreError) -> Self {
ScopeResolutionError::Store(value.to_string())
}
}
fn project_lookup_error(error: StoreError, workspace: &str, project: &str) -> ScopeResolutionError {
match error {
StoreError::ProjectNameAmbiguous { holders, .. } => {
ScopeResolutionError::ProjectNameAmbiguous {
workspace: workspace.to_owned(),
project: project.to_owned(),
holders,
}
}
StoreError::Forbidden(message) => ScopeResolutionError::Forbidden(format!(
"not authorized for {project}: this needs write access. {message}"
)),
other => other.into(),
}
}
/// Resolves workspace/project names according to the policy requested by the
/// caller. Construct per request; it only borrows existing handles.
pub struct ScopeResolver<'a> {
reader: &'a ReaderPool,
writer: Option<&'a WriterHandle>,
active_project: Option<&'a ActiveProject>,
default_workspace_id: WorkspaceId,
default_project_id: ProjectId,
/// Per-project authorization principal (#708). `None` skips the gate
/// entirely, preserving legacy behaviour for callers that have not opted
/// in. When set, every resolved read/write scope is run through the
/// `authorize_project` choke point before it is returned.
authz: Option<ProjectPrincipal>,
/// Whether the deployment distinguishes operators; only meaningful when
/// [`Self::authz`] is set.
distinguishes_operators: bool,
}
/// Look up an explicit workspace/project pair without creating anything.
///
/// This free function serves surfaces like admin/web routes that do not have a
/// current-project default. [`ScopeResolver::lookup_existing`] delegates here.
pub async fn lookup_existing_scope(
reader: &ReaderPool,
workspace: &str,
project: &str,
) -> Result<ResolvedScope, ScopeResolutionError> {
let workspace_id = lookup_existing_workspace(reader, workspace).await?;
let project_id = reader
.resolve_existing_project_name(workspace_id, project.to_owned())
.await
.map_err(|error| project_lookup_error(error, workspace, project))?
.ok_or_else(|| ScopeResolutionError::ProjectNotFoundInWorkspace {
workspace: workspace.to_owned(),
project: project.to_owned(),
})?;
Ok(ResolvedScope {
workspace_id,
project_id,
})
}
/// Look up an explicit workspace by name without creating anything.
///
/// This is for admin/destructive surfaces that operate at workspace granularity
/// and must fail closed on typos instead of auto-creating a scope.
pub async fn lookup_existing_workspace(
reader: &ReaderPool,
workspace: &str,
) -> Result<WorkspaceId, ScopeResolutionError> {
reader
.find_workspace(workspace.to_owned())
.await?
.ok_or_else(|| ScopeResolutionError::WorkspaceNotFound {
workspace: workspace.to_owned(),
})
}
/// Create or fetch an explicit workspace/project pair.
///
/// This is the only helper that may create a scope, and should only be used by
/// write-style paths whose public contract says they create missing projects.
pub async fn create_explicit_scope(
writer: &WriterHandle,
workspace: &str,
project: &str,
) -> Result<ResolvedWriteScope, ScopeResolutionError> {
let workspace_id = writer.get_or_create_workspace(workspace.to_owned()).await?;
let resolved = writer
.resolve_project_name_for_write(workspace_id, project.to_owned(), None, false)
.await
.map_err(|error| project_lookup_error(error, workspace, project))?;
Ok(ResolvedWriteScope {
scope: ResolvedScope {
workspace_id,
project_id: resolved.project_id,
},
promoted_from: resolved.promoted_from,
})
}
/// Run a resolved scope through the per-project choke point (#708).
///
/// A read is decided on the read pool; a write on the writer actor's own
/// connection when a writer is given, so the check cannot race a concurrent
/// grant change against the write it guards.
async fn decide_scope(
reader: &ReaderPool,
writer: Option<&WriterHandle>,
scope: ResolvedScope,
principal: &ProjectPrincipal,
distinguishes_operators: bool,
need: ProjectAccess,
) -> Result<(), ScopeResolutionError> {
let decision = match (need, writer) {
(ProjectAccess::Write, Some(writer)) => {
writer
.authorize_project(
scope.workspace_id,
scope.project_id,
principal.clone(),
distinguishes_operators,
need,
)
.await?
}
_ => {
reader
.authorize_project(
scope.workspace_id,
scope.project_id,
principal.clone(),
distinguishes_operators,
need,
)
.await?
}
};
if decision.is_ok() {
return Ok(());
}
// A refusal names the project and both levels, so it says what to ask
// for and can never be mistaken for an empty or missing project. Built on
// the denial path only, where the extra lookups cost nothing that matters.
let held = reader
.resolve_project_authz(
scope.workspace_id,
scope.project_id,
principal.clone(),
distinguishes_operators,
)
.await?
.grant;
let name = reader
.project_name_by_id(scope.workspace_id, scope.project_id)
.await?
.unwrap_or_else(|| "the resolved project".to_owned());
Err(ScopeResolutionError::Forbidden(refusal_message(
&name, held, need,
)))
}
fn refusal_message(project: &str, held: Option<GrantLevel>, need: ProjectAccess) -> String {
let need = match need {
ProjectAccess::Read => "read",
ProjectAccess::Write => "write",
};
match held {
Some(held) => format!(
"not authorized for {project}: you have {} access and this needs {need}. \
Ask the server operator to raise your access.",
held.as_str()
),
None => format!(
"not authorized for {project}. This is an access problem, not an empty \
memory — ask the server operator to grant you {need} access on it."
),
}
}
/// Authorize a scope resolved outside a [`ScopeResolver`] for `viewer` (#708).
///
/// For routes that name a project directly — admin, web, hook captures — and
/// so have no current-project default to resolve through. `viewer` is the
/// database user the request authenticated as; `None` (the root token, or an
/// install with no database users) skips the check, as a resolver with no
/// principal attached does.
///
/// # Errors
/// [`ScopeResolutionError::Forbidden`] when a restricted project refuses the
/// viewer; store failures otherwise.
pub async fn authorize_scope_for(
reader: &ReaderPool,
writer: Option<&WriterHandle>,
scope: ResolvedScope,
viewer: Option<UserId>,
need: ProjectAccess,
) -> Result<ResolvedScope, ScopeResolutionError> {
let Some(viewer) = viewer else {
return Ok(scope);
};
decide_scope(
reader,
writer,
scope,
&ProjectPrincipal::user(viewer),
true,
need,
)
.await?;
Ok(scope)
}
/// [`lookup_existing_scope`], authorized for `viewer` at `need`.
///
/// # Errors
/// As [`lookup_existing_scope`] and [`authorize_scope_for`].
pub async fn lookup_existing_scope_guarded(
reader: &ReaderPool,
workspace: &str,
project: &str,
viewer: Option<UserId>,
need: ProjectAccess,
) -> Result<ResolvedScope, ScopeResolutionError> {
let scope = lookup_existing_scope(reader, workspace, project).await?;
authorize_scope_for(reader, None, scope, viewer, need).await
}
/// Resolve an existing ID inside the named workspace, then authorize it.
/// Never creates a workspace/project or falls back to a name on refusal.
///
/// # Errors
/// Missing coordinates, insufficient access, or a store failure.
pub async fn lookup_project_id_guarded(
reader: &ReaderPool,
workspace: &str,
project_id: ProjectId,
viewer: Option<UserId>,
need: ProjectAccess,
) -> Result<ResolvedScope, ScopeResolutionError> {
let workspace_id = lookup_existing_workspace(reader, workspace).await?;
let Some(project) = reader.project_name_by_id(workspace_id, project_id).await? else {
return Err(ScopeResolutionError::ProjectNotFoundInWorkspace {
workspace: workspace.to_owned(),
project: project_id.to_string(),
});
};
if need == ProjectAccess::Write {
refuse_foreign_profile_name(Some(workspace), &project, viewer)?;
}
authorize_scope_for(
reader,
None,
ResolvedScope {
workspace_id,
project_id,
},
viewer,
need,
)
.await
}
/// [`create_explicit_scope`] on behalf of `viewer`, authorized for a write.
/// Returns promotion metadata that the runtime caller must use to refresh the
/// scope manifest after the SQL transaction commits.
///
/// A project this call creates records `viewer` as its creator in the same
/// transaction, and the choke point admits a creator, so they can write to and
/// read back what they just made. A project that already existed is decided
/// like any other write — "create" is never a way into somebody else's
/// restricted project, and because the writer decides which case applies,
/// there is no window between a lookup and a create for another user to win.
///
/// # Errors
/// As [`create_explicit_scope`] and [`authorize_scope_for`].
pub async fn create_explicit_scope_guarded(
reader: &ReaderPool,
writer: &WriterHandle,
workspace: &str,
project: &str,
viewer: Option<UserId>,
) -> Result<ResolvedWriteScope, ScopeResolutionError> {
let _ = reader;
refuse_foreign_profile_name(Some(workspace), project, viewer)?;
let workspace_id = writer.get_or_create_workspace(workspace.to_owned()).await?;
create_project_in_workspace_guarded(writer, workspace_id, workspace, project, viewer, true)
.await
}
/// Refusal for an explicit write that names a profile project it does not own.
pub const PROFILE_NAME_RESERVED: &str = "profile projects are reserved: write profile entries \
with scope \"profile\", which resolves your own profile";
/// A database user may name exactly one profile project explicitly: their own
/// private profile, `default/_profile.<their id>`. Any other `_profile` or
/// `_profile.*` name is refused before anything is created, so a user cannot
/// create (squat) another operator's private profile and lock its owner out,
/// nor create a workspace profile outside the profile path. A caller with no
/// database user (root, or a single-user server) may, for repair.
///
/// `workspace` is the name the caller gave; `None` (the workspace inferred
/// from the active project or the server default) never matches, so a user
/// names `default` explicitly to reach their own private profile this way.
fn refuse_foreign_profile_name(
workspace: Option<&str>,
project: &str,
viewer: Option<UserId>,
) -> Result<(), ScopeResolutionError> {
if !ai_memory_core::profile::is_profile_project(project) {
return Ok(());
}
let Some(viewer) = viewer else {
return Ok(());
};
if workspace == Some(ai_memory_core::DEFAULT_WORKSPACE_NAME)
&& project == ai_memory_core::profile::user_profile_project(viewer)
{
return Ok(());
}
Err(ScopeResolutionError::Forbidden(
PROFILE_NAME_RESERVED.to_owned(),
))
}
/// [`create_explicit_scope_guarded`] for a workspace already resolved by id.
/// `workspace` is that workspace's name, used only in error messages.
async fn create_project_in_workspace_guarded(
writer: &WriterHandle,
workspace_id: WorkspaceId,
workspace: &str,
project: &str,
viewer: Option<UserId>,
promote: bool,
) -> Result<ResolvedWriteScope, ScopeResolutionError> {
let principal = viewer.map(ProjectPrincipal::user);
let resolved = if promote {
writer
.resolve_project_name_for_write(
workspace_id,
project.to_owned(),
principal,
viewer.is_some(),
)
.await
} else {
writer
.resolve_project_name_for_write_without_promotion(
workspace_id,
project.to_owned(),
principal,
viewer.is_some(),
)
.await
}
.map_err(|error| project_lookup_error(error, workspace, project))?;
let scope = ResolvedScope {
workspace_id,
project_id: resolved.project_id,
};
if let Some(error) = resolved.authorization_error {
return Err(ScopeResolutionError::Forbidden(format!(
"not authorized for {project}: this needs write access. {}",
error.message()
)));
}
Ok(ResolvedWriteScope {
scope,
promoted_from: resolved.promoted_from,
})
}
/// Refusal for a private-profile request that carries no database user: a
/// `user` profile belongs to one, and an anonymous or root caller has none.
pub const PRIVATE_PROFILE_NEEDS_USER: &str = "this server keeps a private profile per database \
user; authenticate with your own API key to read or write yours";
/// Where the cross-project profile lives for a caller, without creating it
/// (`docs/design-cross-project-profile.md`). `workspace_id` is the workspace of
/// the project the caller is in; `viewer` the database user the request
/// authenticated as. `Ok(None)` means there is no profile to read yet, or
/// none for this caller (a private profile with no database user).
///
/// A private profile is read through the per-project choke point, so only its
/// creator (and root, as with every restricted project) is admitted.
///
/// # Errors
/// Store failures, and [`ScopeResolutionError::Forbidden`] if a private
/// profile refuses the viewer.
pub async fn lookup_profile_scope(
reader: &ReaderPool,
share: ai_memory_core::profile::EffectiveProfileShare,
workspace_id: WorkspaceId,
viewer: Option<UserId>,
) -> Result<Option<ResolvedScope>, ScopeResolutionError> {
use ai_memory_core::profile::{EffectiveProfileShare, WORKSPACE_PROFILE_PROJECT};
match share {
EffectiveProfileShare::Global => lookup_global_scope(reader).await,
EffectiveProfileShare::Workspace => Ok(reader
.find_project(workspace_id, WORKSPACE_PROFILE_PROJECT.to_owned())
.await?
.map(|project_id| ResolvedScope {
workspace_id,
project_id,
})),
EffectiveProfileShare::User => {
let Some(viewer) = viewer else {
return Ok(None);
};
let Some(default_workspace) = reader
.find_workspace(ai_memory_core::DEFAULT_WORKSPACE_NAME.to_owned())
.await?
else {
return Ok(None);
};
let Some(project_id) = reader
.find_project(
default_workspace,
ai_memory_core::profile::user_profile_project(viewer),
)
.await?
else {
return Ok(None);
};
let scope = ResolvedScope {
workspace_id: default_workspace,
project_id,
};
authorize_scope_for(reader, None, scope, Some(viewer), ProjectAccess::Read)
.await
.map(Some)
}
}
}
/// Create or fetch the caller's profile scope for a write, authorized.
///
/// The shared scopes (`global`, `workspace`) go through the reserved-scope
/// write gate: on a server with database users only root or a `write` grant
/// on that scope may write it. A private profile is created restricted, with
/// the caller as its creator, so only they (and root) can use it.
///
/// # Errors
/// [`ScopeResolutionError::Forbidden`] when the gate refuses the caller or a
/// private profile is requested without a database user; store failures
/// otherwise.
pub async fn create_profile_scope(
reader: &ReaderPool,
writer: &WriterHandle,
share: ai_memory_core::profile::EffectiveProfileShare,
workspace_id: WorkspaceId,
viewer: Option<UserId>,
) -> Result<ResolvedScope, ScopeResolutionError> {
use ai_memory_core::profile::{EffectiveProfileShare, WORKSPACE_PROFILE_PROJECT};
match share {
EffectiveProfileShare::Global => {
let workspace_id = writer
.get_or_create_workspace(ai_memory_core::DEFAULT_WORKSPACE_NAME.to_owned())
.await?;
create_project_in_workspace_guarded(
writer,
workspace_id,
ai_memory_core::DEFAULT_WORKSPACE_NAME,
ai_memory_core::GLOBAL_SCOPE_PROJECT,
viewer,
false,
)
.await
.map(|resolved| resolved.scope)
}
EffectiveProfileShare::Workspace => {
let workspace = reader
.workspace_name_by_id(workspace_id)
.await?
.unwrap_or_else(|| workspace_id.to_string());
create_project_in_workspace_guarded(
writer,
workspace_id,
&workspace,
WORKSPACE_PROFILE_PROJECT,
viewer,
false,
)
.await
.map(|resolved| resolved.scope)
}
EffectiveProfileShare::User => {
let Some(viewer) = viewer else {
return Err(ScopeResolutionError::Forbidden(
PRIVATE_PROFILE_NEEDS_USER.to_owned(),
));
};
let workspace_id = writer
.get_or_create_workspace(ai_memory_core::DEFAULT_WORKSPACE_NAME.to_owned())
.await?;
create_project_in_workspace_guarded(
writer,
workspace_id,
ai_memory_core::DEFAULT_WORKSPACE_NAME,
&ai_memory_core::profile::user_profile_project(viewer),
Some(viewer),
false,
)
.await
.map(|resolved| resolved.scope)
}
}
}
/// [`resolve_many_existing_scopes`], every scope authorized for `viewer`.
///
/// A refused scope fails the whole call rather than being dropped: silently
/// returning the permitted subset would answer a cross-project search with a
/// short list that looks like "nothing was found there", and a refusal must
/// never read as empty memory.
///
/// # Errors
/// As [`resolve_many_existing_scopes`] and [`authorize_scope_for`].
pub async fn resolve_many_existing_scopes_guarded(
reader: &ReaderPool,
scopes: &[ScopeName],
max: usize,
viewer: Option<UserId>,
need: ProjectAccess,
) -> Result<Vec<ResolvedScope>, ScopeResolutionError> {
let resolved = resolve_many_existing_scopes(reader, scopes, max).await?;
for scope in &resolved {
authorize_scope_for(reader, None, *scope, viewer, need).await?;
}
Ok(resolved)
}
/// Look up the reserved global preferences scope
/// ([`ai_memory_core::GLOBAL_SCOPE_PROJECT`] in the default workspace)
/// without creating it. Returns `Ok(None)` when it doesn't exist yet — the
/// scope participates in default reads by existence, so an absent scope
/// means "nothing to union in", never an error (issue #154).
///
/// Unauthorized by design: the global scope is unioned into everybody's
/// default reads, and the unscoped-read filters admit it for every viewer
/// (#708). Writing it is gated: the choke point admits only root or a `write`
/// grant on it, so user-facing writes resolve it through a [`ScopeResolver`]
/// rather than [`create_global_scope`].
///
/// # Errors
/// Propagates store failures only; a missing workspace or project is `None`.
pub async fn lookup_global_scope(
reader: &ReaderPool,
) -> Result<Option<ResolvedScope>, ScopeResolutionError> {
let Some(workspace_id) = reader
.find_workspace(ai_memory_core::DEFAULT_WORKSPACE_NAME.to_owned())
.await?
else {
return Ok(None);
};
let Some(project_id) = reader
.find_project(
workspace_id,
ai_memory_core::GLOBAL_SCOPE_PROJECT.to_owned(),
)
.await?
else {
return Ok(None);
};
Ok(Some(ResolvedScope {
workspace_id,
project_id,
}))
}
/// Create or fetch the reserved global preferences scope, unauthorized.
/// For server-internal callers and tests: a caller acting for a user resolves
/// it through a [`ScopeResolver`], whose choke point gates the write.
///
/// # Errors
/// Propagates store failures.
pub async fn create_global_scope(
writer: &WriterHandle,
) -> Result<ResolvedScope, ScopeResolutionError> {
let workspace = ai_memory_core::DEFAULT_WORKSPACE_NAME;
let project = ai_memory_core::GLOBAL_SCOPE_PROJECT;
let workspace_id = writer.get_or_create_workspace(workspace.to_owned()).await?;
let resolved = writer
.resolve_project_name_for_write_without_promotion(
workspace_id,
project.to_owned(),
None,
false,
)
.await
.map_err(|error| project_lookup_error(error, workspace, project))?;
Ok(ResolvedScope {
workspace_id,
project_id: resolved.project_id,
})
}
/// Resolve and de-duplicate explicit multi-scope names without creating
/// anything. Surfaces that do not have a current-project default (admin/web)
/// can call this directly; [`ScopeResolver::resolve_many_existing`] delegates
/// here.
pub async fn resolve_many_existing_scopes(
reader: &ReaderPool,
scopes: &[ScopeName],
max: usize,
) -> Result<Vec<ResolvedScope>, ScopeResolutionError> {
if scopes.len() > max {
return Err(ScopeResolutionError::TooManyScopes {
max,
actual: scopes.len(),
});
}
let mut seen = HashSet::new();
let mut resolved = Vec::new();
for scope in scopes {
let workspace =
trimmed_opt(Some(&scope.workspace)).ok_or(ScopeResolutionError::ScopeWorkspaceEmpty)?;
let project =
trimmed_opt(Some(&scope.project)).ok_or(ScopeResolutionError::ScopeProjectEmpty)?;
let ids = lookup_existing_scope(reader, workspace, project).await?;
if seen.insert(ids) {
resolved.push(ids);
}
}
Ok(resolved)
}
impl<'a> ScopeResolver<'a> {
/// Build a resolver for read-only policies.
#[must_use]
pub fn new(
reader: &'a ReaderPool,
default_workspace_id: WorkspaceId,
default_project_id: ProjectId,
) -> Self {
Self {
reader,
writer: None,
active_project: None,
default_workspace_id,
default_project_id,
authz: None,
distinguishes_operators: false,
}
}
/// Attach the writer handle needed by create-on-write resolution.
#[must_use]
pub fn with_writer(mut self, writer: &'a WriterHandle) -> Self {
self.writer = Some(writer);
self
}
/// Opt into the per-project authorization choke point (#708).
///
/// Once attached, every scope this resolver returns is run through
/// `authorize_project`: reads through the read pool, writes through the
/// writer actor (defense in depth) when a writer is attached. In slice 2
/// every project is `open`, so this is a behaviour-preserving pass-through.
#[must_use]
pub fn with_project_authz(
mut self,
principal: ProjectPrincipal,
distinguishes_operators: bool,
) -> Self {
self.authz = Some(principal);
self.distinguishes_operators = distinguishes_operators;
self
}
/// Run the resolved scope through the authorization choke point (#708).
///
/// A no-op when no principal is attached. A read is decided on the read
/// pool; a write is decided on the writer actor's own connection when a
/// writer is attached, so the check cannot race a concurrent grant change
/// against the write it guards.
async fn authorize_scope(
&self,
scope: ResolvedScope,
need: ProjectAccess,
) -> Result<(), ScopeResolutionError> {
let Some(principal) = self.authz.as_ref() else {
return Ok(());
};
decide_scope(
self.reader,
self.writer,
scope,
principal,
self.distinguishes_operators,
need,
)
.await
}
/// Attach the active-project map used for current-project defaults.
#[must_use]
pub fn with_active_project(mut self, active_project: &'a ActiveProject) -> Self {
self.active_project = Some(active_project);
self
}
/// Look up an explicit workspace/project pair without creating anything.
/// Used by read, maintenance, and destructive paths.
pub async fn lookup_existing(
&self,
workspace: &str,
project: &str,
) -> Result<ResolvedScope, ScopeResolutionError> {
lookup_existing_scope(self.reader, workspace, project).await
}
async fn resolve_named_in_workspace(
&self,
workspace_id: WorkspaceId,
workspace: &str,
project: &str,
need: ProjectAccess,
) -> Result<Option<ResolvedScope>, ScopeResolutionError> {
let project_id = self
.reader
.resolve_existing_project_name(workspace_id, project.to_owned())
.await
.map_err(|error| project_lookup_error(error, workspace, project))?;
let Some(project_id) = project_id else {
return Ok(None);
};
let scope = ResolvedScope {
workspace_id,
project_id,
};
self.authorize_scope(scope, need).await?;
Ok(Some(scope))
}
/// An existing project named by both its workspace and project names.
async fn resolve_explicit_pair(
&self,
workspace: &str,
project: &str,
need: ProjectAccess,
) -> Result<ResolvedScope, ScopeResolutionError> {
let workspace_id = lookup_existing_workspace(self.reader, workspace).await?;
self.resolve_named_in_workspace(workspace_id, workspace, project, need)
.await?
.ok_or_else(|| ScopeResolutionError::ProjectNotFoundInWorkspace {
workspace: workspace.to_owned(),
project: project.to_owned(),
})
}
/// Resolve MCP-style read arguments: explicit pair if both names are
/// provided, reject partial pair, otherwise use project-only lookup or the
/// current-project/default fallback chain.
pub async fn resolve_read_args(
&self,
explicit_workspace: Option<&str>,
explicit_project: Option<&str>,
actor: &ActorKey,
) -> Result<ResolvedScope, ScopeResolutionError> {
self.resolve_existing_args(
explicit_workspace,
explicit_project,
actor,
ProjectAccess::Read,
)
.await
}
/// [`Self::resolve_read_args`], plus where the scope came from.
pub async fn resolve_read_args_traced(
&self,
explicit_workspace: Option<&str>,
explicit_project: Option<&str>,
actor: &ActorKey,
) -> Result<(ResolvedScope, ScopeSource), ScopeResolutionError> {
self.resolve_existing_args_traced(
explicit_workspace,
explicit_project,
actor,
ProjectAccess::Read,
)
.await
}
/// Resolve read-shaped arguments naming an EXISTING scope, authorized at
/// `need` (#708).
///
/// The argument shape is not the access level. Tools that delete a page,
/// record feedback, sweep, lint, accept a handoff or pop a message take the
/// same arguments as a read and all mutate; resolving them as a read would
/// let a `read` grant do each of those. The shape says which scope; `need`
/// says what the caller may do to it. Never creates — that is
/// [`Self::resolve_write_args`].
pub async fn resolve_existing_args(
&self,
explicit_workspace: Option<&str>,
explicit_project: Option<&str>,
actor: &ActorKey,
need: ProjectAccess,
) -> Result<ResolvedScope, ScopeResolutionError> {
self.resolve_existing_args_traced(explicit_workspace, explicit_project, actor, need)
.await
.map(|(scope, _)| scope)
}
/// [`Self::resolve_existing_args`], plus where the scope came from.
pub async fn resolve_existing_args_traced(
&self,
explicit_workspace: Option<&str>,
explicit_project: Option<&str>,
actor: &ActorKey,
need: ProjectAccess,
) -> Result<(ResolvedScope, ScopeSource), ScopeResolutionError> {
match (
trimmed_opt(explicit_workspace),
trimmed_opt(explicit_project),
) {
(Some(workspace), Some(project)) => {
let exact = self.resolve_explicit_pair(workspace, project, need).await;
let scope = match (exact, split_slashed_project(project)) {
// #1152: an agent passed a `workspace/project` label as the
// project. The exact name still wins, so a project created
// with a `/` before renames refused one stays reachable.
(
Err(
error @ (ScopeResolutionError::WorkspaceNotFound { .. }
| ScopeResolutionError::ProjectNotFoundInWorkspace { .. }),
),
Some((label_workspace, label_project)),
) => self
.resolve_explicit_pair(label_workspace, label_project, need)
.await
.map_err(|_| error)?,
(exact, _) => exact?,
};
Ok((scope, ScopeSource::Explicit))
}
(Some(_), None) => Err(ScopeResolutionError::WorkspaceProjectPairRequired),
(None, project) => {
self.resolve_current_or_project_traced(project, actor, need)
.await
}
}
}
/// Resolve a project-only read, or the current/default project when no
/// project was supplied.
pub async fn resolve_current_or_project(
&self,
explicit_project: Option<&str>,
actor: &ActorKey,
) -> Result<ResolvedScope, ScopeResolutionError> {
self.resolve_current_or_project_traced(explicit_project, actor, ProjectAccess::Read)
.await
.map(|(scope, _)| scope)
}
async fn resolve_current_or_project_traced(
&self,
explicit_project: Option<&str>,
actor: &ActorKey,
need: ProjectAccess,
) -> Result<(ResolvedScope, ScopeSource), ScopeResolutionError> {
// Read path, so `read_pointer`: it adds the startup seed for a caller
// the pointer knows nothing about, which is every caller in the window
// between a restart and the first hook event (#678). `resolve_write_args`
// below deliberately stays on `get_for` / `lookup_for` — a write must
// not be attributed to a project reconstructed from history the caller
// never named.
let pointer = self
.active_project
.map_or(ReadPointer::Unset, |a| a.read_pointer(actor));
let source = match pointer {
ReadPointer::Session(..) => ScopeSource::Session,
ReadPointer::SharedSlot(..) => ScopeSource::SharedSlot,
ReadPointer::StartupSeed(..) => ScopeSource::StartupSeed,
ReadPointer::Mismatch => ScopeSource::DefaultAfterMismatch,
ReadPointer::Unset => ScopeSource::Default,
};
let active = pointer.ids();
if let Some(project) = trimmed_opt(explicit_project) {
if let Some((active_ws, _)) = active
&& let Some(scope) = self
.resolve_named_in_workspace(active_ws, "the active workspace", project, need)
.await?
{
return Ok((scope, ScopeSource::Explicit));
}
if active.map(|(ws, _)| ws) != Some(self.default_workspace_id)
&& let Some(scope) = self
.resolve_named_in_workspace(
self.default_workspace_id,
"the default workspace",
project,
need,
)
.await?
{
return Ok((scope, ScopeSource::Explicit));
}
return Err(ScopeResolutionError::ProjectNotFoundInActiveOrDefault {
project: project.to_owned(),
});
}
let (workspace_id, project_id) =
active.unwrap_or((self.default_workspace_id, self.default_project_id));
let scope = ResolvedScope {
workspace_id,
project_id,
};
self.authorize_scope(scope, need).await?;
Ok((scope, source))
}
/// Resolve a write target. Explicit names may create the workspace/project;
/// absence means current-project/default. Partial explicit scopes fail.
pub async fn resolve_write_args(
&self,
explicit_workspace: Option<&str>,
explicit_project: Option<&str>,
actor: &ActorKey,
) -> Result<ResolvedWriteScope, ScopeResolutionError> {
let Some(project) = trimmed_opt(explicit_project) else {
if trimmed_opt(explicit_workspace).is_some() {
return Err(ScopeResolutionError::WorkspaceProjectPairRequired);
}
// #564: a caller carrying a coordinate that resolves to nothing is not
// asking for the server default — it is a mismatch, and the page it
// writes would be real, attributed, searchable, and in a project nobody
// looks in. Refuse and name the two fixes. Callers with no coordinate at
// all (anonymous/legacy) keep resolving through the default as before.
let (workspace_id, project_id) = match self.active_project.map(|a| a.lookup_for(actor))
{
Some(ActiveProjectLookup::Resolved(workspace_id, project_id)) => {
(workspace_id, project_id)
}
Some(ActiveProjectLookup::Mismatch) => {
return Err(ScopeResolutionError::AmbiguousUnscopedWrite);
}
Some(ActiveProjectLookup::Unset) | None => {
(self.default_workspace_id, self.default_project_id)
}
};
let scope = ResolvedScope {
workspace_id,
project_id,
};
self.authorize_scope(scope, ProjectAccess::Write).await?;
return Ok(ResolvedWriteScope {
scope,
promoted_from: None,
});
};
let Some(writer) = self.writer else {
return Err(ScopeResolutionError::WriterRequired);
};
let active = self.active_project.and_then(|a| a.get_for(actor));
// #1152: a project name never contains `/` (renames refuse one), so a
// write naming one is a `workspace/project` label passed as the
// project. Resolve an existing project of that exact name, else the
// label's own pair, and never create either.
if let Some((label_workspace, label_project)) = split_slashed_project(project) {
let exact = match trimmed_opt(explicit_workspace) {
Some(workspace) => {
self.resolve_explicit_pair(workspace, project, ProjectAccess::Write)
.await
}
None => {
let workspace_id = active
.map(|(workspace_id, _)| workspace_id)
.unwrap_or(self.default_workspace_id);
self.resolve_named_in_workspace(
workspace_id,
"the active workspace",
project,
ProjectAccess::Write,
)
.await?
.ok_or_else(|| {
ScopeResolutionError::ProjectNotFoundInWorkspace {
workspace: "the active workspace".to_owned(),
project: project.to_owned(),
}
})
}
};
let scope = match exact {
Err(
error @ (ScopeResolutionError::WorkspaceNotFound { .. }
| ScopeResolutionError::ProjectNotFoundInWorkspace { .. }),
) => {
let creator = self.authz.as_ref().and_then(|principal| principal.user_id);
refuse_foreign_profile_name(Some(label_workspace), label_project, creator)?;
self.resolve_explicit_pair(label_workspace, label_project, ProjectAccess::Write)
.await
.map_err(|_| error)?
}
exact => exact?,
};
return Ok(ResolvedWriteScope {
scope,
promoted_from: None,
});
}
let workspace_id = match trimmed_opt(explicit_workspace) {
Some(workspace) => writer.get_or_create_workspace(workspace.to_owned()).await?,
None => active
.map(|(workspace_id, _)| workspace_id)
.unwrap_or(self.default_workspace_id),
};
let creator = self.authz.as_ref().and_then(|principal| principal.user_id);
refuse_foreign_profile_name(trimmed_opt(explicit_workspace), project, creator)?;
let resolved = writer
.resolve_project_name_for_write(
workspace_id,
project.to_owned(),
self.authz.clone(),
self.distinguishes_operators,
)
.await
.map_err(|error| {
project_lookup_error(
error,
trimmed_opt(explicit_workspace).unwrap_or("the active workspace"),
project,
)
})?;
let scope = ResolvedScope {
workspace_id,
project_id: resolved.project_id,
};
if let Some(error) = resolved.authorization_error {
return Err(ScopeResolutionError::Forbidden(format!(
"not authorized for {project}: this needs write access. {}",
error.message()
)));
}
Ok(ResolvedWriteScope {
scope,
promoted_from: resolved.promoted_from,
})
}
/// Resolve and de-duplicate an explicit multi-scope list, every scope
/// authorized for a read.
///
/// A refused scope fails the whole call rather than being dropped — see
/// [`resolve_many_existing_scopes_guarded`].
pub async fn resolve_many_existing(
&self,
scopes: &[ScopeName],
max: usize,
) -> Result<Vec<ResolvedScope>, ScopeResolutionError> {
let resolved = resolve_many_existing_scopes(self.reader, scopes, max).await?;
for scope in &resolved {
self.authorize_scope(*scope, ProjectAccess::Read).await?;
}
Ok(resolved)
}
}
fn trimmed_opt(value: Option<&str>) -> Option<&str> {
value.map(str::trim).filter(|s| !s.is_empty())
}
/// The `(workspace, project)` halves of a `workspace/project` label passed
/// as a project name (#1152): exactly one `/` with a name on each side.
fn split_slashed_project(value: &str) -> Option<(&str, &str)> {
let (left, right) = value.split_once('/')?;
if left.is_empty() || right.is_empty() || right.contains('/') {
return None;
}
Some((left, right))
}
#[cfg(test)]
mod tests {
use super::*;
use crate::Store;
use ai_memory_core::NewUser;
use crate::{AccessMode, GrantLevel};
/// A `workspace/project` label passed as the project names the split
/// (#1152); an ordinary miss keeps the plain message.
#[test]
fn a_slashed_project_name_points_at_the_separate_arguments() {
let glued = ScopeResolutionError::ProjectNotFoundInWorkspace {
workspace: "default".into(),
project: "myorg/myproject".into(),
}
.to_string();
assert!(
glued.contains("pass workspace \"myorg\" and project \"myproject\""),
"{glued}"
);
let plain = ScopeResolutionError::ProjectNotFoundInWorkspace {
workspace: "default".into(),
project: "ghost".into(),
}
.to_string();
assert_eq!(plain, "project 'ghost' not found in workspace 'default'");
}
/// Regression for #1152: a `workspace/project` label accidentally passed
/// as the project argument (with the workspace hardcoded to the
/// literal `"default"` by whatever client-side fallback constructed
/// the args from a marker file) must auto-split and resolve to the
/// (split_ws, split_proj) scope. Without the split the call falls into
/// `ProjectNotFoundInWorkspace` and the handoff the agent was trying
/// to write silently disappears, which is the user-reported class.
#[tokio::test]
async fn slashed_project_argument_splits_to_workspace_and_project() {
let tmp = tempfile::TempDir::new().unwrap();
let store = Store::open(tmp.path()).unwrap();
let default_ws = store
.writer
.get_or_create_workspace("default")
.await
.unwrap();
let default_scratch = store
.writer
.get_or_create_project(default_ws, "scratch", None)
.await
.unwrap();
// The real target: a separate workspace, with a project whose
// name does NOT contain a slash.
let myorg_ws = store.writer.get_or_create_workspace("myorg").await.unwrap();
let myproject = store
.writer
.get_or_create_project(myorg_ws, "myproject", None)
.await
.unwrap();
let resolver = ScopeResolver::new(&store.reader, default_ws, default_scratch);
// Wrong workspace (`"default"`) + a `myorg/myproject` label jammed
// into the project field. With auto-split, this resolves to
// (myorg, myproject). Without the fix it fails with
// `ProjectNotFoundInWorkspace { workspace: "default",
// project: "myorg/myproject" }` and the user's handoff is lost.
let resolved = resolver
.resolve_existing_args(
Some("default"),
Some("myorg/myproject"),
&ActorKey::default(),
ProjectAccess::Write,
)
.await
.expect("slashed project argument must auto-split");
assert_eq!(
resolved.workspace_id, myorg_ws,
"split should land in the (myorg) workspace"
);
assert_eq!(
resolved.project_id, myproject,
"split should land in the (myproject) project"
);
// Control: a project name that genuinely does not split must
// still go through the original `ProjectNotFoundInWorkspace`
// path (so a typo is not silently masked).
let err = resolver
.resolve_existing_args(
Some("default"),
Some("does-not-exist"),
&ActorKey::default(),
ProjectAccess::Write,
)
.await
.expect_err("a non-split project miss must surface the original error");
assert!(
matches!(err, ScopeResolutionError::ProjectNotFoundInWorkspace { .. }),
"{err}"
);
}
/// #1152: a write never creates a project whose name carries a `/`. The
/// label's own pair is written to when it exists, and anything else is
/// refused rather than created.
#[tokio::test]
async fn a_slashed_write_resolves_its_own_pair_and_never_creates() {
let tmp = tempfile::TempDir::new().unwrap();
let store = Store::open(tmp.path()).unwrap();
let default_ws = store
.writer
.get_or_create_workspace("default")
.await
.unwrap();
let scratch = store
.writer
.get_or_create_project(default_ws, "scratch", None)
.await
.unwrap();
let myorg_ws = store.writer.get_or_create_workspace("myorg").await.unwrap();
let myproject = store
.writer
.get_or_create_project(myorg_ws, "myproject", None)
.await
.unwrap();
let resolver =
ScopeResolver::new(&store.reader, default_ws, scratch).with_writer(&store.writer);
let actor = ActorKey::default();
for workspace in [Some("default"), None] {
let written = resolver
.resolve_write_args(workspace, Some("myorg/myproject"), &actor)
.await
.unwrap();
assert_eq!(
(written.scope.workspace_id, written.scope.project_id),
(myorg_ws, myproject),
"{workspace:?}"
);
}
let err = resolver
.resolve_write_args(Some("default"), Some("myorg/ghost"), &actor)
.await
.unwrap_err();
assert!(
matches!(err, ScopeResolutionError::ProjectNotFoundInWorkspace { .. }),
"{err}"
);
for (workspace_id, name) in [
(default_ws, "myorg/myproject"),
(default_ws, "myorg/ghost"),
(myorg_ws, "ghost"),
] {
assert_eq!(
store
.reader
.resolve_existing_project_name(workspace_id, name.to_owned())
.await
.unwrap(),
None,
"{name} must not have been created"
);
}
}
/// A project created with a `/` in its name before renames refused one
/// is still reached by that exact name, on reads and writes.
#[tokio::test]
async fn an_existing_slashed_project_wins_over_the_split() {
let tmp = tempfile::TempDir::new().unwrap();
let store = Store::open(tmp.path()).unwrap();
let default_ws = store
.writer
.get_or_create_workspace("default")
.await
.unwrap();
let legacy = store
.writer
.get_or_create_project(default_ws, "myorg/myproject", None)
.await
.unwrap();
let myorg_ws = store.writer.get_or_create_workspace("myorg").await.unwrap();
store
.writer
.get_or_create_project(myorg_ws, "myproject", None)
.await
.unwrap();
let resolver =
ScopeResolver::new(&store.reader, default_ws, legacy).with_writer(&store.writer);
let actor = ActorKey::default();
let read = resolver
.resolve_existing_args(
Some("default"),
Some("myorg/myproject"),
&actor,
ProjectAccess::Read,
)
.await
.unwrap();
assert_eq!(read.project_id, legacy);
let written = resolver
.resolve_write_args(Some("default"), Some("myorg/myproject"), &actor)
.await
.unwrap();
assert_eq!(written.scope.project_id, legacy);
}
/// The split names a pair the caller could have passed directly, so it
/// is authorized exactly like one: a user without a grant on the
/// label's project is refused on reads and writes, and nothing is
/// created in its place.
#[tokio::test]
async fn a_slashed_label_reaches_only_a_project_the_caller_may_use() {
let tmp = tempfile::TempDir::new().unwrap();
let store = Store::open(tmp.path()).unwrap();
let (ws, project, _, bob) = guard_fixture(&store).await;
let other_ws = store.writer.get_or_create_workspace("other").await.unwrap();
let secret = store
.writer
.get_or_create_project(other_ws, "secret", None)
.await
.unwrap();
let actor = ActorKey::default();
let bob_resolver = as_user(&store, ws, project, bob);
for need in [ProjectAccess::Read, ProjectAccess::Write] {
let refused = bob_resolver
.resolve_existing_args(Some("default"), Some("other/secret"), &actor, need)
.await;
assert!(refused.is_err(), "{need:?}: {refused:?}");
}
let refused = bob_resolver
.resolve_write_args(Some("default"), Some("other/secret"), &actor)
.await;
assert!(refused.is_err(), "{refused:?}");
assert_eq!(
store
.reader
.resolve_existing_project_name(ws, "other/secret".to_owned())
.await
.unwrap(),
None
);
// Control: with a grant, the same label reaches the project.
grant(&store, bob, secret, GrantLevel::Write).await;
let read = bob_resolver
.resolve_existing_args(
Some("default"),
Some("other/secret"),
&actor,
ProjectAccess::Write,
)
.await
.unwrap();
assert_eq!(read.project_id, secret);
let written = bob_resolver
.resolve_write_args(Some("default"), Some("other/secret"), &actor)
.await
.unwrap();
assert_eq!(written.scope.project_id, secret);
}
async fn user_named(store: &Store, username: &str) -> UserId {
store
.writer
.create_human_user(
NewUser {
username: username.to_owned(),
name: None,
email: None,
},
ai_memory_core::UserRole::User,
None,
false,
)
.await
.unwrap()
}
/// A restricted project plus two users, neither holding anything on it.
async fn guard_fixture(store: &Store) -> (WorkspaceId, ProjectId, UserId, UserId) {
// Grants only decide anything in a restricted project; every project
// these tests create starts restricted.
store
.writer
.set_new_project_mode(AccessMode::Restricted)
.await
.unwrap();
let ws = store
.writer
.get_or_create_workspace("default")
.await
.unwrap();
let project = store
.writer
.get_or_create_project(ws, "client-work", None)
.await
.unwrap();
let alice = user_named(store, "alice").await;
let bob = user_named(store, "bob").await;
(ws, project, alice, bob)
}
async fn grant(store: &Store, user: UserId, project: ProjectId, level: GrantLevel) {
store
.writer
.grant_memory(user, project, level, None)
.await
.unwrap();
}
fn created_by(store: &Store, project: ProjectId) -> Option<UserId> {
let conn = rusqlite::Connection::open(store.db_path()).unwrap();
conn.query_row(
"SELECT created_by FROM projects WHERE id = ?1",
rusqlite::params![project.as_bytes()],
|row| row.get::<_, Option<Vec<u8>>>(0),
)
.unwrap()
.map(|raw| UserId::from_slice(&raw).unwrap())
}
fn as_user<'a>(
store: &'a Store,
ws: WorkspaceId,
project: ProjectId,
user: UserId,
) -> ScopeResolver<'a> {
ScopeResolver::new(&store.reader, ws, project)
.with_writer(&store.writer)
.with_project_authz(ProjectPrincipal::user(user), true)
}
/// The argument shape and the level are independent, and must stay so.
///
/// Mutating tools take the same arguments as reads. Resolving those as a
/// read is what would let a `read` grant delete pages, so the level is the
/// caller's to state — on the explicit-pair branch and on the
/// current-project fallback alike.
#[tokio::test]
async fn the_argument_shape_does_not_decide_the_level() {
let tmp = tempfile::TempDir::new().unwrap();
let store = Store::open(tmp.path()).unwrap();
let (ws, project, alice, _) = guard_fixture(&store).await;
grant(&store, alice, project, GrantLevel::Read).await;
let resolver = as_user(&store, ws, project, alice);
let actor = ActorKey::default();
for (label, workspace, name) in [
("explicit pair", Some("default"), Some("client-work")),
("current-project fallback", None, None),
] {
resolver
.resolve_existing_args(workspace, name, &actor, ProjectAccess::Read)
.await
.unwrap_or_else(|e| panic!("{label}: a reader may read: {e}"));
let err = resolver
.resolve_existing_args(workspace, name, &actor, ProjectAccess::Write)
.await
.unwrap_err();
assert!(
err.is_forbidden(),
"{label}: a reader must not reach a write: {err:?}"
);
}
}
/// Root and an install with no database users both arrive as no viewer,
/// and neither may change behaviour.
#[tokio::test]
async fn no_viewer_resolves_exactly_as_before() {
let tmp = tempfile::TempDir::new().unwrap();
let store = Store::open(tmp.path()).unwrap();
let (ws, project, _, _) = guard_fixture(&store).await;
let scope = lookup_existing_scope_guarded(
&store.reader,
"default",
"client-work",
None,
ProjectAccess::Write,
)
.await
.unwrap();
assert_eq!(
scope,
ResolvedScope {
workspace_id: ws,
project_id: project
}
);
}
#[tokio::test]
async fn a_user_reaches_only_what_they_were_granted() {
let tmp = tempfile::TempDir::new().unwrap();
let store = Store::open(tmp.path()).unwrap();
let (_, project, alice, bob) = guard_fixture(&store).await;
grant(&store, alice, project, GrantLevel::Read).await;
let lookup = |user, need| {
lookup_existing_scope_guarded(&store.reader, "default", "client-work", Some(user), need)
};
lookup(alice, ProjectAccess::Read).await.unwrap();
assert!(
lookup(alice, ProjectAccess::Write)
.await
.unwrap_err()
.is_forbidden()
);
// Bob holds nothing. The refusal must say so — not resolve to an
// empty project, which would read as "there is nothing here".
let err = lookup(bob, ProjectAccess::Read).await.unwrap_err();
assert!(err.is_forbidden(), "{err:?}");
assert!(!err.is_not_found());
}
#[tokio::test]
async fn creating_authorizes_against_a_project_that_already_exists() {
let tmp = tempfile::TempDir::new().unwrap();
let store = Store::open(tmp.path()).unwrap();
let (ws, project, alice, bob) = guard_fixture(&store).await;
grant(&store, alice, project, GrantLevel::Read).await;
let create = |name: &'static str, user| {
create_explicit_scope_guarded(&store.reader, &store.writer, "default", name, Some(user))
};
// "Create" is not a way around the choke point: the project is already
// there, so Bob's write is refused exactly as a read would be, and
// Alice's read grant does not cover a write.
assert!(create("client-work", bob).await.unwrap_err().is_forbidden());
assert!(
create("client-work", alice)
.await
.unwrap_err()
.is_forbidden()
);
assert_eq!(created_by(&store, project), None);
// A project that does not exist yet is created with Bob as its
// creator, who is admitted without any grant.
let fresh = create("brand-new", bob).await.unwrap();
assert_eq!(fresh.scope.workspace_id, ws);
assert_eq!(created_by(&store, fresh.scope.project_id), Some(bob));
assert!(
store
.reader
.grants_for(bob, fresh.scope.project_id)
.await
.unwrap()
.is_empty(),
"the creator needs no grant"
);
lookup_existing_scope_guarded(
&store.reader,
"default",
"brand-new",
Some(bob),
ProjectAccess::Write,
)
.await
.expect("the creator reaches what they created");
// A second "create" of the same name by someone else is a write to an
// existing project: refused, and it does not make them its creator.
assert!(create("brand-new", alice).await.unwrap_err().is_forbidden());
assert_eq!(created_by(&store, fresh.scope.project_id), Some(bob));
}
/// With no viewer — root, or an install with no database users — a created
/// project records no creator: there is no user to attribute it to.
#[tokio::test]
async fn creating_without_a_viewer_records_no_creator() {
let tmp = tempfile::TempDir::new().unwrap();
let store = Store::open(tmp.path()).unwrap();
guard_fixture(&store).await;
let fresh = create_explicit_scope_guarded(
&store.reader,
&store.writer,
"default",
"unattributed",
None,
)
.await
.unwrap();
assert_eq!(created_by(&store, fresh.scope.project_id), None);
}
/// The MCP write path creates through the resolver, not the free function,
/// and must behave the same.
#[tokio::test]
async fn write_args_record_the_creator_and_check_everyone_else() {
let tmp = tempfile::TempDir::new().unwrap();
let store = Store::open(tmp.path()).unwrap();
let (ws, project, alice, bob) = guard_fixture(&store).await;
let actor = ActorKey::default();
let as_bob = as_user(&store, ws, project, bob);
let created = as_bob
.resolve_write_args(Some("default"), Some("bobs-repo"), &actor)
.await
.unwrap();
assert_eq!(created_by(&store, created.scope.project_id), Some(bob));
as_bob
.resolve_write_args(Some("default"), Some("bobs-repo"), &actor)
.await
.expect("the creator writes to it again");
let err = as_user(&store, ws, project, alice)
.resolve_write_args(Some("default"), Some("bobs-repo"), &actor)
.await
.unwrap_err();
assert!(err.is_forbidden(), "{err:?}");
}
#[tokio::test]
async fn a_refused_scope_fails_the_search_instead_of_shortening_it() {
let tmp = tempfile::TempDir::new().unwrap();
let store = Store::open(tmp.path()).unwrap();
let (ws, granted, alice, _) = guard_fixture(&store).await;
let refused = store
.writer
.get_or_create_project(ws, "other-team", None)
.await
.unwrap();
grant(&store, alice, granted, GrantLevel::Read).await;
let names = [
ScopeName::new("default", "client-work"),
ScopeName::new("default", "client-work"),
ScopeName::new("default", "other-team"),
];
let err = resolve_many_existing_scopes_guarded(
&store.reader,
&names,
25,
Some(alice),
ProjectAccess::Read,
)
.await
.unwrap_err();
assert!(err.is_forbidden(), "{err:?}");
let err = as_user(&store, ws, granted, alice)
.resolve_many_existing(&names, 25)
.await
.unwrap_err();
assert!(err.is_forbidden(), "the resolver agrees: {err:?}");
// Every scope granted: the call succeeds, still de-duplicated.
grant(&store, alice, refused, GrantLevel::Read).await;
let resolved = as_user(&store, ws, granted, alice)
.resolve_many_existing(&names, 25)
.await
.unwrap();
assert_eq!(resolved.len(), 2);
}
#[tokio::test]
async fn a_revoked_grant_denies_like_one_never_granted() {
let tmp = tempfile::TempDir::new().unwrap();
let store = Store::open(tmp.path()).unwrap();
let (_, project, alice, bob) = guard_fixture(&store).await;
store
.writer
.grant_memory(alice, project, GrantLevel::Write, Some(bob))
.await
.unwrap();
assert!(
store
.writer
.revoke_memory(alice, project, Some(bob))
.await
.unwrap()
);
let err = lookup_existing_scope_guarded(
&store.reader,
"default",
"client-work",
Some(alice),
ProjectAccess::Read,
)
.await
.unwrap_err();
assert!(err.is_forbidden(), "{err:?}");
}
#[tokio::test]
async fn read_args_reject_partial_scope() {
let tmp = tempfile::TempDir::new().unwrap();
let store = Store::open(tmp.path()).unwrap();
let ws = store
.writer
.get_or_create_workspace("default")
.await
.unwrap();
let project = store
.writer
.get_or_create_project(ws, "scratch", None)
.await
.unwrap();
let resolver = ScopeResolver::new(&store.reader, ws, project);
let err = resolver
.resolve_read_args(Some("default"), None, &ActorKey::default())
.await
.unwrap_err();
assert_eq!(err, ScopeResolutionError::WorkspaceProjectPairRequired);
assert_eq!(err.to_string(), WORKSPACE_PROJECT_PAIR_REQUIRED);
}
#[tokio::test]
async fn project_only_read_prefers_active_workspace_then_default() {
let tmp = tempfile::TempDir::new().unwrap();
let store = Store::open(tmp.path()).unwrap();
let default_ws = store
.writer
.get_or_create_workspace("default")
.await
.unwrap();
let default_scratch = store
.writer
.get_or_create_project(default_ws, "scratch", None)
.await
.unwrap();
let active_ws = store.writer.get_or_create_workspace("team").await.unwrap();
let active_scratch = store
.writer
.get_or_create_project(active_ws, "scratch", None)
.await
.unwrap();
let active_project = ActiveProject::new();
let actor = ActorKey {
user: Some("alice".into()),
session_id: Some("s1".into()),
};
active_project.set_for(&actor, active_ws, active_scratch, false);
let resolver = ScopeResolver::new(&store.reader, default_ws, default_scratch)
.with_active_project(&active_project);
let scope = resolver
.resolve_read_args(None, Some("scratch"), &actor)
.await
.unwrap();
assert_eq!(scope.as_tuple(), (active_ws, active_scratch));
let err = resolver
.resolve_read_args(None, Some("missing"), &actor)
.await
.unwrap_err();
assert_eq!(
err,
ScopeResolutionError::ProjectNotFoundInActiveOrDefault {
project: "missing".into()
}
);
}
#[tokio::test]
async fn write_args_create_project_in_active_workspace() {
let tmp = tempfile::TempDir::new().unwrap();
let store = Store::open(tmp.path()).unwrap();
let default_ws = store
.writer
.get_or_create_workspace("default")
.await
.unwrap();
let default_project = store
.writer
.get_or_create_project(default_ws, "scratch", None)
.await
.unwrap();
let active_ws = store.writer.get_or_create_workspace("team").await.unwrap();
let active_project_id = store
.writer
.get_or_create_project(active_ws, "current", None)
.await
.unwrap();
let active_project = ActiveProject::new();
let actor = ActorKey {
user: None,
session_id: Some("s1".into()),
};
active_project.set_for(&actor, active_ws, active_project_id, false);
let resolver = ScopeResolver::new(&store.reader, default_ws, default_project)
.with_writer(&store.writer)
.with_active_project(&active_project);
let created = resolver
.resolve_write_args(None, Some("new-project"), &actor)
.await
.unwrap();
assert_eq!(created.scope.workspace_id, active_ws);
assert!(
store
.reader
.find_project(default_ws, "new-project".into())
.await
.unwrap()
.is_none(),
"project-only writes must not recreate the baked default workspace"
);
assert_eq!(
store
.reader
.find_project(active_ws, "new-project".into())
.await
.unwrap(),
Some(created.scope.project_id)
);
}
#[tokio::test]
async fn multi_scope_resolution_deduplicates_and_validates() {
let tmp = tempfile::TempDir::new().unwrap();
let store = Store::open(tmp.path()).unwrap();
let ws = store
.writer
.get_or_create_workspace("default")
.await
.unwrap();
let project = store
.writer
.get_or_create_project(ws, "scratch", None)
.await
.unwrap();
let resolver = ScopeResolver::new(&store.reader, ws, project);
let scopes = vec![
ScopeName::new("default", "scratch"),
ScopeName::new(" default ", " scratch "),
];
let resolved = resolver.resolve_many_existing(&scopes, 25).await.unwrap();
assert_eq!(
resolved,
vec![ResolvedScope {
workspace_id: ws,
project_id: project
}]
);
let err = resolver
.resolve_many_existing(&[ScopeName::new("", "scratch")], 25)
.await
.unwrap_err();
assert_eq!(err, ScopeResolutionError::ScopeWorkspaceEmpty);
let err = resolver
.resolve_many_existing(
&[
ScopeName::new("default", "scratch"),
ScopeName::new("default", "scratch"),
],
1,
)
.await
.unwrap_err();
assert_eq!(
err,
ScopeResolutionError::TooManyScopes { max: 1, actual: 2 }
);
}
#[tokio::test]
async fn global_scope_lookup_is_none_until_created_then_stable() {
let tmp = tempfile::TempDir::new().unwrap();
let store = Store::open(tmp.path()).unwrap();
// Reads never materialise the reserved scope.
assert_eq!(lookup_global_scope(&store.reader).await.unwrap(), None);
assert_eq!(
lookup_global_scope(&store.reader).await.unwrap(),
None,
"lookup must stay a pure read"
);
// The write path creates it once; lookup then resolves the same ids.
let created = create_global_scope(&store.writer).await.unwrap();
let looked_up = lookup_global_scope(&store.reader).await.unwrap();
assert_eq!(looked_up, Some(created));
// Idempotent create.
let again = create_global_scope(&store.writer).await.unwrap();
assert_eq!(again, created);
}
/// Expected outcome for one table-driven read-resolution row.
#[derive(Debug)]
enum Expected {
Resolved(WorkspaceId, ProjectId),
Failed(ScopeResolutionError),
}
struct ReadCase {
name: &'static str,
workspace: Option<&'static str>,
project: Option<&'static str>,
active: Option<(WorkspaceId, ProjectId)>,
expected: Expected,
}
/// AGENTS.md mandates a table-driven suite over the scope-resolution
/// policies: partial scope, missing explicit scope, active-project
/// precedence, and cross-workspace isolation. One fixture with two
/// workspaces carrying a same-named project feeds every row.
#[tokio::test]
async fn read_resolution_table_driven() {
let tmp = tempfile::TempDir::new().unwrap();
let store = Store::open(tmp.path()).unwrap();
let default_ws = store
.writer
.get_or_create_workspace("default")
.await
.unwrap();
let default_scratch = store
.writer
.get_or_create_project(default_ws, "scratch", None)
.await
.unwrap();
let alpha_ws = store.writer.get_or_create_workspace("alpha").await.unwrap();
let alpha_app = store
.writer
.get_or_create_project(alpha_ws, "app", None)
.await
.unwrap();
let alpha_shared = store
.writer
.get_or_create_project(alpha_ws, "shared", None)
.await
.unwrap();
let beta_ws = store.writer.get_or_create_workspace("beta").await.unwrap();
let beta_shared = store
.writer
.get_or_create_project(beta_ws, "shared", None)
.await
.unwrap();
let beta_other = store
.writer
.get_or_create_project(beta_ws, "other", None)
.await
.unwrap();
assert_ne!(
alpha_shared, beta_shared,
"same-named projects must get distinct ids per workspace"
);
let cases = vec![
// --- Partial scope fails closed ---
ReadCase {
name: "workspace without project is rejected",
workspace: Some("alpha"),
project: None,
active: Some((alpha_ws, alpha_app)),
expected: Expected::Failed(ScopeResolutionError::WorkspaceProjectPairRequired),
},
ReadCase {
name: "project-only read does not scan every workspace",
workspace: None,
project: Some("app"), // exists only in alpha; no active pointer
active: None,
expected: Expected::Failed(
ScopeResolutionError::ProjectNotFoundInActiveOrDefault {
project: "app".into(),
},
),
},
ReadCase {
name: "project-only read of a missing project fails closed",
workspace: None,
project: Some("ghost"),
active: Some((alpha_ws, alpha_app)),
expected: Expected::Failed(
ScopeResolutionError::ProjectNotFoundInActiveOrDefault {
project: "ghost".into(),
},
),
},
// --- Missing explicit scope errors without creating ---
ReadCase {
name: "missing workspace errors",
workspace: Some("ghost"),
project: Some("app"),
active: None,
expected: Expected::Failed(ScopeResolutionError::WorkspaceNotFound {
workspace: "ghost".into(),
}),
},
ReadCase {
name: "missing project in existing workspace errors",
workspace: Some("alpha"),
project: Some("ghost"),
active: Some((alpha_ws, alpha_app)),
expected: Expected::Failed(ScopeResolutionError::ProjectNotFoundInWorkspace {
workspace: "alpha".into(),
project: "ghost".into(),
}),
},
// --- Active-project precedence ---
ReadCase {
name: "explicit pair beats active project",
workspace: Some("beta"),
project: Some("other"),
active: Some((alpha_ws, alpha_app)),
expected: Expected::Resolved(beta_ws, beta_other),
},
ReadCase {
name: "no args resolves the active project",
workspace: None,
project: None,
active: Some((alpha_ws, alpha_app)),
expected: Expected::Resolved(alpha_ws, alpha_app),
},
ReadCase {
name: "no args and no active resolves the default",
workspace: None,
project: None,
active: None,
expected: Expected::Resolved(default_ws, default_scratch),
},
ReadCase {
name: "whitespace-only args resolve the default",
workspace: Some(" "),
project: Some(" "),
active: None,
expected: Expected::Resolved(default_ws, default_scratch),
},
ReadCase {
name: "project-only prefers the active workspace",
workspace: None,
project: Some("shared"),
active: Some((alpha_ws, alpha_app)),
expected: Expected::Resolved(alpha_ws, alpha_shared),
},
ReadCase {
name: "project-only falls back to the default workspace",
workspace: None,
project: Some("scratch"), // exists only in default
active: Some((alpha_ws, alpha_app)),
expected: Expected::Resolved(default_ws, default_scratch),
},
// --- Cross-workspace isolation ---
ReadCase {
name: "shared resolves in alpha when alpha is named",
workspace: Some("alpha"),
project: Some("shared"),
active: None,
expected: Expected::Resolved(alpha_ws, alpha_shared),
},
ReadCase {
name: "shared resolves in beta when beta is named",
workspace: Some("beta"),
project: Some("shared"),
active: None,
expected: Expected::Resolved(beta_ws, beta_shared),
},
ReadCase {
name: "project-only with beta active stays in beta",
workspace: None,
project: Some("shared"),
active: Some((beta_ws, beta_other)),
expected: Expected::Resolved(beta_ws, beta_shared),
},
];
let actor = ActorKey {
user: Some("alice".into()),
session_id: Some("s1".into()),
};
for case in &cases {
let active_project = ActiveProject::new();
if let Some((ws, proj)) = case.active {
active_project.set_for(&actor, ws, proj, false);
}
let resolver = ScopeResolver::new(&store.reader, default_ws, default_scratch)
.with_active_project(&active_project);
let result = resolver
.resolve_read_args(case.workspace, case.project, &actor)
.await;
match (&result, &case.expected) {
(Ok(scope), Expected::Resolved(ws, proj)) => {
assert_eq!(
scope.as_tuple(),
(*ws, *proj),
"case '{}' resolved the wrong scope",
case.name
);
}
(Err(err), Expected::Failed(expected)) => {
assert_eq!(err, expected, "case '{}' failed the wrong way", case.name);
}
(result, expected) => panic!(
"case '{}': expected {expected:?}, got {result:?}",
case.name
),
}
}
// The failing read rows must not have auto-created anything.
assert!(
store
.reader
.find_workspace("ghost".into())
.await
.unwrap()
.is_none(),
"read resolution must never create workspaces"
);
assert!(
store
.reader
.find_project(alpha_ws, "ghost".into())
.await
.unwrap()
.is_none(),
"read resolution must never create projects"
);
// The write-style helper is the only path that may create, and once it
// does, the no-create lookup resolves the same ids.
let created = create_explicit_scope(&store.writer, "ghost", "app")
.await
.unwrap();
assert_eq!(
lookup_existing_scope(&store.reader, "ghost", "app")
.await
.unwrap(),
created.scope
);
// Multi-scope resolution keeps same-named projects in their own
// workspaces and fails closed when one entry is missing.
let resolver = ScopeResolver::new(&store.reader, default_ws, default_scratch);
let both = resolver
.resolve_many_existing(
&[
ScopeName::new("alpha", "shared"),
ScopeName::new("beta", "shared"),
],
25,
)
.await
.unwrap();
assert_eq!(
both,
vec![
ResolvedScope {
workspace_id: alpha_ws,
project_id: alpha_shared
},
ResolvedScope {
workspace_id: beta_ws,
project_id: beta_shared
},
]
);
let err = resolver
.resolve_many_existing(
&[
ScopeName::new("alpha", "shared"),
ScopeName::new("beta", "ghost"),
],
25,
)
.await
.unwrap_err();
assert_eq!(
err,
ScopeResolutionError::ProjectNotFoundInWorkspace {
workspace: "beta".into(),
project: "ghost".into()
}
);
}
/// Build a store with a `default/scratch` fallback plus an `ActiveProject`.
async fn scoped_fixture(
tmp: &tempfile::TempDir,
) -> (Store, WorkspaceId, ProjectId, WorkspaceId, ProjectId) {
let store = Store::open(tmp.path()).unwrap();
let default_ws = store
.writer
.get_or_create_workspace("default")
.await
.unwrap();
let default_proj = store
.writer
.get_or_create_project(default_ws, "scratch", None)
.await
.unwrap();
let team_ws = store.writer.get_or_create_workspace("team").await.unwrap();
let team_proj = store
.writer
.get_or_create_project(team_ws, "real-work", None)
.await
.unwrap();
(store, default_ws, default_proj, team_ws, team_proj)
}
#[tokio::test]
async fn unscoped_write_with_unresolvable_coordinate_errors() {
// #564: a caller that HAS a coordinate but whose pointer misses used to be
// written into the server default — a real, attributed, searchable page that
// nobody goes looking for. Refuse instead.
let tmp = tempfile::TempDir::new().unwrap();
let (store, default_ws, default_proj, team_ws, team_proj) = scoped_fixture(&tmp).await;
let active_project = ActiveProject::new();
let publisher = ActorKey {
user: Some("alice".into()),
session_id: Some("s1".into()),
};
active_project.set_for(&publisher, team_ws, team_proj, false);
// A different operator entirely: carries a coordinate, matches nothing.
let stranger = ActorKey {
user: Some("bob".into()),
session_id: Some("s9".into()),
};
let resolver = ScopeResolver::new(&store.reader, default_ws, default_proj)
.with_writer(&store.writer)
.with_active_project(&active_project);
let err = resolver
.resolve_write_args(None, None, &stranger)
.await
.unwrap_err();
assert_eq!(err, ScopeResolutionError::AmbiguousUnscopedWrite);
assert!(err.is_bad_request());
}
#[tokio::test]
async fn unscoped_write_without_any_coordinate_uses_the_shared_slot() {
// Anonymous/legacy callers resolve through the shared slot by design and must
// keep working — the error is only for a caller that HAS a coordinate. Note
// this resolves to the last published pointer, not the server default:
// `set_for` writes the shared slot alongside the per-actor entry.
let tmp = tempfile::TempDir::new().unwrap();
let (store, default_ws, default_proj, team_ws, team_proj) = scoped_fixture(&tmp).await;
let active_project = ActiveProject::new();
let publisher = ActorKey {
user: Some("alice".into()),
session_id: Some("s1".into()),
};
active_project.set_for(&publisher, team_ws, team_proj, false);
let resolver = ScopeResolver::new(&store.reader, default_ws, default_proj)
.with_writer(&store.writer)
.with_active_project(&active_project);
let scope = resolver
.resolve_write_args(None, None, &ActorKey::default())
.await
.unwrap();
assert_eq!(scope.scope.as_tuple(), (team_ws, team_proj));
}
#[tokio::test]
async fn unscoped_write_on_an_install_with_no_pointer_uses_the_default() {
// An install with no lifecycle hooks feeding the pointer has never keyed
// anything and has an empty shared slot. There is no better information
// anywhere, so the configured default stays the answer — including for a
// caller that does carry a coordinate.
let tmp = tempfile::TempDir::new().unwrap();
let (store, default_ws, default_proj, _team_ws, _team_proj) = scoped_fixture(&tmp).await;
let active_project = ActiveProject::new();
let actor = ActorKey {
user: Some("alice".into()),
session_id: Some("s1".into()),
};
let resolver = ScopeResolver::new(&store.reader, default_ws, default_proj)
.with_writer(&store.writer)
.with_active_project(&active_project);
let scope = resolver
.resolve_write_args(None, None, &actor)
.await
.unwrap();
assert_eq!(scope.scope.as_tuple(), (default_ws, default_proj));
}
#[tokio::test]
async fn unscoped_write_with_resolving_pointer_uses_it() {
let tmp = tempfile::TempDir::new().unwrap();
let (store, default_ws, default_proj, team_ws, team_proj) = scoped_fixture(&tmp).await;
let active_project = ActiveProject::new();
let actor = ActorKey {
user: Some("alice".into()),
session_id: Some("s1".into()),
};
active_project.set_for(&actor, team_ws, team_proj, false);
let resolver = ScopeResolver::new(&store.reader, default_ws, default_proj)
.with_writer(&store.writer)
.with_active_project(&active_project);
let scope = resolver
.resolve_write_args(None, None, &actor)
.await
.unwrap();
assert_eq!(scope.scope.as_tuple(), (team_ws, team_proj));
}
#[tokio::test]
async fn unscoped_read_with_unresolvable_coordinate_still_falls_back() {
// Reads keep the fallback: a read answering from the default project is a
// wrong answer the caller can see; a write is a misfile they cannot.
let tmp = tempfile::TempDir::new().unwrap();
let (store, default_ws, default_proj, team_ws, team_proj) = scoped_fixture(&tmp).await;
let active_project = ActiveProject::new();
let publisher = ActorKey {
user: Some("alice".into()),
session_id: Some("s1".into()),
};
active_project.set_for(&publisher, team_ws, team_proj, false);
let stranger = ActorKey {
user: Some("bob".into()),
session_id: Some("s9".into()),
};
let resolver = ScopeResolver::new(&store.reader, default_ws, default_proj)
.with_active_project(&active_project);
let scope = resolver
.resolve_read_args(None, None, &stranger)
.await
.unwrap();
assert_eq!(scope.as_tuple(), (default_ws, default_proj));
}
#[tokio::test]
async fn the_startup_seed_answers_reads_and_never_retargets_a_write() {
// #678: after a restart the pointer is empty, so an unscoped read
// resolved through the baked default and reported an empty project.
// The seed fixes the read. It must not follow into the write path:
// `resolve_write_args` still resolves as if nothing were published, so
// no page is attributed to a project rebuilt from someone else's
// history.
let tmp = tempfile::TempDir::new().unwrap();
let (store, default_ws, default_proj, team_ws, team_proj) = scoped_fixture(&tmp).await;
let active_project = ActiveProject::new();
active_project.seed_read_fallback(team_ws, team_proj);
for actor in [
// The session that outlived the daemon: coordinate intact, keyed
// entry gone with the process.
ActorKey {
user: Some("alice".into()),
session_id: Some("s1".into()),
},
// And a caller with no coordinate at all.
ActorKey::default(),
] {
let read = ScopeResolver::new(&store.reader, default_ws, default_proj)
.with_active_project(&active_project)
.resolve_read_args(None, None, &actor)
.await
.unwrap();
assert_eq!(
read.as_tuple(),
(team_ws, team_proj),
"read must degrade to the seeded scope, not the empty default"
);
let write = ScopeResolver::new(&store.reader, default_ws, default_proj)
.with_writer(&store.writer)
.with_active_project(&active_project)
.resolve_write_args(None, None, &actor)
.await
.unwrap();
assert_eq!(
write.scope.as_tuple(),
(default_ws, default_proj),
"write target must be exactly what it was before the seed existed"
);
}
// A named project still resolves inside the workspace the seed points
// at — that is a find-only read, and cross-workspace isolation holds:
// `real-work` exists only in `team`.
let named = ScopeResolver::new(&store.reader, default_ws, default_proj)
.with_active_project(&active_project)
.resolve_read_args(None, Some("real-work"), &ActorKey::default())
.await
.unwrap();
assert_eq!(named.as_tuple(), (team_ws, team_proj));
}
#[tokio::test]
async fn traced_read_resolution_reports_where_the_scope_came_from() {
// #757: every row is a read that succeeds, so the source is the only
// way a caller can tell an answer about its own project from one about
// somebody else's.
let tmp = tempfile::TempDir::new().unwrap();
let (store, default_ws, default_proj, team_ws, team_proj) = scoped_fixture(&tmp).await;
let hook_session = ActorKey {
user: None,
session_id: Some("hook-session".into()),
};
let static_client = ActorKey {
user: None,
session_id: Some("mcp-transport-session".into()),
};
let unset = ActiveProject::new();
let seeded = ActiveProject::new();
seeded.seed_read_fallback(team_ws, team_proj);
let live = ActiveProject::new();
live.set_for(&hook_session, team_ws, team_proj, false);
struct Case<'a> {
name: &'static str,
pointer: Option<&'a ActiveProject>,
workspace: Option<&'static str>,
project: Option<&'static str>,
actor: &'a ActorKey,
expected: (WorkspaceId, ProjectId),
source: ScopeSource,
}
let cases = [
Case {
name: "explicit pair",
pointer: Some(&live),
workspace: Some("default"),
project: Some("scratch"),
actor: &static_client,
expected: (default_ws, default_proj),
source: ScopeSource::Explicit,
},
Case {
name: "project only",
pointer: Some(&live),
workspace: None,
project: Some("real-work"),
actor: &hook_session,
expected: (team_ws, team_proj),
source: ScopeSource::Explicit,
},
Case {
name: "caller's own hook session",
pointer: Some(&live),
workspace: None,
project: None,
actor: &hook_session,
expected: (team_ws, team_proj),
source: ScopeSource::Session,
},
Case {
name: "static client on a live install",
pointer: Some(&live),
workspace: None,
project: None,
actor: &static_client,
expected: (default_ws, default_proj),
source: ScopeSource::DefaultAfterMismatch,
},
Case {
name: "caller with no coordinate",
pointer: Some(&live),
workspace: None,
project: None,
actor: &ActorKey::default(),
expected: (team_ws, team_proj),
source: ScopeSource::SharedSlot,
},
Case {
name: "restart window",
pointer: Some(&seeded),
workspace: None,
project: None,
actor: &static_client,
expected: (team_ws, team_proj),
source: ScopeSource::StartupSeed,
},
Case {
name: "no pointer information",
pointer: Some(&unset),
workspace: None,
project: None,
actor: &static_client,
expected: (default_ws, default_proj),
source: ScopeSource::Default,
},
Case {
name: "no pointer attached",
pointer: None,
workspace: None,
project: None,
actor: &hook_session,
expected: (default_ws, default_proj),
source: ScopeSource::Default,
},
];
for case in cases {
let mut resolver = ScopeResolver::new(&store.reader, default_ws, default_proj);
if let Some(pointer) = case.pointer {
resolver = resolver.with_active_project(pointer);
}
let (scope, source) = resolver
.resolve_read_args_traced(case.workspace, case.project, case.actor)
.await
.unwrap();
assert_eq!(scope.as_tuple(), case.expected, "{}", case.name);
assert_eq!(source, case.source, "{}", case.name);
let untraced = resolver
.resolve_read_args(case.workspace, case.project, case.actor)
.await
.unwrap();
assert_eq!(
untraced, scope,
"{}: tracing must not change the answer",
case.name
);
}
assert!(ScopeSource::DefaultAfterMismatch.is_fallback());
assert!(ScopeSource::StartupSeed.is_fallback());
for honest in [
ScopeSource::Explicit,
ScopeSource::Session,
ScopeSource::SharedSlot,
ScopeSource::Default,
] {
assert!(!honest.is_fallback(), "{honest}");
}
}
}