feat(gems): three-pass schema migration aligning state-hub with GEMS

Implements CUST-WP-0007. Resolves inconsistencies I-1, I-2, I-5, I-6
identified in the GEMS audit (GenericEntityModellingSystem.md).

Pass 1 (e1f2a3b4c5d6): domain_id FK on extension_points and
technical_debt (replaces raw string column); repo_id FK on contributions.
Fixes domain-filtering bugs in EP/TD dashboard pages.

Pass 2 (f2a3b4c5d6e7): repo_id nullable FK on workstreams, aligning
the GEMS primary attachment with ADR-001 (repo > topic). Dashboard
pages updated to prefer repo->domain over topic->domain.

Pass 3 (a3b4c5d6e7f8): SBOMSnapshot container entity (GEMS Complex
between Repository and SBOMEntry). Ingest is now additive — each call
creates a new snapshot; history is retained. List/report endpoints
filter to latest snapshot per repo via _latest_snapshot_ids_subquery().
New endpoints: GET /sbom/snapshots/, GET /sbom/snapshots/{id}/.
Dashboard gains a Snapshot History section.

Also adds GEMS analysis artefacts: wiki/GEMS-StateHub-TypeRegistry.md,
wiki/GEMS-StateHub-SWOT.md, workplans/CUST-WP-0006 (analysis),
workplans/CUST-WP-0007 (migration, now completed).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

api/models/__init__.py

@@ -10,6 +10,7 @@ from api.models.extension_point import ExtensionPoint, EPStatus
 from api.models.technical_debt import TechnicalDebt, TDStatus
 from api.models.managed_repo import ManagedRepo
 from api.models.contribution import Contribution, ContributionType, ContributionStatus
+from api.models.sbom_snapshot import SBOMSnapshot
 from api.models.sbom_entry import SBOMEntry, Ecosystem
 
 __all__ = [
@@ -25,5 +26,6 @@ __all__ = [
     "TechnicalDebt", "TDStatus",
     "ManagedRepo",
     "Contribution", "ContributionType", "ContributionStatus",
+    "SBOMSnapshot",
     "SBOMEntry", "Ecosystem",
 ]

api/models/contribution.py

@@ -50,6 +50,9 @@ class Contribution(Base, TimestampMixin):
     related_workstream_id: Mapped[uuid.UUID | None] = mapped_column(
         UUID(as_uuid=True), ForeignKey("workstreams.id", ondelete="SET NULL"), nullable=True
     )
+    repo_id: Mapped[uuid.UUID | None] = mapped_column(
+        UUID(as_uuid=True), ForeignKey("managed_repos.id", ondelete="SET NULL"), nullable=True
+    )
     submitted_at: Mapped[datetime | None] = mapped_column(
         DateTime(timezone=True), nullable=True
     )
@@ -60,3 +63,4 @@ class Contribution(Base, TimestampMixin):
 
     topic: Mapped["Topic"] = relationship("Topic", lazy="selectin")  # noqa: F821
     workstream: Mapped["Workstream"] = relationship("Workstream", lazy="selectin")  # noqa: F821
+    repo: Mapped["ManagedRepo"] = relationship("ManagedRepo", lazy="selectin")  # noqa: F821

api/models/extension_point.py

@@ -25,7 +25,12 @@ class ExtensionPoint(Base, TimestampMixin):
     ep_id: Mapped[str | None] = mapped_column(
         String(30), nullable=True, unique=True, index=True
     )  # human-readable ref, e.g. EP-CUST-001
-    domain: Mapped[str] = mapped_column(String(50), nullable=False, index=True)
+    domain_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("domains.id", ondelete="RESTRICT"),
+        nullable=False,
+        index=True,
+    )
     title: Mapped[str] = mapped_column(String(255), nullable=False)
     description: Mapped[str | None] = mapped_column(Text, nullable=True)
     location: Mapped[str | None] = mapped_column(String(500), nullable=True)
@@ -43,5 +48,10 @@ class ExtensionPoint(Base, TimestampMixin):
         UUID(as_uuid=True), ForeignKey("workstreams.id", ondelete="SET NULL"), nullable=True
     )
 
+    domain: Mapped["Domain"] = relationship("Domain", lazy="selectin")  # noqa: F821
     topic: Mapped["Topic"] = relationship("Topic", lazy="selectin")  # noqa: F821
     workstream: Mapped["Workstream"] = relationship("Workstream", lazy="selectin")  # noqa: F821
+
+    @property
+    def domain_slug(self) -> str:
+        return self.domain.slug if self.domain is not None else ""

api/models/managed_repo.py

@@ -34,3 +34,7 @@ class ManagedRepo(Base, TimestampMixin):
     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 ""

api/models/sbom_entry.py

@@ -37,6 +37,12 @@ class SBOMEntry(Base):
     license_spdx: Mapped[str | None] = mapped_column(String(100), nullable=True)
     is_direct: Mapped[bool] = mapped_column(Boolean, nullable=False, default=True)
     is_dev: Mapped[bool] = mapped_column(Boolean, nullable=False, default=False)
+    snapshot_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("sbom_snapshots.id", ondelete="RESTRICT"),
+        nullable=False,
+        index=True,
+    )
     snapshot_at: Mapped[datetime] = mapped_column(
         DateTime(timezone=True), nullable=False
     )
@@ -45,3 +51,6 @@ class SBOMEntry(Base):
     )
 
     repo: Mapped["ManagedRepo"] = relationship("ManagedRepo", lazy="selectin")  # noqa: F821
+    snapshot: Mapped["SBOMSnapshot"] = relationship(  # noqa: F821
+        "SBOMSnapshot", lazy="selectin", back_populates="entries"
+    )

api/models/sbom_snapshot.py

@@ -0,0 +1,32 @@
+import uuid
+from datetime import datetime
+
+from sqlalchemy import DateTime, ForeignKey, Integer, String
+from sqlalchemy.dialects.postgresql import UUID
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from api.models.base import Base, new_uuid
+
+
+class SBOMSnapshot(Base):
+    """Container entity for a point-in-time SBOM scan of a repository (GEMS Complex)."""
+    __tablename__ = "sbom_snapshots"
+
+    id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True), primary_key=True, default=new_uuid
+    )
+    repo_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("managed_repos.id", ondelete="RESTRICT"),
+        nullable=False,
+        index=True,
+    )
+    snapshot_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
+    source: Mapped[str | None] = mapped_column(String(200), nullable=True)
+    entry_count: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
+
+    repo: Mapped["ManagedRepo"] = relationship("ManagedRepo", lazy="selectin")  # noqa: F821
+    entries: Mapped[list["SBOMEntry"]] = relationship(  # noqa: F821
+        "SBOMEntry", lazy="select", back_populates="snapshot"
+    )

api/models/technical_debt.py

@@ -25,7 +25,12 @@ class TechnicalDebt(Base, TimestampMixin):
     td_id: Mapped[str | None] = mapped_column(
         String(30), nullable=True, unique=True, index=True
     )  # human-readable ref, e.g. TD-CUST-001
-    domain: Mapped[str] = mapped_column(String(50), nullable=False, index=True)
+    domain_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("domains.id", ondelete="RESTRICT"),
+        nullable=False,
+        index=True,
+    )
     title: Mapped[str] = mapped_column(String(255), nullable=False)
     description: Mapped[str | None] = mapped_column(Text, nullable=True)
     location: Mapped[str | None] = mapped_column(String(500), nullable=True)
@@ -43,5 +48,10 @@ class TechnicalDebt(Base, TimestampMixin):
         UUID(as_uuid=True), ForeignKey("workstreams.id", ondelete="SET NULL"), nullable=True
     )
 
+    domain: Mapped["Domain"] = relationship("Domain", lazy="selectin")  # noqa: F821
     topic: Mapped["Topic"] = relationship("Topic", lazy="selectin")  # noqa: F821
     workstream: Mapped["Workstream"] = relationship("Workstream", lazy="selectin")  # noqa: F821
+
+    @property
+    def domain_slug(self) -> str:
+        return self.domain.slug if self.domain is not None else ""

api/models/workstream.py

@@ -34,7 +34,15 @@ class Workstream(Base, TimestampMixin):
     owner: Mapped[str | None] = mapped_column(String(100), nullable=True)
     due_date: Mapped[date | None] = mapped_column(Date, nullable=True)
 
+    repo_id: Mapped[uuid.UUID | None] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("managed_repos.id", ondelete="SET NULL"),
+        nullable=True,
+        index=True,
+    )
+
     topic: Mapped["Topic"] = relationship("Topic", back_populates="workstreams")  # noqa: F821
+    repo: Mapped["ManagedRepo"] = relationship("ManagedRepo", lazy="selectin")  # noqa: F821
     tasks: Mapped[list["Task"]] = relationship(  # noqa: F821
         "Task", back_populates="workstream", lazy="selectin"
     )