AlphaSwarm Config Subsystem

Catalog date: 2026-06-24.

The alphaswarm_config subsystem provides a centralized, hardened, and audited configuration resolution engine for the AlphaSwarm platform. It is an embedded Python package plus the monolith /configs/* HTTP control plane; it is not deployed as a standalone Kubernetes service.

Architecture

The configuration subsystem is built as a standalone package that can be imported by any service in the AlphaSwarm fleet (API, Worker, Controller, etc.). Host applications register database, audit, settings-bootstrap, and optional cell-registry adapters at process startup.

Layered Resolution

Configuration is resolved through a hierarchy of layers, where more specific layers override more general ones:

1. Global: Default settings from environment variables or hardcoded defaults.
2. Organization: Settings specific to an entire organization.
3. Team: Settings specific to a team within an organization.
4. User: Personal user settings.
5. Workspace: Settings for a specific workspace.
6. Project: Settings for a specific project.
7. Cell: Topology-aware settings for a specific deployment cell.

Components

• Engine: The core resolution logic that merges layers and validates them against schemas.
• Cache: An in-process, generation-aware ConfigCache that allows for atomic snapshot swaps of configuration state.
• Schemas: Namespace-specific Pydantic v2 models that ensure configuration payloads are correctly typed and valid.
• Persistence: SQLAlchemy models for storing overlays (ConfigOverlayRow) and their immutable history (ConfigOverlayRevision).
• Flags: An OpenFeature-compliant provider that bridges the configuration engine into a standard feature flagging API.
• Delivery: In-process watch/replay plus Postgres LISTEN/NOTIFY catch-up for multi-replica cache invalidation.
• Rollout: Cohort, canary, linear rollout, disable, and auto-rollback control.
• Metrics: Applied-version tracking and optional OpenTelemetry counters/histograms with bounded labels.

Feature Gates (Gaps A-F)

The subsystem is evolving through a series of "Gaps" (A through F), each gated by a feature flag in the Settings to ensure backward compatibility during migration.

Gate	Gap	Status	Description
config_expiry_enforced	Gap F	Implemented, default OFF	Honors the expires_at column at resolution time.
config_listen_notify_enabled	Gap A	Implemented, default OFF	Enables cross-process event delivery via Postgres.
config_rollout_enabled	Gap C	Implemented, default OFF	Enables the progressive rollout engine.
config_metrics_enabled	Gap D	Implemented, default OFF	Enables OpenTelemetry configuration metrics.
config_cell_placement_enabled	Gap B	Implemented, default OFF	Enables tenant-to-cell placement logic.
config_openfeature_provider_enabled	M4	Implemented, default OFF	Registers the optional OpenFeature provider when the SDK extra is installed.

Operations

Mutations

All configuration changes (mutations) must go through the governed funnel (set_overlay / clear_overlay), which ensures:

1. Validation: The payload matches the registered schema for its namespace.
2. Audit: A SecurityAuditEvent is emitted with a content hash and diff.
3. Immutability: A new ConfigOverlayRevision is recorded.
4. Notification: Local and (if enabled) remote listeners are notified of the change.

Observability

When config_metrics_enabled is ON, the subsystem emits the following metrics:

• config_loaded_version: The version currently loaded in the process cache.
• config_stale_read_seconds: Histogram of lag between mutation and cache update.
• config_apply_error_total: Counter of failed configuration applications.