memuron 0.1.1__py3-none-any.whl

memuron/persistence/identity_store.py

@@ -0,0 +1,918 @@
+"""Users, organizations, and memberships for Memuron auth."""
+
+from __future__ import annotations
+
+import json
+import re
+import sqlite3
+import threading
+from contextlib import contextmanager
+from datetime import UTC, datetime
+from pathlib import Path
+from time import monotonic
+from typing import Any, Iterator
+from uuid import uuid4
+
+from memuron.spaces.model import compile_space_token, default_personal_space, slugify_space
+
+import psycopg
+from artha_engine.store import is_postgres_dsn
+from psycopg.rows import dict_row
+from psycopg_pool import ConnectionPool
+
+
+def _utcnow() -> datetime:
+    return datetime.now(UTC).replace(tzinfo=None)
+
+
+def _slugify(value: str) -> str:
+    slug = re.sub(r"[^a-z0-9]+", "-", value.lower()).strip("-")
+    return slug or "org"
+
+
+class IdentityStore:
+    def __init__(self, database_target: str | Path) -> None:
+        self.database_target = str(database_target)
+        self.is_postgres = is_postgres_dsn(self.database_target)
+        self._space_cache: dict[tuple[str, str], tuple[float, list[dict[str, Any]]]] = {}
+        self._space_cache_lock = threading.RLock()
+        self._pool: ConnectionPool | None = None
+        if self.is_postgres:
+            self._pool = ConnectionPool(
+                conninfo=self.database_target,
+                min_size=1,
+                max_size=8,
+                kwargs={"row_factory": dict_row},
+                open=True,
+            )
+        self._init_schema()
+
+    @classmethod
+    def from_target(cls, database_target: str | Path) -> "IdentityStore":
+        return cls(database_target)
+
+    def _init_schema(self) -> None:
+        if self.is_postgres:
+            with self._connect_postgres() as conn:
+                conn.execute(
+                    """
+                    CREATE TABLE IF NOT EXISTS memuron_users (
+                      id UUID PRIMARY KEY,
+                      email TEXT NOT NULL UNIQUE,
+                      password_hash TEXT NOT NULL,
+                      name TEXT NOT NULL,
+                      created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+                    )
+                    """
+                )
+                conn.execute(
+                    """
+                    CREATE TABLE IF NOT EXISTS memuron_orgs (
+                      id UUID PRIMARY KEY,
+                      slug TEXT NOT NULL UNIQUE,
+                      name TEXT NOT NULL,
+                      created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+                    )
+                    """
+                )
+                conn.execute(
+                    """
+                    CREATE TABLE IF NOT EXISTS memuron_org_memberships (
+                      org_id UUID NOT NULL REFERENCES memuron_orgs(id) ON DELETE CASCADE,
+                      user_id UUID NOT NULL REFERENCES memuron_users(id) ON DELETE CASCADE,
+                      role TEXT NOT NULL DEFAULT 'member',
+                      created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+                      PRIMARY KEY (org_id, user_id)
+                    )
+                    """
+                )
+                conn.execute(
+                    """
+                    CREATE TABLE IF NOT EXISTS memuron_org_spaces (
+                      id UUID PRIMARY KEY,
+                      org_id UUID NOT NULL REFERENCES memuron_orgs(id) ON DELETE CASCADE,
+                      slug TEXT NOT NULL,
+                      name TEXT NOT NULL,
+                      token TEXT NOT NULL,
+                      description TEXT NOT NULL DEFAULT '',
+                      guardian_prompt TEXT NOT NULL DEFAULT '',
+                      is_default BOOLEAN NOT NULL DEFAULT FALSE,
+                      created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+                      UNIQUE (org_id, slug),
+                      UNIQUE (org_id, token)
+                    )
+                    """
+                )
+                conn.execute(
+                    """
+                    CREATE TABLE IF NOT EXISTS memuron_user_space_prefs (
+                      user_id UUID NOT NULL REFERENCES memuron_users(id) ON DELETE CASCADE,
+                      space_id UUID NOT NULL REFERENCES memuron_org_spaces(id) ON DELETE CASCADE,
+                      enabled BOOLEAN NOT NULL DEFAULT FALSE,
+                      updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+                      PRIMARY KEY (user_id, space_id)
+                    )
+                    """
+                )
+                conn.commit()
+                self._migrate_clerk_schema(conn)
+            return
+
+        with self._connect_sqlite() as conn:
+            conn.executescript(
+                """
+                CREATE TABLE IF NOT EXISTS memuron_users (
+                  id TEXT PRIMARY KEY,
+                  email TEXT NOT NULL UNIQUE COLLATE NOCASE,
+                  password_hash TEXT NOT NULL,
+                  name TEXT NOT NULL,
+                  created_at TEXT NOT NULL
+                );
+                CREATE TABLE IF NOT EXISTS memuron_orgs (
+                  id TEXT PRIMARY KEY,
+                  slug TEXT NOT NULL UNIQUE COLLATE NOCASE,
+                  name TEXT NOT NULL,
+                  created_at TEXT NOT NULL
+                );
+                CREATE TABLE IF NOT EXISTS memuron_org_memberships (
+                  org_id TEXT NOT NULL,
+                  user_id TEXT NOT NULL,
+                  role TEXT NOT NULL DEFAULT 'member',
+                  created_at TEXT NOT NULL,
+                  PRIMARY KEY (org_id, user_id),
+                  FOREIGN KEY (org_id) REFERENCES memuron_orgs(id) ON DELETE CASCADE,
+                  FOREIGN KEY (user_id) REFERENCES memuron_users(id) ON DELETE CASCADE
+                );
+                CREATE TABLE IF NOT EXISTS memuron_org_spaces (
+                  id TEXT PRIMARY KEY,
+                  org_id TEXT NOT NULL,
+                  slug TEXT NOT NULL COLLATE NOCASE,
+                  name TEXT NOT NULL,
+                  token TEXT NOT NULL,
+                  description TEXT NOT NULL DEFAULT '',
+                  guardian_prompt TEXT NOT NULL DEFAULT '',
+                  is_default INTEGER NOT NULL DEFAULT 0,
+                  created_at TEXT NOT NULL,
+                  UNIQUE (org_id, slug),
+                  UNIQUE (org_id, token),
+                  FOREIGN KEY (org_id) REFERENCES memuron_orgs(id) ON DELETE CASCADE
+                );
+                CREATE TABLE IF NOT EXISTS memuron_user_space_prefs (
+                  user_id TEXT NOT NULL,
+                  space_id TEXT NOT NULL,
+                  enabled INTEGER NOT NULL DEFAULT 0,
+                  updated_at TEXT NOT NULL,
+                  PRIMARY KEY (user_id, space_id),
+                  FOREIGN KEY (user_id) REFERENCES memuron_users(id) ON DELETE CASCADE,
+                  FOREIGN KEY (space_id) REFERENCES memuron_org_spaces(id) ON DELETE CASCADE
+                );
+                """
+            )
+            conn.commit()
+            self._migrate_clerk_schema_sqlite(conn)
+
+    def _migrate_clerk_schema(self, conn: psycopg.Connection[Any]) -> None:
+        conn.execute(
+            "ALTER TABLE IF EXISTS memuron_org_spaces "
+            "DROP CONSTRAINT IF EXISTS memuron_org_spaces_org_id_fkey"
+        )
+        conn.execute(
+            "ALTER TABLE IF EXISTS memuron_user_space_prefs "
+            "DROP CONSTRAINT IF EXISTS memuron_user_space_prefs_user_id_fkey"
+        )
+        conn.execute(
+            "ALTER TABLE IF EXISTS memuron_user_space_prefs "
+            "DROP CONSTRAINT IF EXISTS memuron_user_space_prefs_space_id_fkey"
+        )
+        conn.execute(
+            """
+            ALTER TABLE memuron_org_spaces
+            ALTER COLUMN org_id TYPE TEXT USING org_id::text
+            """
+        )
+        conn.execute(
+            """
+            ALTER TABLE memuron_user_space_prefs
+            ALTER COLUMN user_id TYPE TEXT USING user_id::text
+            """
+        )
+        conn.commit()
+
+    def _migrate_clerk_schema_sqlite(self, conn: sqlite3.Connection) -> None:
+        _ = conn
+
+    def ensure_org_spaces(self, org_id: str, user_id: str) -> list[dict[str, Any]]:
+        spaces = self.ensure_default_spaces(org_id)
+        if user_id != "system":
+            for space in spaces:
+                if space.get("is_default"):
+                    self.seed_space_pref_for_user(user_id, space["id"], enabled=True)
+                    break
+            else:
+                if spaces:
+                    self.seed_space_pref_for_user(user_id, spaces[0]["id"], enabled=True)
+        self._invalidate_space_cache()
+        if user_id == "system":
+            return spaces
+        return self.list_user_org_spaces(user_id, org_id)
+
+    @contextmanager
+    def _connect_postgres(self) -> Iterator[psycopg.Connection[Any]]:
+        if self._pool is None:
+            raise RuntimeError("PostgreSQL pool is unavailable")
+        with self._pool.connection() as conn:
+            yield conn
+
+    def close(self) -> None:
+        with self._space_cache_lock:
+            self._space_cache.clear()
+        if self._pool is not None:
+            self._pool.close()
+            self._pool = None
+
+    def _invalidate_space_cache(self) -> None:
+        with self._space_cache_lock:
+            self._space_cache.clear()
+
+    @contextmanager
+    def _connect_sqlite(self) -> Iterator[sqlite3.Connection]:
+        path = Path(self.database_target)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        conn = sqlite3.connect(path)
+        conn.row_factory = sqlite3.Row
+        try:
+            yield conn
+        finally:
+            conn.close()
+
+    def _public_user(self, row: dict[str, Any]) -> dict[str, Any]:
+        return {
+            "id": str(row["id"]),
+            "email": str(row["email"]),
+            "name": str(row["name"]),
+            "created_at": str(row["created_at"]),
+        }
+
+    def _public_org(self, row: dict[str, Any]) -> dict[str, Any]:
+        return {
+            "id": str(row["id"]),
+            "slug": str(row["slug"]),
+            "name": str(row["name"]),
+            "created_at": str(row["created_at"]),
+        }
+
+    def create_user(self, *, email: str, password_hash: str, name: str) -> dict[str, Any]:
+        user_id = str(uuid4())
+        now = _utcnow().isoformat()
+        normalized_email = email.strip().lower()
+        if self.is_postgres:
+            with self._connect_postgres() as conn:
+                try:
+                    row = conn.execute(
+                        """
+                        INSERT INTO memuron_users (id, email, password_hash, name, created_at)
+                        VALUES (%s, %s, %s, %s, %s)
+                        RETURNING *
+                        """,
+                        (user_id, normalized_email, password_hash, name.strip(), now),
+                    ).fetchone()
+                    conn.commit()
+                except psycopg.errors.UniqueViolation as exc:
+                    raise ValueError("email already registered") from exc
+            return self._public_user(row)
+        with self._connect_sqlite() as conn:
+            try:
+                conn.execute(
+                    """
+                    INSERT INTO memuron_users (id, email, password_hash, name, created_at)
+                    VALUES (?, ?, ?, ?, ?)
+                    """,
+                    (user_id, normalized_email, password_hash, name.strip(), now),
+                )
+                conn.commit()
+            except sqlite3.IntegrityError as exc:
+                raise ValueError("email already registered") from exc
+            row = conn.execute(
+                "SELECT * FROM memuron_users WHERE id = ?",
+                (user_id,),
+            ).fetchone()
+        return self._public_user(dict(row))
+
+    def get_user_by_email(self, email: str) -> dict[str, Any] | None:
+        normalized_email = email.strip().lower()
+        if self.is_postgres:
+            with self._connect_postgres() as conn:
+                row = conn.execute(
+                    "SELECT * FROM memuron_users WHERE lower(email) = %s",
+                    (normalized_email,),
+                ).fetchone()
+            return dict(row) if row else None
+        with self._connect_sqlite() as conn:
+            row = conn.execute(
+                "SELECT * FROM memuron_users WHERE lower(email) = ?",
+                (normalized_email,),
+            ).fetchone()
+        return dict(row) if row else None
+
+    def get_user_by_id(self, user_id: str) -> dict[str, Any] | None:
+        if self.is_postgres:
+            with self._connect_postgres() as conn:
+                row = conn.execute(
+                    "SELECT * FROM memuron_users WHERE id = %s",
+                    (user_id,),
+                ).fetchone()
+            return dict(row) if row else None
+        with self._connect_sqlite() as conn:
+            row = conn.execute(
+                "SELECT * FROM memuron_users WHERE id = ?",
+                (user_id,),
+            ).fetchone()
+        return dict(row) if row else None
+
+    def _unique_org_slug(self, base_slug: str) -> str:
+        slug = _slugify(base_slug)
+        candidate = slug
+        suffix = 1
+        while self.get_org_by_slug(candidate) is not None:
+            candidate = f"{slug}-{suffix}"
+            suffix += 1
+        return candidate
+
+    def create_org(self, *, name: str, slug: str | None = None) -> dict[str, Any]:
+        org_id = str(uuid4())
+        now = _utcnow().isoformat()
+        org_slug = self._unique_org_slug(slug or name)
+        if self.is_postgres:
+            with self._connect_postgres() as conn:
+                row = conn.execute(
+                    """
+                    INSERT INTO memuron_orgs (id, slug, name, created_at)
+                    VALUES (%s, %s, %s, %s)
+                    RETURNING *
+                    """,
+                    (org_id, org_slug, name.strip(), now),
+                ).fetchone()
+                conn.commit()
+            return self._public_org(row)
+        with self._connect_sqlite() as conn:
+            conn.execute(
+                """
+                INSERT INTO memuron_orgs (id, slug, name, created_at)
+                VALUES (?, ?, ?, ?)
+                """,
+                (org_id, org_slug, name.strip(), now),
+            )
+            conn.commit()
+            row = conn.execute(
+                "SELECT * FROM memuron_orgs WHERE id = ?",
+                (org_id,),
+            ).fetchone()
+        return self._public_org(dict(row))
+
+    def get_org_by_id(self, org_id: str) -> dict[str, Any] | None:
+        if self.is_postgres:
+            with self._connect_postgres() as conn:
+                row = conn.execute(
+                    "SELECT * FROM memuron_orgs WHERE id = %s",
+                    (org_id,),
+                ).fetchone()
+            return self._public_org(row) if row else None
+        with self._connect_sqlite() as conn:
+            row = conn.execute(
+                "SELECT * FROM memuron_orgs WHERE id = ?",
+                (org_id,),
+            ).fetchone()
+        return self._public_org(dict(row)) if row else None
+
+    def get_org_by_slug(self, slug: str) -> dict[str, Any] | None:
+        if self.is_postgres:
+            with self._connect_postgres() as conn:
+                row = conn.execute(
+                    "SELECT * FROM memuron_orgs WHERE slug = %s",
+                    (slug,),
+                ).fetchone()
+            return self._public_org(row) if row else None
+        with self._connect_sqlite() as conn:
+            row = conn.execute(
+                "SELECT * FROM memuron_orgs WHERE slug = ?",
+                (slug,),
+            ).fetchone()
+        return self._public_org(dict(row)) if row else None
+
+    def add_membership(self, *, org_id: str, user_id: str, role: str = "member") -> None:
+        now = _utcnow().isoformat()
+        if self.is_postgres:
+            with self._connect_postgres() as conn:
+                conn.execute(
+                    """
+                    INSERT INTO memuron_org_memberships (org_id, user_id, role, created_at)
+                    VALUES (%s, %s, %s, %s)
+                    ON CONFLICT (org_id, user_id) DO UPDATE SET role = EXCLUDED.role
+                    """,
+                    (org_id, user_id, role, now),
+                )
+                conn.commit()
+            return
+        with self._connect_sqlite() as conn:
+            conn.execute(
+                """
+                INSERT INTO memuron_org_memberships (org_id, user_id, role, created_at)
+                VALUES (?, ?, ?, ?)
+                ON CONFLICT (org_id, user_id) DO UPDATE SET role = excluded.role
+                """,
+                (org_id, user_id, role, now),
+            )
+            conn.commit()
+
+    def get_membership(self, *, org_id: str, user_id: str) -> dict[str, Any] | None:
+        if self.is_postgres:
+            with self._connect_postgres() as conn:
+                row = conn.execute(
+                    """
+                    SELECT role, created_at FROM memuron_org_memberships
+                    WHERE org_id = %s AND user_id = %s
+                    """,
+                    (org_id, user_id),
+                ).fetchone()
+            return dict(row) if row else None
+        with self._connect_sqlite() as conn:
+            row = conn.execute(
+                """
+                SELECT role, created_at FROM memuron_org_memberships
+                WHERE org_id = ? AND user_id = ?
+                """,
+                (org_id, user_id),
+            ).fetchone()
+        return dict(row) if row else None
+
+    def list_user_orgs(self, user_id: str) -> list[dict[str, Any]]:
+        if self.is_postgres:
+            with self._connect_postgres() as conn:
+                rows = conn.execute(
+                    """
+                    SELECT o.id, o.slug, o.name, o.created_at, m.role
+                    FROM memuron_org_memberships m
+                    JOIN memuron_orgs o ON o.id = m.org_id
+                    WHERE m.user_id = %s
+                    ORDER BY o.name ASC
+                    """,
+                    (user_id,),
+                ).fetchall()
+        else:
+            with self._connect_sqlite() as conn:
+                rows = conn.execute(
+                    """
+                    SELECT o.id, o.slug, o.name, o.created_at, m.role
+                    FROM memuron_org_memberships m
+                    JOIN memuron_orgs o ON o.id = m.org_id
+                    WHERE m.user_id = ?
+                    ORDER BY o.name ASC
+                    """,
+                    (user_id,),
+                ).fetchall()
+        return [
+            {
+                **self._public_org(dict(row)),
+                "role": str(row["role"]),
+            }
+            for row in rows
+        ]
+
+    def _public_space(self, row: dict[str, Any], *, is_enabled: bool | None = None) -> dict[str, Any]:
+        is_default = row.get("is_default")
+        if isinstance(is_default, int):
+            is_default = bool(is_default)
+        payload = {
+            "id": str(row["id"]),
+            "org_id": str(row["org_id"]),
+            "slug": str(row["slug"]),
+            "name": str(row["name"]),
+            "token": str(row["token"]),
+            "description": str(row.get("description") or ""),
+            "guardian_prompt": str(row.get("guardian_prompt") or ""),
+            "is_default": bool(is_default),
+            "created_at": str(row["created_at"]),
+        }
+        if is_enabled is not None:
+            payload["is_enabled"] = is_enabled
+        return payload
+
+    def _unique_space_slug(self, org_id: str, base_slug: str) -> str:
+        slug = slugify_space(base_slug)
+        candidate = slug
+        suffix = 1
+        while self.get_space_by_slug(org_id, candidate) is not None:
+            candidate = f"{slug}-{suffix}"
+            suffix += 1
+        return candidate
+
+    def create_space(
+        self,
+        *,
+        org_id: str,
+        name: str,
+        slug: str | None = None,
+        description: str = "",
+        guardian_prompt: str = "",
+        is_default: bool = False,
+    ) -> dict[str, Any]:
+        space_id = str(uuid4())
+        now = _utcnow().isoformat()
+        space_slug = self._unique_space_slug(org_id, slug or name)
+        token = compile_space_token(space_slug)
+        if is_default:
+            self._clear_default_space(org_id)
+        if self.is_postgres:
+            with self._connect_postgres() as conn:
+                row = conn.execute(
+                    """
+                    INSERT INTO memuron_org_spaces (
+                      id, org_id, slug, name, token, description, guardian_prompt,
+                      is_default, created_at
+                    )
+                    VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s)
+                    RETURNING *
+                    """,
+                    (
+                        space_id,
+                        org_id,
+                        space_slug,
+                        name.strip(),
+                        token,
+                        description.strip(),
+                        guardian_prompt.strip(),
+                        is_default,
+                        now,
+                    ),
+                ).fetchone()
+                conn.commit()
+            created = self._public_space(row)
+            self._invalidate_space_cache()
+            return created
+        with self._connect_sqlite() as conn:
+            conn.execute(
+                """
+                INSERT INTO memuron_org_spaces (
+                  id, org_id, slug, name, token, description, guardian_prompt,
+                  is_default, created_at
+                )
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+                """,
+                (
+                    space_id,
+                    org_id,
+                    space_slug,
+                    name.strip(),
+                    token,
+                    description.strip(),
+                    guardian_prompt.strip(),
+                    1 if is_default else 0,
+                    now,
+                ),
+            )
+            conn.commit()
+            row = conn.execute(
+                "SELECT * FROM memuron_org_spaces WHERE id = ?",
+                (space_id,),
+            ).fetchone()
+        created = self._public_space(dict(row))
+        self._invalidate_space_cache()
+        return created
+
+    def _clear_default_space(self, org_id: str) -> None:
+        if self.is_postgres:
+            with self._connect_postgres() as conn:
+                conn.execute(
+                    "UPDATE memuron_org_spaces SET is_default = FALSE WHERE org_id = %s",
+                    (org_id,),
+                )
+                conn.commit()
+            return
+        with self._connect_sqlite() as conn:
+            conn.execute(
+                "UPDATE memuron_org_spaces SET is_default = 0 WHERE org_id = ?",
+                (org_id,),
+            )
+            conn.commit()
+
+    def ensure_default_spaces(self, org_id: str) -> list[dict[str, Any]]:
+        spaces = self.list_org_spaces(org_id)
+        if spaces:
+            return spaces
+        defaults = default_personal_space(org_id=org_id)
+        created = self.create_space(
+            org_id=org_id,
+            name=defaults["name"],
+            slug=defaults["slug"],
+            description=defaults["description"],
+            guardian_prompt=defaults["guardian_prompt"],
+            is_default=True,
+        )
+        return [created]
+
+    def list_org_spaces(self, org_id: str) -> list[dict[str, Any]]:
+        if self.is_postgres:
+            with self._connect_postgres() as conn:
+                rows = conn.execute(
+                    """
+                    SELECT * FROM memuron_org_spaces
+                    WHERE org_id = %s
+                    ORDER BY is_default DESC, name ASC
+                    """,
+                    (org_id,),
+                ).fetchall()
+        else:
+            with self._connect_sqlite() as conn:
+                rows = conn.execute(
+                    """
+                    SELECT * FROM memuron_org_spaces
+                    WHERE org_id = ?
+                    ORDER BY is_default DESC, name ASC
+                    """,
+                    (org_id,),
+                ).fetchall()
+        return [self._public_space(dict(row)) for row in rows]
+
+    def _load_space_prefs(self, user_id: str, space_ids: list[str]) -> dict[str, bool]:
+        if not space_ids:
+            return {}
+        if self.is_postgres:
+            with self._connect_postgres() as conn:
+                rows = conn.execute(
+                    """
+                    SELECT space_id, enabled FROM memuron_user_space_prefs
+                    WHERE user_id = %s AND space_id = ANY(%s)
+                    """,
+                    (user_id, space_ids),
+                ).fetchall()
+        else:
+            placeholders = ",".join("?" for _ in space_ids)
+            with self._connect_sqlite() as conn:
+                rows = conn.execute(
+                    f"""
+                    SELECT space_id, enabled FROM memuron_user_space_prefs
+                    WHERE user_id = ? AND space_id IN ({placeholders})
+                    """,
+                    (user_id, *space_ids),
+                ).fetchall()
+        prefs: dict[str, bool] = {}
+        for row in rows:
+            enabled = row["enabled"]
+            if isinstance(enabled, int):
+                enabled = bool(enabled)
+            prefs[str(row["space_id"])] = bool(enabled)
+        return prefs
+
+    def _upsert_space_pref(self, user_id: str, space_id: str, enabled: bool) -> None:
+        now = _utcnow().isoformat()
+        if self.is_postgres:
+            with self._connect_postgres() as conn:
+                conn.execute(
+                    """
+                    INSERT INTO memuron_user_space_prefs (user_id, space_id, enabled, updated_at)
+                    VALUES (%s, %s, %s, %s)
+                    ON CONFLICT (user_id, space_id)
+                    DO UPDATE SET enabled = EXCLUDED.enabled, updated_at = EXCLUDED.updated_at
+                    """,
+                    (user_id, space_id, enabled, now),
+                )
+                conn.commit()
+            return
+        with self._connect_sqlite() as conn:
+            conn.execute(
+                """
+                INSERT INTO memuron_user_space_prefs (user_id, space_id, enabled, updated_at)
+                VALUES (?, ?, ?, ?)
+                ON CONFLICT (user_id, space_id)
+                DO UPDATE SET enabled = excluded.enabled, updated_at = excluded.updated_at
+                """,
+                (user_id, space_id, 1 if enabled else 0, now),
+            )
+            conn.commit()
+
+    def list_user_org_spaces(self, user_id: str, org_id: str) -> list[dict[str, Any]]:
+        cache_key = (user_id, org_id)
+        now = monotonic()
+        with self._space_cache_lock:
+            cached = self._space_cache.get(cache_key)
+            if cached is not None and cached[0] > now:
+                return [dict(space) for space in cached[1]]
+
+        if self.is_postgres:
+            with self._connect_postgres() as conn:
+                rows = conn.execute(
+                    """
+                    SELECT s.*, p.enabled AS pref_enabled
+                    FROM memuron_org_spaces s
+                    LEFT JOIN memuron_user_space_prefs p
+                      ON p.space_id = s.id AND p.user_id = %s
+                    WHERE s.org_id = %s
+                    ORDER BY s.is_default DESC, s.name ASC
+                    """,
+                    (user_id, org_id),
+                ).fetchall()
+        else:
+            with self._connect_sqlite() as conn:
+                rows = conn.execute(
+                    """
+                    SELECT s.*, p.enabled AS pref_enabled
+                    FROM memuron_org_spaces s
+                    LEFT JOIN memuron_user_space_prefs p
+                      ON p.space_id = s.id AND p.user_id = ?
+                    WHERE s.org_id = ?
+                    ORDER BY s.is_default DESC, s.name ASC
+                    """,
+                    (user_id, org_id),
+                ).fetchall()
+        if not rows:
+            self.ensure_default_spaces(org_id)
+            return self.list_user_org_spaces(user_id, org_id)
+
+        output: list[dict[str, Any]] = []
+        for raw_row in rows:
+            space = dict(raw_row)
+            enabled = space.pop("pref_enabled", None)
+            if enabled is None:
+                enabled = bool(space["is_default"])
+                self._upsert_space_pref(user_id, str(space["id"]), enabled)
+            output.append(self._public_space(space, is_enabled=bool(enabled)))
+        with self._space_cache_lock:
+            self._space_cache[cache_key] = (
+                monotonic() + 30.0,
+                [dict(space) for space in output],
+            )
+        return [dict(space) for space in output]
+
+    def get_enabled_org_spaces(self, user_id: str, org_id: str) -> list[dict[str, Any]]:
+        return [
+            space
+            for space in self.list_user_org_spaces(user_id, org_id)
+            if space.get("is_enabled")
+        ]
+
+    def set_space_enabled(
+        self,
+        user_id: str,
+        org_id: str,
+        space_id: str,
+        *,
+        enabled: bool,
+    ) -> dict[str, Any]:
+        space = self.get_space_by_id(space_id)
+        if space is None or space["org_id"] != org_id:
+            raise ValueError("space not found in organization")
+        if not enabled:
+            enabled_spaces = self.get_enabled_org_spaces(user_id, org_id)
+            if len(enabled_spaces) <= 1 and any(item["id"] == space_id for item in enabled_spaces):
+                raise ValueError("at least one space must stay enabled")
+        self._upsert_space_pref(user_id, space_id, enabled)
+        self._invalidate_space_cache()
+        return self._public_space(space, is_enabled=enabled)
+
+    def seed_space_pref_for_user(
+        self,
+        user_id: str,
+        space_id: str,
+        *,
+        enabled: bool,
+    ) -> None:
+        prefs = self._load_space_prefs(user_id, [space_id])
+        if space_id in prefs:
+            return
+        self._upsert_space_pref(user_id, space_id, enabled)
+        self._invalidate_space_cache()
+
+    def get_space_by_id(self, space_id: str) -> dict[str, Any] | None:
+        if self.is_postgres:
+            with self._connect_postgres() as conn:
+                row = conn.execute(
+                    "SELECT * FROM memuron_org_spaces WHERE id = %s",
+                    (space_id,),
+                ).fetchone()
+            return self._public_space(row) if row else None
+        with self._connect_sqlite() as conn:
+            row = conn.execute(
+                "SELECT * FROM memuron_org_spaces WHERE id = ?",
+                (space_id,),
+            ).fetchone()
+        return self._public_space(dict(row)) if row else None
+
+    def get_space_by_slug(self, org_id: str, slug: str) -> dict[str, Any] | None:
+        if self.is_postgres:
+            with self._connect_postgres() as conn:
+                row = conn.execute(
+                    """
+                    SELECT * FROM memuron_org_spaces
+                    WHERE org_id = %s AND slug = %s
+                    """,
+                    (org_id, slug),
+                ).fetchone()
+            return self._public_space(row) if row else None
+        with self._connect_sqlite() as conn:
+            row = conn.execute(
+                """
+                SELECT * FROM memuron_org_spaces
+                WHERE org_id = ? AND slug = ?
+                """,
+                (org_id, slug),
+            ).fetchone()
+        return self._public_space(dict(row)) if row else None
+
+    def get_default_space(self, org_id: str) -> dict[str, Any] | None:
+        spaces = self.ensure_default_spaces(org_id)
+        for space in spaces:
+            if space["is_default"]:
+                return space
+        return spaces[0] if spaces else None
+
+    def set_default_space(self, org_id: str, space_id: str) -> dict[str, Any]:
+        space = self.get_space_by_id(space_id)
+        if space is None or space["org_id"] != org_id:
+            raise ValueError("space not found in organization")
+        self._clear_default_space(org_id)
+        if self.is_postgres:
+            with self._connect_postgres() as conn:
+                row = conn.execute(
+                    """
+                    UPDATE memuron_org_spaces
+                    SET is_default = TRUE
+                    WHERE id = %s AND org_id = %s
+                    RETURNING *
+                    """,
+                    (space_id, org_id),
+                ).fetchone()
+                conn.commit()
+            updated = self._public_space(row)
+            self._invalidate_space_cache()
+            return updated
+        with self._connect_sqlite() as conn:
+            conn.execute(
+                """
+                UPDATE memuron_org_spaces
+                SET is_default = 1
+                WHERE id = ? AND org_id = ?
+                """,
+                (space_id, org_id),
+            )
+            conn.commit()
+            row = conn.execute(
+                "SELECT * FROM memuron_org_spaces WHERE id = ?",
+                (space_id,),
+            ).fetchone()
+        updated = self._public_space(dict(row))
+        self._invalidate_space_cache()
+        return updated
+
+    def update_space(
+        self,
+        space_id: str,
+        *,
+        name: str | None = None,
+        description: str | None = None,
+        guardian_prompt: str | None = None,
+    ) -> dict[str, Any]:
+        space = self.get_space_by_id(space_id)
+        if space is None:
+            raise ValueError("space not found")
+        updates: dict[str, Any] = {}
+        if name is not None:
+            updates["name"] = name.strip()
+        if description is not None:
+            updates["description"] = description.strip()
+        if guardian_prompt is not None:
+            updates["guardian_prompt"] = guardian_prompt.strip()
+        if not updates:
+            return space
+        if self.is_postgres:
+            set_clause = ", ".join(f"{key} = %s" for key in updates)
+            with self._connect_postgres() as conn:
+                row = conn.execute(
+                    f"UPDATE memuron_org_spaces SET {set_clause} WHERE id = %s RETURNING *",
+                    (*updates.values(), space_id),
+                ).fetchone()
+                conn.commit()
+            updated = self._public_space(row)
+            self._invalidate_space_cache()
+            return updated
+        set_clause = ", ".join(f"{key} = ?" for key in updates)
+        with self._connect_sqlite() as conn:
+            conn.execute(
+                f"UPDATE memuron_org_spaces SET {set_clause} WHERE id = ?",
+                (*updates.values(), space_id),
+            )
+            conn.commit()
+            row = conn.execute(
+                "SELECT * FROM memuron_org_spaces WHERE id = ?",
+                (space_id,),
+            ).fetchone()
+        updated = self._public_space(dict(row))
+        self._invalidate_space_cache()
+        return updated
+
+    def dump_state(self) -> str:
+        return json.dumps(
+            {
+                "database_target": self.database_target,
+                "is_postgres": self.is_postgres,
+            }
+        )