Add hub-core package, docs, and State Hub integration scaffold

Extract the first reusable slice (models, schemas, routers, MCP, migrations)
from state-hub with INTENT/SCOPE, agent instructions, workplan, and aligned
inter_hub capability registry index.

hub_core/models/__init__.py

@@ -0,0 +1,23 @@
+from hub_core.models.agent_message import AgentMessage
+from hub_core.models.base import Base, TimestampMixin, new_uuid
+from hub_core.models.capability_catalog import CapabilityCatalog
+from hub_core.models.capability_request import CapabilityRequest
+from hub_core.models.domain import Domain
+from hub_core.models.managed_repo import ManagedRepo
+from hub_core.models.progress_event import ProgressEvent
+from hub_core.models.tpsc import TPSCCatalog, TPSCEntry, TPSCSnapshot
+
+__all__ = [
+    "AgentMessage",
+    "Base",
+    "CapabilityCatalog",
+    "CapabilityRequest",
+    "Domain",
+    "ManagedRepo",
+    "ProgressEvent",
+    "TPSCCatalog",
+    "TPSCEntry",
+    "TPSCSnapshot",
+    "TimestampMixin",
+    "new_uuid",
+]

hub_core/models/agent_message.py

@@ -0,0 +1,44 @@
+import uuid
+from datetime import datetime
+
+from sqlalchemy import DateTime, ForeignKey, String, Text, text
+from sqlalchemy.dialects.postgresql import UUID
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from hub_core.models.base import Base, new_uuid
+
+
+class AgentMessage(Base):
+    __tablename__ = "agent_messages"
+
+    id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True), primary_key=True, default=new_uuid
+    )
+    from_agent: Mapped[str] = mapped_column(String(100), nullable=False)
+    to_agent: Mapped[str] = mapped_column(String(100), nullable=False, index=True)
+    subject: Mapped[str] = mapped_column(String(500), nullable=False)
+    body: Mapped[str] = mapped_column(Text, nullable=False)
+    thread_id: Mapped[uuid.UUID | None] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("agent_messages.id", ondelete="SET NULL"),
+        nullable=True,
+        index=True,
+    )
+    read_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True
+    )
+    archived_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True
+    )
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        server_default=text("now()"),
+        nullable=False,
+    )
+
+    thread_root: Mapped["AgentMessage | None"] = relationship(
+        "AgentMessage",
+        remote_side="AgentMessage.id",
+        foreign_keys=[thread_id],
+        lazy="select",
+    )

hub_core/models/base.py

@@ -0,0 +1,25 @@
+import uuid
+from datetime import datetime
+
+from sqlalchemy import DateTime, func
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+class TimestampMixin:
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now(), nullable=False
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        server_default=func.now(),
+        onupdate=func.now(),
+        nullable=False,
+    )
+
+
+def new_uuid() -> uuid.UUID:
+    return uuid.uuid4()

hub_core/models/capability_catalog.py

@@ -0,0 +1,50 @@
+import uuid
+
+from sqlalchemy import ARRAY, ForeignKey, String, Text, UniqueConstraint
+from sqlalchemy.dialects.postgresql import UUID
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from hub_core.models.base import Base, TimestampMixin, new_uuid
+
+
+class CapabilityCatalog(Base, TimestampMixin):
+    __tablename__ = "capability_catalog"
+    __table_args__ = (
+        UniqueConstraint("domain_id", "capability_type", "title", name="uq_catalog_domain_type_title"),
+    )
+
+    id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True), primary_key=True, default=new_uuid
+    )
+    domain_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("domains.id", ondelete="RESTRICT"),
+        nullable=False,
+        index=True,
+    )
+    repo_id: Mapped[uuid.UUID | None] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("managed_repos.id", ondelete="SET NULL"),
+        nullable=True,
+        index=True,
+    )
+    capability_type: Mapped[str] = mapped_column(String(50), nullable=False)
+    title: Mapped[str] = mapped_column(String(255), nullable=False)
+    description: Mapped[str | None] = mapped_column(Text, nullable=True)
+    keywords: Mapped[list[str]] = mapped_column(
+        ARRAY(String), nullable=False, server_default="{}"
+    )
+    status: Mapped[str] = mapped_column(
+        String(20), nullable=False, default="active", server_default="active"
+    )
+
+    domain: Mapped["Domain"] = relationship("Domain", lazy="selectin")  # noqa: F821
+    repo: Mapped["ManagedRepo | None"] = relationship("ManagedRepo", lazy="selectin")  # noqa: F821
+
+    @property
+    def domain_slug(self) -> str:
+        return self.domain.slug if self.domain is not None else ""
+
+    @property
+    def repo_slug(self) -> str | None:
+        return self.repo.slug if self.repo is not None else None

hub_core/models/capability_request.py

@@ -0,0 +1,76 @@
+import uuid
+from datetime import datetime
+
+from sqlalchemy import DateTime, ForeignKey, String, Text
+from sqlalchemy.dialects.postgresql import JSONB, UUID
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from hub_core.models.base import Base, TimestampMixin, new_uuid
+
+
+class CapabilityRequest(Base, TimestampMixin):
+    __tablename__ = "capability_requests"
+
+    id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True), primary_key=True, default=new_uuid
+    )
+    title: Mapped[str] = mapped_column(String(500), nullable=False)
+    description: Mapped[str | None] = mapped_column(Text, nullable=True)
+    capability_type: Mapped[str] = mapped_column(String(50), nullable=False)
+    priority: Mapped[str] = mapped_column(
+        String(20), nullable=False, default="medium", server_default="medium"
+    )
+    status: Mapped[str] = mapped_column(
+        String(20), nullable=False, default="requested", server_default="requested"
+    )
+
+    requesting_domain_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("domains.id", ondelete="RESTRICT"),
+        nullable=False,
+        index=True,
+    )
+    requesting_agent: Mapped[str] = mapped_column(String(100), nullable=False)
+    request_context: Mapped[dict | None] = mapped_column(JSONB, nullable=True)
+
+    fulfilling_domain_id: Mapped[uuid.UUID | None] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("domains.id", ondelete="SET NULL"),
+        nullable=True,
+        index=True,
+    )
+    fulfilling_agent: Mapped[str | None] = mapped_column(String(100), nullable=True)
+    fulfillment_context: Mapped[dict | None] = mapped_column(JSONB, nullable=True)
+
+    catalog_entry_id: Mapped[uuid.UUID | None] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("capability_catalog.id", ondelete="SET NULL"),
+        nullable=True,
+    )
+
+    resolution_note: Mapped[str | None] = mapped_column(Text, nullable=True)
+    routing_note: Mapped[str | None] = mapped_column(Text, nullable=True)
+    dispute_reason: Mapped[str | None] = mapped_column(Text, nullable=True)
+    disputed_by: Mapped[str | None] = mapped_column(String(100), nullable=True)
+    dispute_suggested_domain: Mapped[str | None] = mapped_column(String(100), nullable=True)
+    disputed_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+    accepted_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+    completed_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+
+    requesting_domain: Mapped["Domain"] = relationship(  # noqa: F821
+        "Domain", foreign_keys=[requesting_domain_id], lazy="selectin"
+    )
+    fulfilling_domain: Mapped["Domain | None"] = relationship(  # noqa: F821
+        "Domain", foreign_keys=[fulfilling_domain_id], lazy="selectin"
+    )
+    catalog_entry: Mapped["CapabilityCatalog | None"] = relationship(  # noqa: F821
+        "CapabilityCatalog", lazy="selectin"
+    )
+
+    @property
+    def requesting_domain_slug(self) -> str:
+        return self.requesting_domain.slug if self.requesting_domain else ""
+
+    @property
+    def fulfilling_domain_slug(self) -> str | None:
+        return self.fulfilling_domain.slug if self.fulfilling_domain else None

hub_core/models/domain.py

@@ -0,0 +1,23 @@
+import uuid
+
+from sqlalchemy import String, Text
+from sqlalchemy.dialects.postgresql import UUID
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from hub_core.models.base import Base, TimestampMixin, new_uuid
+
+
+class Domain(Base, TimestampMixin):
+    __tablename__ = "domains"
+
+    id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True), primary_key=True, default=new_uuid
+    )
+    slug: Mapped[str] = mapped_column(String(50), unique=True, nullable=False, index=True)
+    name: Mapped[str] = mapped_column(String(200), nullable=False)
+    description: Mapped[str | None] = mapped_column(Text, nullable=True)
+    status: Mapped[str] = mapped_column(String(20), nullable=False, default="active")
+
+    repos: Mapped[list["ManagedRepo"]] = relationship(  # noqa: F821
+        "ManagedRepo", back_populates="domain", lazy="selectin"
+    )

hub_core/models/managed_repo.py

@@ -0,0 +1,37 @@
+import uuid
+
+from sqlalchemy import ForeignKey, String, Text
+from sqlalchemy.dialects.postgresql import JSONB, UUID
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from hub_core.models.base import Base, TimestampMixin, new_uuid
+
+
+class ManagedRepo(Base, TimestampMixin):
+    __tablename__ = "managed_repos"
+
+    id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True), primary_key=True, default=new_uuid
+    )
+    domain_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("domains.id", ondelete="RESTRICT"),
+        nullable=False,
+        index=True,
+    )
+    slug: Mapped[str] = mapped_column(String(100), unique=True, nullable=False, index=True)
+    name: Mapped[str] = mapped_column(String(200), nullable=False)
+    local_path: Mapped[str | None] = mapped_column(Text, nullable=True)
+    host_paths: Mapped[dict] = mapped_column(JSONB, nullable=False, default=dict, server_default="{}")
+    remote_url: Mapped[str | None] = mapped_column(Text, nullable=True)
+    description: Mapped[str | None] = mapped_column(Text, nullable=True)
+    status: Mapped[str] = mapped_column(String(20), nullable=False, default="active")
+    git_fingerprint: Mapped[str | None] = mapped_column(String(40), nullable=True, index=True)
+
+    domain: Mapped["Domain"] = relationship(  # noqa: F821
+        "Domain", back_populates="repos", lazy="selectin"
+    )
+
+    @property
+    def domain_slug(self) -> str:
+        return self.domain.slug if self.domain is not None else ""

hub_core/models/progress_event.py

@@ -0,0 +1,27 @@
+import uuid
+from datetime import datetime
+
+from sqlalchemy import DateTime, String, Text, func
+from sqlalchemy.dialects.postgresql import JSONB, UUID
+from sqlalchemy.orm import Mapped, mapped_column
+
+from hub_core.models.base import Base, new_uuid
+
+
+class ProgressEvent(Base):
+    """Generic append-only event log for hub activity."""
+
+    __tablename__ = "progress_events"
+
+    id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True), primary_key=True, default=new_uuid
+    )
+    event_type: Mapped[str] = mapped_column(String(50), nullable=False, index=True)
+    summary: Mapped[str] = mapped_column(Text, nullable=False)
+    detail: Mapped[dict | None] = mapped_column(JSONB, nullable=True)
+    subject_refs: Mapped[dict | None] = mapped_column(JSONB, nullable=True)
+    author: Mapped[str | None] = mapped_column(String(100), nullable=True)
+    session_id: Mapped[str | None] = mapped_column(String(100), nullable=True)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now(), nullable=False, index=True
+    )

hub_core/models/tpsc.py

@@ -0,0 +1,78 @@
+import uuid
+from datetime import datetime
+
+from sqlalchemy import Boolean, DateTime, ForeignKey, Integer, String, Text, func
+from sqlalchemy.dialects.postgresql import JSON, UUID
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from hub_core.models.base import Base
+
+
+class TPSCCatalog(Base):
+    __tablename__ = "tpsc_catalog"
+
+    id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    slug: Mapped[str] = mapped_column(String(100), nullable=False, unique=True, index=True)
+    name: Mapped[str] = mapped_column(String(200), nullable=False)
+    provider: Mapped[str | None] = mapped_column(String(200), nullable=True)
+    category: Mapped[str | None] = mapped_column(String(100), nullable=True)
+    website_url: Mapped[str | None] = mapped_column(Text, nullable=True)
+    pricing_model: Mapped[str] = mapped_column(String(20), nullable=False, server_default="unknown")
+    gdpr_maturity: Mapped[str] = mapped_column(
+        String(20), nullable=False, server_default="unknown", index=True
+    )
+    gdpr_notes: Mapped[str | None] = mapped_column(Text, nullable=True)
+    dpa_available: Mapped[bool] = mapped_column(Boolean, nullable=False, server_default="false")
+    tos_url: Mapped[str | None] = mapped_column(Text, nullable=True)
+    privacy_policy_url: Mapped[str | None] = mapped_column(Text, nullable=True)
+    data_processing_regions: Mapped[list | None] = mapped_column(JSON, nullable=True)
+    data_retention_notes: Mapped[str | None] = mapped_column(Text, nullable=True)
+    status: Mapped[str] = mapped_column(String(20), nullable=False, server_default="active")
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now(), onupdate=func.now()
+    )
+
+    entries: Mapped[list["TPSCEntry"]] = relationship("TPSCEntry", back_populates="catalog_entry")
+
+
+class TPSCSnapshot(Base):
+    __tablename__ = "tpsc_snapshots"
+
+    id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    repo_id: Mapped[uuid.UUID | None] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("managed_repos.id", ondelete="SET NULL"),
+        nullable=True,
+        index=True,
+    )
+    snapshot_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
+    source_file: Mapped[str | None] = mapped_column(String(200), nullable=True)
+    entry_count: Mapped[int] = mapped_column(Integer, nullable=False, server_default="0")
+
+    entries: Mapped[list["TPSCEntry"]] = relationship(
+        "TPSCEntry", back_populates="snapshot", cascade="all, delete-orphan"
+    )
+
+
+class TPSCEntry(Base):
+    __tablename__ = "tpsc_entries"
+
+    id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    snapshot_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("tpsc_snapshots.id", ondelete="CASCADE"),
+        nullable=False,
+        index=True,
+    )
+    catalog_id: Mapped[uuid.UUID | None] = mapped_column(
+        UUID(as_uuid=True), ForeignKey("tpsc_catalog.id", ondelete="SET NULL"), nullable=True
+    )
+    service_slug: Mapped[str] = mapped_column(String(100), nullable=False, index=True)
+    purpose: Mapped[str | None] = mapped_column(Text, nullable=True)
+    auth_type: Mapped[str | None] = mapped_column(String(50), nullable=True)
+    endpoint_override: Mapped[str | None] = mapped_column(Text, nullable=True)
+    notes: Mapped[str | None] = mapped_column(Text, nullable=True)
+
+    snapshot: Mapped["TPSCSnapshot"] = relationship("TPSCSnapshot", back_populates="entries")
+    catalog_entry: Mapped["TPSCCatalog | None"] = relationship("TPSCCatalog", back_populates="entries")