-
Notifications
You must be signed in to change notification settings - Fork 3
Description
Description
Introduce a new context architecture for modules that cleanly separates module-level configuration (system contexts) from user-level data (user contexts). This design ensures predictable defaults, persistence of active selections, and minimal ceremony for module authors. For each module's vault, this architecture also defines a clear directory structure separating system context storage from user context storage.
Problem / Motivation
-
Need a clean separation between module configuration (system context) and user data (user context).
-
Each module should be able to:
- Resolve a canonical default system context (
default). - Maintain additional system contexts as selectable modes.
- Persist the last selected system context and automatically restore it when the module loads.
- Resolve a canonical default system context (
Solution Summary
-
Every module gets a built-in default system context named
default. -
Modules can define and use multiple system contexts (same schema) as selectable modes (e.g.,
default,experimental,staging). -
The active system context name is stored in a separate file:
- Stores only the name of the active context (string).
- Read automatically on module load to determine which system context to open.
- No file locking on read (safe for concurrent module loads).
- Independent from actual system context files (which remain self-contained).
-
User contexts are kept separate:
- Store per-user data (accounts, tokens, preferences).
- Not affected by which system context is active.
-
Vault directory segregation: Each module's context vault is organized into distinct folders for system contexts and user contexts.
- System context files reside under a dedicated
module/subfolder within the vault. - User context files reside under a dedicated
user/subfolder. - The active context name metadata file is stored in the
module/folder and kept unencrypted (plaintext).
- System context files reside under a dedicated
File Layout (Vault Example)
$HOME/.contextvaults/
└── <VaultName>/
├── module/ # System contexts (shared module configuration)
│ ├── active-context # Active system context name (plaintext, not encrypted)
│ ├── default.json # Default system context (always present, encrypted)
│ ├── experimental.json # Optional alternative context (encrypted)
│ └── staging.json # Optional alternative context (encrypted)
│
├── user/ # User contexts (per-user data)
│ ├── marius.json # Example user context (encrypted)
│ └── sigrid.json # Example user context (encrypted)
│
├── shard # Vault encryption key
└── config.json # Vault metadata/config
Goals
- Provide a first-class system context type for module configuration.
- Guarantee existence of a
defaultsystem context per module. - Support multiple system-level configurations (same schema, selectable modes).
- Keep user contexts distinct from system contexts.
- Persist and recall active system context in a dedicated metadata file.
- Ensure fallback to
defaultif metadata is missing or invalid. - Minimize complexity for module authors.
Acceptance Criteria
- ✅ On module load, the active system context is read from the metadata file.
- ✅ Metadata file contains only the active context name.
- ✅ Metadata file is separate from context data files.
- ✅ Metadata file is stored as plaintext (not encrypted).
- ✅ Reads do not lock the file.
- ✅ Missing/invalid metadata triggers fallback to
default. - ✅ System and user context files are stored in separate
module/anduser/subdirectories for each vault. - ✅ Users can explicitly access either system or user contexts via the Context commands (default behavior remains user contexts).
- ✅ Documentation updated to reflect new architecture.
Alternatives Considered
-
Embed active context name inside each context file
- ❌ Risk of format drift, unnecessary coupling.
-
Use registry or environment variables
- ❌ Risk of platform dependence, loss of portability.
Risks / Considerations
- Possible stale reads if context switching happens outside managed APIs.
- Need graceful handling for missing or corrupted metadata file (fallback to
default). - Backward compatibility: Existing vaults should be seamlessly migrated to the new folder structure (e.g. move legacy context files into
user/subdirectory) to avoid breaking current contexts.
Additional Context
-
System context files remain self-contained and interchangeable.
-
Context selection metadata remains separate.
-
Clear boundary:
- System contexts → Module-level configuration (shared).
- User contexts → Per-user accounts/data.
Code-Level Changes
-
Extend
Get-Contextto support a new parameter-Type:-
Default value:
'User'. -
Allowed values:
'User','Module'. -
Example:
Get-Context -Vault MyVault -Id default -Type Module
-
-
Ensure that context creation, switching, and persistence APIs respect the new folder structure.
-
Add migration logic for existing vaults to move old contexts into
user/by default. -
Update documentation, examples, and Pester tests.