ADR-019: AEnvironment Platform Re-architecture

Status: Accepted Version: 1.0 Date: 2025-12-18 Supersedes: N/A Related ADRs: N/A Related PRDs: N/A

Context

The AEnvironment platform currently uses a file-based config.json and a set of diverse services. We wish to adopt SEA™ DSL and SEA™ Services (Semantic Core, Knowledge Graph) as the foundational platform.

The goal is SEA™ itself—demonstrating and utilizing the SEA™ platform capabilities for environment management—rather than just “using DSL as config.”

Decision

We will execute a Full Runtime Rewrite of AEnvironment around SEA™ Services (Option B from the analysis).

• Canonical Truth: SEA™ DSL (Semantic Core) is the tier-0 source of truth for all environment definitions, replacing config.json as the primary input.
• Projections: We will build deterministic Projection Workers to translate SEA™ DSL ASTs into:
  • Runtime Configurations.
  • Deployment Manifests (Helm/K8s).
  • Documentation.
• Data Flow: SemanticChangeEvent -> Semantic Core -> Event Bus -> Projection Workers -> Runtime State.
• Language Stack: Rust for the Semantic Core and critical projection logic to ensure correctness and performance.

Rationale

• Isomorphism: To fully realize the “Define Once, Project Everywhere” vision of SEA™, the runtime must respond to semantic changes, not just read static files.
• Governance: By placing Semantic Core at the center, we enable executable governance (CALM policies) that gate environment creation/updates at the definition level.
• Graph-Native: This architecture natively populates the Knowledge Graph, enabling queries like “Which environments use tool X?” without scraping configs.

Constraints

• MUST use SEA™ DSL as tier-0 source of truth for environment definitions
• MUST use deterministic Projection Workers for translating ASTs
• MUST use event-driven data flow via SemanticChangeEvent
• MUST use Rust for Semantic Core and critical projection logic
• MUST support Local-First CLI and Bundle Caching for offline operation
• MUST NOT use config.json as primary input

Quality Attributes

• Isomorphic “Define Once, Project Everywhere” architecture
• Executable governance via CALM policies
• Graph-native environment queries
• Offline-capable via Local-First CLI
• Correctness and performance via Rust implementation

Bounded Contexts Impacted

• AEnvironment Platform
• Semantic Core
• Knowledge Graph
• Projection Workers
• Event Bus

Consequences

Positive

• Full realization of SEA™ vision
• Executable governance at definition level
• Native Knowledge Graph population
• Deterministic, reproducible projections

Negative

• Tier-0 Dependency: Semantic Core availability becomes critical
• Projection Brittleness: Projections can break (mitigated by regression tests and retry queues)
• Operational Complexity: Transforms AEnvironment from “config reader” to “event-driven platform”

Additional Notes

Rollout Plan

1. Semantic Core (Rust): Stabilize parsing/validation.
2. One-Way Projections: DSL -> Config.
3. Governance Gates: Enforce policy checks.
4. Event Model: Full event-driven updates.

Risk Mitigations

• Tier-0 Dependency: Mitigated with Local-First CLI and Bundle Caching (SDKs can work offline with signed bundles).
• Projection Brittleness: Mitigated by treating projections as Regression Tests and using retry queues.