Module workspace 

Multi-workspace routing for the MCP/REST server (SPEC-0014, DESIGN-0008).

A WorkspaceRouter owns a set of WorkspaceRuntimes (one per registered workspace) and dispatches built-in tool calls to the runtime selected by a request. The router is a dispatch layer only: it never merges stores, and the underlying query functions (search_documents / get_document / get_sources) keep operating on a single &Config.

Multi-workspace behavior is additive and opt-in. The default server runs in ServerMode::Compat — represented internally as a router holding one workspace — and behaves byte-for-byte like the pre-router server. Multi mode (ServerMode::Multi) is activated only by the explicit --workspaces flag and is the only mode that emits workspace-labeled responses.

Phase 1 (this module) routes built-in tools to a selected workspace. The workspace = "all" fan-out (Phase 2) and origin-scoped extensions (Phase 3) are deferred — all currently returns unsupported_workspace_selector.

Structs

RegistryDefaults

[defaults] table of the registry.

WorkspaceEntry

A single [workspaces.<id>] entry.

WorkspaceRegistry

The user-level registry of known workspaces (SPEC-0014 R1/R2).

WorkspaceRouter

Routes built-in operations to the selected WorkspaceRuntime.

WorkspaceRuntime

In-memory runtime for one workspace: its id, root, resolved config, and health.

Enums

FanOut 🔒

Outcome of one workspace’s fan-out operation.

ResolutionMode

How a workspace’s effective Config was resolved (SPEC-0014 R4/R5), surfaced by the workspaces tool so the divergence is visible.

RouterError

Router error codes (SPEC-0014 R64). Returned to REST as the existing JSON error shape and to MCP as a tool error.

ServerMode

Whether the server emits the pre-router flat shapes (Compat) or the workspace-labeled shapes (Multi). Chosen once at startup by activation path, never by the number of registered workspaces (SPEC-0014 R14/R15).

WorkspaceHealth

Two-tier health (SPEC-0014 R60/R61). Cheap validation happens at startup; the SQLite store is opened lazily by the query functions on first use.

Constants

ALL_SELECTOR

The reserved selector meaning “every enabled workspace”.

DEFAULT_SEARCH_DEADLINE_MS

Default per-workspace deadline for an all fan-out search (SPEC-0014 R33).

FAN_OUT_CONCURRENCY

Maximum number of workspaces searched concurrently during an all fan-out.

Functions

build_multi_router

Build a multi-workspace WorkspaceRouter from a parsed registry (R60).

build_runtime 🔒

Resolve one registry entry into a runtime, capturing validation/config errors as an unavailable-but-listed runtime.

cmd_add

ctx workspace add — register a workspace, validating paths at write time.

cmd_list

ctx workspace list — print registered workspaces.

cmd_remove

ctx workspace remove — drop a workspace from the registry.

default_enabled 🔒

default_registry_path

The default registry location: $XDG_CONFIG_HOME/ctx/workspaces.toml (R1).

fan_out 🔒

Run op for each (id, input) under a concurrency cap and a per-item deadline, returning outcomes paired with their id in the input order.

is_valid_workspace_id

Whether id is a valid workspace id: [A-Za-z0-9][A-Za-z0-9_-]* (R-def).

load_or_default 🔒

Load the registry from path, or a fresh empty one if the file is absent.

write_registry 🔒

Persist a registry to disk, creating the parent directory if needed.