Ecosystem Philosophy
The Ecosystem Philosophy
The Aggrega architecture is guided by core design principles that balance flexibility with predictability. By maintaining clear boundaries and standardized contracts, a fundamentally generic compiler can seamlessly orchestrate everything from standard cloud-native infrastructure to highly specialized AI intelligence.
1. Core Mechanics: The Physics of the Architecture
- Separation of Concerns (Conway’s Law): Developers do not write physical infrastructure code, and Ops do not hardcode application logic. The architecture’s guidance divides authoring into Domain-Driven boundaries, a separation the compiler does not enforce (see Invariant 7).
- Late Binding (Dependency Inversion): Developers request abstract Interfaces (e.g.,
type: enterprise-agent), not specific Implementations (e.g.,helm-chart-v2). The Manifest resolves the interface to the correct implementation at compile time, allowing true multi-target deployments from a single source file. - AOT Purity (No Live Cloud Fetching): The compiler is agnostic to the live cloud. It never authenticates with infrastructure APIs or fetches live IP addresses during compilation. It operates entirely on Control Inversion, mapping deterministic pointers and passing abstract Injection Contracts ahead of time so the runtime environment can safely resolve the final physical connections.
2. The Developer Experience: Intent & Abstraction
- Semantic Developer Experience (The 5-Keyword Map Standard): To prevent cognitive friction, developers use exactly five universally understood keywords within a Map-based YAML topology:
parameters: The global environment contract (e.g., passing dynamic disk sizes).values: The core cognitive/business logic payload (Developer Owned).uses: The explicitly declared network edges and dependencies (Developer Owned).infra: The physical footprint and mechanical sizing (Ops Owned, banned from the Aggregate).inject: The strict delivery contract mapping local variables to target, provides keys (env,file,arg). This mechanism is extensible.
- Capability-Agnostic Terminology: To prevent underlying infrastructure realities (like the Kubernetes term
namespace) from bleeding into the developer experience, the platform utilizes universal concepts likeboundaries. - Explicit Intent & The “Loud Guardrail” (No Ghost Infrastructure): The compiler must never invent compute or features that the developer did not explicitly declare. Using a policy engine to silently inject a security proxy creates “Ghost Infrastructure”—when it breaks, the developer ends up debugging a proxy that doesn’t exist in their YAML. Instead of silently mutating the architecture, Wasm policy plugins act strictly as Loud Guardrails. If a topology violates security, the compiler halts the build and returns a highly specific error (e.g., “Error: PII data flowing to a model provider through the AI gateway
router. You must explicitly attach thecore/data-maskingfeature to it”), forcing the developer to fix their own Single Source of Truth.
3. The Unopinionated Compiler: Processing & Orchestration
- Programmable Policies (The Unopinionated Compiler): The core Go compiler is a content-neutral, calculating mechanism. It parses YAML, traverses graphs, and evaluates label intersections. The actual “intelligence” (e.g., enforcing that model traffic carrying restricted data passes through an AI gateway that masks sensitive text) is programmed dynamically by the enterprise using pluggable WebAssembly (Wasm) sockets for Abstract Syntax Tree (AST) mutations—altering the parsed, in-memory representation of the configuration—and policy validation.
- Schema Agnosticism (open source dictionary): The core compiler is agnostic to physical execution layers. It does not possess hardcoded schemas for Helm, Terraform, or Docker Compose. Instead, the
sourceblock of an Ops Recipe is an open dictionary whose keys are provider-defined and surface to the Recipe’s templates as.source.*. The core resolves a fetched source by a built-in{ kind, url, version }form (kinds:helm-oci-chart,helm-https-chart,compose-https-fragment,git-repository), which already decouples the compiler from the cloud languages it manipulates. See the Recipesourcereference for the fetch model. - Explicit Plugin Orchestration: The core Go compiler acts strictly as a neutral graph builder and never guesses how to process a node. Instead, all domain intelligence is explicitly orchestrated via dedicated WebAssembly (Wasm) sockets at two distinct levels.
1. Global Sockets: Enterprise policies and formatting are evaluated by explicitly registered compiler sockets (e.g., the governance
label-transformrole for metadata auto-tagging, a governance verdict role for topological security, and the renderer socket for final artifact generation). 2. Implementation Pipelines: Component-specific mutation logic is orchestrated by theManifest; when it resolves an abstract interface to a concreteRecipe, that implementation explicitly declares a sequentialpipelinearray of Wasm plugins to execute. The compiler simply feeds the capability-agnostic Intermediate Representation (IR) graph into these defined sockets, ensuring all domain-specific logic remains strictly versioned in the ecosystem rather than hardcoded into the compiler core. - Flat Compilation & Feature Atomicity: Aggrega does not manage state, ping endpoints, or wait for a rollout to finish. The compiler evaluates nested modules and resolves them down into a flat, 1-dimensional Intermediate Representation (IR) graph before passing the data to the Wasm rendering plugins. Crucially, while the graph is flattened, the compiler preserves Feature Atomicity. If a proxy feature autonomously declares a network edge to a secure vault, the compiler records the semantic origin of that edge, ensuring Wasm policy engines can execute $O(1)$ lookups without falsely attributing the connection to the parent component. Finally, to support temporal sequencing, each boundary in the Release carries a
syncWave: <integer>value; each rendering plugin translates the per-boundary wave into whatever its own target expresses ordering with — an execution-order annotation the downstream GitOps controller reads, or a dependency between the services of the file it renders — while a target with no ordering surface at all records the wave without sequencing on it.
4. The Semantic Ontology: Identification & Taxonomy
- The Operational Cloud-Native Ontology: To ensure open-source Wasm plugins and corporate policies can interoperate universally, the
component.aggrega.ai/typelabel maps exclusively to a closed set of universal cloud primitives (server,worker,task,function,stateful-server,resource). This is Aggrega’s own key: the published Component schema enumerates the values it takes, and a document carrying anything else is refused when it loads. Fixing that vocabulary centrally is what guarantees autonomous policy engines and community-built Wasm rendering plugins read the same word for the same shape when they meet a Component neither of their authors wrote. The compiler still infers nothing from the string — it matches the value against a selector and provisions nothing on its own account; what the closed set buys is that everyone’s selector is matching the same vocabulary. - Classifying on an axis Aggrega does not define: the closed set covers this one reserved key. A catalog that needs its own classification — a tier, a data zone, a service class, a finer split of the primitives — authors its own label key beside the reserved one, since the Component schema accepts any further label key with a string value and every selector surface reads it the same way. Extension happens on your key, not inside Aggrega’s, which is what lets an enterprise vocabulary grow without the shared one drifting.
- Duck Typing (Semantic Traits via Labels): If the base types are purely cloud-native, all cognitive, operational, and compliance intelligence is layered entirely through semantic duck-typing. Labels authored by the Platform Architect (e.g.,
model.aggrega.ai/capability: generative,compliance.aggrega.ai/data-class: restricted) act as the true identity of the node. Features bind dynamically to components based on these label selectors.
5. Enterprise Governance: Schemas & Inheritance
-
Strict API Partitioning & Enterprise Discoverability: Following Kubernetes standards, all payload definitions uniformly reside within a
spec:block. Resource identity, characteristic labeling, and explicit compiler instructions reside strictly in themetadata:block. To guarantee strict resolution, every shareable YAML artifact strictly mandates a Regex-enforced SemVerversionstring. Furthermore, to support OCI registry discoverability and lifecycle governance, themetadatablock supports an optional Enterprise Metadata Suite. This suite includesdescription, a structuredmaintainersobject array (name, email, url),license,repository,home(documentation URL), andkeywords(for search indexing). End-of-life is managed outside the document:aggrega deprecateattaches a signed deprecation marker — a severity, a reason and an optional replacement — to an already-published artifact without changing its published bytes. -
Schema Extensibility (The Kubernetes CRD Pattern): To avoid updating the core compiler schema for every new AI or infrastructure feature, the platform uses JSON Schema 2020-12 to validate configurations. Platform Architects write strict types, validation logic, and default values directly inside the Catalog components’
schema:block — typically authored in compact form, a YAML-shaped shorthand that fits per-field constraints on one line (port: { type: integer, min: 1, max: 65535, default: 8080 }) and compiles to JSON Schema 2020-12 before validation runs. Full JSON Schema YAML remains a co-equal authoring option for schemas that need its complete vocabulary. Catalogs that grow large enough to benefit from cross-Component schema reuse pull common shapes (probe blocks, resource limits, named-port shapes) into a dedicated SchemaLibrary entity and reference them via the JSON Schema$ref:keyword. -
Schema Inheritance (Payload Baselines): To keep a baseline authored once, the platform splits inheritance into two distinct tiers. Standard YAML metadata (including semantic labels),
Manifestmappings, andReleaseconfigurations utilize traditional merge strategies to allow necessary environment overrides. The payload schemas (schema:) do not merge that way, and the two catalog kinds part company: a Feature’sschema:composes with its base’s under JSON Schema 2020-12 composition semantics, walked at workspace load by a merger with source-position provenance tagging so every leaf in the merged schema carries its originating file; an extending Component authors no payload content at all — it writes the literal markerschema: inheritedand receives its base’s block exactly as the base authored it, at every depth of a chain. A Component’s baseline is therefore guaranteed by construction rather than by policy: the child’s contract simply is the base’s, so there is nothing for the child to relax. What such a Component composes instead is structure — its attachment slots, topology sockets, self-inject allowlist and namedassertions— and a child that needs a tighter rule than its base declares expresses it as an addedassertions:entry, which the base’s rules keep alongside rather than replacing. Broader topological security and label governance remain properly delegated to the Wasm governance socket. -
Interface Parity & Auto-Implementation: To prevent Ops from duplicating Recipe YAMLs when an Architect spawns a slightly altered flavor of a Base Component, a Recipe written against a base serves every Component that extends it, at any depth of the chain. The extending Component writes
schema: inherited, so it adds no root key tovalues/infra/providesthat the base’s Recipe would be incapable of consuming. The Manifest still maps the extending type with an entry of its own, and the mapping check accepts that entry when the mapped Recipe’simplementsnames the type or any base it extends (see A Recipe written against a base serves everything that extends it). The Ghost Infrastructure Tracker (emitting warnings when no template the bound Recipe declares reads an authored key, to prevent “Ghost Infrastructure”) is the corresponding rendering-phase guardrail. -
implementsVersion Matching: Theimplementsfield on Recipes and FeatureRecipes supports three forms to balance strictness with ecosystem flexibility:- Exact version:
implements: "core/api-server:1.0.0"— matches only1.0.0. For Recipes tightly coupled to a specific schema version. - Major-compatible (SemVer range):
implements: "core/api-server:^1.0.0"— matches>=1.0.0, <2.0.0. Designed for Recipes that ride the Component’s SemVer compatibility guarantees: minor and patch bumps are assumed backward-compatible per SemVer, and the compiler checks that the Component’s version satisfies the range. - Unversioned:
implements: "core/api-server"— matches any version. For Recipes that are genuinely version-agnostic (e.g., a generic worker Recipe that only uses.context.inject.envand no version-specificvaluesfields).
implementsnever selects a Recipe: the Manifest names the Recipe for each component type, and the compiler checks that the mapped Recipe’simplementsaccepts that type in one of the three forms, halting on a mismatch. The same declaration is how the compiler suggests candidate Recipes when a component type has no mapping.The three-form pattern lets Recipes declare the version contract that fits their actual coupling to the Component’s schema. Recipes tightly bound to a specific schema version pin exactly; Recipes that ride the Component’s SemVer compatibility guarantees use a major-compatible range; Recipes whose behavior does not depend on Component version at all stay unversioned. The result is that minor Component version bumps do not force Ops to either pin Component versions or maintain parallel Recipes per version.
- Exact version: