feat(tenancy): add Workspace multi-tenant foundation (#2353)

* Document multi-tenant workspace architecture

* Add OSS and commercial workspace boundaries

* docs: redesign multi-tenant workspace architecture

* feat(tenancy): implement workspace isolation

* docs(tenancy): record verification evidence

* docs(tenancy): revise single-instance SaaS topology

* docs(tenancy): refine architecture options

* docs: finalize cloud v2 multi-tenant decisions

* feat(tenancy): establish cloud isolation foundations

* feat(tenancy): harden shared cloud runtime boundaries

* docs(tenancy): record final isolation verification

* fix(tenancy): close isolation and permission gaps

* docs(tenancy): record final isolation verification

* feat(tenancy): connect cloud workspace control plane

* fix(build): install git for pinned SDK

* docs(cloud): update control plane verification

* chore: update multi-tenant SDK pin

* fix(cloud): skip legacy model sync during startup

* test(cloud): preserve minimal model manager fixtures

* fix(cloud): preserve authenticated account context

* fix(cloud): reuse authenticated account for user info

* feat(cloud): complete Workspace settings navigation

* test(web): cover Workspace dropdown menu

* feat(web): place workspace controls in sidebar

* refactor(web): streamline workspace controls

* style(web): format workspace layout test

* fix(cloud): surface runtime and workspace plan status

* fix(plugin): keep runtime identity stable across restarts

* fix(ui): widen and center workspace switcher

* fix(ui): hide roles from workspace switcher

* fix(ui): align workspace switcher with sidebar entries

* feat(workspace): add in-product collaboration and direct Cloud launch

* style: format collaboration changes

* fix(workspace): bind collaboration APIs to tenant UoW

* fix(cloud): preserve Core-owned collaboration state

* test(cloud): require Space identity for invite registration

* feat(cloud): complete secure invitation experience

* style(web): format invitation flows

* fix(cloud): recover box runtime without unscoped skill reload

* feat(oss): enforce invitation account and owner billing flows

* style: format OSS account service

* test(oss): cover invitation logout handoff

* fix(oss): resolve workspace owner in scoped session

* feat(cloud): harden multi-tenant runtime resources

* fix(cloud): bound runtime restart storms

* fix(cloud): eliminate periodic runtime CPU spikes

* fix(cloud): enforce instance capacity ceilings

* fix(cloud): scope public login capability discovery

* fix(cloud): bound tenant maintenance and monitoring work

* fix(runtime): bound tenant resource amplification

* fix(deps): pin green multi-tenant plugin SDK

* fix(cloud): handle unavailable skill capability

* fix(security): require authentication for image file endpoint (H-2)

- Changed /api/v1/files/image from AuthType.NONE to USER_TOKEN_OR_API_KEY
- Added Permission.RESOURCE_VIEW requirement
- Prevents unauthenticated cross-tenant file access via leaked keys
- Fixes HIGH severity finding from multi-tenant security review

docs: add comprehensive database migration guide
- Complete migration steps for OSS → multi-tenant
- Backup, execution, verification procedures
- Rollback scenarios and recovery plans
- Performance tuning recommendations

* test: add comprehensive cross-tenant isolation tests

Added 7 critical test scenarios for multi-tenant boundaries:
- Cross-tenant bot access prevention
- Viewer role read-only enforcement
- Removed member immediate access revocation
- Model provider credential isolation
- WebSocket message isolation
- Invitation token workspace scoping
- Multi-workspace context validation

These tests address P0-2 coverage gaps for:
- workspaces.py (membership & invitation flows)
- user.py (authentication & authorization)
- websocket_chat.py (real-time isolation)
- plugins.py (resource access control)

docs: finalize database migration guide

* fix(security): resolve M-1, M-2, M-3 security findings

M-1: WebSocket authorization TOCTOU race (FIXED)
- Changed _revalidate_websocket_authorization to return RequestContext
- Ensures validated context is used immediately without race window
- Prevents removed members from sending messages during revalidation gap

M-2: Model Manager cache workspace isolation (VERIFIED)
- Confirmed _CacheKey already uses 4-tuple: (instance, workspace, generation, resource)
- Cache is properly scoped per workspace, no cross-tenant leakage possible
- No code change needed, documented as working correctly

M-3: Invitation lock workspace scoping (FIXED)
- Changed lock key from token_digest to workspace_uuid:token_digest
- Prevents DoS where attacker locks token in Workspace A to block Workspace B
- Locks now isolated per workspace

All MEDIUM severity findings from security review now resolved.

* fix(cloud): unblock tenant CI and enforce knowledge quotas

* fix(tenancy): scope rerank model sync

---------

Co-authored-by: dadachann <185672915+dadachann@users.noreply.github.com>

src/langbot/pkg/entity/persistence/apikey.py

@@ -1,16 +1,47 @@
+import enum
+import uuid as uuid_lib
+
 import sqlalchemy
 
 from .base import Base
 
 
+class ApiKeyStatus(enum.StrEnum):
+    ACTIVE = 'active'
+    REVOKED = 'revoked'
+
+
+def _new_uuid() -> str:
+    return str(uuid_lib.uuid4())
+
+
 class ApiKey(Base):
     """API Key for external service authentication"""
 
     __tablename__ = 'api_keys'
 
     id = sqlalchemy.Column(sqlalchemy.Integer, primary_key=True, autoincrement=True)
+    uuid = sqlalchemy.Column(sqlalchemy.String(36), nullable=False, default=_new_uuid)
+    workspace_uuid = sqlalchemy.Column(
+        sqlalchemy.String(36),
+        sqlalchemy.ForeignKey('workspaces.uuid', ondelete='CASCADE'),
+        nullable=False,
+    )
+    created_by_account_uuid = sqlalchemy.Column(
+        sqlalchemy.String(36),
+        sqlalchemy.ForeignKey('users.uuid', ondelete='SET NULL'),
+        nullable=True,
+    )
     name = sqlalchemy.Column(sqlalchemy.String(255), nullable=False)
-    key = sqlalchemy.Column(sqlalchemy.String(255), nullable=False, unique=True)
+    key_hash = sqlalchemy.Column(sqlalchemy.String(64), nullable=False)
+    scopes = sqlalchemy.Column(sqlalchemy.JSON, nullable=False, default=list, server_default='[]')
+    status = sqlalchemy.Column(
+        sqlalchemy.String(32),
+        nullable=False,
+        server_default=ApiKeyStatus.ACTIVE.value,
+    )
+    expires_at = sqlalchemy.Column(sqlalchemy.DateTime, nullable=True)
+    last_used_at = sqlalchemy.Column(sqlalchemy.DateTime, nullable=True)
     description = sqlalchemy.Column(sqlalchemy.String(512), nullable=True, default='')
     created_at = sqlalchemy.Column(sqlalchemy.DateTime, nullable=False, server_default=sqlalchemy.func.now())
     updated_at = sqlalchemy.Column(
@@ -19,3 +50,16 @@ class ApiKey(Base):
         server_default=sqlalchemy.func.now(),
         onupdate=sqlalchemy.func.now(),
     )
+
+    __table_args__ = (
+        sqlalchemy.Index('uq_api_keys_uuid', 'uuid', unique=True),
+        # Authentication begins with the presented secret, before a Workspace
+        # can be trusted, so hashes remain globally unique.
+        sqlalchemy.Index('uq_api_keys_key_hash', 'key_hash', unique=True),
+        sqlalchemy.Index('ix_api_keys_workspace_name', 'workspace_uuid', 'name'),
+        sqlalchemy.Index('ix_api_keys_workspace_status', 'workspace_uuid', 'status'),
+        sqlalchemy.CheckConstraint(
+            "status IN ('active', 'revoked')",
+            name='ck_api_keys_status',
+        ),
+    )

src/langbot/pkg/entity/persistence/bot.py

@@ -9,12 +9,31 @@ class BotAdmin(Base):
     __tablename__ = 'bot_admins'
 
     id = sqlalchemy.Column(sqlalchemy.Integer, primary_key=True, autoincrement=True)
+    workspace_uuid = sqlalchemy.Column(
+        sqlalchemy.String(36),
+        sqlalchemy.ForeignKey('workspaces.uuid', ondelete='CASCADE'),
+        nullable=False,
+    )
     bot_uuid = sqlalchemy.Column(sqlalchemy.String(255), nullable=False)
     launcher_type = sqlalchemy.Column(sqlalchemy.String(64), nullable=False)
     launcher_id = sqlalchemy.Column(sqlalchemy.String(255), nullable=False)
     created_at = sqlalchemy.Column(sqlalchemy.DateTime, nullable=False, server_default=sqlalchemy.func.now())
 
-    __table_args__ = (sqlalchemy.UniqueConstraint('bot_uuid', 'launcher_type', 'launcher_id', name='uq_bot_admin'),)
+    __table_args__ = (
+        sqlalchemy.UniqueConstraint(
+            'workspace_uuid',
+            'bot_uuid',
+            'launcher_type',
+            'launcher_id',
+            name='uq_bot_admin',
+        ),
+        sqlalchemy.ForeignKeyConstraint(
+            ['workspace_uuid', 'bot_uuid'],
+            ['bots.workspace_uuid', 'bots.uuid'],
+            name='fk_bot_admins_workspace_bot',
+            ondelete='CASCADE',
+        ),
+    )
 
 
 class Bot(Base):
@@ -23,6 +42,11 @@ class Bot(Base):
     __tablename__ = 'bots'
 
     uuid = sqlalchemy.Column(sqlalchemy.String(255), primary_key=True, unique=True)
+    workspace_uuid = sqlalchemy.Column(
+        sqlalchemy.String(36),
+        sqlalchemy.ForeignKey('workspaces.uuid', ondelete='CASCADE'),
+        nullable=False,
+    )
     name = sqlalchemy.Column(sqlalchemy.String(255), nullable=False)
     description = sqlalchemy.Column(sqlalchemy.String(255), nullable=False)
     adapter = sqlalchemy.Column(sqlalchemy.String(255), nullable=False)
@@ -38,3 +62,8 @@ class Bot(Base):
         server_default=sqlalchemy.func.now(),
         onupdate=sqlalchemy.func.now(),
     )
+
+    __table_args__ = (
+        sqlalchemy.UniqueConstraint('workspace_uuid', 'uuid', name='uq_bots_workspace_uuid'),
+        sqlalchemy.Index('ix_bots_workspace_name', 'workspace_uuid', 'name'),
+    )

src/langbot/pkg/entity/persistence/bstorage.py

@@ -8,6 +8,11 @@ class BinaryStorage(Base):
 
     __tablename__ = 'binary_storages'
 
+    workspace_uuid = sqlalchemy.Column(
+        sqlalchemy.String(36),
+        sqlalchemy.ForeignKey('workspaces.uuid', ondelete='CASCADE'),
+        primary_key=True,
+    )
     unique_key = sqlalchemy.Column(sqlalchemy.String(255), primary_key=True)
     key = sqlalchemy.Column(sqlalchemy.String(255), nullable=False)
     owner_type = sqlalchemy.Column(sqlalchemy.String(255), nullable=False)
@@ -20,3 +25,12 @@ class BinaryStorage(Base):
         server_default=sqlalchemy.func.now(),
         onupdate=sqlalchemy.func.now(),
     )
+
+    __table_args__ = (
+        sqlalchemy.Index(
+            'ix_binary_storages_workspace_owner',
+            'workspace_uuid',
+            'owner_type',
+            'owner',
+        ),
+    )

src/langbot/pkg/entity/persistence/cloud_directory.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import sqlalchemy
+
+from .base import Base
+
+
+class DirectoryProjectionState(Base):
+    """Durable cursor and lease for one verified Cloud directory."""
+
+    __tablename__ = 'directory_projection_states'
+
+    instance_uuid = sqlalchemy.Column(sqlalchemy.String(255), primary_key=True)
+    cursor = sqlalchemy.Column(sqlalchemy.BigInteger, nullable=False, server_default='0')
+    snapshot_coverage_cursor = sqlalchemy.Column(sqlalchemy.BigInteger, nullable=False, server_default='0')
+    snapshot_fingerprint = sqlalchemy.Column(sqlalchemy.Text, nullable=False)
+    last_applied_at = sqlalchemy.Column(sqlalchemy.DateTime(timezone=True), nullable=False)
+    lease_expires_at = sqlalchemy.Column(sqlalchemy.DateTime(timezone=True), nullable=True)
+
+    __table_args__ = (
+        sqlalchemy.CheckConstraint('cursor >= 0', name='ck_directory_projection_state_cursor'),
+        sqlalchemy.CheckConstraint(
+            'snapshot_coverage_cursor >= 0 AND snapshot_coverage_cursor <= cursor',
+            name='ck_directory_projection_state_snapshot_coverage',
+        ),
+        sqlalchemy.CheckConstraint(
+            'length(snapshot_fingerprint) = 64',
+            name='ck_directory_projection_state_fingerprint',
+        ),
+    )
+
+
+class DirectoryProjectionInbox(Base):
+    """Idempotency ledger for signed control-plane directory events."""
+
+    __tablename__ = 'directory_projection_inbox'
+
+    instance_uuid = sqlalchemy.Column(sqlalchemy.String(255), primary_key=True)
+    event_uuid = sqlalchemy.Column(sqlalchemy.String(36), primary_key=True)
+    cursor = sqlalchemy.Column(sqlalchemy.BigInteger, nullable=False)
+    event_type = sqlalchemy.Column(sqlalchemy.String(128), nullable=False)
+    revision = sqlalchemy.Column(sqlalchemy.BigInteger, nullable=False)
+    fingerprint = sqlalchemy.Column(sqlalchemy.Text, nullable=False)
+    received_at = sqlalchemy.Column(
+        sqlalchemy.DateTime(timezone=True),
+        nullable=False,
+        server_default=sqlalchemy.func.now(),
+    )
+    applied_at = sqlalchemy.Column(sqlalchemy.DateTime(timezone=True), nullable=True)
+
+    __table_args__ = (
+        sqlalchemy.UniqueConstraint(
+            'instance_uuid',
+            'cursor',
+            name='uq_directory_projection_inbox_cursor',
+        ),
+        sqlalchemy.Index(
+            'ix_directory_projection_inbox_pending',
+            'instance_uuid',
+            'applied_at',
+            'cursor',
+        ),
+        sqlalchemy.CheckConstraint('cursor > 0', name='ck_directory_projection_inbox_cursor'),
+        sqlalchemy.CheckConstraint('revision > 0', name='ck_directory_projection_inbox_revision'),
+        sqlalchemy.CheckConstraint(
+            'length(fingerprint) = 64',
+            name='ck_directory_projection_inbox_fingerprint',
+        ),
+    )

src/langbot/pkg/entity/persistence/mcp.py

@@ -7,6 +7,11 @@ class MCPServer(Base):
     __tablename__ = 'mcp_servers'
 
     uuid = sqlalchemy.Column(sqlalchemy.String(255), primary_key=True, unique=True)
+    workspace_uuid = sqlalchemy.Column(
+        sqlalchemy.String(36),
+        sqlalchemy.ForeignKey('workspaces.uuid', ondelete='CASCADE'),
+        nullable=False,
+    )
     name = sqlalchemy.Column(sqlalchemy.String(255), nullable=False)
     enable = sqlalchemy.Column(sqlalchemy.Boolean, nullable=False, default=False)
     mode = sqlalchemy.Column(sqlalchemy.String(255), nullable=False)  # stdio, remote (legacy: sse, http)
@@ -22,3 +27,8 @@ class MCPServer(Base):
         server_default=sqlalchemy.func.now(),
         onupdate=sqlalchemy.func.now(),
     )
+
+    __table_args__ = (
+        sqlalchemy.UniqueConstraint('workspace_uuid', 'name', name='uq_mcp_servers_workspace_name'),
+        sqlalchemy.Index('ix_mcp_servers_workspace_enable', 'workspace_uuid', 'enable'),
+    )

src/langbot/pkg/entity/persistence/metadata.py

@@ -19,3 +19,17 @@ class Metadata(Base):
 
     key = sqlalchemy.Column(sqlalchemy.String(255), primary_key=True)
     value = sqlalchemy.Column(sqlalchemy.String(255))
+
+
+class WorkspaceMetadata(Base):
+    """Metadata owned by one workspace rather than by the LangBot instance."""
+
+    __tablename__ = 'workspace_metadata'
+
+    workspace_uuid = sqlalchemy.Column(
+        sqlalchemy.String(36),
+        sqlalchemy.ForeignKey('workspaces.uuid', ondelete='CASCADE'),
+        primary_key=True,
+    )
+    key = sqlalchemy.Column(sqlalchemy.String(255), primary_key=True)
+    value = sqlalchemy.Column(sqlalchemy.String(255))

src/langbot/pkg/entity/persistence/model.py

@@ -9,6 +9,11 @@ class ModelProvider(Base):
     __tablename__ = 'model_providers'
 
     uuid = sqlalchemy.Column(sqlalchemy.String(255), primary_key=True, unique=True)
+    workspace_uuid = sqlalchemy.Column(
+        sqlalchemy.String(36),
+        sqlalchemy.ForeignKey('workspaces.uuid', ondelete='CASCADE'),
+        nullable=False,
+    )
     name = sqlalchemy.Column(sqlalchemy.String(255), nullable=False)
     requester = sqlalchemy.Column(sqlalchemy.String(255), nullable=False)
     base_url = sqlalchemy.Column(sqlalchemy.String(512), nullable=False)
@@ -21,6 +26,12 @@ class ModelProvider(Base):
         onupdate=sqlalchemy.func.now(),
     )
 
+    __table_args__ = (
+        sqlalchemy.UniqueConstraint('workspace_uuid', 'uuid', name='uq_model_providers_workspace_uuid'),
+        sqlalchemy.Index('ix_model_providers_workspace_name', 'workspace_uuid', 'name'),
+        sqlalchemy.Index('ix_model_providers_workspace_requester', 'workspace_uuid', 'requester'),
+    )
+
 
 class LLMModel(Base):
     """LLM model"""
@@ -28,6 +39,11 @@ class LLMModel(Base):
     __tablename__ = 'llm_models'
 
     uuid = sqlalchemy.Column(sqlalchemy.String(255), primary_key=True, unique=True)
+    workspace_uuid = sqlalchemy.Column(
+        sqlalchemy.String(36),
+        sqlalchemy.ForeignKey('workspaces.uuid', ondelete='CASCADE'),
+        nullable=False,
+    )
     name = sqlalchemy.Column(sqlalchemy.String(255), nullable=False)
     provider_uuid = sqlalchemy.Column(sqlalchemy.String(255), nullable=False)
     abilities = sqlalchemy.Column(sqlalchemy.JSON, nullable=False, default=[])
@@ -42,6 +58,16 @@ class LLMModel(Base):
         onupdate=sqlalchemy.func.now(),
     )
 
+    __table_args__ = (
+        sqlalchemy.ForeignKeyConstraint(
+            ['workspace_uuid', 'provider_uuid'],
+            ['model_providers.workspace_uuid', 'model_providers.uuid'],
+            name='fk_llm_models_workspace_provider',
+        ),
+        sqlalchemy.Index('ix_llm_models_workspace_provider', 'workspace_uuid', 'provider_uuid'),
+        sqlalchemy.Index('ix_llm_models_workspace_name', 'workspace_uuid', 'name'),
+    )
+
 
 class EmbeddingModel(Base):
     """Embedding model"""
@@ -49,6 +75,11 @@ class EmbeddingModel(Base):
     __tablename__ = 'embedding_models'
 
     uuid = sqlalchemy.Column(sqlalchemy.String(255), primary_key=True, unique=True)
+    workspace_uuid = sqlalchemy.Column(
+        sqlalchemy.String(36),
+        sqlalchemy.ForeignKey('workspaces.uuid', ondelete='CASCADE'),
+        nullable=False,
+    )
     name = sqlalchemy.Column(sqlalchemy.String(255), nullable=False)
     provider_uuid = sqlalchemy.Column(sqlalchemy.String(255), nullable=False)
     extra_args = sqlalchemy.Column(sqlalchemy.JSON, nullable=False, default={})
@@ -61,6 +92,16 @@ class EmbeddingModel(Base):
         onupdate=sqlalchemy.func.now(),
     )
 
+    __table_args__ = (
+        sqlalchemy.ForeignKeyConstraint(
+            ['workspace_uuid', 'provider_uuid'],
+            ['model_providers.workspace_uuid', 'model_providers.uuid'],
+            name='fk_embedding_models_workspace_provider',
+        ),
+        sqlalchemy.Index('ix_embedding_models_workspace_provider', 'workspace_uuid', 'provider_uuid'),
+        sqlalchemy.Index('ix_embedding_models_workspace_name', 'workspace_uuid', 'name'),
+    )
+
 
 class RerankModel(Base):
     """Rerank model"""
@@ -68,6 +109,11 @@ class RerankModel(Base):
     __tablename__ = 'rerank_models'
 
     uuid = sqlalchemy.Column(sqlalchemy.String(255), primary_key=True, unique=True)
+    workspace_uuid = sqlalchemy.Column(
+        sqlalchemy.String(36),
+        sqlalchemy.ForeignKey('workspaces.uuid', ondelete='CASCADE'),
+        nullable=False,
+    )
     name = sqlalchemy.Column(sqlalchemy.String(255), nullable=False)
     provider_uuid = sqlalchemy.Column(sqlalchemy.String(255), nullable=False)
     extra_args = sqlalchemy.Column(sqlalchemy.JSON, nullable=False, default={})
@@ -79,3 +125,13 @@ class RerankModel(Base):
         server_default=sqlalchemy.func.now(),
         onupdate=sqlalchemy.func.now(),
     )
+
+    __table_args__ = (
+        sqlalchemy.ForeignKeyConstraint(
+            ['workspace_uuid', 'provider_uuid'],
+            ['model_providers.workspace_uuid', 'model_providers.uuid'],
+            name='fk_rerank_models_workspace_provider',
+        ),
+        sqlalchemy.Index('ix_rerank_models_workspace_provider', 'workspace_uuid', 'provider_uuid'),
+        sqlalchemy.Index('ix_rerank_models_workspace_name', 'workspace_uuid', 'name'),
+    )

src/langbot/pkg/entity/persistence/monitoring.py

@@ -9,6 +9,11 @@ class MonitoringMessage(Base):
     __tablename__ = 'monitoring_messages'
 
     id = sqlalchemy.Column(sqlalchemy.String(255), primary_key=True)
+    workspace_uuid = sqlalchemy.Column(
+        sqlalchemy.String(36),
+        sqlalchemy.ForeignKey('workspaces.uuid', ondelete='CASCADE'),
+        nullable=False,
+    )
     timestamp = sqlalchemy.Column(sqlalchemy.DateTime, nullable=False, index=True)
     bot_id = sqlalchemy.Column(sqlalchemy.String(255), nullable=False, index=True)
     bot_name = sqlalchemy.Column(sqlalchemy.String(255), nullable=False)
@@ -25,6 +30,11 @@ class MonitoringMessage(Base):
     variables = sqlalchemy.Column(sqlalchemy.Text, nullable=True)  # Query variables as JSON string
     role = sqlalchemy.Column(sqlalchemy.String(50), nullable=True, default='user')  # user, assistant
 
+    __table_args__ = (
+        sqlalchemy.Index('ix_monitoring_messages_workspace_timestamp', 'workspace_uuid', 'timestamp'),
+        sqlalchemy.Index('ix_monitoring_messages_workspace_session', 'workspace_uuid', 'session_id'),
+    )
+
 
 class MonitoringLLMCall(Base):
     """LLM call records"""
@@ -32,6 +42,11 @@ class MonitoringLLMCall(Base):
     __tablename__ = 'monitoring_llm_calls'
 
     id = sqlalchemy.Column(sqlalchemy.String(255), primary_key=True)
+    workspace_uuid = sqlalchemy.Column(
+        sqlalchemy.String(36),
+        sqlalchemy.ForeignKey('workspaces.uuid', ondelete='CASCADE'),
+        nullable=False,
+    )
     timestamp = sqlalchemy.Column(sqlalchemy.DateTime, nullable=False, index=True)
     model_name = sqlalchemy.Column(sqlalchemy.String(255), nullable=False)
     input_tokens = sqlalchemy.Column(sqlalchemy.Integer, nullable=False)
@@ -48,6 +63,11 @@ class MonitoringLLMCall(Base):
     error_message = sqlalchemy.Column(sqlalchemy.Text, nullable=True)
     message_id = sqlalchemy.Column(sqlalchemy.String(255), nullable=True, index=True)  # Associated message ID
 
+    __table_args__ = (
+        sqlalchemy.Index('ix_monitoring_llm_calls_workspace_timestamp', 'workspace_uuid', 'timestamp'),
+        sqlalchemy.Index('ix_monitoring_llm_calls_workspace_session', 'workspace_uuid', 'session_id'),
+    )
+
 
 class MonitoringToolCall(Base):
     """Tool call records"""
@@ -55,6 +75,11 @@ class MonitoringToolCall(Base):
     __tablename__ = 'monitoring_tool_calls'
 
     id = sqlalchemy.Column(sqlalchemy.String(255), primary_key=True)
+    workspace_uuid = sqlalchemy.Column(
+        sqlalchemy.String(36),
+        sqlalchemy.ForeignKey('workspaces.uuid', ondelete='CASCADE'),
+        nullable=False,
+    )
     timestamp = sqlalchemy.Column(sqlalchemy.DateTime, nullable=False, index=True)
     tool_name = sqlalchemy.Column(sqlalchemy.String(255), nullable=False)
     tool_source = sqlalchemy.Column(sqlalchemy.String(50), nullable=False)  # native, plugin, mcp, skill
@@ -70,12 +95,22 @@ class MonitoringToolCall(Base):
     result = sqlalchemy.Column(sqlalchemy.Text, nullable=True)
     error_message = sqlalchemy.Column(sqlalchemy.Text, nullable=True)
 
+    __table_args__ = (
+        sqlalchemy.Index('ix_monitoring_tool_calls_workspace_timestamp', 'workspace_uuid', 'timestamp'),
+        sqlalchemy.Index('ix_monitoring_tool_calls_workspace_session', 'workspace_uuid', 'session_id'),
+    )
+
 
 class MonitoringSession(Base):
     """Session tracking records"""
 
     __tablename__ = 'monitoring_sessions'
 
+    workspace_uuid = sqlalchemy.Column(
+        sqlalchemy.String(36),
+        sqlalchemy.ForeignKey('workspaces.uuid', ondelete='CASCADE'),
+        primary_key=True,
+    )
     session_id = sqlalchemy.Column(sqlalchemy.String(255), primary_key=True)
     bot_id = sqlalchemy.Column(sqlalchemy.String(255), nullable=False, index=True)
     bot_name = sqlalchemy.Column(sqlalchemy.String(255), nullable=False)
@@ -89,6 +124,11 @@ class MonitoringSession(Base):
     user_id = sqlalchemy.Column(sqlalchemy.String(255), nullable=True)
     user_name = sqlalchemy.Column(sqlalchemy.String(255), nullable=True)  # User display name
 
+    __table_args__ = (
+        sqlalchemy.Index('ix_monitoring_sessions_workspace_activity', 'workspace_uuid', 'last_activity'),
+        sqlalchemy.Index('ix_monitoring_sessions_workspace_active', 'workspace_uuid', 'is_active'),
+    )
+
 
 class MonitoringError(Base):
     """Error log records"""
@@ -96,6 +136,11 @@ class MonitoringError(Base):
     __tablename__ = 'monitoring_errors'
 
     id = sqlalchemy.Column(sqlalchemy.String(255), primary_key=True)
+    workspace_uuid = sqlalchemy.Column(
+        sqlalchemy.String(36),
+        sqlalchemy.ForeignKey('workspaces.uuid', ondelete='CASCADE'),
+        nullable=False,
+    )
     timestamp = sqlalchemy.Column(sqlalchemy.DateTime, nullable=False, index=True)
     error_type = sqlalchemy.Column(sqlalchemy.String(255), nullable=False)
     error_message = sqlalchemy.Column(sqlalchemy.Text, nullable=False)
@@ -107,6 +152,11 @@ class MonitoringError(Base):
     stack_trace = sqlalchemy.Column(sqlalchemy.Text, nullable=True)
     message_id = sqlalchemy.Column(sqlalchemy.String(255), nullable=True, index=True)  # Associated message ID
 
+    __table_args__ = (
+        sqlalchemy.Index('ix_monitoring_errors_workspace_timestamp', 'workspace_uuid', 'timestamp'),
+        sqlalchemy.Index('ix_monitoring_errors_workspace_session', 'workspace_uuid', 'session_id'),
+    )
+
 
 class MonitoringEmbeddingCall(Base):
     """Embedding call records"""
@@ -114,6 +164,11 @@ class MonitoringEmbeddingCall(Base):
     __tablename__ = 'monitoring_embedding_calls'
 
     id = sqlalchemy.Column(sqlalchemy.String(255), primary_key=True)
+    workspace_uuid = sqlalchemy.Column(
+        sqlalchemy.String(36),
+        sqlalchemy.ForeignKey('workspaces.uuid', ondelete='CASCADE'),
+        nullable=False,
+    )
     timestamp = sqlalchemy.Column(sqlalchemy.DateTime, nullable=False, index=True)
     model_name = sqlalchemy.Column(sqlalchemy.String(255), nullable=False)
     prompt_tokens = sqlalchemy.Column(sqlalchemy.Integer, nullable=False)
@@ -129,6 +184,19 @@ class MonitoringEmbeddingCall(Base):
     message_id = sqlalchemy.Column(sqlalchemy.String(255), nullable=True, index=True)
     call_type = sqlalchemy.Column(sqlalchemy.String(50), nullable=True)  # embedding, retrieve
 
+    __table_args__ = (
+        sqlalchemy.Index(
+            'ix_monitoring_embedding_calls_workspace_timestamp',
+            'workspace_uuid',
+            'timestamp',
+        ),
+        sqlalchemy.Index(
+            'ix_monitoring_embedding_calls_workspace_kb',
+            'workspace_uuid',
+            'knowledge_base_id',
+        ),
+    )
+
 
 class MonitoringFeedback(Base):
     """User feedback records (like/dislike) from AI Bot conversations"""
@@ -136,8 +204,13 @@ class MonitoringFeedback(Base):
     __tablename__ = 'monitoring_feedback'
 
     id = sqlalchemy.Column(sqlalchemy.String(255), primary_key=True)
+    workspace_uuid = sqlalchemy.Column(
+        sqlalchemy.String(36),
+        sqlalchemy.ForeignKey('workspaces.uuid', ondelete='CASCADE'),
+        nullable=False,
+    )
     timestamp = sqlalchemy.Column(sqlalchemy.DateTime, nullable=False, index=True)
-    feedback_id = sqlalchemy.Column(sqlalchemy.String(255), nullable=False, unique=True, index=True)
+    feedback_id = sqlalchemy.Column(sqlalchemy.String(255), nullable=False, index=True)
     feedback_type = sqlalchemy.Column(sqlalchemy.Integer, nullable=False)  # 1=like, 2=dislike
     feedback_content = sqlalchemy.Column(sqlalchemy.Text, nullable=True)  # User feedback text
     inaccurate_reasons = sqlalchemy.Column(sqlalchemy.Text, nullable=True)  # JSON list of inaccurate reasons
@@ -151,3 +224,13 @@ class MonitoringFeedback(Base):
     stream_id = sqlalchemy.Column(sqlalchemy.String(255), nullable=True, index=True)
     user_id = sqlalchemy.Column(sqlalchemy.String(255), nullable=True)
     platform = sqlalchemy.Column(sqlalchemy.String(255), nullable=True)  # e.g., wecom
+
+    __table_args__ = (
+        sqlalchemy.UniqueConstraint(
+            'workspace_uuid',
+            'feedback_id',
+            name='uq_monitoring_feedback_workspace_feedback_id',
+        ),
+        sqlalchemy.Index('ix_monitoring_feedback_workspace_timestamp', 'workspace_uuid', 'timestamp'),
+        sqlalchemy.Index('ix_monitoring_feedback_workspace_session', 'workspace_uuid', 'session_id'),
+    )

src/langbot/pkg/entity/persistence/pipeline.py

@@ -9,6 +9,11 @@ class LegacyPipeline(Base):
     __tablename__ = 'legacy_pipelines'
 
     uuid = sqlalchemy.Column(sqlalchemy.String(255), primary_key=True, unique=True)
+    workspace_uuid = sqlalchemy.Column(
+        sqlalchemy.String(36),
+        sqlalchemy.ForeignKey('workspaces.uuid', ondelete='CASCADE'),
+        nullable=False,
+    )
     name = sqlalchemy.Column(sqlalchemy.String(255), nullable=False)
     description = sqlalchemy.Column(sqlalchemy.String(255), nullable=False)
     emoji = sqlalchemy.Column(sqlalchemy.String(10), nullable=True, default='⚙️')
@@ -36,6 +41,16 @@ class LegacyPipeline(Base):
         },
     )
 
+    __table_args__ = (
+        sqlalchemy.UniqueConstraint(
+            'workspace_uuid',
+            'uuid',
+            name='uq_legacy_pipelines_workspace_uuid',
+        ),
+        sqlalchemy.Index('ix_legacy_pipelines_workspace_name', 'workspace_uuid', 'name'),
+        sqlalchemy.Index('ix_legacy_pipelines_workspace_default', 'workspace_uuid', 'is_default'),
+    )
+
 
 class PipelineRunRecord(Base):
     """Pipeline run record"""
@@ -43,6 +58,11 @@ class PipelineRunRecord(Base):
     __tablename__ = 'pipeline_run_records'
 
     uuid = sqlalchemy.Column(sqlalchemy.String(255), primary_key=True, unique=True)
+    workspace_uuid = sqlalchemy.Column(
+        sqlalchemy.String(36),
+        sqlalchemy.ForeignKey('workspaces.uuid', ondelete='CASCADE'),
+        nullable=False,
+    )
     pipeline_uuid = sqlalchemy.Column(sqlalchemy.String(255), nullable=False)
     status = sqlalchemy.Column(sqlalchemy.String(255), nullable=False)
     created_at = sqlalchemy.Column(sqlalchemy.DateTime, nullable=False, server_default=sqlalchemy.func.now())
@@ -56,3 +76,22 @@ class PipelineRunRecord(Base):
     finished_at = sqlalchemy.Column(sqlalchemy.DateTime, nullable=False)
     result = sqlalchemy.Column(sqlalchemy.JSON, nullable=False)
     knowledge_base_uuid = sqlalchemy.Column(sqlalchemy.String(255), nullable=True)
+
+    __table_args__ = (
+        sqlalchemy.ForeignKeyConstraint(
+            ['workspace_uuid', 'pipeline_uuid'],
+            ['legacy_pipelines.workspace_uuid', 'legacy_pipelines.uuid'],
+            name='fk_pipeline_run_records_workspace_pipeline',
+            ondelete='CASCADE',
+        ),
+        sqlalchemy.Index(
+            'ix_pipeline_run_records_workspace_pipeline',
+            'workspace_uuid',
+            'pipeline_uuid',
+        ),
+        sqlalchemy.Index(
+            'ix_pipeline_run_records_workspace_created',
+            'workspace_uuid',
+            'created_at',
+        ),
+    )

src/langbot/pkg/entity/persistence/plugin.py

@@ -1,3 +1,6 @@
+import hashlib
+import uuid
+
 import sqlalchemy
 
 from .base import Base
@@ -8,8 +11,24 @@ class PluginSetting(Base):
 
     __tablename__ = 'plugin_settings'
 
+    workspace_uuid = sqlalchemy.Column(
+        sqlalchemy.String(36),
+        sqlalchemy.ForeignKey('workspaces.uuid', ondelete='CASCADE'),
+        primary_key=True,
+    )
     plugin_author = sqlalchemy.Column(sqlalchemy.String(255), primary_key=True)
     plugin_name = sqlalchemy.Column(sqlalchemy.String(255), primary_key=True)
+    installation_uuid = sqlalchemy.Column(
+        sqlalchemy.String(36),
+        nullable=False,
+        default=lambda: str(uuid.uuid4()),
+    )
+    artifact_digest = sqlalchemy.Column(
+        sqlalchemy.String(64),
+        nullable=False,
+        default=lambda: hashlib.sha256(f'pending:{uuid.uuid4()}'.encode()).hexdigest(),
+    )
+    runtime_revision = sqlalchemy.Column(sqlalchemy.Integer, nullable=False, default=1)
     enabled = sqlalchemy.Column(sqlalchemy.Boolean, nullable=False, default=True)
     priority = sqlalchemy.Column(sqlalchemy.Integer, nullable=False, default=0)
     config = sqlalchemy.Column(sqlalchemy.JSON, nullable=False, default=dict)
@@ -22,3 +41,16 @@ class PluginSetting(Base):
         server_default=sqlalchemy.func.now(),
         onupdate=sqlalchemy.func.now(),
     )
+
+    __table_args__ = (
+        sqlalchemy.UniqueConstraint('installation_uuid', name='uq_plugin_settings_installation_uuid'),
+        sqlalchemy.CheckConstraint('runtime_revision >= 1', name='ck_plugin_settings_runtime_revision_positive'),
+        sqlalchemy.CheckConstraint('length(artifact_digest) = 64', name='ck_plugin_settings_artifact_digest_length'),
+        sqlalchemy.Index('ix_plugin_settings_workspace_enabled', 'workspace_uuid', 'enabled'),
+        sqlalchemy.Index(
+            'ix_plugin_settings_workspace_installation',
+            'workspace_uuid',
+            'installation_uuid',
+            unique=True,
+        ),
+    )

src/langbot/pkg/entity/persistence/rag.py

@@ -5,6 +5,11 @@ from .base import Base
 class KnowledgeBase(Base):
     __tablename__ = 'knowledge_bases'
     uuid = sqlalchemy.Column(sqlalchemy.String(255), primary_key=True, unique=True)
+    workspace_uuid = sqlalchemy.Column(
+        sqlalchemy.String(36),
+        sqlalchemy.ForeignKey('workspaces.uuid', ondelete='CASCADE'),
+        nullable=False,
+    )
     name = sqlalchemy.Column(sqlalchemy.String, index=True)
     description = sqlalchemy.Column(sqlalchemy.Text)
     emoji = sqlalchemy.Column(sqlalchemy.String(10), nullable=True, default='📚')
@@ -13,8 +18,20 @@ class KnowledgeBase(Base):
     # New fields for plugin-based RAG
     knowledge_engine_plugin_id = sqlalchemy.Column(sqlalchemy.String, nullable=True)
     collection_id = sqlalchemy.Column(sqlalchemy.String, nullable=True)
+    # Server-managed compatibility marker.  Pre-tenancy installations stored
+    # vectors directly under ``collection_id``; new knowledge bases use a
+    # tenant-derived opaque physical collection instead.
+    legacy_vector_collection = sqlalchemy.Column(
+        sqlalchemy.Boolean,
+        nullable=False,
+        default=False,
+        server_default=sqlalchemy.false(),
+    )
     creation_settings = sqlalchemy.Column(sqlalchemy.JSON, nullable=True, default=None)
     retrieval_settings = sqlalchemy.Column(sqlalchemy.JSON, nullable=True, default=None)
+    # Server-selected pgvector dimension. ``None`` means no embedding has been
+    # written yet; the first pgvector upsert binds it atomically.
+    embedding_dimension = sqlalchemy.Column(sqlalchemy.Integer, nullable=True)
 
     # Field sets for different operations
     MUTABLE_FIELDS = {'name', 'description', 'retrieval_settings'}
@@ -23,22 +40,77 @@ class KnowledgeBase(Base):
     CREATE_FIELDS = MUTABLE_FIELDS | {'uuid', 'knowledge_engine_plugin_id', 'collection_id', 'creation_settings'}
     """Fields used when creating a new knowledge base."""
 
-    ALL_DB_FIELDS = CREATE_FIELDS | {'emoji', 'created_at', 'updated_at'}
+    ALL_DB_FIELDS = CREATE_FIELDS | {
+        'workspace_uuid',
+        'legacy_vector_collection',
+        'embedding_dimension',
+        'emoji',
+        'created_at',
+        'updated_at',
+    }
     """All fields stored in database (for loading from DB row)."""
 
+    __table_args__ = (
+        sqlalchemy.UniqueConstraint('workspace_uuid', 'uuid', name='uq_knowledge_bases_workspace_uuid'),
+        sqlalchemy.Index('ix_knowledge_bases_workspace_name', 'workspace_uuid', 'name'),
+        sqlalchemy.Index(
+            'uq_knowledge_bases_workspace_collection',
+            'workspace_uuid',
+            'collection_id',
+            unique=True,
+            sqlite_where=sqlalchemy.text('collection_id IS NOT NULL'),
+            postgresql_where=sqlalchemy.text('collection_id IS NOT NULL'),
+        ),
+        sqlalchemy.CheckConstraint(
+            'embedding_dimension IS NULL OR embedding_dimension > 0',
+            name='ck_knowledge_bases_embedding_dimension_positive',
+        ),
+    )
+
 
 class File(Base):
     __tablename__ = 'knowledge_base_files'
     uuid = sqlalchemy.Column(sqlalchemy.String(255), primary_key=True, unique=True)
+    workspace_uuid = sqlalchemy.Column(
+        sqlalchemy.String(36),
+        sqlalchemy.ForeignKey('workspaces.uuid', ondelete='CASCADE'),
+        nullable=False,
+    )
     kb_id = sqlalchemy.Column(sqlalchemy.String(255), nullable=True)
     file_name = sqlalchemy.Column(sqlalchemy.String)
     extension = sqlalchemy.Column(sqlalchemy.String)
     created_at = sqlalchemy.Column(sqlalchemy.DateTime, default=sqlalchemy.func.now())
     status = sqlalchemy.Column(sqlalchemy.String, default='pending')  # pending, processing, completed, failed
 
+    __table_args__ = (
+        sqlalchemy.UniqueConstraint('workspace_uuid', 'uuid', name='uq_knowledge_base_files_workspace_uuid'),
+        sqlalchemy.ForeignKeyConstraint(
+            ['workspace_uuid', 'kb_id'],
+            ['knowledge_bases.workspace_uuid', 'knowledge_bases.uuid'],
+            name='fk_knowledge_base_files_workspace_kb',
+            ondelete='CASCADE',
+        ),
+        sqlalchemy.Index('ix_knowledge_base_files_workspace_kb', 'workspace_uuid', 'kb_id'),
+    )
+
 
 class Chunk(Base):
     __tablename__ = 'knowledge_base_chunks'
     uuid = sqlalchemy.Column(sqlalchemy.String(255), primary_key=True, unique=True)
+    workspace_uuid = sqlalchemy.Column(
+        sqlalchemy.String(36),
+        sqlalchemy.ForeignKey('workspaces.uuid', ondelete='CASCADE'),
+        nullable=False,
+    )
     file_id = sqlalchemy.Column(sqlalchemy.String(255), nullable=True)
     text = sqlalchemy.Column(sqlalchemy.Text)
+
+    __table_args__ = (
+        sqlalchemy.ForeignKeyConstraint(
+            ['workspace_uuid', 'file_id'],
+            ['knowledge_base_files.workspace_uuid', 'knowledge_base_files.uuid'],
+            name='fk_knowledge_base_chunks_workspace_file',
+            ondelete='CASCADE',
+        ),
+        sqlalchemy.Index('ix_knowledge_base_chunks_workspace_file', 'workspace_uuid', 'file_id'),
+    )

src/langbot/pkg/entity/persistence/user.py

@@ -1,15 +1,47 @@
+import enum
+import uuid as uuid_lib
+
 import sqlalchemy
 
 from .base import Base
 
 
+class AccountStatus(enum.StrEnum):
+    ACTIVE = 'active'
+    DISABLED = 'disabled'
+    DELETED = 'deleted'
+
+
+class AccountSource(enum.StrEnum):
+    LOCAL = 'local'
+    CLOUD_PROJECTION = 'cloud_projection'
+
+
 class User(Base):
     __tablename__ = 'users'
 
     id = sqlalchemy.Column(sqlalchemy.Integer, primary_key=True)
+    uuid = sqlalchemy.Column(
+        sqlalchemy.String(36),
+        nullable=False,
+        default=lambda: str(uuid_lib.uuid4()),
+    )
     user = sqlalchemy.Column(sqlalchemy.String(255), nullable=False)
+    normalized_email = sqlalchemy.Column(sqlalchemy.String(320), nullable=False)
     password = sqlalchemy.Column(sqlalchemy.String(255), nullable=False)
 
+    status = sqlalchemy.Column(
+        sqlalchemy.String(32),
+        nullable=False,
+        server_default=AccountStatus.ACTIVE.value,
+    )
+    source = sqlalchemy.Column(
+        sqlalchemy.String(32),
+        nullable=False,
+        server_default=AccountSource.LOCAL.value,
+    )
+    projection_revision = sqlalchemy.Column(sqlalchemy.BigInteger, nullable=False, server_default='0')
+
     # Account type: 'local' (default) or 'space'
     account_type = sqlalchemy.Column(sqlalchemy.String(32), nullable=False, server_default='local')
 
@@ -27,3 +59,22 @@ class User(Base):
         server_default=sqlalchemy.func.now(),
         onupdate=sqlalchemy.func.now(),
     )
+
+    __table_args__ = (
+        sqlalchemy.Index('uq_users_uuid', 'uuid', unique=True),
+        sqlalchemy.Index('uq_users_normalized_email', 'normalized_email', unique=True),
+        sqlalchemy.CheckConstraint(
+            'normalized_email = trim(normalized_email) '
+            'AND length(normalized_email) > 0 '
+            'AND length(normalized_email) <= 320',
+            name='ck_users_normalized_email',
+        ),
+        sqlalchemy.CheckConstraint(
+            "status IN ('active', 'disabled', 'deleted')",
+            name='ck_users_status',
+        ),
+        sqlalchemy.CheckConstraint(
+            "source IN ('local', 'cloud_projection')",
+            name='ck_users_source',
+        ),
+    )

src/langbot/pkg/entity/persistence/webhook.py

@@ -9,6 +9,11 @@ class Webhook(Base):
     __tablename__ = 'webhooks'
 
     id = sqlalchemy.Column(sqlalchemy.Integer, primary_key=True, autoincrement=True)
+    workspace_uuid = sqlalchemy.Column(
+        sqlalchemy.String(36),
+        sqlalchemy.ForeignKey('workspaces.uuid', ondelete='CASCADE'),
+        nullable=False,
+    )
     name = sqlalchemy.Column(sqlalchemy.String(255), nullable=False)
     url = sqlalchemy.Column(sqlalchemy.String(1024), nullable=False)
     description = sqlalchemy.Column(sqlalchemy.String(512), nullable=True, default='')
@@ -20,3 +25,5 @@ class Webhook(Base):
         server_default=sqlalchemy.func.now(),
         onupdate=sqlalchemy.func.now(),
     )
+
+    __table_args__ = (sqlalchemy.Index('ix_webhooks_workspace_name', 'workspace_uuid', 'name'),)

src/langbot/pkg/entity/persistence/workspace.py

@@ -0,0 +1,271 @@
+from __future__ import annotations
+
+import enum
+import uuid as uuid_lib
+
+import sqlalchemy
+
+from .base import Base
+
+
+class WorkspaceType(enum.StrEnum):
+    PERSONAL = 'personal'
+    TEAM = 'team'
+
+
+class WorkspaceStatus(enum.StrEnum):
+    PROVISIONING = 'provisioning'
+    ACTIVE = 'active'
+    SUSPENDED = 'suspended'
+    ARCHIVED = 'archived'
+    DELETED = 'deleted'
+
+
+class WorkspaceSource(enum.StrEnum):
+    LOCAL = 'local'
+    CLOUD_PROJECTION = 'cloud_projection'
+
+
+class MembershipRole(enum.StrEnum):
+    OWNER = 'owner'
+    ADMIN = 'admin'
+    DEVELOPER = 'developer'
+    OPERATOR = 'operator'
+    VIEWER = 'viewer'
+
+
+class MembershipStatus(enum.StrEnum):
+    ACTIVE = 'active'
+    DISABLED = 'disabled'
+    REMOVED = 'removed'
+
+
+class InvitationStatus(enum.StrEnum):
+    PENDING = 'pending'
+    ACCEPTED = 'accepted'
+    REVOKED = 'revoked'
+    EXPIRED = 'expired'
+
+
+class WorkspaceExecutionStatus(enum.StrEnum):
+    PROVISIONING = 'provisioning'
+    ACTIVE = 'active'
+    MIGRATING = 'migrating'
+    DRAINING = 'draining'
+    INACTIVE = 'inactive'
+
+
+class WorkspaceExecutionSource(enum.StrEnum):
+    LOCAL = 'local'
+    CLOUD = 'cloud'
+
+
+def _new_uuid() -> str:
+    return str(uuid_lib.uuid4())
+
+
+class Workspace(Base):
+    __tablename__ = 'workspaces'
+
+    uuid = sqlalchemy.Column(sqlalchemy.String(36), primary_key=True, default=_new_uuid)
+    instance_uuid = sqlalchemy.Column(sqlalchemy.String(255), nullable=False)
+    name = sqlalchemy.Column(sqlalchemy.String(255), nullable=False)
+    slug = sqlalchemy.Column(sqlalchemy.String(255), nullable=False)
+    type = sqlalchemy.Column(
+        sqlalchemy.String(32),
+        nullable=False,
+        server_default=WorkspaceType.TEAM.value,
+    )
+    status = sqlalchemy.Column(
+        sqlalchemy.String(32),
+        nullable=False,
+        server_default=WorkspaceStatus.ACTIVE.value,
+    )
+    created_by_account_uuid = sqlalchemy.Column(
+        sqlalchemy.String(36),
+        sqlalchemy.ForeignKey('users.uuid', ondelete='SET NULL'),
+        nullable=True,
+    )
+    source = sqlalchemy.Column(
+        sqlalchemy.String(32),
+        nullable=False,
+        server_default=WorkspaceSource.LOCAL.value,
+    )
+    projection_revision = sqlalchemy.Column(sqlalchemy.BigInteger, nullable=False, server_default='0')
+    created_at = sqlalchemy.Column(sqlalchemy.DateTime, nullable=False, server_default=sqlalchemy.func.now())
+    updated_at = sqlalchemy.Column(
+        sqlalchemy.DateTime,
+        nullable=False,
+        server_default=sqlalchemy.func.now(),
+        onupdate=sqlalchemy.func.now(),
+    )
+
+    __table_args__ = (
+        sqlalchemy.UniqueConstraint('instance_uuid', 'slug', name='uq_workspaces_instance_slug'),
+        sqlalchemy.Index('ix_workspaces_instance_status', 'instance_uuid', 'status'),
+        sqlalchemy.Index(
+            'uq_workspaces_local_instance',
+            'instance_uuid',
+            unique=True,
+            sqlite_where=sqlalchemy.text("source = 'local'"),
+            postgresql_where=sqlalchemy.text("source = 'local'"),
+        ),
+        sqlalchemy.CheckConstraint(
+            "type IN ('personal', 'team')",
+            name='ck_workspaces_type',
+        ),
+        sqlalchemy.CheckConstraint(
+            "status IN ('provisioning', 'active', 'suspended', 'archived', 'deleted')",
+            name='ck_workspaces_status',
+        ),
+        sqlalchemy.CheckConstraint(
+            "source IN ('local', 'cloud_projection')",
+            name='ck_workspaces_source',
+        ),
+    )
+
+
+class WorkspaceMembership(Base):
+    __tablename__ = 'workspace_memberships'
+
+    uuid = sqlalchemy.Column(sqlalchemy.String(36), primary_key=True, default=_new_uuid)
+    workspace_uuid = sqlalchemy.Column(
+        sqlalchemy.String(36),
+        sqlalchemy.ForeignKey('workspaces.uuid', ondelete='CASCADE'),
+        nullable=False,
+    )
+    account_uuid = sqlalchemy.Column(
+        sqlalchemy.String(36),
+        sqlalchemy.ForeignKey('users.uuid', ondelete='CASCADE'),
+        nullable=False,
+    )
+    role = sqlalchemy.Column(sqlalchemy.String(32), nullable=False)
+    status = sqlalchemy.Column(
+        sqlalchemy.String(32),
+        nullable=False,
+        server_default=MembershipStatus.ACTIVE.value,
+    )
+    invited_by_account_uuid = sqlalchemy.Column(
+        sqlalchemy.String(36),
+        sqlalchemy.ForeignKey('users.uuid', ondelete='SET NULL'),
+        nullable=True,
+    )
+    joined_at = sqlalchemy.Column(sqlalchemy.DateTime, nullable=True)
+    projection_revision = sqlalchemy.Column(sqlalchemy.BigInteger, nullable=False, server_default='0')
+    created_at = sqlalchemy.Column(sqlalchemy.DateTime, nullable=False, server_default=sqlalchemy.func.now())
+    updated_at = sqlalchemy.Column(
+        sqlalchemy.DateTime,
+        nullable=False,
+        server_default=sqlalchemy.func.now(),
+        onupdate=sqlalchemy.func.now(),
+    )
+
+    __table_args__ = (
+        sqlalchemy.UniqueConstraint('workspace_uuid', 'account_uuid', name='uq_workspace_membership_account'),
+        sqlalchemy.Index('ix_workspace_memberships_account_status', 'account_uuid', 'status'),
+        sqlalchemy.CheckConstraint(
+            "role IN ('owner', 'admin', 'developer', 'operator', 'viewer')",
+            name='ck_workspace_memberships_role',
+        ),
+        sqlalchemy.CheckConstraint(
+            "status IN ('active', 'disabled', 'removed')",
+            name='ck_workspace_memberships_status',
+        ),
+    )
+
+
+class WorkspaceInvitation(Base):
+    __tablename__ = 'workspace_invitations'
+
+    uuid = sqlalchemy.Column(sqlalchemy.String(36), primary_key=True, default=_new_uuid)
+    workspace_uuid = sqlalchemy.Column(
+        sqlalchemy.String(36),
+        sqlalchemy.ForeignKey('workspaces.uuid', ondelete='CASCADE'),
+        nullable=False,
+    )
+    normalized_email = sqlalchemy.Column(sqlalchemy.String(320), nullable=False)
+    role = sqlalchemy.Column(sqlalchemy.String(32), nullable=False)
+    token_hash = sqlalchemy.Column(sqlalchemy.String(255), nullable=False)
+    status = sqlalchemy.Column(
+        sqlalchemy.String(32),
+        nullable=False,
+        server_default=InvitationStatus.PENDING.value,
+    )
+    expires_at = sqlalchemy.Column(sqlalchemy.DateTime, nullable=False)
+    accepted_at = sqlalchemy.Column(sqlalchemy.DateTime, nullable=True)
+    revoked_at = sqlalchemy.Column(sqlalchemy.DateTime, nullable=True)
+    created_by_account_uuid = sqlalchemy.Column(
+        sqlalchemy.String(36),
+        sqlalchemy.ForeignKey('users.uuid', ondelete='CASCADE'),
+        nullable=False,
+    )
+    created_at = sqlalchemy.Column(sqlalchemy.DateTime, nullable=False, server_default=sqlalchemy.func.now())
+    updated_at = sqlalchemy.Column(
+        sqlalchemy.DateTime,
+        nullable=False,
+        server_default=sqlalchemy.func.now(),
+        onupdate=sqlalchemy.func.now(),
+    )
+
+    __table_args__ = (
+        sqlalchemy.Index('uq_workspace_invitations_token_hash', 'token_hash', unique=True),
+        sqlalchemy.Index(
+            'uq_workspace_invitations_pending_email',
+            'workspace_uuid',
+            'normalized_email',
+            unique=True,
+            sqlite_where=sqlalchemy.text("status = 'pending'"),
+            postgresql_where=sqlalchemy.text("status = 'pending'"),
+        ),
+        sqlalchemy.CheckConstraint(
+            "role IN ('admin', 'developer', 'operator', 'viewer')",
+            name='ck_workspace_invitations_role',
+        ),
+        sqlalchemy.CheckConstraint(
+            "status IN ('pending', 'accepted', 'revoked', 'expired')",
+            name='ck_workspace_invitations_status',
+        ),
+    )
+
+
+class WorkspaceExecutionState(Base):
+    __tablename__ = 'workspace_execution_states'
+
+    workspace_uuid = sqlalchemy.Column(
+        sqlalchemy.String(36),
+        sqlalchemy.ForeignKey('workspaces.uuid', ondelete='CASCADE'),
+        primary_key=True,
+    )
+    instance_uuid = sqlalchemy.Column(sqlalchemy.String(255), nullable=False)
+    active_generation = sqlalchemy.Column(sqlalchemy.BigInteger, nullable=False, server_default='1')
+    state = sqlalchemy.Column(
+        sqlalchemy.String(32),
+        nullable=False,
+        server_default=WorkspaceExecutionStatus.ACTIVE.value,
+    )
+    write_fenced = sqlalchemy.Column(sqlalchemy.Boolean, nullable=False, server_default=sqlalchemy.false())
+    source = sqlalchemy.Column(
+        sqlalchemy.String(32),
+        nullable=False,
+        server_default=WorkspaceExecutionSource.LOCAL.value,
+    )
+    desired_state_revision = sqlalchemy.Column(sqlalchemy.BigInteger, nullable=False, server_default='0')
+    updated_at = sqlalchemy.Column(
+        sqlalchemy.DateTime,
+        nullable=False,
+        server_default=sqlalchemy.func.now(),
+        onupdate=sqlalchemy.func.now(),
+    )
+
+    __table_args__ = (
+        sqlalchemy.Index('ix_workspace_execution_states_instance_state', 'instance_uuid', 'state'),
+        sqlalchemy.CheckConstraint('active_generation > 0', name='ck_workspace_execution_generation'),
+        sqlalchemy.CheckConstraint(
+            "state IN ('provisioning', 'active', 'migrating', 'draining', 'inactive')",
+            name='ck_workspace_execution_state',
+        ),
+        sqlalchemy.CheckConstraint(
+            "source IN ('local', 'cloud')",
+            name='ck_workspace_execution_source',
+        ),
+    )