the-custodian/wiki/GEMS-StateHub-SWOT.md

SWOT Analysis — Migrating State-Hub to GEMS

Evaluation of migrating the Custodian State Hub data store from its current ad-hoc relational schema to the Generic Entity Modelling System (GEMS) as defined in wiki/GenericEntityModellingSystem.md and instantiated in wiki/GEMS-StateHub-TypeRegistry.md.

Created: 2026-03-02 Author: Custodian (analytical session)

---

Migration Options Under Consideration

Before the SWOT, three architectural options are in scope:

Option A — Full Generic Entity Model Single entities table + attachments junction + JSONB payload. True GEMS implementation. All current typed tables dissolved into the entity model.

Option B — Typed-Table Approach with GEMS Constraints Keep typed tables (domains, topics, workstreams, etc.) but add:

• A universal entity_id abstraction layer
• An attachments junction table for secondary attachments
• Application-level GEMS constraint validation
• Fix all structural inconsistencies (I-1 through I-8 in CUST-WP-0006)

Option C — Incremental Normalization (Pattern C from GEMS §9) Fix the most critical inconsistencies immediately (I-1, I-2, I-5), leave lesser items wrapped/deferred. No generic entity table introduced.

---

SWOT Analysis

Strengths

S1 — Uniform modeling surface eliminates special-casing (all options) Currently each entity type has bespoke FKs, bespoke routers, and bespoke MCP tools. GEMS gives a predictable pattern: every entity has a primary context and optional secondaries. New entity types follow the same pattern with zero schema design work.

S2 — Fixes real, observable bugs (Options B and C) The domain string inconsistency (I-1) causes SBOM and EP/TD dashboard views to silently display wrong or missing domain associations. The Workstream/Topic container mismatch (I-2) causes domain attribution to fail in the Dependencies view. These are current user-visible defects — migration resolves them.

S3 — ADR-001 alignment (Options B and C) ADR-001 mandates that workstreams originate in repos. The current schema forces workstreams under Topics. Migrating Workstream.primary → Repository would bring the schema into conformance with the governing ADR.

S4 — Enables first-class graph queries (Option A, partially B) With Relations as first-class entities, queries like "what decisions influenced which tasks?" or "what dependencies cross domain boundaries?" become uniform and indexable. Currently these require ad-hoc multi-table joins.

S5 — Incremental migration is supported by the model (all options) GEMS §9 explicitly defines integration patterns for existing systems. Pattern C (progressive normalization) allows working systems to remain stable while the most valuable types are migrated first.

S6 — Future-proofs multi-domain cross-system queries As more repositories are registered and domains become interdependent, the current schema's inconsistencies compound. GEMS alignment now prevents exponential complexity accumulation.

---

Weaknesses

W1 — Option A requires full schema rewrite (high risk) Dissolving typed tables into a generic entity model means every router, every MCP tool, every dashboard data loader, and every Alembic migration must be rewritten. This is weeks of work with high regression risk.

W2 — Loss of SQL-level type safety (Option A) Typed tables give the database schema as documentation and enforce type-correct relations at the DB constraint level (FK types, enum columns). A generic entity table with JSONB payloads moves type enforcement to the application layer, which is easier to break silently.

W3 — GEMS does not define a concrete SQL schema The GEMS document is conceptual. Translating the attachment list model into PostgreSQL requires design decisions (indexed JSONB vs. junction table, UUID ordering, etc.) that are not trivial and have performance implications.

W4 — ProgressEvent's multi-attach pattern doesn't map cleanly to GEMS ProgressEvent's current schema (nullable topic_id, workstream_id, task_id, decision_id) is intentionally flexible for an append-only log. GEMS's "exactly one primary attachment" rule may force awkward choices (e.g. always using Workstream as primary even for domain-level events).

W5 — Ecosystem root is of uncertain value Adding an explicit Ecosystem singleton adds ceremony for little practical query benefit in the current six-domain setup. It may become valuable when the system grows to multi-tenant or multi-ecosystem scope, but is premature now.

---

Opportunities

O1 — Snapshot diffing for SBOM (SBOMSnapshot entity) Adding a SBOMSnapshot container (resolves I-5) enables: "what packages were added/removed between ingests?" This is a direct user value feature, not just architectural cleanup.

O2 — Unified contribution and decision provenance graph With Relation entities, you can model "Decision D motivates Workstream W" or "Contribution C implements Decision D" as queryable, auditable edges. This is the foundation for a richer Custodian agent that can reason about the provenance of work items.

O3 — Generic dashboard patterns Once GEMS is in place, dashboard pages can share a single entity-browsing component rather than one bespoke page per entity type. This reduces UI technical debt significantly.

O4 — Enabling cross-repo task relations (DependsOn at Repository scope) With Relations as first-class, it becomes natural to register "Task A in repo X blocks Task B in repo Y" — a cross-repo dependency that the current WorkstreamDependency table cannot model.

O5 — Type registry as a self-documenting schema A GEMS Type Registry is human-readable, machine-validatable, and version-controlled. It replaces the current implicit understanding of "what can be attached to what" with an explicit contract.

---

Threats

T1 — Risk of over-engineering a working system The state-hub currently works well enough for its intended read-model role. A full schema rewrite to achieve theoretical elegance could introduce regressions, stall other domain work, and deliver minimal user-visible value in the short term.

T2 — ADR-001 workplan file format would need updates If Workstream moves from Topic to Repository as its primary container, every existing workplan frontmatter field (topic_slug) would need to become or add repo_slug. All workplan files across all registered repos require updating.

T3 — Hybrid state during incremental migration is confusing Pattern C leaves the system in a mixed state for an extended period: some entities are GEMS-conformant, others are legacy. Tooling must handle both shapes simultaneously, increasing maintenance burden.

T4 — Dashboard rewrites could introduce new bugs The dashboard is the primary UI for the hub. Rewriting data loaders and query patterns risks introducing visual regressions that would go unnoticed without a test suite (there is currently none for the dashboard).

T5 — No migration dry-run tooling exists The current make sync-workplans doesn't exist yet (CUST-WP future deliverable). Running migrations against production data without a rollback path is risky.

---

Verdict and Recommended Path

Recommended: Option C — Incremental Normalization

Proceed in three targeted passes, each independently releasable:

Pass 1 — Fix structural inconsistencies (I-1, I-6): low risk, high consistency gain

• Migrate ExtensionPoint.domain (String) → domain_id FK + back-fill
• Migrate TechnicalDebt.domain (String) → domain_id FK + back-fill
• Add repo_id FK to Contribution (nullable initially)
• This pass has zero API breaking changes; only DB schema and router filter logic change.

Pass 2 — Align Workstream with ADR-001 (I-2): medium risk, architectural gain

• Add repo_id FK to Workstream (nullable initially, then enforce)
• Update MCP create_workstream to require repo_id
• Update workplan frontmatter format to include repo_slug
• Migrate dependencies.md to use repo instead of topic for domain resolution
• Decision DEC-GEMS-002 must be resolved before this pass begins

Pass 3 — Add SBOMSnapshot container (I-5): medium risk, feature gain

• Add sbom_snapshots table + FK from sbom_entries
• Update ingest API to create/find snapshot per repo+timestamp
• Enable snapshot history and diff queries in SBOM dashboard
• Decision DEC-GEMS-004 must be resolved before this pass begins

Deferred: Full generic entity model (Option A), Ecosystem root (I-7), DependsOn as first-class Relation (I-8), ManagedRepo.topic_id cleanup (I-4). These are tracked as extension points; revisit after Passes 1-3 are stable.

---

Decision Dependency Map

DEC-GEMS-001 (architecture)  ──────────────────────────────────► Pass 3+
DEC-GEMS-002 (workstream/topic vs repo)  ──────────────────────► Pass 2
DEC-GEMS-003 (domain string → FK)  ────────────────────────────► Pass 1
DEC-GEMS-004 (SBOMSnapshot container)  ────────────────────────► Pass 3
DEC-GEMS-005 (Ecosystem root)  ─────────────────────────────────► Deferred
DEC-GEMS-006 (DependsOn as Relation entity)  ───────────────────► Deferred

Pass 1 can begin as soon as DEC-GEMS-003 is resolved (expected: trivially yes). Pass 2 requires DEC-GEMS-002 resolution (breaking change; needs explicit approval). Pass 3 requires DEC-GEMS-004 resolution.