Architecture: How should the 3-tier capability override system work for th...

Documentation for Sessions

🏗️ Architecture: How should the 3-tier capability override system work for th...

Date: 2026-03-31
Time: 18:42:25 UTC
Session: gspace1-293.5
Agent: backend
Confidence: 92%
Status: ✅ Documented

📋 Decision Context

Question:

How should the 3-tier capability override system work for the core/personal layer architecture?

Task: S293: Override storage for capability system

🎯 Decision Made

Chosen:

Resolution order: userOverride > spaceOverride > matrixDefault. Non-overridable capabilities (EDIT_CORE_VALUES, IMPERSONATE_USER, etc.) skip overrides entirely. Overrides stored in MongoDB capability-overrides collection with unique compound index on {spaceId, userId, capability}. Redis-cached 60s TTL. Executive-only REST API at /engine/capabilities/overrides.

Options Considered:

  1. Flat matrix with no overrides (simplest but not customizable)
  2. 3-tier resolution with overridable flag (chosen)
  3. Full ACL system with permission inheritance and deny lists

💭 Reasoning

The user's core requirement was two layers: a core layer (affects ALL Vittos, executive-controlled) and a personalizable layer (per-space/user customizable). The 3-tier resolution maps directly: matrix = core defaults, space overrides = builder customization, user overrides = individual grants/revocations. The overridable flag prevents privilege escalation on critical capabilities (EDIT_CORE_VALUES, MANAGE_VAULT, IMPERSONATE_USER, etc. are non-overridable — even an executive override record won't bypass them, the matrix is final). A full ACL system was rejected as over-engineering — the override count per user will be small (5-10), not thousands. The MongoDB schema follows existing patterns (SpaceAIPreferences, PersonaUserPreference). TTL index on expiresAt enables future time-limited grants without code changes.

📁 Files Involved

🔗 Related

Auto-generated by MCP Smart Consolidation