Decompose Management into resource-family modules

[gbaudrit]

Technical category

Architecture

Area

Cross-cutting

Problem

Management currently names both the global architectural plane used to administer Agentstration and a concrete project family that owns an expanding set of unrelated resource families. Because every declarative resource is managed through the control plane, the project name suggests that Flow, Trigger, Tool, Secret, model configuration, identity, and other resources should all belong to Agentstration.Management.*.

The implementation consequently combines generic resource mechanics and several distinct lifecycles under one apparent bounded context. API folders, test projects, storage adapters, coverage partitions, and diagnostics reproduce the same ambiguity by inferring ownership from the Management prefix.

Impact

The current naming obscures dependency direction and makes ownership difficult to review. Domain behavior can drift into generic Management services, cross-plane endpoints can be classified as Management APIs, and business test projects can acquire executable-host dependencies.

A naive decomposition would create a project for every resource or repeat Abstractions + Core + Contracts + Storage for every family. That would replace one oversized module with an excessive project graph without improving the useful boundaries.

No priority is assigned because there is no evidence that this architectural debt currently blocks a release or causes a user-facing failure.

Expected outcome

Management Plane or Control Plane is documented as an architectural umbrella and API façade composed of a small number of resource-family modules. It is not the name of a catch-all business domain.

The primary resource families are:

• Agentstration.Agents: Agent, AgentRevision, AgentDeployment, and their provisioning lifecycle.
• Agentstration.Triggers: Trigger declaration, scheduling, TriggerOccurrence, firing policies, and history.
• Agentstration.Flows: Flow authoring, FlowVersion publication, FlowRun execution, events, recovery, and causality.
• Agentstration.Models: ModelProvider, ModelProfile, and the explicitly reviewed placement of RuntimeProfile.
• Agentstration.Tools: ToolProvider, Tool, ToolDefinition, execution hooks, and governance.
• Agentstration.Secrets: Vault, Secret, value protection, and provider boundaries.

Existing cohesive domains such as Work, Runtime, Identity, Packs, Sources, Extensions, and Resources remain independent. Every resource family owns its schemas, validation, lifecycle, and domain events. Generic metadata, canonical addressing, namespaces, and scopes remain shared only where genuinely domain-neutral.

Scope

• Inventory every resource kind, service, storage port, endpoint group, hosted worker, and test project currently placed under the Management name.
• Add an ADR reserving Control Plane for the architectural umbrella and defining the plural resource-family naming convention.
• Supersede or refine ADR-0011 and align the Flow ownership decisions in ADR-0010 and ADR-0019 with the Agentstration.Flows family.
• Assign every existing managed resource kind to one explicit resource family.
• Rename, reduce, or remove the current Agentstration.Management.* project family through reviewable increments.
• Move family-specific contracts, validation, use cases, events, and storage ports to their owners.
• Keep shared resource primitives narrow and domain-neutral.
• Separate Trigger declaration APIs from Trigger occurrence creation, execution, and history while keeping both within the Triggers family.
• Separate generic control-plane concerns from API transport, authentication, Console presentation, executable-host composition, and cross-family operational projections.
• Realign project references, namespaces, architecture tests, test ownership, solution inventories, coverage shards, and hosted diagnostics.
• Decompose SQLite and PostgreSQL persistence by ownership where lifecycle-specific state requires it, while allowing truly generic resource persistence and physical database infrastructure to remain shared.
• Keep the modular monolith and one deployable standalone process.
• Preserve deterministic, offline, local-first behavior.

Out of scope

• Creating one project for every resource type.
• Repeating the full Abstractions/Core/Contracts/provider-specific Storage project pattern for every family without a demonstrated dependency boundary.
• Renaming public resource kinds, HTTP routes, JSON/YAML fields, or persisted identities without a separate compatibility decision.
• Moving FlowRun into Agent Runtime or TriggerOccurrence into Flows or Work.
• Implementing new resource capabilities solely to support the decomposition.
• Implementing the secure Console BFF from Deploy the operations Console as a secure BFF #201.
• Introducing microservices, an external broker, or a mandatory external database.
• Treating Fast/Integration lanes or coverage shards as architectural boundaries.
• Completing the decomposition inside PR ci(test): parallelize coverage and hosted diagnostics #357 or PR test: align suites with API and Console boundaries #360.

Dependencies

• Align test projects and architecture rules with the API and Console boundary #142 and PR test: align suites with API and Console boundaries #360 establish API, Console, host, and test boundaries; their organization may remain an intermediate state but must not be treated as final resource ownership.
• Split service registration into module-owned composition extensions #240 is complementary work for module-owned dependency-injection composition.
• Deploy the operations Console as a secure BFF #201 depends on explicit API and trust boundaries but is not an implementation prerequisite.
• PR ci(test): parallelize coverage and hosted diagnostics #357 must be adjusted when project identities and test inventories change.
• ADR-0011 currently defines the dedicated Management module and must be superseded or refined.
• ADR-0010 and ADR-0019 define current Flow and FlowRun ownership.
• ADR-0080 documents scope policies for resource kinds and must remain behaviorally consistent.

Implementation guidance

Use plural resource-family project names consistently. A family may contain several aggregates and capabilities when they share one lifecycle; use folders and namespaces for subdivisions such as Agentstration.Flows.Authoring, Agentstration.Flows.Execution, Agentstration.Triggers.Configuration, and Agentstration.Triggers.History.

Create an additional assembly only when it enforces a real boundary, such as isolating a provider dependency, publishing a cross-family contract, or preventing a forbidden reference. Do not use assembly count as a proxy for DDD alignment.

Use small ports for legitimate family relationships:

• Triggers resolves and submits a logical Flow target.
• Flows invokes Agents and Tools through provider-neutral execution ports.
• Infrastructure implements and composes those ports.
• Work records the functional task and result without taking ownership of FlowRun or TriggerOccurrence.

Keep architectural ownership, transport surface, functional test lane, and CI shard as independent classifications.

Alternatives considered

• Keep Management as the owner of every declarative resource: rejected because the resource families have distinct invariants and execution lifecycles.
• Rename Management to ControlPlane without decomposition: rejected because all resource families participate in the Control Plane.
• Use capability names such as Orchestration and Automation alongside resource-family names such as Agents: rejected because mixing conventions makes project ownership less predictable.
• Create a project per resource or per aggregate: rejected because it would produce excessive assemblies and repeated infrastructure.
• Split projects according to HTTP route groups: rejected because transport layout is not domain ownership.
• Perform one repository-wide extraction without an ownership ADR: rejected because it would create a large mechanical change without an agreed target architecture.

Acceptance criteria

• An accepted ADR distinguishes the Control Plane from concrete resource-family modules.
• The ADR adopts a consistent plural family convention and assigns every existing managed resource kind to one family.
• The target map explicitly covers Agents, Triggers, Flows, Models, Tools, Secrets, Work, Runtime, Identity, Packs, Sources, Extensions, and shared Resources.
• No resource is assigned to generic Management solely because it is declarative or exposed through a control-plane API.
• The current Agentstration.Management.* family is removed or reduced to a documented, domain-neutral responsibility.
• Each new project enforces a documented compilation, contract, or adapter boundary; resources are not given projects mechanically.
• Family-specific validation, use cases, events, and persistence ports reside with their accepted owner.
• Triggers owns both Trigger definitions and TriggerOccurrences while exposing distinct configuration and execution responsibilities.
• Flows owns Flow, FlowVersion, FlowRun, events, recovery, and causality.
• Agents owns Agent revisions, deployments, and provisioning without depending on Triggers or Flows.
• Runtime Run, WorkItem, identity/session, API transport, Console presentation, and Web host composition remain with their respective families or layers.
• Business test projects do not reference the executable Web host solely to exercise HTTP endpoints.
• Architecture tests enforce accepted dependency directions and prevent drift back into a catch-all Management module.
• Existing routes, serialized contracts, ETag behavior, scope rules, and persisted data remain compatible or have an explicitly approved migration.
• SQLite and PostgreSQL lifecycle-specific data have explicit family ownership without requiring one physical database per family.
• Fast, Integration, coverage, performance, and diagnostics inventories include every affected test project exactly once where applicable.

Tests and validation

• Run the Release restore and build with warnings as errors after each extraction increment.
• Run both deterministic functional lanes and preserve their complete expected inventories.
• Add architecture tests for every accepted family and forbidden cross-family dependency.
• Add or retain contract tests for resource scopes, ETags, generations, workspace isolation, and persistence compatibility.
• Verify Trigger configuration separately from manual and scheduled occurrence execution, idempotency, concurrency, failure history, and Work/Flow submission.
• Verify Flow authoring, publication, execution, cancellation, recovery, child-Flow behavior, and Agent/Tool ports.
• Generate the consolidated functional coverage report and verify all renamed product assemblies are included while test and performance assemblies remain excluded.
• Run hosted integration diagnostics for affected API or host test assemblies.
• Verify the standalone SQLite profile remains executable without Internet access, Docker, an external database, or a live LLM.
• Verify existing SQLite and PostgreSQL data remains readable across project, assembly, namespace, or schema migrations.

Additional context

This concern was exposed while reviewing PR #357 and PR #360. Coverage sharding did not create the ownership problem, but hard-coded project inventories can preserve it. PR #360 improves physical API and Console test boundaries while this task defines the final resource-family ownership model.

The intended granularity is a small number of coherent families, not one project per resource and not one assembly for every DDD concept.

Child tasks

• Compose family-owned API modules through a lightweight aggregator #363 — Compose family-owned API modules through a lightweight aggregator

Related: #142, #201, #240, PR #357, and PR #360.

Attachments

None.

Preliminary checks

• I searched for an existing issue covering this work.