Deploy complete BrainAPI source 42cde77950db

All tracked files from Git commit 42cde77950db2e24a1b7acbc3477274bd9cad06a; required Docker inputs checked before upload.

.env.example

@@ -102,13 +102,14 @@ PUBLIC_BASE_URL="http://localhost:8000"
 BRAINPAT_TOKEN="your_token"
 
 # MultiBrain
-# Choose to allow or block automatic creation of new brains on requests with non existing new brain_ids
-BRAIN_CREATION_ALLOWED="true"
+# Legacy flag; API requests never provision brains implicitly.
+# Create explicitly through POST /system/brains or POST /system/workspaces.
+BRAIN_CREATION_ALLOWED="false"
 
 # Production ingress and plugin startup policy.
 CORS_ALLOWED_ORIGINS=""
 PLUGIN_FAILURE_POLICY="fail"
-# Choose whether to fallback to default brain if not provided
+# Resolve a missing scope to an already-registered default brain; never creates it
 DEFAULT_BRAIN_FALLBACK="true"
 
 # Optional anonymous, read-only documentation search demo (disabled by default)

.gitignore

@@ -17,8 +17,7 @@ gcp_credentials.json
 mcp-stdio-http-bridge/target/
 mcp-stdio-http-bridge/dist/
 
-plugins/*
-!plugins/readme.txt
+plugins/**
 
 
 .git

deploy/README.md

@@ -117,10 +117,46 @@ docker compose --env-file /etc/brainapi/light.env -f deploy/docker-compose.light
 The seed command downloads the published V2 documentation, records its SHA-256
 marker, skips an already-current corpus, and polls the asynchronous ingestion
 task. It requires the private system `BRAINPAT_TOKEN` inside the deployment; do
-not expose that token through the gateway. After the first successful seed,
-`BRAIN_CREATION_ALLOWED` may be returned to the operator's normal setting.
+not expose that token through the gateway. The seed command explicitly creates
+the brain; `BRAIN_CREATION_ALLOWED` does not enable implicit API provisioning.
 
 Expose the API origin as `api.brain-api.dev`, with TLS, and put the Cloudflare
 gateway in front of root-domain `/api/*`. The application itself deliberately
 does not implement client rate limiting; the checked-in gateway owns the
 30-request/60-second demo limit.
+
+
+## Brain registry contract
+
+The persisted registry is authoritative. Retrieval, query, agent, and MCP access
+cannot provision an unknown brain, even with `BRAIN_CREATION_ALLOWED=true`.
+Explicit unknown API scopes return `404 BRAIN_NOT_FOUND`. A missing scope can
+resolve to `default` only when `DEFAULT_BRAIN_FALLBACK=true` and that brain is
+already registered. Create brains with `POST /system/brains` or
+`POST /system/workspaces`; duplicate brain creation returns
+`409 BRAIN_ALREADY_EXISTS`, including concurrent inserts.
+
+Brain IDs accept 1–128 ASCII letters, digits, hyphens, and underscores, starting
+with a letter or digit. `system` is reserved (case insensitive). The same rules
+apply to create, clear, and delete; workspace slugs retain their narrower syntax.
+`/system/brains-list` returns persisted registry identities only. Orphan physical
+databases never appear as registered brains or acquire generated PATs.
+
+Clear preserves registered identity and physical storage. Explicit delete also
+removes the PostgreSQL database, including a named orphan without a registry
+row. These are destructive operations: target only an intended identifier.
+
+Run the deterministic gate and the opt-in real integration gate:
+
+```bash
+PYTHONPATH=.:tests python -m pytest -q tests/test_brain_registry_contract.py tests/test_brain_lifecycle.py
+BRAINAPI_REGISTRY_TEST_CONTAINER=<disposable-local-container> \
+  PYTHONPATH=.:tests python -m pytest -q tests/integration/test_brain_registry_contract.py
+```
+
+The integration gate requires a disposable local HF CPU container with the
+candidate source and its normal entrypoint environment. It invokes
+`bash /app/entrypoint.sh --qualify-registry`, compares actual PostgreSQL catalogs
+and application Redis state around unknown GET/search/context requests, tests
+concurrent storage inserts, and deletes only its own collision-checked temporary
+namespaces. It does not clean production probe artifacts or other existing brains.

deploy/env.heavy.example

@@ -104,9 +104,10 @@ MONGO_SYSTEM_DATABASE="system"
 BRAINPAT_TOKEN="your_token"
 
 # MultiBrain
-# Choose to allow or block automatic creation of new brains on requests with non existing new brain_ids
-BRAIN_CREATION_ALLOWED="true"
-# Choose whether to fallback to default brain if not provided
+# Legacy flag; API requests never provision brains implicitly.
+# Create explicitly through POST /system/brains or POST /system/workspaces.
+BRAIN_CREATION_ALLOWED="false"
+# Resolve a missing scope to an already-registered default brain; never creates it
 DEFAULT_BRAIN_FALLBACK="true"
 
 # Optional anonymous, read-only documentation search demo (disabled by default)

deploy/env.light.example

@@ -102,9 +102,10 @@ MONGO_SYSTEM_DATABASE="system"
 BRAINPAT_TOKEN="your_token"
 
 # MultiBrain
-# Choose to allow or block automatic creation of new brains on requests with non existing new brain_ids
-BRAIN_CREATION_ALLOWED="true"
-# Choose whether to fallback to default brain if not provided
+# Legacy flag; API requests never provision brains implicitly.
+# Create explicitly through POST /system/brains or POST /system/workspaces.
+BRAIN_CREATION_ALLOWED="false"
+# Resolve a missing scope to an already-registered default brain; never creates it
 DEFAULT_BRAIN_FALLBACK="true"
 
 # Optional anonymous, read-only documentation search demo (disabled by default)

deploy/env.public-demo.example

@@ -12,5 +12,5 @@ SEARCH_FUSION="rrf"
 SEARCH_BM25_K1="1.2"
 SEARCH_BM25_B="0.75"
 
-# Required only while the seed command creates agentdemo for the first time.
-BRAIN_CREATION_ALLOWED="true"
+# The seed command explicitly provisions agentdemo through POST /system/brains.
+BRAIN_CREATION_ALLOWED="false"

entrypoint.sh

@@ -11,12 +11,12 @@ export PIPELINE_MODE="${PIPELINE_MODE:-lightweight}"
 export MODELS_MODE="${MODELS_MODE:-local}"
 export LLM_SMALL_PROVIDER="${LLM_SMALL_PROVIDER:-ollama}"
 export LLM_LARGE_PROVIDER="${LLM_LARGE_PROVIDER:-ollama}"
-export EMBEDDINGS_PROVIDER="ollama"
+export EMBEDDINGS_PROVIDER="${EMBEDDINGS_PROVIDER:-ollama}"
 export OLLAMA_HOST="${OLLAMA_HOST:-127.0.0.1}"
 export OLLAMA_PORT="${OLLAMA_PORT:-11434}"
 export OLLAMA_MODELS="${OLLAMA_MODELS:-/opt/ollama-models}"
 export OLLAMA_NO_CLOUD="${OLLAMA_NO_CLOUD:-true}"
-export OLLAMA_EMBEDDING_MODEL="embeddinggemma-2:270m"
+export OLLAMA_EMBEDDING_MODEL="${OLLAMA_EMBEDDING_MODEL:-embeddinggemma-2:270m}"
 export OLLAMA_NUM_PARALLEL="${OLLAMA_NUM_PARALLEL:-1}"
 export OLLAMA_MAX_LOADED_MODELS="${OLLAMA_MAX_LOADED_MODELS:-1}"
 export OLLAMA_NUM_THREADS="${OLLAMA_NUM_THREADS:-2}"
@@ -74,26 +74,13 @@ export REDIS_PASSWORD
 export CELERY_BROKER_URL="redis://:${REDIS_PASSWORD}@127.0.0.1:6379/0"
 export CELERY_RESULT_BACKEND="redis://:${REDIS_PASSWORD}@127.0.0.1:6379/0"
 
-echo "========== Effective embedding configuration =========="
-printf 'EMBEDDINGS_PROVIDER=%q\n' "${EMBEDDINGS_PROVIDER:-}"
-printf 'OLLAMA_EMBEDDING_MODEL=%q\n' "${OLLAMA_EMBEDDING_MODEL:-}"
-printf 'EMBEDDINGS_LOCAL_MODEL=%q\n' "${EMBEDDINGS_LOCAL_MODEL:-}"
-printf 'EMBEDDING_PROFILE=%q\n' "${EMBEDDING_PROFILE:-}"
-printf 'EMBEDDING_NATIVE_DIMENSION=%q\n' "${EMBEDDING_NATIVE_DIMENSION:-}"
-printf 'EMBEDDING_MRL_DIMENSION=%q\n' "${EMBEDDING_MRL_DIMENSION:-}"
-printf 'EMBEDDING_NODES_DIMENSION=%q\n' "${EMBEDDING_NODES_DIMENSION:-}"
-printf 'EMBEDDING_TRIPLETS_DIMENSION=%q\n' "${EMBEDDING_TRIPLETS_DIMENSION:-}"
-printf 'EMBEDDING_OBSERVATIONS_DIMENSION=%q\n' "${EMBEDDING_OBSERVATIONS_DIMENSION:-}"
-printf 'EMBEDDING_DATA_DIMENSION=%q\n' "${EMBEDDING_DATA_DIMENSION:-}"
-printf 'EMBEDDING_RELATIONSHIPS_DIMENSION=%q\n' "${EMBEDDING_RELATIONSHIPS_DIMENSION:-}"
-echo "========================================================"
-
 # docker exec starts with the image environment, not this script's exports.
 # Load the same runtime defaults/credentials for qualification without restarting
 # or reinitializing the already-running application services.
-if [ "${1:-}" = "--qualify" ]; then
-    exec /app/.venv/bin/python /app/scripts/qualify_hf_embeddings.py
-fi
+case "${1:-}" in
+    --qualify) exec /app/.venv/bin/python /app/scripts/qualify_hf_embeddings.py ;;
+    --qualify-registry) exec /app/.venv/bin/python /app/scripts/qualify_brain_registry.py ;;
+esac
 
 # Print non-secret startup diagnostics
 echo "=================================================="

scripts/qualify_brain_registry.py

@@ -0,0 +1,171 @@
+"""Destructive only to unique disposable test namespaces; run via entrypoint --qualify-registry.
+
+Exercises actual HTTP controllers, PostgreSQL catalogs, Redis, graph/vector clients,
+and concurrent registry inserts. Never targets a preexisting brain or external data.
+"""
+from concurrent.futures import ThreadPoolExecutor
+import json
+import os
+from pathlib import Path
+import sys
+from uuid import uuid4
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+import httpx
+
+from src.core.instances import cache_adapter, data_adapter, graph_adapter, vector_store_adapter
+from src.lib.postgresql._naming import brain_db_name
+from src.lib.postgresql import _provisioning as pg
+from src.services.brain_identity import BrainAlreadyExistsError, BrainNotFoundError
+
+
+def check(condition, message):
+    if not condition:
+        raise RuntimeError(message)
+
+
+def identities(api):
+    response = api.get('/system/brains-list')
+    response.raise_for_status()
+    return sorted((b['name_key'], b['id']) for b in response.json())
+
+
+def storage_snapshot():
+    with pg.borrow(pg.get_system_pool()) as conn, conn.cursor() as cursor:
+        cursor.execute('SELECT id, name_key, document FROM data_brains ORDER BY name_key')
+        registry = cursor.fetchall()
+        cursor.execute('SELECT document FROM data_workspaces ORDER BY id')
+        workspaces = cursor.fetchall()
+    with pg.borrow(pg.get_pool(pg._maintenance_dbname())) as conn, conn.cursor() as cursor:
+        cursor.execute('SELECT datname FROM pg_database ORDER BY datname')
+        databases = cursor.fetchall()
+    # Include values, not just key names. Unrelated Celery heartbeat bookkeeping
+    # is outside application namespaces and excluded from this comparison.
+    redis = cache_adapter.cache.client
+    cache = {key: redis.dump(key) for pattern in ('system:brain*', 'codex*')
+             for key in redis.scan_iter(match=pattern)}
+    return registry, workspaces, databases, cache
+
+
+def read(api, endpoint, brain_id):
+    if endpoint == 'entities':
+        return api.get('/retrieve/entities', params={'brain_id': brain_id})
+    return api.post('/retrieve/' + endpoint, json={
+        'brain_id': brain_id, 'query' if endpoint == 'search' else 'text': 'registry isolation probe',
+    })
+
+
+def qualify():
+    suffix = uuid4().hex[:12]
+    unknown = 'codex_unknown_' + suffix
+    names = ['codex-test-' + suffix, 'codex_test_' + suffix]
+    orphan = 'codex_orphan_' + suffix
+    race = 'codex_race_' + suffix
+    # Cleanup is limited to namespaces proven absent before this test.
+    temporary = names + [orphan, race]
+    created = set()
+    results = {}
+    api_url = os.getenv('QUALIFY_API_URL', 'http://127.0.0.1:7860')
+    with httpx.Client(base_url=api_url, headers={'BrainPAT': os.environ['BRAINPAT_TOKEN']},
+                      timeout=120, trust_env=False) as api:
+        before_ids = identities(api)
+        before = storage_snapshot()
+        for name in temporary + [unknown]:
+            check(data_adapter.get_brain(name) is None, 'Test namespace collision')
+            check(brain_db_name(name) not in {r[0] for r in before[2]}, 'Test storage collision')
+        try:
+            for endpoint in ('entities', 'search', 'context'):
+                response = read(api, endpoint, unknown)
+                check(response.status_code == 404, 'Unknown ' + endpoint + ' did not return 404')
+                check(response.json()['error']['code'] == 'BRAIN_NOT_FOUND', 'Wrong missing-brain code')
+                check(storage_snapshot() == before, 'Unknown read changed registry/workspaces/databases/cache')
+                check(identities(api) == before_ids, 'Unknown read changed public identities')
+                results['unknown_' + endpoint] = '404 BRAIN_NOT_FOUND; storage/cache unchanged'
+
+            # Defense in depth: bypass HTTP and hit each real storage read path.
+            data = data_adapter.data
+            graph = graph_adapter.graph._store
+            vectors = vector_store_adapter.vector_store
+            backend_before = (set(data._initialized_brains), set(graph._schema_ready),
+                              dict(graph._brains), set(vectors._initialized_stores),
+                              set(vectors._brain_extensions_ready))
+            for operation in (
+                lambda: data.get_text_chunks(brain_id=unknown),
+                lambda: graph.get_brain(unknown),
+                lambda: vectors.search_vectors([1.0] + [0.0] * 511, brain_id=unknown, store='data'),
+            ):
+                try:
+                    operation()
+                except BrainNotFoundError:
+                    pass
+                else:
+                    raise RuntimeError('Unknown direct backend read accepted')
+            check(storage_snapshot() == before, 'Direct backend read changed persistent state')
+            check(backend_before == (set(data._initialized_brains), set(graph._schema_ready),
+                                    dict(graph._brains), set(vectors._initialized_stores),
+                                    set(vectors._brain_extensions_ready)), 'Unknown backend read populated a cache')
+            results['direct_backend_reads'] = 'data/graph/vector rejected; catalogs and caches unchanged'
+
+            for name in names:
+                created.add(name)
+                response = api.post('/system/brains', json={'brain_id': name})
+                check(response.status_code == 200, 'Explicit create failed')
+                identity = (response.json()['name_key'], response.json()['id'])
+                duplicate = api.post('/system/brains', json={'brain_id': name})
+                check(duplicate.status_code == 409 and duplicate.json()['error']['code'] == 'BRAIN_ALREADY_EXISTS', 'Duplicate was not conflict')
+                check(identity in identities(api) and identities(api) == identities(api), 'Identity changed')
+                for endpoint in ('entities', 'search', 'context'):
+                    response = read(api, endpoint, name)
+                    check(response.status_code == 200, 'Known ' + endpoint + ' failed: ' + str(response.status_code))
+                clear = api.post('/system/brains/' + name + '/clear')
+                check(clear.status_code == 200, 'Clear rejected supported identifier')
+                check(identity in identities(api), 'Clear changed registry identity')
+                response = api.delete('/system/brains/' + name)
+                check(response.status_code == 200, 'Delete rejected supported identifier')
+                check(data_adapter.get_brain(name) is None, 'Delete retained registry')
+                check(brain_db_name(name) not in {r[0] for r in storage_snapshot()[2]}, 'Delete retained physical storage')
+            results['known_reads_identifiers_duplicates'] = 'GET/search/context 200; stable IDs; duplicate 409; clear/delete hyphen and underscore passed'
+
+            # No preflight lookup: exercise real concurrent storage uniqueness handling.
+            created.add(race)
+            def create_concurrently(_):
+                try:
+                    data_adapter.create_brain(race)
+                    return 'created'
+                except BrainAlreadyExistsError:
+                    return 'conflict'
+            with ThreadPoolExecutor(max_workers=2) as executor:
+                outcomes = sorted(executor.map(create_concurrently, range(2)))
+            check(outcomes == ['conflict', 'created'], 'Storage uniqueness race was not a domain conflict')
+            results['storage_duplicate_race'] = 'one create, one domain conflict'
+
+            # Create only a physical database, without ever creating a registry row.
+            created.add(orphan)
+            pg.ensure_database_exists(brain_db_name(orphan))
+            check(data_adapter.get_brain(orphan) is None, 'Orphan unexpectedly registered')
+            check(all(n != orphan for n, _ in identities(api)), 'Orphan exposed as registered brain')
+            def orphan_schema():
+                with pg.borrow(pg.get_pool(brain_db_name(orphan))) as conn, conn.cursor() as cur:
+                    cur.execute("SELECT schemaname, tablename FROM pg_tables ORDER BY schemaname, tablename")
+                    return cur.fetchall()
+            orphan_before = orphan_schema()
+            for endpoint in ('entities', 'search', 'context'):
+                response = read(api, endpoint, orphan)
+                check(response.status_code == 404, 'Orphan storage authorized an unknown read')
+            check(orphan_schema() == orphan_before, 'Orphan read created tables')
+            response = api.delete('/system/brains/' + orphan)
+            check(response.status_code == 200 and response.json()['existed'] is False, 'Orphan cleanup failed')
+            check(brain_db_name(orphan) not in {r[0] for r in storage_snapshot()[2]}, 'Orphan database remains')
+            check(data_adapter.get_brain(orphan) is None, 'Orphan cleanup created a registry row')
+            results['orphan_cleanup'] = 'physical database removed without registry creation'
+        finally:
+            for name in sorted(created):
+                response = api.delete('/system/brains/' + name)
+                check(response.status_code == 200, 'Temporary brain cleanup failed')
+        check(identities(api) == before_ids, 'Temporary qualification changed preexisting brain identities')
+    results['result'] = 'passed'
+    print(json.dumps(results, sort_keys=True))
+
+
+if __name__ == '__main__':
+    qualify()

scripts/seed_public_demo.py

@@ -10,6 +10,10 @@ import sys
 import time
 
 import requests
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+from src.services.brain_identity import InvalidBrainIdError, validate_brain_id
 
 
 DEFAULT_DOCS_URL = "https://brainapi.lumen-labs.ai/docs/llms-full.txt"
@@ -27,8 +31,10 @@ def main() -> int:
     if not token:
         print("BRAINPAT_TOKEN is required", file=sys.stderr)
         return 2
-    if not args.brain.isalnum() or args.brain == "system":
-        print("Demo brain must be a non-system alphanumeric identifier", file=sys.stderr)
+    try:
+        args.brain = validate_brain_id(args.brain)
+    except InvalidBrainIdError as error:
+        print(str(error), file=sys.stderr)
         return 2
 
     api_url = args.api_url.rstrip("/")
@@ -48,7 +54,14 @@ def main() -> int:
     if existing.status_code == 200 and existing.json().get("total", 0) > 0:
         print(f"Public demo brain {args.brain!r} is already current ({digest[:12]}).")
         return 0
-    if existing.status_code not in (200, 406):
+    if existing.status_code in (404, 406) and existing.json().get("error", {}).get("code") == "BRAIN_NOT_FOUND":
+        created = requests.post(
+            f"{api_url}/system/brains", headers=headers,
+            json={"brain_id": args.brain}, timeout=30,
+        )
+        if not (created.status_code == 409 and created.json().get("error", {}).get("code") == "BRAIN_ALREADY_EXISTS"):
+            created.raise_for_status()
+    else:
         existing.raise_for_status()
 
     payload = {

src/adapters/data.py

@@ -99,7 +99,17 @@ class DataAdapter:
         """
         Create a new brain in the data client.
         """
-        return self.data.create_brain(name_key=name_key)
+        brain = self.data.create_brain(name_key=name_key)
+        from src.config import config
+        if config.data_db.strip().lower() != "postgresql" and (
+            config.vector_db.strip().lower() == "postgresql"
+            or config.graph_db.strip().lower() == "networkx"
+        ):
+            # A Mongo registry with PostgreSQL graph/vectors also provisions only
+            # at this explicit creation boundary, never from backend reads.
+            from src.lib.postgresql._provisioning import ensure_brain_database
+            ensure_brain_database(brain.name_key)
+        return brain
 
     def get_brain(self, name_key: str) -> Brain:
         """

src/config.py

@@ -389,16 +389,8 @@ class EmbeddingsConfig:
         self.local_model = os.getenv("EMBEDDINGS_LOCAL_MODEL", "BAAI/bge-small-en-v1.5")
         self.small_model = os.getenv("EMBEDDINGS_SMALL_MODEL", "BAAI/bge-small-en-v1.5")
 
-        provider = (provider or "").strip().lower()
-        model = (model or "").strip()
         gemma = provider == "ollama" and model == "embeddinggemma-2:270m"
-        self.profile = (
-            os.getenv(
-                "EMBEDDING_PROFILE",
-                "embeddinggemma2-text-v1" if gemma else "",
-            )
-            or ""
-        ).strip()
+        self.profile = os.getenv("EMBEDDING_PROFILE", "embeddinggemma2-text-v1" if gemma else "")
         default_dimension = 512 if gemma else 384
 
         self.embedding_nodes_dimension = (
@@ -438,17 +430,7 @@ class EmbeddingsConfig:
         if gemma or self.profile == "embeddinggemma2-text-v1":
             if not (gemma and self.profile == "embeddinggemma2-text-v1" and self.native_dimension == 768
                     and self.mrl_dimension == 512 and dimensions == {512}):
-                raise ValueError(
-                    "embeddinggemma2-text-v1 configuration mismatch: "
-                    f"provider={provider!r}, model={model!r}, "
-                    f"profile={self.profile!r}, "
-                    f"native_dimension={self.native_dimension!r}, "
-                    f"mrl_dimension={self.mrl_dimension!r}, "
-                    f"stored_dimensions={sorted(dimensions)!r}; "
-                    "expected provider='ollama', model='embeddinggemma-2:270m', "
-                    "profile='embeddinggemma2-text-v1', native=768, MRL=512, "
-                    "all stored dimensions=512"
-                )
+                raise ValueError("embeddinggemma2-text-v1 requires ollama embeddinggemma-2:270m, native 768, MRL 512 and all stored dimensions 512; use a new index when changing profiles")
         elif self.mrl_dimension:
             raise ValueError("MRL is only supported by the qualified embeddinggemma2-text-v1 profile")
 

src/lib/mongo/client.py

@@ -16,6 +16,7 @@ from pymongo.database import Database
 from pymongo.collection import Collection
 from src.adapters.interfaces.data import DataClient, SearchResult
 from src.config import config
+from src.services.brain_identity import BrainAlreadyExistsError, validate_brain_id
 from src.constants.data import Brain, KGChanges, Observation, StructuredData, TextChunk, Workspace
 
 
@@ -139,10 +140,15 @@ class MongoClient(DataClient):
         return structured_data
 
     def create_brain(self, name_key: str) -> Brain:
+        name_key = validate_brain_id(name_key)
         collection = self.get_collection("brains", config.mongo.system_database)
         brain = Brain(name_key=name_key)
         brain_dict = brain.model_dump(mode="json", exclude={"id"})
-        result = collection.insert_one(brain_dict)
+        collection.create_index("name_key", unique=True)
+        try:
+            result = collection.insert_one(brain_dict)
+        except DuplicateKeyError:
+            raise BrainAlreadyExistsError("Brain already exists") from None
         brain.id = str(result.inserted_id)
         return brain
 

src/lib/postgresql/_provisioning.py

@@ -35,6 +35,7 @@ import psycopg2.pool
 from psycopg2 import sql
 
 from src.config import config
+from src.services.brain_identity import BrainNotFoundError, validate_brain_id
 
 from ._naming import BRAIN_DB_PREFIX, brain_db_name
 
@@ -101,6 +102,12 @@ class _PoolRegistry:
             self._evict_if_needed()
             return pool
 
+    def discard(self, dbname: str) -> None:
+        with self._lock:
+            pool = self._pools.pop(dbname, None)
+            if pool is not None:
+                pool.closeall()
+
     def _evict_if_needed(self) -> None:
         while len(self._pools) > _MAX_OPEN_POOLS:
             evicted_name, evicted_pool = self._pools.popitem(last=False)
@@ -124,14 +131,34 @@ def get_system_pool() -> psycopg2.pool.ThreadedConnectionPool:
 
 
 def get_brain_pool(brain_id: str) -> psycopg2.pool.ThreadedConnectionPool:
+    require_registered_brain(brain_id)
     return _registry.get(brain_db_name(brain_id))
 
 
+def require_registered_brain(brain_id: str) -> None:
+    """Authorize an existing namespace from persisted state, never by storage/cache."""
+    brain_id = validate_brain_id(brain_id)
+    if config.data_db.strip().lower() != "postgresql":
+        # Mixed storage profiles still use their configured canonical registry.
+        from src.services.data.main import data_adapter
+        if data_adapter.get_brain(name_key=brain_id) is None:
+            raise BrainNotFoundError("Brain not found")
+        return
+    with borrow(get_system_pool()) as conn:
+        with conn.cursor() as cur:
+            cur.execute("SELECT 1 FROM data_brains WHERE name_key = %s", (brain_id,))
+            if cur.fetchone() is None:
+                raise BrainNotFoundError("Brain not found")
+
+
 @contextmanager
 def borrow(pool: psycopg2.pool.ThreadedConnectionPool) -> Iterator[psycopg2.extensions.connection]:
     conn = pool.getconn()
     try:
         yield conn
+    except BaseException:
+        conn.rollback()
+        raise
     finally:
         pool.putconn(conn)
 
@@ -181,6 +208,7 @@ def ensure_database_exists(dbname: str) -> None:
 
 def ensure_brain_database(brain_id: str) -> str:
     """Return the per-brain database name, creating the database if needed."""
+    require_registered_brain(brain_id)
     dbname = brain_db_name(brain_id)
     ensure_database_exists(dbname)
     return dbname
@@ -232,7 +260,7 @@ def clear_brain_database(
             if cur.fetchone() is None:
                 return []
 
-    with borrow(get_brain_pool(brain_id)) as conn:
+    with borrow(get_pool(dbname)) as conn:
         with conn.cursor() as cur:
             cur.execute(
                 "SELECT tablename FROM pg_tables "
@@ -255,3 +283,24 @@ def clear_brain_database(
                 )
         conn.commit()
     return tables
+
+
+def drop_brain_database(brain_id: str) -> None:
+    """Explicit lifecycle delete, including unregistered orphan storage."""
+    brain_id = validate_brain_id(brain_id)
+    dbname = brain_db_name(brain_id)
+    if dbname in {_system_dbname(), _maintenance_dbname()}:
+        raise ValueError("Cannot delete an infrastructure database")
+    _registry.discard(dbname)
+    conn = psycopg2.connect(
+        host=config.postgresql.host, port=config.postgresql.port,
+        user=config.postgresql.username, password=config.postgresql.password,
+        dbname=_maintenance_dbname(),
+    )
+    try:
+        conn.autocommit = True
+        with conn.cursor() as cur:
+            cur.execute(sql.SQL("DROP DATABASE IF EXISTS {} WITH (FORCE)").format(sql.Identifier(dbname)))
+    finally:
+        conn.close()
+    _created_dbs.discard(dbname)

src/lib/postgresql/data.py

@@ -17,6 +17,7 @@ import psycopg2.extras
 
 from src.adapters.interfaces.data import DataClient, SearchResult
 from src.config import SEARCH_FTS_REGCONFIGS, config
+from src.services.brain_identity import BrainAlreadyExistsError, validate_brain_id
 from src.constants.data import (
     Brain,
     KGChanges,
@@ -27,11 +28,6 @@ from src.constants.data import (
     Workspace,
 )
 
-from ._naming import (
-    brain_db_name,
-    brain_id_from_db_name,
-    is_internal_brain_db_suffix,
-)
 from ._provisioning import (
     borrow,
     ensure_brain_database,
@@ -39,7 +35,8 @@ from ._provisioning import (
     get_brain_pool,
     get_system_pool,
     clear_brain_database,
-    list_brain_database_names,
+    drop_brain_database,
+    require_registered_brain,
 )
 
 
@@ -272,7 +269,7 @@ class PostgreSQLDataClient(DataClient):
     def _brain_connection(
         self, brain_id: str
     ) -> Iterator[psycopg2.extensions.connection]:
-        self._ensure_brain_schema(brain_id)
+        # Existing connection only: provisioning belongs to create_brain().
         with borrow(get_brain_pool(brain_id)) as conn:
             yield conn
 
@@ -290,6 +287,7 @@ class PostgreSQLDataClient(DataClient):
             self._system_initialized = True
 
     def _ensure_brain_schema(self, brain_id: str) -> None:
+        require_registered_brain(brain_id)
         alt_regconfig = config.search_fts_regconfig_for_brain(brain_id)
         needs_base = brain_id not in self._initialized_brains
         needs_search = (
@@ -536,23 +534,27 @@ class PostgreSQLDataClient(DataClient):
         return structured_data
 
     def create_brain(self, name_key: str) -> Brain:
+        name_key = validate_brain_id(name_key)
         brain = Brain(name_key=name_key)
         document = brain.model_dump(mode="json")
-        with self._system_connection() as conn:
-            with conn.cursor() as cur:
-                cur.execute(
-                    """
-                    INSERT INTO data_brains (id, name_key, pat, document)
-                    VALUES (%s, %s, %s, %s::jsonb)
-                    """,
-                    (
-                        brain.id,
-                        brain.name_key,
-                        brain.pat,
-                        json.dumps(document, default=str),
-                    ),
-                )
-            conn.commit()
+        try:
+            with self._system_connection() as conn:
+                with conn.cursor() as cur:
+                    cur.execute(
+                        """
+                        INSERT INTO data_brains (id, name_key, pat, document)
+                        VALUES (%s, %s, %s, %s::jsonb)
+                        """,
+                        (
+                            brain.id,
+                            brain.name_key,
+                            brain.pat,
+                            json.dumps(document, default=str),
+                        ),
+                    )
+                conn.commit()
+        except psycopg2.errors.UniqueViolation:
+            raise BrainAlreadyExistsError("Brain already exists") from None
         self._ensure_brain_schema(name_key)
         return brain
 
@@ -585,22 +587,10 @@ class PostgreSQLDataClient(DataClient):
             with conn.cursor(cursor_factory=psycopg2.extras.RealDictCursor) as cur:
                 cur.execute("SELECT document FROM data_brains")
                 rows = cur.fetchall()
-        registered = [Brain.model_validate(row["document"]) for row in rows]
-        by_key = {brain.name_key: brain for brain in registered}
-        known_db_names = {
-            brain_db_name(brain.name_key) for brain in registered
-        } | {brain_db_name(brain.id) for brain in registered}
-
-        for db_name in list_brain_database_names():
-            if db_name in known_db_names:
-                continue
-            suffix = brain_id_from_db_name(db_name)
-            if not suffix or is_internal_brain_db_suffix(suffix):
-                continue
-            if suffix not in by_key:
-                by_key[suffix] = Brain(name_key=suffix)
-
-        return sorted(by_key.values(), key=lambda brain: brain.name_key)
+        return sorted(
+            (Brain.model_validate(row["document"]) for row in rows),
+            key=lambda brain: brain.name_key,
+        )
 
     def create_workspace(self, workspace: Workspace) -> Workspace:
         with self._system_connection() as conn:
@@ -647,6 +637,12 @@ class PostgreSQLDataClient(DataClient):
     def clear_brain_data(self, brain_id: str) -> None:
         clear_brain_database(brain_id)
 
+    def delete_brain_storage(self, brain_id: str) -> None:
+        drop_brain_database(brain_id)
+        self._initialized_brains.discard(brain_id)
+        self._search_ready_brains.discard(brain_id)
+        self._search_alt_brains.discard(brain_id)
+
     def delete_brain_registry(self, brain_id: str) -> bool:
         with self._system_connection() as conn:
             with conn.cursor() as cur:

src/lib/postgresql/graph_store.py

@@ -19,7 +19,7 @@ import psycopg2.extras
 
 from src.config import config
 
-from ._provisioning import borrow, ensure_brain_database, get_brain_pool
+from ._provisioning import borrow, require_registered_brain, get_brain_pool
 from .read_query import (
     MAX_READ_QUERY_ROWS,
     READ_QUERY_TIMEOUT_MS,
@@ -152,9 +152,9 @@ class PostgreSQLGraphStore:
     """
     Graph driver that persists each brain into its own Postgres database.
 
-    The per-brain database is provisioned lazily through ``ensure_brain_database``
-    and accessed through the shared LRU pool registry. Each database owns a flat
-    schema (no ``brain_id`` columns, no ``kg_brains`` reference table) because
+    The per-brain database is provisioned explicitly at brain creation, then
+    accessed through registry-checked connections in the shared LRU pool registry.
+    Each database owns a flat schema (no ``brain_id`` columns, no ``kg_brains`` reference table) because
     the brain identity is encoded in the database name itself.
     """
 
@@ -226,6 +226,7 @@ class PostgreSQLGraphStore:
         self._brains_lock = threading.RLock()
 
     def _ensure_brain_schema(self, brain_id: str) -> None:
+        require_registered_brain(brain_id)
         needs_base = brain_id not in self._schema_ready
         needs_search = (
             bool(config.search_enabled) and brain_id not in self._search_ready_brains
@@ -240,7 +241,6 @@ class PostgreSQLGraphStore:
             )
             if not needs_base and not needs_search:
                 return
-            ensure_brain_database(brain_id)
             with borrow(get_brain_pool(brain_id)) as conn:
                 if needs_base:
                     with conn.cursor() as cur:
@@ -384,6 +384,8 @@ class PostgreSQLGraphStore:
     def invalidate_brain(self, brain_id: str) -> None:
         with self._brains_lock:
             self._brains.pop(brain_id, None)
+            self._schema_ready.discard(brain_id)
+            self._search_ready_brains.discard(brain_id)
 
     def _db_graph_counts(self, brain_id: str) -> tuple[int, int]:
         self._ensure_brain_schema(brain_id)
@@ -397,6 +399,7 @@ class PostgreSQLGraphStore:
 
     def _load_brain(self, brain_id: str) -> _BrainGraph:
         """Read path: refresh from Postgres when another process wrote data."""
+        require_registered_brain(brain_id)
         with self._brains_lock:
             cached = self._brains.get(brain_id)
             cached_counts = (

src/lib/postgresql/vectors.py

@@ -27,7 +27,7 @@ from src.lib.embeddings.profile import EmbeddingProfileError, index_profile, req
 from ._provisioning import (
     borrow,
     clear_brain_database,
-    ensure_brain_database,
+    require_registered_brain,
     get_brain_pool,
 )
 
@@ -136,12 +136,12 @@ class PostgreSQLVectorStoreClient(VectorStoreClient):
             yield conn
 
     def _ensure_extension(self, brain_id: str) -> None:
+        require_registered_brain(brain_id)
         if brain_id in self._brain_extensions_ready:
             return
         with self._lock:
             if brain_id in self._brain_extensions_ready:
                 return
-            ensure_brain_database(brain_id)
             with borrow(get_brain_pool(brain_id)) as conn:
                 with conn.cursor() as cur:
                     cur.execute("CREATE EXTENSION IF NOT EXISTS vector")
@@ -150,8 +150,13 @@ class PostgreSQLVectorStoreClient(VectorStoreClient):
 
     def clear_brain_data(self, brain_id: str) -> None:
         clear_brain_database(brain_id, table_prefixes=("vectors_",))
+        self._brain_extensions_ready.discard(brain_id)
+        self._initialized_stores = {
+            key for key in self._initialized_stores if not key.startswith(f"{brain_id}:")
+        }
 
     def _ensure_store(self, store: str, brain_id: str) -> None:
+        require_registered_brain(brain_id)
         if store not in EMBEDDING_STORES_SIZES:
             raise ValueError(f"Store {store} not available")
         dimension = EMBEDDING_STORES_SIZES[store]

src/services/api/controllers/system.py

@@ -9,7 +9,7 @@ Modified By: Christian Nonis <alch.infoemail@gmail.com>
 """
 
 import asyncio
-import re
+from src.services.brain_identity import validate_brain_id
 
 from src.services.api.constants.requests import CreateBrainRequest
 from src.services.brain_lifecycle import BrainLifecycleService
@@ -28,9 +28,8 @@ async def create_new_brain(request: CreateBrainRequest):
     """
     Create a new brain
     """
-    if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9_-]{0,127}", request.brain_id):
-        raise ValueError("brain_id contains unsupported characters")
-    result = await asyncio.to_thread(data_adapter.create_brain, request.brain_id)
+    brain_id = validate_brain_id(request.brain_id)
+    result = await asyncio.to_thread(data_adapter.create_brain, brain_id)
     return result
 
 

src/services/api/errors.py

@@ -12,6 +12,7 @@ from fastapi.responses import JSONResponse
 from pydantic import BaseModel, Field, JsonValue
 from starlette.exceptions import HTTPException as StarletteHTTPException
 from src.lib.embeddings.profile import EmbeddingProfileError
+from src.services.brain_identity import BrainNotFoundError, BrainAlreadyExistsError, InvalidBrainIdError
 
 
 class ErrorInfo(BaseModel):
@@ -158,6 +159,25 @@ def install_error_handlers(app: FastAPI) -> None:
             detail=exc.errors(),
         )
 
+    @app.exception_handler(BrainNotFoundError)
+    async def missing_brain_handler(request: Request, _exc: BrainNotFoundError):
+        return error_response(
+            request, status_code=404, detail="Brain not found", code="BRAIN_NOT_FOUND",
+            resolution="Create the brain explicitly or select a registered brain.",
+        )
+
+    @app.exception_handler(BrainAlreadyExistsError)
+    async def duplicate_brain_handler(request: Request, _exc: BrainAlreadyExistsError):
+        return error_response(
+            request, status_code=409, detail="Brain already exists", code="BRAIN_ALREADY_EXISTS",
+            message="A brain with this identifier already exists.",
+            resolution="Select the existing brain or create a different identifier.",
+        )
+
+    @app.exception_handler(InvalidBrainIdError)
+    async def invalid_brain_handler(request: Request, exc: InvalidBrainIdError):
+        return error_response(request, status_code=400, detail=str(exc), code=exc.code)
+
     @app.exception_handler(EmbeddingProfileError)
     async def embedding_profile_exception_handler(request: Request, exc: EmbeddingProfileError):
         return error_response(

src/services/api/middlewares/auth.py

@@ -94,7 +94,7 @@ class BrainPATMiddleware(BaseHTTPMiddleware):
                 detail="Brain ID is required.",
                 code="BRAIN_ID_REQUIRED",
                 message="A brain identifier is required.",
-                resolution="Send X-Brain-ID with the intended alphanumeric brain name.",
+                resolution="Send X-Brain-ID using 1-128 ASCII letters, digits, hyphens, or underscores, starting with a letter or digit.",
             )
         cachepat_key = f"brainpat:{brain_id}"
         if system_pat and secrets.compare_digest(brainpat, system_pat):

src/services/api/middlewares/brains.py

@@ -16,12 +16,11 @@ from email.parser import BytesParser
 
 from fastapi import Request
 from starlette.middleware.base import BaseHTTPMiddleware
-from starlette import status
 
 from src.services.api.console_static import is_console_path
 from src.services.api.errors import error_response
 from src.services.data.main import data_adapter
-from src.services.kg_agent.main import cache_adapter
+from src.services.brain_identity import InvalidBrainIdError, validate_brain_id
 from src.services.workspaces import WorkspaceScopeConflictError, resolve_workspace_scope
 
 
@@ -102,7 +101,7 @@ class BrainMiddleware(BaseHTTPMiddleware):
                         body_data = json.loads(body)
                         if isinstance(body_data, dict):
                             body_brain_id = body_data.get("brain_id")
-                            if body_brain_id:
+                            if isinstance(body_brain_id, str):
                                 body_brain_id = body_brain_id.rstrip()
                     except (json.JSONDecodeError, ValueError):
                         pass
@@ -163,83 +162,41 @@ class BrainMiddleware(BaseHTTPMiddleware):
         brain_id, scope_error = await _get_brain_id()
         if scope_error is not None:
             return scope_error
-        brain_creation_allowed = os.getenv("BRAIN_CREATION_ALLOWED") == "true"
         default_brain_fallback = os.getenv("DEFAULT_BRAIN_FALLBACK") == "true"
 
         # Bypassing system routes --------------------------------
         if request.url.path.startswith("/system") or request.url.path == "/":
             return await call_next(request)
 
-        # Cleanup checks -----------------------------------------
-        if brain_id == "system":
+        # Scope resolution never provisions a brain, even with legacy creation flags.
+        if brain_id is None and default_brain_fallback:
+            brain_id = "default"
+        if brain_id is None:
             return error_response(
-                request,
-                status_code=status.HTTP_400_BAD_REQUEST,
-                detail="System brain is not allowed to be used.",
-                code="BRAIN_ID_RESERVED",
-                message="The system brain is reserved.",
-                resolution="Select a non-system application brain.",
+                request, status_code=400, detail="Brain ID is required.",
+                code="BRAIN_ID_REQUIRED",
             )
-        if brain_id and not re.fullmatch(
-            r"[A-Za-z0-9][A-Za-z0-9_-]{0,127}", brain_id
-        ):
+        try:
+            brain_id = validate_brain_id(brain_id)
+        except InvalidBrainIdError as error:
             return error_response(
-                request,
-                status_code=status.HTTP_400_BAD_REQUEST,
-                detail="Brain ID contains unsupported characters.",
-                code="BRAIN_ID_INVALID",
-                message="The brain identifier is invalid.",
-                resolution="Use letters, digits, hyphens, or underscores.",
-                extra={"value": brain_id},
+                request, status_code=400, detail=str(error),
+                code=error.code,
+                resolution="Use 1-128 ASCII letters, digits, hyphens, or underscores, starting with a letter or digit; system is reserved.",
             )
-
         try:
-            cached_brain_id = cache_adapter.get(
-                key=f"brain:{brain_id}", brain_id="system"
-            )
-            if brain_id and not cached_brain_id:
-                stored_brain = data_adapter.get_brain(name_key=brain_id)
-
-                request.state.brain_id = brain_id
-
-                if not stored_brain and brain_creation_allowed:
-                    new_brain = data_adapter.create_brain(name_key=brain_id)
-                    cache_adapter.set(
-                        key=f"brain:{brain_id}",
-                        value=new_brain.id,
-                        brain_id="system",
-                    )
-                elif stored_brain:
-                    cache_adapter.set(
-                        key=f"brain:{brain_id}",
-                        value=stored_brain.id,
-                        brain_id="system",
-                    )
-            elif not brain_id and default_brain_fallback:
-                default_brain = data_adapter.get_brain(name_key="default")
-                if not default_brain:
-                    default_brain = data_adapter.create_brain(name_key="default")
-                    cache_adapter.set(
-                        key="brain:default",
-                        value=default_brain.id,
-                        brain_id="system",
-                    )
-                    request.state.brain_id = "default"
-                else:
-                    cache_adapter.set(
-                        key="brain:default",
-                        value=default_brain.id,
-                        brain_id="system",
-                    )
-                    request.state.brain_id = "default"
+            # A stale cache must never override registry deletion or authorize storage.
+            stored_brain = data_adapter.get_brain(name_key=brain_id)
         except Exception:
-            request.state.brain_id = brain_id or "default"
-
-        if getattr(request.state, "brain_id", None) is None:
             return error_response(
-                request,
-                status_code=status.HTTP_406_NOT_ACCEPTABLE,
-                detail="Brain not found or creation is not allowed.",
+                request, status_code=503, detail="Brain registry unavailable",
             )
-
+        if stored_brain is None:
+            request.state.brain_id = None
+            return error_response(
+                request, status_code=404, detail="Brain not found",
+                code="BRAIN_NOT_FOUND",
+                resolution="Create the brain explicitly or select a registered brain.",
+            )
+        request.state.brain_id = brain_id
         return await call_next(request)

src/services/api/routes/public.py

@@ -4,6 +4,8 @@ from __future__ import annotations
 
 import os
 
+from src.services.brain_identity import InvalidBrainIdError, validate_brain_id
+
 from fastapi import APIRouter, HTTPException, Query
 from pydantic import BaseModel, Field
 
@@ -71,7 +73,9 @@ async def demo_search(
         raise HTTPException(status_code=404, detail="Public demo search is disabled")
 
     brain_id = os.getenv("PUBLIC_DEMO_BRAIN_ID", "agentdemo").strip()
-    if not brain_id or not brain_id.isalnum() or brain_id == "system":
+    try:
+        brain_id = validate_brain_id(brain_id)
+    except InvalidBrainIdError:
         raise HTTPException(
             status_code=503,
             detail="Public demo brain is not configured correctly",

src/services/api/routes/system.py

@@ -62,9 +62,9 @@ async def clear_brain(brain_id: str, request: Request):
             request,
             status_code=400,
             detail=str(error),
-            code="BRAIN_ID_INVALID",
+            code=error.code,
             message="The brain identifier is invalid.",
-            resolution="Use an alphanumeric brain ID that starts with a letter.",
+            resolution="Use 1-128 ASCII letters, digits, hyphens, or underscores, starting with a letter or digit; system is reserved.",
         )
     except BrainNotFoundError as error:
         return error_response(
@@ -112,9 +112,9 @@ async def delete_brain(brain_id: str, request: Request):
             request,
             status_code=400,
             detail=str(error),
-            code="BRAIN_ID_INVALID",
+            code=error.code,
             message="The brain identifier is invalid.",
-            resolution="Use an alphanumeric brain ID that starts with a letter.",
+            resolution="Use 1-128 ASCII letters, digits, hyphens, or underscores, starting with a letter or digit; system is reserved.",
         )
     except BrainLifecycleBusyError as error:
         return error_response(

src/services/brain_identity.py

@@ -0,0 +1,33 @@
+"""Canonical public brain identifiers and registry domain errors."""
+
+import re
+
+
+class InvalidBrainIdError(ValueError):
+    """Invalid or reserved public brain identifier."""
+    code = "BRAIN_ID_INVALID"
+
+
+class ReservedBrainIdError(InvalidBrainIdError):
+    """The identifier belongs to BrainAPI infrastructure."""
+    code = "BRAIN_ID_RESERVED"
+
+
+class BrainNotFoundError(LookupError):
+    """The canonical registry does not contain the requested brain."""
+
+
+class BrainAlreadyExistsError(ValueError):
+    """A registry uniqueness constraint rejected brain creation."""
+
+
+def validate_brain_id(brain_id: str) -> str:
+    value = brain_id.strip() if isinstance(brain_id, str) else ""
+    if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9_-]{0,127}", value):
+        raise InvalidBrainIdError(
+            "brain_id must be 1-128 ASCII letters, digits, hyphens, or underscores "
+            "and start with a letter or digit"
+        )
+    if value.lower() == "system":
+        raise ReservedBrainIdError('brain_id "system" is reserved')
+    return value

src/services/brain_lifecycle.py

@@ -7,6 +7,10 @@ from dataclasses import dataclass
 import logging
 from typing import Any, Iterator, Protocol
 
+from src.services.brain_identity import (
+    BrainNotFoundError, InvalidBrainIdError, validate_brain_id,
+)
+
 
 logger = logging.getLogger(__name__)
 
@@ -15,14 +19,6 @@ class BrainLifecycleError(RuntimeError):
     """Base class for lifecycle failures safe to map at the API boundary."""
 
 
-class InvalidBrainIdError(BrainLifecycleError):
-    """Raised when a lifecycle target is invalid or reserved."""
-
-
-class BrainNotFoundError(BrainLifecycleError):
-    """Raised when a clear operation targets an unknown brain."""
-
-
 class BrainLifecycleBusyError(BrainLifecycleError):
     """Raised when another lifecycle operation already owns the brain lock."""
 
@@ -74,21 +70,6 @@ class BrainLifecycleResult:
         }
 
 
-def validate_brain_id(brain_id: str) -> str:
-    normalized = (brain_id or "").strip()
-    if (
-        not normalized
-        or not normalized.isalnum()
-        or not normalized[0].isalpha()
-    ):
-        raise InvalidBrainIdError(
-            "brain_id must be alphanumeric and start with a letter"
-        )
-    if normalized.lower() == "system":
-        raise InvalidBrainIdError('brain_id "system" is reserved')
-    return normalized
-
-
 class BrainLifecycleService:
     """Clear or delete one brain across the active storage profile."""
 
@@ -183,6 +164,10 @@ class BrainLifecycleService:
                 )
                 raise BrainCleanupError(brain_id, ["registry_cache"]) from None
             try:
+                # PostgreSQL namespaces must disappear even when registry-less.
+                delete_storage = getattr(self._data, "delete_brain_storage", None)
+                if delete_storage is not None:
+                    delete_storage(brain_id)
                 self._data.delete_brain_registry(brain_id)
             except Exception:
                 logger.exception("Failed to delete registry for brain %s", brain_id)

src/services/mcp/utils.py

@@ -12,6 +12,7 @@ Modified By: Christian Nonis <alch.infoemail@gmail.com>
 import secrets
 
 from src.config import config
+from src.services.brain_identity import BrainNotFoundError, validate_brain_id
 from src.services.data.main import data_adapter
 
 
@@ -25,6 +26,10 @@ def guard_brainpat(pat: str = None, target_brain: str = None) -> bool | str:
     if pat and config.brainpat_token and secrets.compare_digest(
         pat, config.brainpat_token
     ):
+        if target_brain:
+            target_brain = validate_brain_id(target_brain)
+            if data_adapter.get_brain(target_brain) is None:
+                raise BrainNotFoundError("Brain not found")
         return True
 
     brains = data_adapter.get_brains_list()

src/services/workspaces.py

@@ -9,6 +9,7 @@ from hashlib import sha1
 from urllib.parse import quote, urlsplit
 
 from src.constants.data import Brain, Workspace
+from src.services.brain_identity import BrainAlreadyExistsError, validate_brain_id
 
 SLUG_RE = re.compile(r"^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$")
 
@@ -133,7 +134,11 @@ class WorkspaceService:
             raise WorkspaceConflictError(
                 f'Brain "{slug}" already exists; run workspace bootstrap'
             )
-        self.repository.create_brain(slug)
+        validate_brain_id(slug)
+        try:
+            self.repository.create_brain(slug)
+        except BrainAlreadyExistsError:
+            raise WorkspaceConflictError("Brain already exists") from None
         return self.repository.create_workspace(
             Workspace(
                 brain_id=slug,

tests/integration/test_brain_registry_contract.py

@@ -0,0 +1,27 @@
+"""Opt-in gate against a disposable local HF CPU container, never the live Space."""
+import json
+import os
+import subprocess
+
+import pytest
+
+
+@pytest.mark.integration
+def test_real_registry_storage_contract():
+    container = os.getenv('BRAINAPI_REGISTRY_TEST_CONTAINER')
+    if not container:
+        pytest.skip('Set BRAINAPI_REGISTRY_TEST_CONTAINER to a disposable HF CPU container')
+    environment = dict(os.environ)
+    for selector in ('DOCKER_HOST', 'DOCKER_CONTEXT', 'DOCKER_TLS', 'DOCKER_TLS_VERIFY', 'DOCKER_CERT_PATH'):
+        environment.pop(selector, None)
+    result = subprocess.run(
+        ['docker', '--host=unix:///var/run/docker.sock', 'exec', container,
+         'bash', '/app/entrypoint.sh', '--qualify-registry'],
+        env=environment, capture_output=True, text=True, timeout=300, check=True,
+    )
+    report = json.loads(result.stdout.strip().splitlines()[-1])
+    assert report['result'] == 'passed'
+    for operation in ('entities', 'search', 'context'):
+        assert report['unknown_' + operation] == '404 BRAIN_NOT_FOUND; storage/cache unchanged'
+    assert report['storage_duplicate_race'] == 'one create, one domain conflict'
+    assert report['orphan_cleanup'] == 'physical database removed without registry creation'

tests/test_agent_api.py

@@ -17,7 +17,6 @@ def agent_client(monkeypatch):
     monkeypatch.setenv("BRAINPAT_TOKEN", "system-secret")
     monkeypatch.setenv("PUBLIC_BASE_URL", "https://brain.example")
     monkeypatch.setattr(brains, "data_adapter", data)
-    monkeypatch.setattr(brains, "cache_adapter", cache)
     monkeypatch.setattr(auth, "data_adapter", data)
     monkeypatch.setattr(auth, "cache_adapter", cache)
     monkeypatch.setattr(agent, "data_adapter", data)

tests/test_agent_readiness_api.py

@@ -150,8 +150,8 @@ class StructuredErrorTests(unittest.TestCase):
             return {"ok": True}
 
         with patch(
-            "src.services.api.middlewares.brains.cache_adapter.get",
-            side_effect=ConnectionError("redis secret"),
+            "src.services.api.middlewares.brains.data_adapter.get_brain",
+            side_effect=ConnectionError("registry secret"),
         ):
             response = TestClient(app).get(
                 "/protected",
@@ -159,7 +159,7 @@ class StructuredErrorTests(unittest.TestCase):
             )
         self.assertEqual(response.status_code, 503)
         self.assertEqual(response.json()["error"]["code"], "SERVICE_UNAVAILABLE")
-        self.assertNotIn("redis secret", response.text)
+        self.assertNotIn("registry secret", response.text)
 
 
 class PublicApiTests(unittest.TestCase):

tests/test_brain_lifecycle.py

@@ -133,7 +133,7 @@ def test_partial_cleanup_keeps_registry_for_a_safe_retry():
     assert "registry:delete:demo" not in events
 
 
-@pytest.mark.parametrize("brain_id", ["", "123", "bad-id", "system"])
+@pytest.mark.parametrize("brain_id", ["", "bad id", "-bad", "system", "SYSTEM", "a" * 129])
 def test_lifecycle_rejects_invalid_or_reserved_brain_ids(brain_id: str):
     with pytest.raises(InvalidBrainIdError):
         validate_brain_id(brain_id)

tests/test_brain_registry_contract.py

@@ -0,0 +1,341 @@
+"""Registry authority at the HTTP, PostgreSQL, and MCP boundaries."""
+from contextlib import contextmanager
+from copy import deepcopy
+from types import SimpleNamespace
+from unittest.mock import MagicMock
+
+import psycopg2
+import pytest
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+from src.constants.data import Brain
+from src.lib.postgresql import _provisioning, data, graph_store, vectors
+from src.services.api.errors import install_error_handlers
+from src.services.api.middlewares import auth, brains
+from src.services.api.routes import retrieve, system
+from src.services.api.controllers import system as system_controller
+from src.services.brain_identity import (
+    BrainAlreadyExistsError, BrainNotFoundError, InvalidBrainIdError, validate_brain_id,
+)
+from src.services.brain_lifecycle import BrainLifecycleService
+
+
+VALID_IDS = ['alpha', 'alpha123', 'lifeos-projects', 'probe_readonly_check_123', 'A1-test_name', '123', 'a' * 128]
+INVALID_IDS = ['', '-bad', '_bad', 'bad id', 'a/b', 'éclair', 'a' * 129, 'system', 'SYSTEM']
+
+
+class Registry:
+    def __init__(self):
+        self.rows = {}
+        self.databases = set()
+        self.workspaces = {}
+        self.cache = {}
+
+    def get_brain(self, name_key):
+        return self.rows.get(name_key)
+
+    def create_brain(self, name_key):
+        if name_key in self.rows:
+            raise BrainAlreadyExistsError('Brain already exists')
+        brain = Brain(name_key=name_key)
+        self.rows[name_key] = brain
+        self.databases.add(name_key)
+        return brain
+
+    def get_brains_list(self):
+        return sorted(self.rows.values(), key=lambda b: b.name_key)
+
+    def clear_brain_data(self, brain_id):
+        pass
+
+    def delete_brain_storage(self, brain_id):
+        self.databases.discard(brain_id)
+
+    def delete_brain_registry(self, brain_id):
+        return self.rows.pop(brain_id, None) is not None
+
+    def clear_brain_registry_cache(self, brain_id):
+        self.cache.pop(brain_id, None)
+
+    def snapshot(self):
+        return deepcopy((self.rows, self.databases, self.workspaces, self.cache))
+
+
+@pytest.fixture
+def api(monkeypatch):
+    registry = Registry()
+    monkeypatch.setenv('BRAINPAT_TOKEN', 'contract-system-pat')
+    monkeypatch.setattr(brains, 'data_adapter', registry)
+    monkeypatch.setattr(auth, 'data_adapter', registry)
+    monkeypatch.setattr(system_controller, 'data_adapter', registry)
+    lifecycle = BrainLifecycleService(data_client=registry, graph_client=registry,
+                                    vector_client=registry, cache_client=registry)
+    monkeypatch.setattr(system, 'get_brain_lifecycle_service', lambda: lifecycle)
+    # Controllers are isolated here; real storage + actual retrieval run in integration.
+    async def entities(*args, **kwargs):
+        return {'message': 'ok', 'entities': [], 'total': 0}
+    async def search(*args, **kwargs):
+        return {'hits': []}
+    async def context(*args, **kwargs):
+        return {'text_context': '', 'triples': []}
+    monkeypatch.setattr(retrieve, 'retrieve_get_entities_controller', entities)
+    monkeypatch.setattr(retrieve, 'search_controller', search)
+    monkeypatch.setattr(retrieve, 'retrieve_get_context_controller', context)
+    app = FastAPI()
+    install_error_handlers(app)
+    app.add_middleware(auth.BrainPATMiddleware)
+    app.add_middleware(brains.BrainMiddleware)
+    app.include_router(system.system_router)
+    app.include_router(retrieve.retrieve_router)
+    return TestClient(app), registry
+
+
+def read(client, kind, brain_id):
+    headers = {'BrainPAT': 'contract-system-pat'}
+    if kind == 'entities':
+        return client.get('/retrieve/entities', params={'brain_id': brain_id}, headers=headers)
+    return client.post('/retrieve/' + kind, json={
+        'brain_id': brain_id, 'query' if kind == 'search' else 'text': 'probe',
+    }, headers=headers)
+
+
+@pytest.mark.parametrize('kind', ['entities', 'search', 'context'])
+@pytest.mark.parametrize('creation_allowed', ['true', 'false'])
+def test_unknown_retrieval_is_side_effect_free(api, monkeypatch, kind, creation_allowed):
+    client, registry = api
+    monkeypatch.setenv('BRAIN_CREATION_ALLOWED', creation_allowed)
+    # Deliberately stale positive cache cannot make an orphan authoritative.
+    registry.cache['probe_readonly_check_123'] = 'stale-id'
+    before = registry.snapshot()
+    response = read(client, kind, 'probe_readonly_check_123')
+    assert response.status_code == 404
+    assert response.json()['error']['code'] == 'BRAIN_NOT_FOUND'
+    assert registry.snapshot() == before
+
+
+@pytest.mark.parametrize('kind', ['entities', 'search', 'context'])
+def test_explicitly_provisioned_brain_reads_keep_identity(api, kind):
+    client, registry = api
+    created = client.post('/system/brains', json={'brain_id': 'known-brain'},
+                          headers={'BrainPAT': 'contract-system-pat'})
+    assert created.status_code == 200
+    before = registry.snapshot()
+    response = read(client, kind, 'known-brain')
+    assert response.status_code == 200, response.text
+    assert registry.snapshot() == before
+
+
+@pytest.mark.parametrize('brain_id', VALID_IDS)
+def test_create_clear_delete_identifier_parity(api, brain_id):
+    client, registry = api
+    headers = {'BrainPAT': 'contract-system-pat'}
+    assert validate_brain_id(brain_id) == brain_id
+    assert client.post('/system/brains', headers=headers, json={'brain_id': brain_id}).status_code == 200
+    identity = (registry.rows[brain_id].id, registry.rows[brain_id].pat)
+    assert client.post(f'/system/brains/{brain_id}/clear', headers=headers).status_code == 200
+    assert (registry.rows[brain_id].id, registry.rows[brain_id].pat) == identity
+    assert client.delete(f'/system/brains/{brain_id}', headers=headers).status_code == 200
+    assert brain_id not in registry.rows and brain_id not in registry.databases
+
+
+@pytest.mark.parametrize('brain_id', INVALID_IDS)
+def test_invalid_identifiers_rejected_consistently(api, brain_id):
+    client, registry = api
+    with pytest.raises(InvalidBrainIdError) as invalid:
+        validate_brain_id(brain_id)
+    before = registry.snapshot()
+    response = client.post('/system/brains', headers={'BrainPAT': 'contract-system-pat'}, json={'brain_id': brain_id})
+    assert response.status_code == 400
+    assert response.json()['error']['code'] == invalid.value.code
+    assert registry.snapshot() == before
+    lifecycle = BrainLifecycleService(data_client=registry, graph_client=registry,
+                                    vector_client=registry, cache_client=registry)
+    for operation in (lifecycle.clear, lifecycle.delete):
+        with pytest.raises(InvalidBrainIdError):
+            operation(brain_id)
+    assert registry.snapshot() == before
+
+
+def test_duplicate_create_is_safe_conflict(api):
+    client, registry = api
+    headers = {'BrainPAT': 'contract-system-pat'}
+    assert client.post('/system/brains', headers=headers, json={'brain_id': 'alpha'}).status_code == 200
+    before = registry.snapshot()
+    response = client.post('/system/brains', headers=headers, json={'brain_id': 'alpha'})
+    assert response.status_code == 409
+    assert response.json()['error']['code'] == 'BRAIN_ALREADY_EXISTS'
+    assert registry.rows['alpha'].pat not in response.text
+    assert registry.snapshot() == before
+
+
+def test_orphan_delete_does_not_register_brain(api):
+    client, registry = api
+    registry.databases.add('orphan_storage')
+    response = client.delete('/system/brains/orphan_storage', headers={'BrainPAT': 'contract-system-pat'})
+    assert response.status_code == 200
+    assert response.json()['existed'] is False
+    assert not registry.rows and not registry.databases
+
+
+def test_postgres_unique_violation_maps_to_domain_conflict(monkeypatch):
+    client = data.PostgreSQLDataClient()
+    connection = MagicMock()
+    connection.cursor.return_value.__enter__.return_value.execute.side_effect = psycopg2.errors.UniqueViolation('secret DB details')
+    @contextmanager
+    def connect():
+        yield connection
+    monkeypatch.setattr(client, '_system_connection', connect)
+    provision = MagicMock()
+    monkeypatch.setattr(client, '_ensure_brain_schema', provision)
+    with pytest.raises(BrainAlreadyExistsError, match='^Brain already exists$'):
+        client.create_brain('alpha')
+    provision.assert_not_called()
+
+
+def test_registry_list_never_discovers_or_synthesizes_storage_brains(monkeypatch):
+    client = data.PostgreSQLDataClient()
+    registered = Brain(name_key='persisted')
+    connection = MagicMock()
+    connection.cursor.return_value.__enter__.return_value.fetchall.return_value = [
+        {'document': registered.model_dump(mode='json')},
+    ]
+    @contextmanager
+    def connect():
+        yield connection
+    monkeypatch.setattr(client, '_system_connection', connect)
+    discovery = MagicMock(return_value=['brain_persisted', 'brain_orphan'])
+    monkeypatch.setattr(_provisioning, 'list_brain_database_names', discovery)
+    assert client.get_brains_list() == client.get_brains_list() == [registered]
+    discovery.assert_not_called()
+
+
+@pytest.mark.parametrize('backend', ['data', 'graph', 'vectors'])
+def test_unknown_backend_read_cannot_create_storage_or_cache(monkeypatch, backend):
+    connection = MagicMock()
+    connection.cursor.return_value.__enter__.return_value.fetchone.return_value = None
+    pool = MagicMock()
+    pool.getconn.return_value = connection
+    monkeypatch.setattr(_provisioning.config, 'data_db', 'postgresql')
+    monkeypatch.setattr(_provisioning, 'get_system_pool', lambda: pool)
+    allocate = MagicMock(side_effect=AssertionError('brain connection allocated'))
+    provision = MagicMock(side_effect=AssertionError('database created'))
+    monkeypatch.setattr(_provisioning._registry, 'get', allocate)
+    monkeypatch.setattr(_provisioning, 'ensure_database_exists', provision)
+    if backend == 'data':
+        client = data.PostgreSQLDataClient()
+        operation = lambda: client.get_text_chunks(brain_id='unknown')
+        snapshots = lambda: deepcopy(client._initialized_brains)
+    elif backend == 'graph':
+        monkeypatch.setattr(graph_store.config, 'postgresql', SimpleNamespace(validate_credentials=lambda: None))
+        client = graph_store.PostgreSQLGraphStore()
+        operation = lambda: client.get_brain('unknown')
+        snapshots = lambda: deepcopy((client._schema_ready, client._brains))
+    else:
+        client = vectors.PostgreSQLVectorStoreClient()
+        operation = lambda: client.search_vectors([1, 0, 0], brain_id='unknown', store='data')
+        snapshots = lambda: deepcopy((client._brain_extensions_ready, client._initialized_stores))
+    before = snapshots()
+    with pytest.raises(BrainNotFoundError):
+        operation()
+    assert snapshots() == before
+    allocate.assert_not_called()
+    provision.assert_not_called()
+    statements = [c.args[0] for c in connection.cursor.return_value.__enter__.return_value.execute.call_args_list]
+    assert statements and all(s.startswith('SELECT ') for s in statements)
+
+
+def test_mcp_system_pat_does_not_authorize_unknown_storage(monkeypatch):
+    from src.services.mcp import utils
+    registry = Registry()
+    monkeypatch.setattr(utils, 'data_adapter', registry)
+    monkeypatch.setattr(utils.config, 'brainpat_token', 'system-pat')
+    before = registry.snapshot()
+    with pytest.raises(BrainNotFoundError):
+        utils.guard_brainpat('system-pat', 'unknown')
+    assert registry.snapshot() == before
+
+
+def test_default_fallback_never_provisions_a_missing_default(api, monkeypatch):
+    client, registry = api
+    monkeypatch.setenv('DEFAULT_BRAIN_FALLBACK', 'true')
+    monkeypatch.setenv('BRAIN_CREATION_ALLOWED', 'true')
+    before = registry.snapshot()
+    response = client.post('/retrieve/search', json={'query': 'probe'}, headers={'BrainPAT': 'contract-system-pat'})
+    assert response.status_code == 404
+    assert response.json()['error']['code'] == 'BRAIN_NOT_FOUND'
+    assert registry.snapshot() == before
+
+
+def test_stale_graph_and_vector_cache_cannot_replace_registry(monkeypatch):
+    def missing(brain_id):
+        raise BrainNotFoundError('Brain not found')
+    monkeypatch.setattr(graph_store.config, 'postgresql', SimpleNamespace(validate_credentials=lambda: None))
+    monkeypatch.setattr(graph_store, 'require_registered_brain', missing)
+    graph = graph_store.PostgreSQLGraphStore()
+    graph._brains['deleted'] = graph_store._BrainGraph('deleted')
+    graph._schema_ready.add('deleted')
+    with pytest.raises(BrainNotFoundError):
+        graph.get_brain('deleted')
+    monkeypatch.setattr(vectors, 'require_registered_brain', missing)
+    vector = vectors.PostgreSQLVectorStoreClient()
+    vector._brain_extensions_ready.add('deleted')
+    with pytest.raises(BrainNotFoundError):
+        vector._ensure_extension('deleted')
+
+
+def test_mongo_unique_violation_maps_to_domain_conflict(monkeypatch):
+    from pymongo.errors import DuplicateKeyError
+    from src.config import config
+    monkeypatch.setattr(config, 'mongo', SimpleNamespace(
+        system_database='system', connection_string='mongodb://localhost:27017'))
+    from src.lib.mongo.client import MongoClient
+    client = MongoClient.__new__(MongoClient)
+    collection = MagicMock()
+    collection.insert_one.side_effect = DuplicateKeyError('secret database details')
+    client.get_collection = MagicMock(return_value=collection)
+    with pytest.raises(BrainAlreadyExistsError, match='^Brain already exists$'):
+        client.create_brain('alpha')
+    collection.create_index.assert_called_once_with('name_key', unique=True)
+
+
+def test_mixed_profile_provisions_postgres_only_on_explicit_create(monkeypatch):
+    from src.adapters.data import DataAdapter
+    from src.config import config
+    from src.services.data import main
+    monkeypatch.setattr(config, 'data_db', 'mongo')
+    monkeypatch.setattr(config, 'vector_db', 'postgresql')
+    registry = Registry()
+    monkeypatch.setattr(main, 'data_adapter', registry)
+    adapter = DataAdapter()
+    adapter.add_client(registry)
+    allocate = MagicMock()
+    monkeypatch.setattr(_provisioning, 'ensure_brain_database', allocate)
+    with pytest.raises(BrainNotFoundError):
+        _provisioning.require_registered_brain('unknown')
+    allocate.assert_not_called()
+    brain = adapter.create_brain('mixed-profile')
+    allocate.assert_called_once_with(brain.name_key)
+    _provisioning.require_registered_brain('mixed-profile')
+
+
+def test_demo_seed_explicitly_provisions_a_missing_brain(monkeypatch):
+    from scripts import seed_public_demo
+    from unittest.mock import Mock
+    monkeypatch.setenv('BRAINPAT_TOKEN', 'seed-system-pat')
+    monkeypatch.setattr('sys.argv', ['seed_public_demo.py', '--brain', 'seed-demo'])
+    def response(status, payload=None, text=''):
+        result = Mock(status_code=status, text=text)
+        result.json.return_value = payload
+        return result
+    get = Mock(side_effect=[response(200, text='docs'),
+                            response(404, {'error': {'code': 'BRAIN_NOT_FOUND'}}),
+                            response(200, {'status': 'completed'})])
+    post = Mock(side_effect=[response(200, {'name_key': 'seed-demo'}),
+                            response(200, {'task_id': 'seed-task'})])
+    monkeypatch.setattr(seed_public_demo.requests, 'get', get)
+    monkeypatch.setattr(seed_public_demo.requests, 'post', post)
+    assert seed_public_demo.main() == 0
+    assert post.call_args_list[0].args[0].endswith('/system/brains')
+    assert post.call_args_list[0].kwargs['json'] == {'brain_id': 'seed-demo'}
+    assert post.call_args_list[1].args[0].endswith('/ingest/')

tests/test_embeddinggemma2.py

@@ -113,6 +113,7 @@ def test_postgres_rejects_incompatible_index_without_dropping_vectors(gemma, mon
     def connect(brain):
         yield connection
     monkeypatch.setattr(client, '_connection', connect)
+    monkeypatch.setattr(vectors, 'require_registered_brain', lambda brain_id: None)
     monkeypatch.setitem(vectors.EMBEDDING_STORES_SIZES, 'data', 512)
     with pytest.raises(EmbeddingProfileError, match='new empty brain/index'):
         client._ensure_store('data', 'qualification')
@@ -129,6 +130,7 @@ def test_fresh_postgres_schema_records_profile_and_512_dimensions(gemma, monkeyp
     def connect(brain):
         yield connection
     monkeypatch.setattr(client, '_connection', connect)
+    monkeypatch.setattr(vectors, 'require_registered_brain', lambda brain_id: None)
     monkeypatch.setattr(vectors, 'EMBEDDING_STORES_SIZES', dict.fromkeys(
         ('nodes', 'triplets', 'observations', 'data', 'relationships'), 512))
     for store in vectors.EMBEDDING_STORES_SIZES:

tests/test_graph_upsert_contract.py

@@ -170,7 +170,8 @@ class NetworkXUpsertContractTests(unittest.TestCase):
         fresh.graph.add_edge("a", "b", key="r1", rel_type="KNOWS")
         store._reload_brain_locked = MagicMock(return_value=fresh)
 
-        loaded = store._load_brain("brain-a")
+        with patch("src.lib.postgresql.graph_store.require_registered_brain"):
+            loaded = store._load_brain("brain-a")
         self.assertIs(loaded, fresh)
         store._reload_brain_locked.assert_called_once_with("brain-a")
 

tests/test_retrieve_auth_isolation.py

@@ -7,7 +7,7 @@ client = TestClient(app)
 
 @pytest.fixture
 def mock_data_adapter():
-    with patch("src.services.api.middlewares.auth.data_adapter") as mock_da:
+    with patch("src.services.api.middlewares.auth.data_adapter") as mock_da, patch("src.services.api.middlewares.brains.data_adapter", mock_da):
         yield mock_da
 
 @pytest.fixture

tests/test_retrieve_http_contract.py

@@ -5,6 +5,14 @@ from src.services.api.app import app
 
 client = TestClient(app)
 
+@pytest.fixture(autouse=True)
+def registered_scope(monkeypatch):
+    from types import SimpleNamespace
+    from src.services.api.middlewares import brains
+    monkeypatch.setattr(brains.data_adapter, 'get_brain', lambda name_key: SimpleNamespace(name_key=name_key))
+    monkeypatch.setenv('DEFAULT_BRAIN_FALLBACK', 'true')
+
+
 def test_retrieve_search_post_unauthorized():
     response = client.post("/retrieve/search", json={"query": "test"})
     assert response.status_code == 401

tests/test_search_bm25.py

@@ -56,6 +56,13 @@ def _postgres_available() -> bool:
 
 
 class OkapiBm25Tests(unittest.TestCase):
+    def setUp(self):
+        # These unit tests isolate FTS schema policy for registered namespaces.
+        for module in ('src.lib.postgresql.data', 'src.lib.postgresql.graph_store'):
+            guard = patch(module + '.require_registered_brain')
+            guard.start()
+            self.addCleanup(guard.stop)
+
     def test_term_overlap_ranks_above_non_overlap(self):
         overlap = okapi_bm25_document(
             {"license": 2.0},
@@ -165,6 +172,8 @@ class OkapiBm25Tests(unittest.TestCase):
         brain_id = "searchbench_bm25_unit"
         with patch.object(pgdata.config, "search_enabled", True):
             client = pgdata.PostgreSQLDataClient()
+            if client.get_brain(brain_id) is None:
+                client.create_brain(brain_id)
             overlap = TextChunk(
                 id="overlap",
                 text="alice counseling license renewal board",

tests/test_workspace_facade.py

@@ -87,7 +87,6 @@ def facade_client(monkeypatch):
     cache = FacadeCache()
     monkeypatch.setenv("BRAINPAT_TOKEN", "system-secret")
     monkeypatch.setattr(brains, "data_adapter", data)
-    monkeypatch.setattr(brains, "cache_adapter", cache)
     monkeypatch.setattr(auth, "data_adapter", data)
     monkeypatch.setattr(auth, "cache_adapter", cache)
     monkeypatch.setattr(workspace_api, "data_adapter", data)

tests/test_workspace_plugin_contract.py

@@ -65,7 +65,6 @@ def test_workspace_plugin_route_receives_authoritative_brain(monkeypatch):
     data, cache = FacadeData(), FacadeCache()
     monkeypatch.setenv("BRAINPAT_TOKEN", "system-secret")
     monkeypatch.setattr(brains, "data_adapter", data)
-    monkeypatch.setattr(brains, "cache_adapter", cache)
     monkeypatch.setattr(auth, "data_adapter", data)
     monkeypatch.setattr(auth, "cache_adapter", cache)
     app.add_middleware(BrainPATMiddleware)