S232: Universe/Space Database Duplication — Root Cause Analysis & Fixes

Date: 2026-03-18
Session: 232
Status: Implemented

Problem Summary

Multiple issues observed in MongoDB:

1. Duplicate space databases: space_chrome-space-1 and space_chrome-space-1_79fe44376823 for the same logical space
2. Duplicate universes in gograb-api: Multiple documents in gograb-api.universes with same spaceId: "chrome-space-1"
3. Double-prefixed collections: universe_universe_1772912869184_wly1ktx_matchs, universe_universe_1772912869184_wly1ktx_players

Root Causes

1. Space Database Resolver — Slug vs ObjectId (PRIMARY)

Location: backend-api/src/app/spaces/space-database/services/space-database-resolver.service.ts

Cause: resolveSpaceDatabaseName(spaceId) used findById(spaceId) only. When spaceId was a slug (e.g. "chrome-space-1") instead of MongoDB ObjectId:

• findById("chrome-space-1") fails (invalid ObjectId or no match)
• Resolver fell back to space_${spaceId} → space_chrome-space-1
• Meanwhile, correct path with ObjectId produced space_chrome-space-1_79fe44376823

Result: Same space accessed via slug vs ObjectId → two different databases.

Callers passing slug:

• API routes: /api/spaces/:spaceId/universes/... — frontend may use slug in URL
• spaces.service.updateUniverse — accepts slug, resolves to ObjectId internally but passes slug downstream in some paths
• Workflow/deployment: tenantId / spaceId from workflow URLs

2. Entity Schema Service — Hardcoded Legacy Format

Location: backend-api/src/app/data/entity-schema.service.ts

Cause: Used space_${spaceId} directly, bypassing the resolver entirely. When spaceId was a slug, created/accessed space_chrome-space-1.

Fix: Inject SpaceDatabaseService and use resolveSpaceDatabaseName(spaceId).

3. gograb-api.universes Legacy Merge

Location: backend-api/src/app/spaces/space-database/services/space-database-universe.service.ts

Cause: listUniversesInSpace merges universes from:

1. Space database universes collection
2. gograb-api.universes with { spaceId }

When spaceId was slug, gograb-api query returned legacy documents with spaceId: "chrome-space-1". E2E tests and legacy flows may have written to gograb-api.universes with slug as spaceId.

Note: Resolver fix ensures we now resolve slug → ObjectId before any DB access. The gograb-api.universes merge remains for backward compatibility but should receive consistent spaceId.

4. universe_universe_ Double Prefix (Fixed S232)

Cause: Some code path passes universeId that already includes universe_ prefix, and another layer prepends universe_ again. Example: universeId = "universe_1772912869184_wly1ktx" → universe_${universeId} → universe_universe_....

Fix: (1) collection-name.util.ts now strips all leading universe_ prefixes before adding one, ensuring exactly one prefix. (2) space-module-database.service.ts uses buildCollectionName(universeId, 'modules') instead of manual universe_${universeId}_modules. (3) Verification script checks for manual universe_${id}_ construction.

Implemented Fixes

Fix 1: Space Database Resolver — Slug Resolution

File: space-database-resolver.service.ts

• When findById(spaceId) fails and spaceId looks like a slug (contains -, not 24-char hex), try findOne({ spaceSlug: spaceId })
• Use resolved space's ObjectId and databaseFormat/spaceSlug for canonical db name
• Cache both slug and ObjectId → same db name

Fix 2: Entity Schema Service — Use Resolver

File: entity-schema.service.ts

• Inject SpaceDatabaseService
• Replace space_${spaceId} with await this.spaceDatabaseService.resolveSpaceDatabaseName(spaceId) in registerSchema and getSchema

Migration Script (S232)

Run to consolidate orphan DBs and fix double-prefix collections:

yarn migrate:space-db:sot --dry-run   # Preview
yarn migrate:space-db:sot             # Execute

Script: tools/scripts/database/migrate-space-db-to-sot.ts

• Merges space_{slug} → space_{slug}_{shortId} (SSoT)
• Renames universe_universe_* → universe_* in target
• Drops orphan database after merge

Additional Fixes (S232)

• space-modules.service: Removed deprecated getCollection() that used space_${spaceId} directly.
• space-database-collections.service: createSpaceDatabase now uses resolveSpaceDatabaseName(spaceId) when spaceSlug is not provided.

Cleanup Recommendations (Manual)

1. Orphan databases: Use yarn migrate:space-db:sot (see above).

2. gograb-api.universes: Audit documents with spaceId: "chrome-space-1". Update spaceId to canonical ObjectId or migrate to space DB. Consider deprecating the gograb-api.universes merge.

3. Double-prefixed collections: Migration script renames universe_universe_* → universe_*.

API Audit Summary

Verification Scripts (SSoT Enforcement)

Run before merge to ensure no new bypasses:

yarn verify:db:naming

Script: tools/scripts/database/verify-space-database-naming.ts

Checks:

• No direct space_${spaceId} or useDb('space_${...}') in backend-api (except resolver/collection-name.util)
• Entity schema uses SpaceDatabaseService.resolveSpaceDatabaseName
• E2E DatabaseHelper.getSpaceModule uses getSpaceDb() (canonical resolution)
• backend-ai-api getSpaceDatabaseName/getSpaceAIDatabaseName document CONTRACT (canonical spaceId)

Collection naming: All MongoDB universe collections MUST use buildCollectionName(universeId, collection) from collection-name.util.ts. Manual universe_${...}_ construction risks double-prefix (universe_universe_*).

References

• space-database/README.md — Architecture
• docs/english/sessions/S200/200.10-architecture-how-should-gitlab-repos-be-organized... — Slug vs ID confusion (GitLab)
• vitto-engine.service.ts:923 — Previous bug: "preferred slug over _id, causing chrome-space-1 as universeId"