Role system cleanup — MongoDB runbook

Companion to 2026-03-19-role-system-cleanup-handoff.md.
Purpose: Optional data backfills after deploying schema/code changes. Mongoose does not migrate existing documents automatically.

When to run

• After deploying backends that persist platformRole, extended UserHierarchyType, or AI userType enums.
• Run in non-prod first, then production during a maintenance window if you rely on consistent role fields for auth or Vitto.

Canonical values

• PlatformRole (JWT / User.platformRole): executive | developer | admin | builder | user | guest
• JWT roles[] (backend): system, executive, developer, admin, manager, editor, user, viewer (see auth-core constants)
• User hierarchy type (Mongo): includes executive and existing space_* / platform_user values (see user-hierarchy.schema.ts)

Remote monorepo / VM engineering (Vitto)

• Separate tool surface: Host monorepo / VM engineering uses dedicated tools: monorepo_read_file, monorepo_write_file, monorepo_run_command, monorepo_search_code, monorepo_git (when credential bridge is wired). They are monorepoRemoteEngineerOnly: only executive and developer (isMonorepoRemotePlatformEngineer in role-derivation.ts, including legacy JWT via platformRoleFromLegacyRoles).
• Platform building for customers stays on query_platform, edit_module_file, module generation, visual editing, execute_code (E2B), etc. — not the monorepo_* namespace.
• Channels: Agent loop layer follows derivePermissions(platformRole).configAccess when platformRole / jwtRoles are present on channel metadata; otherwise defaults to platform_builder.
• VM routing: SandboxedToolProxyService accepts both legacy names and monorepo_* aliases for the same VM operations.
• Executive full-stack workspace (S244): Only executive (isExecutiveFullStackWorkspaceVmEligible) gets a cold-boot VM with extra RAM/vCPU for running gspace1 inside the guest (multiple yarn serve backends + Nx apps like gograb-space + Chrome). Snapshot restore is skipped for this profile so we do not mix 2 GiB snapshots with a 12 GiB machine class. Defaults: 12288 MiB RAM, 4 vCPU — override with EXECUTIVE_WORKSPACE_VM_MEM_MIB / EXECUTIVE_WORKSPACE_VM_VCPU on backend-vitto-api. Orchestrator clamps with VM_MEM_SIZE_MIB_MAX / VM_VCPU_COUNT_MAX. See Executive workspace VM — gspace1 RAM budget.
• VM + GitHub: Mounting or cloning the private monorepo on the sandbox VM is infra (not this runbook): use a read-only deploy key or short-lived token, run git clone / git fetch in the VM image bootstrap or sandbox init, and point Vitto VM cwd at that tree.

Suggested mongosh checks

Replace database/collection names with your environment values (often gograb or tenant-specific DBs).

1. Users missing platformRole

// Users with legacy shape only (adjust collection name, e.g. users)
db.users.find(
  { platformRole: { $exists: false } },
  { email: 1, role: 1, roles: 1 }
).limit(20);

Backfill (example): derive from existing roles or role using the same rules as platformRoleFromLegacyRoles in role-derivation.ts, or force users through re-login / profile sync so the API sets platformRole. Avoid blind $set unless you have a verified mapping table.

2. User hierarchy rows — executive and level 0

db.userhierarchies.find({ type: 'executive' }).limit(10);
db.userhierarchies.find({ level: { $lt: 1 } }).limit(10);

New schema allows executive and level min 0 for L0. Existing documents without executive need no change unless you onboard executive-tier rows.

3. AI infrastructure / chat-related userType strings

If you store userType on AI session or infra documents, verify values match the expanded enum in ai-infrastructure.schema.ts (executive, admin, builder, user, guest, plus legacy strings). Find unknown values:

const allowed = [
  'developer', 'space_builder', 'platform_user',
  'executive', 'admin', 'builder', 'user', 'guest',
];
db.ai_sessions.find({ userType: { $nin: allowed } }).limit(20); // rename collection as needed

What not to do

• Do not drop or rename collections as part of this cleanup unless a separate migration plan exists.
• Do not remove UserHierarchyType enum values still present in documents (handoff: keep schema compatibility).

Verification

After backfills, spot-check:

1. platformRoleFromLegacyRoles(['manager']) → builder (app code, not Mongo).
2. Executive test user: JWT + User.platformRole = executive, hierarchy level 0 if applicable.
3. No Vitto/chat errors from unexpected userType in stored AI documents.