AIFACTORY-FEAT-004: EnvironmentService: complete delivery¶
Generated from the architecture model
This page is rendered from model/**/*.yaml by tools/docs_model during mkdocs build. Edit the YAML, not this page; hand-written design lives on the linked service, platform and plane pages.
A design artefact, not a tracker
This backlog is generated from model/backlog/ and validated against the architecture model. No work item exists in any tracker, and no item carries a date, an estimate or an assignee (ADR-0029).
Epic Control Plane (PF-01) · Increment I1 Generate a microservice · State elaborated · Route backend-developer · Build order 53 of 185 (Factory code)
EnvironmentService is the service of bounded context BC-01 (Project & Environment). Owns the environments of a project (sandbox, dev, test, staging, production classes), their policy class, connections and the desired deployment references that Provisioning (BC-25) reconciles (BC-01). Its own repository is ConnectSoft.AI.SoftwareFactory.EnvironmentService.
| Delivers | EnvironmentService (complete) |
| Stubs | — |
| Realizes | adrs: ADR-0015, ADR-0017 |
| Requirements | FR-01, FR-05, FUX-01, NFR-01, NFR-04, XL-01, XL-10 |
| Depends on | — |
| Sources | model/services/control-plane/EnvironmentService.yaml |
Scenarios to trace (7, catalog): SCN-EnvironmentService-001 ✓, SCN-EnvironmentService-002 ✓, SCN-EnvironmentService-003 ✓, SCN-EnvironmentService-004 ✓, SCN-EnvironmentService-005 ✓, SCN-EnvironmentService-006 ✓, SCN-EnvironmentService-007 ✓
AIFACTORY-US-055: EnvironmentService serves its scope end to end¶
behavior · persona platform-admin
As a platform admin, I want EnvironmentService in place as the owner of the environments of a project, their policy class and their state, so that every other service reads the class and the state of an environment through one contract and its events.
This is the integration PBI of EnvironmentService, the owner of the environments of a project in the bounded context Project and Environment. An environment is a named target inside a project with a policy class (Sandbox, Development, Test, Staging or Production), a state (Draft, Active, Frozen or Retired), a region, the connections a run may use from it and the reference to the desired deployment that the Runtime Cloud platform reconciles; the service never deploys anything. The repository ConnectSoft.AI.SoftwareFactory.EnvironmentService is created and scaffolded in I0 by AIFACTORY-TASK-010 of feature repository-and-pipeline-conventions (D140) from the pinned base template package with UseFactoryProfile, and this feature starts from that scaffold, so token validation, the seven role policies, the scope chain with its 401, 403 and 404 answers, the tenant row filter, the Orleans messaging profile with the service name environment, health, readiness and the telemetry wiring come from the profile. Every integration event of the service is written as the run event envelope of the contracts package to the Orleans outbox in the transaction of its command (ADR-0014). The feature is delivered by five PBIs: creating an environment and announcing it (AIFACTORY-US-409), reading the environments of a project and the policy class of one environment for a tool call (AIFACTORY-US-410), freezing and unfreezing (AIFACTORY-US-411), the state machine with all five transitions and the EnvironmentStateChanged event (AIFACTORY-US-412) and the inbox handlers for what other services announce about an environment (AIFACTORY-US-413). The public REST operations are reached through ControlPlaneApi and require factory.projects.read or factory.projects.admin; the gateway forwards the user token without exchanging it, and the service accepts the audience of its own gateway (ADR-0015 amendment D117); the internal gRPC method is called by workloads. An environment of another tenant is answered 404, over gRPC NOT_FOUND, the same answer as for an identifier that does not exist, and a missing scope or project right inside the tenant of the caller 403 (ADR-0015). The same holds for a project: a projectId that is unknown in the tenant of the token or belongs to another tenant, which only a caller with the tenant-wide Platform admin role can address past the scope chain, is answered 404 on the two project routes (ADR-0015 amendment D113), and the model names that 404 in the code lists of CreateEnvironment and ListEnvironments (D117). ProjectService is the one required dependency: the service confirms through it that the project exists, and when it is unavailable a command that needs it fails fast and writes nothing. RuntimeEnvironmentService is optional and reached by events only; when it sends no observed state the environment keeps its desired reference. Every other service reads the class and the state of an environment through this contract or from its events.
Acceptance criteria
| AC1 | Given the repository ConnectSoft.AI.SoftwareFactory.EnvironmentService created and scaffolded in I0 by AIFACTORY-TASK-010 of feature repository-and-pipeline-conventions with dotnet new connectsoft-base -n ConnectSoft.AI.SoftwareFactory.EnvironmentService --UseFactoryProfile true from the pinned template package, when its pipeline runs, then the solution builds, the unit and acceptance tests pass with complete reports and a container image is published (ADR-0028, model/services/control-plane/EnvironmentService.yaml). |
| AC2 | Given the service descriptor of the repository, when the contract test compares it with the hosted surface, then EnvironmentService/CreateEnvironment, EnvironmentService/ListEnvironments, EnvironmentService/FreezeEnvironment, EnvironmentService/UnfreezeEnvironment and EnvironmentService/Environments.GetPolicyClass are hosted with the scope, side-effect class, idempotency and response codes of model/services/control-plane/EnvironmentService.yaml, the 404 of the two project routes for a project outside the tenant of the token among them, and the test fails on an endpoint the file does not name. |
| AC3 | Given environments of two tenants and a caller of one, when an operation addresses an environment of the other tenant, then the answer is 404, over gRPC NOT_FOUND, exactly as for an unknown identifier; given a caller without the scope or without a role in the project, when it calls, then the answer is 403; given no token, then 401; and in no case a state changes; a user token that ControlPlaneApi forwards unchanged, whose audience is that gateway, is accepted by the service without a token exchange (ADR-0015, NFR-01). |
| AC4 | Given the outbox of the service after the acceptance suite, when its records are read, then EnvironmentService/EnvironmentCreated and EnvironmentService/EnvironmentStateChanged are the only event types it holds, each written in the transaction of its command under the run event envelope with the tenant of the EnvironmentService/Environment (ADR-0014). |
| AC5 | Given the service starts, when liveness and readiness are probed, then readiness is unready until environment-sql is migrated, while the outbox check of the messaging profile is unhealthy and while the identity authority is unreachable, and connectsoft.factory.environments.frozen is emitted with the dimensions tenant and class while activities and log records carry tenant and project (ADR-0017, model/services/control-plane/EnvironmentService.yaml). |
| Traces: services | EnvironmentService |
| Traces: aggregates | EnvironmentService/Environment |
| Traces: apis | EnvironmentService/CreateEnvironment, EnvironmentService/ListEnvironments, EnvironmentService/FreezeEnvironment, EnvironmentService/UnfreezeEnvironment, EnvironmentService/Environments.GetPolicyClass |
| Traces: events | EnvironmentService/EnvironmentCreated, EnvironmentService/EnvironmentStateChanged |
| Traces: adrs | ADR-0014, ADR-0015, ADR-0017, ADR-0028 |
| Traces: requirements | FR-01, NFR-01 |
| Depends on | AIFACTORY-US-409, AIFACTORY-US-410, AIFACTORY-US-411, AIFACTORY-US-412, AIFACTORY-US-413, feature:repository-and-pipeline-conventions, feature:component-base-template-factory-profile, feature:component-base-template-findings, feature:component-extensions-ai, feature:contracts-package |
| Sources | model/services/control-plane/EnvironmentService.yaml, docs/planes/control/services/environment-service/index.md#purpose-and-responsibilities, docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-013 API hosting skeleton: service descriptor, REST and gRPC hosts, scope policies and problem responses of the 4 REST and 1 gRPC operations |
contract | The service descriptor file lists CreateEnvironment, ListEnvironments, FreezeEnvironment, UnfreezeEnvironment and Environments.GetPolicyClass with scope, side-effect class, idempotency and response codes; the four REST routes and the gRPC method are hosted with the scope policy of each route, problem responses for every modelled refusal code, the 404 of a project outside the tenant of the token on the two project routes among them, the Idempotency-Key filter of CreateEnvironment and the workload scope check of the gRPC method; the behaviour of each operation is delivered by AIFACTORY-US-409 to AIFACTORY-US-411, not here. | ConnectSoft.AI.SoftwareFactory.EnvironmentService |
AIFACTORY-TASK-015 Security, tenancy and telemetry of EnvironmentService |
implementation | The scopes factory.projects.read and factory.projects.admin and the roles of the model are enforced per route, a user token forwarded by ControlPlaneApi is accepted with the audience of that gateway and no token is exchanged (ADR-0015 amendment D117), every query is tenant-filtered so an environment of another tenant is answered 404 (ADR-0015), the messaging-transport secret comes from a secret reference, readiness reports the store, the outbox and the identity authority, and connectsoft.factory.environments.frozen is created through the instrument helper of the observability library with tenant and class. | ConnectSoft.AI.SoftwareFactory.EnvironmentService |
AIFACTORY-TASK-700 Verify environment-service-serves-its-scope by running the declared command |
verification | Run dotnet build -c Release and dotnet test -c Release --no-build in the pipeline of the repository; a run that discovers no test counts as a failure; the runs pass and prove AC1 to AC5 of AIFACTORY-US-055, that is the scaffold, the hosted surface against the service descriptor, the two-tenant matrix with its 404, 403 and 401 answers, the two event types of the outbox and readiness. |
ConnectSoft.AI.SoftwareFactory.EnvironmentService |
AIFACTORY-US-409: Create an environment of a project with its policy class and announce it¶
behavior · persona workspace-admin
As a workspace admin, I want to create an environment of my project with a name, a policy class and a region, so that runs and tool calls that target it are governed by its class from the first call.
A Workspace admin or a Platform admin, a caller whose scope carries factory.projects.admin, creates an environment of a project through the gateway route of EnvironmentService/CreateEnvironment with an Idempotency-Key. The tenant comes from the token and the project from the path, and the project is admitted into the scope only when the token holds a role claim for it or the tenant-wide Platform admin role; a project the token does not grant is refused with 403 and its existence is never confirmed. The body names the environment: its name, its class, one of Sandbox, Development, Test, Staging and Production, and its region, and it may name the connections usable from the environment and the reference to its desired deployment. The model names no 400 for the operation: which status an invalid body receives (a class outside the five values, a missing name or region, an unknown connection id) is an open point reported to the owner, and until it is decided the acceptance test fixes only that an invalid body writes no Environment and no outbox record. The service confirms through ProjectService that the project exists. A caller with the tenant-wide Platform admin role passes the scope chain for any projectId, so the service answers that check itself: when ProjectService reports that the project does not exist in the tenant of the token, which is also its answer for a project of another tenant, the call is answered 404, the same for the foreign and the unknown project, and nothing is written or published (ADR-0015 amendment D113); the model names this 404 in the code list of the operation (D117). When the project exists, the service writes the Environment in state Draft with its policy class and writes the EnvironmentCreated outbox record in the same transaction; the response is 201 with the environment and its location. The policy class is the most important output of the service: a tool call against a Production environment is raised to the production action class, so the class is fixed when the environment is created and travels in the event. Names are unique within a project: a second environment with the same name is refused with 409 by the invariant of the aggregate and the unique index of the table. A repeated call with the same key and the same body returns the same environment and changes nothing; the same key with a different body is refused with 409. When ProjectService is unavailable the call fails fast with a problem response and nothing is written. EnvironmentCreated carries environmentId, projectId, tenantId and class under the run event envelope of the contracts package, with the tenant and the project in the envelope; the dispatcher of the environment messaging profile publishes it on projects.environments.v1.environment-created and retries a transport outage with backoff. IaCProvisioningService, RuntimeEnvironmentService and StudioBff consume the event in their own increments and PBIs; this PBI proves what the publisher can prove. The option Projects:Environments:DefaultClasses is bound with its default; this PBI creates no environment on its own.
Acceptance criteria
| AC1 | Given a caller with factory.projects.admin whose token grants the project of the path and a body that names name, class and region, when EnvironmentService/CreateEnvironment is called with an Idempotency-Key, then the response is 201 with the environment, the EnvironmentService/Environment exists in state Draft with its class in environment-sql, and the EnvironmentService/EnvironmentCreated outbox record is written in the same transaction (SCN-EnvironmentService-001, ADR-0014). |
| AC2 | Given the same call repeated with the same Idempotency-Key and the same body, when it arrives, then the same environment is returned and no second EnvironmentService/Environment and no second outbox record exists; given the same key with a different body, or a name already used by an environment of the project, when EnvironmentService/CreateEnvironment is called, then the answer is 409 and nothing is written (SCN-EnvironmentService-001, ADR-0014). |
| AC3 | Given a caller without factory.projects.admin, or a token that grants no role in the project of the path, when EnvironmentService/CreateEnvironment is called, then the answer is 403 with a problem response that never confirms whether the project exists; given a caller with the tenant-wide Platform admin role and a projectId that does not exist in the tenant of the token or belongs to another tenant, when it is called, then the answer is 404, the same for the foreign and the unknown project (ADR-0015 amendment D113); given ProjectService is unavailable, when it is called, then the call fails fast with a problem response; given an invalid body, for which the model names no status and the status is an open point reported to the owner, when it is called, then the test fixes only that nothing is written; in each case no EnvironmentService/Environment is written and nothing is published (SCN-EnvironmentService-001, ADR-0015). |
| AC4 | Given an environment was created, when the outbox dispatcher of the environment messaging profile publishes EnvironmentService/EnvironmentCreated on projects.environments.v1.environment-created, then the event is sent under the run event envelope with environmentId, projectId, tenantId and class, and a transport outage is retried with backoff so the event is neither lost nor published twice under its event id (SCN-EnvironmentService-006, ADR-0012). |
| Traces: services | EnvironmentService |
| Traces: aggregates | EnvironmentService/Environment |
| Traces: apis | EnvironmentService/CreateEnvironment |
| Traces: events | EnvironmentService/EnvironmentCreated |
| Traces: descriptors | run-event-envelope-v1 |
| Traces: adrs | ADR-0012, ADR-0014, ADR-0015 |
| Traces: requirements | FR-01, XL-01 |
| Traces: scenarios | SCN-EnvironmentService-001, SCN-EnvironmentService-006 |
| Depends on | feature:project-service, feature:contracts-package, feature:component-base-template-factory-profile |
| Sources | model/services/control-plane/EnvironmentService.yaml, docs/planes/control/services/environment-service/index.md#domain-model, docs/reference/schemas/run-event-envelope.schema.json |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-011 Domain model: Environment with its four states, five transitions and the invariants the aggregate enforces |
implementation | The Environment aggregate holds the fields of the model, the transitions Activate, Freeze, Unfreeze and Retire (from Active and from Frozen) and no other, and the version token; each transition raises EnvironmentStateChanged with fromState, toState and the class of the environment; unit tests cover every transition, every rejected pair of states and the three invariants the aggregate enforces: a name is unique within a project (together with the unique index of AIFACTORY-TASK-012), a Frozen environment stays Frozen until it is unfrozen or retired, and every EnvironmentStateChanged announces the class of the environment beside its state (D117). The remaining invariant of the model, that a Production-class environment is not targeted by a run whose release is not Published, is not tested here, because the aggregate knows no run and no release state; RunControlService refuses such a run at submission (D117) and proves it in feature run-control-service. | ConnectSoft.AI.SoftwareFactory.EnvironmentService |
AIFACTORY-TASK-012 Persistence in environment-sql: Environments and EnvironmentConnections with the tenant filter and the unique name index |
migration | Mappings and migrations for the two modelled tables with the tenant column and row filter, the unique index on project and name and the row version as optimistic concurrency token; mapping tests run against an isolated test database, never a shared one. | ConnectSoft.AI.SoftwareFactory.EnvironmentService |
AIFACTORY-TASK-1670 CreateEnvironment with the project check, the idempotency key and the EnvironmentCreated outbox record |
implementation | The operation takes the tenant from the token and the project from the path, confirms the project through ProjectService (fail-fast), writes the Environment in state Draft and the EnvironmentCreated outbox record in one transaction and returns 201 with the location; the idempotent repeat, the 409 for a reused key with a different body and for a duplicate name, the 403 refusals, the 404 for a project that ProjectService reports as absent from the tenant of the token, the same for a foreign and an unknown project (ADR-0015 amendment D113), the failing ProjectService and an invalid body that writes no Environment and no outbox record are covered by acceptance tests. | ConnectSoft.AI.SoftwareFactory.EnvironmentService |
AIFACTORY-TASK-1671 Contract of EnvironmentCreated against the run event envelope of the contracts package |
contract | A golden file fixes EnvironmentCreated on the topic projects.environments.v1.environment-created under run-event-envelope-v1 with environmentId, projectId, tenantId and class and with tenant and project in the envelope; a contract test fails when the serialised event differs from the file or from docs/reference/schemas/run-event-envelope.schema.json, and the envelope type comes from the pinned contracts package. | ConnectSoft.AI.SoftwareFactory.EnvironmentService |
AIFACTORY-TASK-1672 Verify create-an-environment through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-EnvironmentService-001\|Scenario=SCN-EnvironmentService-006)"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-409, including the 404 of a Platform admin for a foreign and for an unknown project, the invalid body that writes nothing and the publication and payload of EnvironmentCreated; consumer handling is proven by the suites of the consumers. |
ConnectSoft.AI.SoftwareFactory.EnvironmentService |
AIFACTORY-US-410: List the environments of a project and return the policy class and state of one environment for a tool call¶
behavior · persona operator
As an operator, I want to see the environments of my project with their class and state, and tool calls to be judged by the class and state the service holds, so that nobody acts on an assumed class or on a freeze that was already lifted.
Two reads serve the two kinds of caller. A member of a project, a caller whose scope carries factory.projects.read, lists the environments of the project through the gateway route of EnvironmentService/ListEnvironments: the response is 200 with every environment of that project in the tenant of the caller, each with its name, class, state and region. The query runs under the tenant row filter and is bound to the project of the path, which is admitted only when the token grants it; environments of other projects and of other tenants never appear, and a project the token does not grant is refused with 403. A caller with the tenant-wide Platform admin role passes the scope chain for any projectId, so the service confirms the project through ProjectService as it does on creation: a projectId that does not exist in the tenant of the token or belongs to another tenant is answered 404, the same for the foreign and the unknown project, and when ProjectService is unavailable the read fails fast (ADR-0015 amendment D113); the model names this 404 in the code list of the operation (D117). A workload, ToolAdapterService before a tool call or PolicyEngineService when it raises the class of an action, asks for the class and the state of one environment through the internal gRPC method EnvironmentService/Environments.GetPolicyClass with an execution-scope-v1 that names the tenant, the project and the environment. The caller presents a workload token, which carries no tenant claim, so the service reads the tenant and project it forwards only when the token holds the service scope that names EnvironmentService (ADR-0015). The model names execution-scope-v1 as the request and as the reply descriptor of the method, and docs/reference/schemas/execution-scope.schema.json allows no additional property and has no field for an environment class or state, so the reply descriptor of the model cannot hold what the method exists to return. That conflict is an open point reported to the owner, and this PBI makes the reply checkable without deciding it: the proto reply message carries the scope fields tenantId, projectId and environmentId of the environment and beside them the fields class (EnvironmentClass) and state (EnvironmentState), and a contract test fixes the message by a golden file, so a later decision changes one message and one file. The class raises a shared-write against a Production environment to a production action, and the state lets the caller refuse a shared-write or production call against a Frozen environment. Both reads write nothing and answer from the committed state of environment-sql. Over gRPC a call without a workload identity is refused with UNAUTHENTICATED, a token without the service scope with PERMISSION_DENIED, a request without an environment with INVALID_ARGUMENT, and an environment that does not exist in the forwarded tenant with NOT_FOUND, which is also the answer for an environment of another tenant; an attempt that receives it takes the failure class permanent. Both callers treat this dependency as fail-fast: when the store is unavailable the method answers UNAVAILABLE and the caller does not guess a class.
Acceptance criteria
| AC1 | Given environments in two projects of one tenant and in another tenant, when a caller with factory.projects.read whose token grants the first project calls EnvironmentService/ListEnvironments for it, then the response is 200 with exactly the environments of that project, each with name, class, state and region, and nothing is written (SCN-EnvironmentService-002, ADR-0015). |
| AC2 | Given a caller without factory.projects.read, or a token that grants no role in the project of the path, when EnvironmentService/ListEnvironments is called, then the answer is 403 with a problem response that never confirms whether the project exists; given a caller with the tenant-wide Platform admin role and a projectId that does not exist in the tenant of the token or belongs to another tenant, when it is called, then the answer is 404, the same for the foreign and the unknown project (ADR-0015 amendment D113); in each case no state changes and nothing is published (SCN-EnvironmentService-002, ADR-0015). |
| AC3 | Given a Production environment in state Frozen and a workload token that holds the service scope, when EnvironmentService/Environments.GetPolicyClass is called with an execution-scope-v1 that names the tenant, the project and the environment, then the reply carries the fields class Production and state Frozen of the reply message fixed by the contract test, beside the scope fields of that environment, and a call after the environment was unfrozen carries state Active (SCN-EnvironmentService-005, FR-05). |
| AC4 | Given a caller without a workload identity, a token without the service scope, a request without an environment, an environment of another tenant or an unavailable store, when EnvironmentService/Environments.GetPolicyClass is called, then the call is refused with UNAUTHENTICATED, PERMISSION_DENIED, INVALID_ARGUMENT, NOT_FOUND or UNAVAILABLE respectively, the environment of another tenant is answered exactly as an unknown one, and no state changes (SCN-EnvironmentService-005, ADR-0015). |
| Traces: services | EnvironmentService |
| Traces: aggregates | EnvironmentService/Environment |
| Traces: apis | EnvironmentService/ListEnvironments, EnvironmentService/Environments.GetPolicyClass |
| Traces: descriptors | execution-scope-v1 |
| Traces: adrs | ADR-0015 |
| Traces: requirements | FR-01, FR-05, NFR-01 |
| Traces: scenarios | SCN-EnvironmentService-002, SCN-EnvironmentService-005 |
| Depends on | AIFACTORY-US-409, feature:component-base-template-factory-profile |
| Sources | model/services/control-plane/EnvironmentService.yaml, model/services/tools-mcp/ToolAdapterService.yaml, model/services/governance/PolicyEngineService.yaml, docs/reference/schemas/execution-scope.schema.json |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-1673 ListEnvironments read model bound to the tenant and the granted project |
implementation | ListEnvironments returns the environments of the project of the path with name, class, state and region under the tenant row filter, admits the project only when the token grants it and answers 403 otherwise; for a caller with the tenant-wide Platform admin role it confirms the project through ProjectService (fail-fast) and answers 404 for a project that is absent from the tenant of the token, the same for a foreign and an unknown project (ADR-0015 amendment D113); environments of other projects and tenants never appear. | ConnectSoft.AI.SoftwareFactory.EnvironmentService |
AIFACTORY-TASK-1674 Environments.GetPolicyClass with the workload scope check and the forwarded tenant |
implementation | Environments.GetPolicyClass reads the tenant, project and environment of execution-scope-v1 only under the service scope of the workload token and answers UNAUTHENTICATED, PERMISSION_DENIED, INVALID_ARGUMENT, NOT_FOUND (also for an environment of another tenant, ADR-0015) and UNAVAILABLE as the PBI states; the proto reply message carries the scope fields tenantId, projectId and environmentId and beside them the fields class (EnvironmentClass) and state (EnvironmentState) from the committed state; a contract test fixes the request and the reply message by a golden file, the one place to change when the owner decides how the reply relates to execution-scope-v1, whose schema has no field for a class or a state; the proto of the method is published with the service descriptor. | ConnectSoft.AI.SoftwareFactory.EnvironmentService |
AIFACTORY-TASK-1675 Verify the two reads through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-EnvironmentService-002\|Scenario=SCN-EnvironmentService-005)"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-410 over the two-tenant and two-project fixture, a Platform admin token for a foreign and for an unknown project, the golden file of the reply message, a workload token with and without the service scope and a stopped store. |
ConnectSoft.AI.SoftwareFactory.EnvironmentService |
AIFACTORY-US-411: Freeze an environment for an incident or a change freeze and lift the freeze¶
behavior · persona workspace-admin
As a workspace admin, I want to freeze an environment and to lift the freeze when the incident or the change window is over, so that gated work against the environment stops at once and resumes without a run being lost.
A freeze is the change-freeze or incident control of an environment. A caller whose scope carries factory.projects.admin and whose token grants the project of the environment freezes it through the gateway route of EnvironmentService/FreezeEnvironment: an Active environment moves to Frozen through the trigger Freeze, and the EnvironmentStateChanged outbox record with fromState Active, toState Frozen and the class of the environment (D117) is written in the same transaction; the response is 200 with the environment. EnvironmentService/UnfreezeEnvironment lifts it: a Frozen environment moves to Active through Unfreeze with its event in the same transaction; the invariant of the aggregate names a Workspace admin as the one who unfreezes, so UnfreezeEnvironment requires, beside the scope, the Workspace admin role for the project of the environment or the tenant-wide Platform admin role, and a caller that holds the scope with another role is answered 403. Both operations are of the production class and naturally idempotent: freezing an environment that is already Frozen, or unfreezing one that is already Active, returns 200, changes nothing and writes no second event. The gauge connectsoft.factory.environments.frozen rises by one with the dimensions tenant and class when an environment becomes Frozen and falls by one when it leaves Frozen, through Unfreeze here or through Retire in AIFACTORY-US-412. The service itself stops no run and no tool call: while the environment is Frozen, RunControlService holds the runs that target it and releases them when it is active again, and ToolAdapterService refuses shared-write and production calls that target it, each on the event and in its own PBI. The environment is addressed by environmentId. An environment that does not exist in the tenant of the caller is answered 404, which is also the answer for an environment of another tenant; a caller without the scope or without a role in the project of the environment is answered 403; an environment in a state that has no such transition, Draft or Retired, is answered 409, as is a call that loses the optimistic concurrency check against a concurrent change. A refused call changes nothing and publishes nothing.
Acceptance criteria
| AC1 | Given an Active environment and a caller with factory.projects.admin whose token grants its project, when EnvironmentService/FreezeEnvironment is called, then the response is 200, the EnvironmentService/Environment is Frozen, the EnvironmentService/EnvironmentStateChanged outbox record with fromState Active, toState Frozen and the class of the environment is written in the same transaction and connectsoft.factory.environments.frozen rises by one for its tenant and class (SCN-EnvironmentService-003, ADR-0014). |
| AC2 | Given a Frozen environment, when EnvironmentService/UnfreezeEnvironment is called with factory.projects.admin by a Workspace admin of the project of the environment, or by a Platform admin, then the response is 200, the environment is Active, the EnvironmentService/EnvironmentStateChanged outbox record with fromState Frozen, toState Active and the class of the environment is written in the same transaction and the gauge falls by one (SCN-EnvironmentService-004, ADR-0014). |
| AC3 | Given an environment already Frozen, when EnvironmentService/FreezeEnvironment is repeated, and an environment already Active, when EnvironmentService/UnfreezeEnvironment is repeated, then each answers 200, the state is unchanged and no second outbox record is written (SCN-EnvironmentService-003, SCN-EnvironmentService-004). |
| AC4 | Given a caller without the scope or without a role in the project of the environment, an environmentId of another tenant or one that does not exist, a Draft or Retired environment, or a concurrent change that wins the version check, when either operation is called, then the answer is 403 for the missing scope or role, 404 for the foreign or unknown environment and 409 for the state or version conflict; given a caller that holds the scope but neither the Workspace admin role for the project of the environment nor the Platform admin role, when EnvironmentService/UnfreezeEnvironment is called, then the answer is 403; each refusal carries a problem response, the state is unchanged and nothing is published (SCN-EnvironmentService-003, SCN-EnvironmentService-004, ADR-0015). |
| Traces: services | EnvironmentService |
| Traces: aggregates | EnvironmentService/Environment |
| Traces: apis | EnvironmentService/FreezeEnvironment, EnvironmentService/UnfreezeEnvironment |
| Traces: events | EnvironmentService/EnvironmentStateChanged |
| Traces: adrs | ADR-0014, ADR-0015 |
| Traces: requirements | FR-05, NFR-04 |
| Traces: scenarios | SCN-EnvironmentService-003, SCN-EnvironmentService-004 |
| Depends on | AIFACTORY-US-409, AIFACTORY-US-412, feature:component-base-template-factory-profile |
| Sources | model/services/control-plane/EnvironmentService.yaml, model/services/control-plane/RunControlService.yaml, docs/planes/control/services/environment-service/index.md#domain-model |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-1676 FreezeEnvironment and UnfreezeEnvironment with their transitions, the outbox record and the frozen gauge |
implementation | Both operations load the environment under the tenant row filter, apply the Freeze or Unfreeze transition of the aggregate with the version check, write EnvironmentStateChanged with fromState, toState and the class of the environment in the same transaction, move connectsoft.factory.environments.frozen with tenant and class, return 200 and the unchanged state on a natural repeat, and answer 403, 404 (also for an environment of another tenant, ADR-0015) and 409 as the PBI states; UnfreezeEnvironment admits, beside the scope, only the Workspace admin role for the project of the environment or the Platform admin role and answers 403 to any other role. | ConnectSoft.AI.SoftwareFactory.EnvironmentService |
AIFACTORY-TASK-1677 Verify freeze-and-unfreeze-an-environment through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-EnvironmentService-003\|Scenario=SCN-EnvironmentService-004)"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-411, including the natural repeat, the gauge, the two-tenant fixture, an unfreeze by a caller that holds the scope without the Workspace admin or Platform admin role and two concurrent calls. |
ConnectSoft.AI.SoftwareFactory.EnvironmentService |
AIFACTORY-US-412: Every state change of an environment is one modelled transition, announced once by EnvironmentStateChanged¶
behavior · persona operator
As an operator, I want every change of the state of an environment to follow the modelled transitions and to be announced once with its old and new state, so that Run Control, the tool boundary and the audit trail act on the same sequence of states the service committed.
The Environment aggregate has four states and five transitions: Draft to Active through Activate, Active to Frozen through Freeze, Frozen to Active through Unfreeze, and Active or Frozen to Retired through Retire. Retired is terminal, and Draft is where CreateEnvironment puts a new environment. The aggregate with exactly these transitions is built by AIFACTORY-TASK-011 of AIFACTORY-US-409, the first PBI that writes an Environment; this PBI delivers the commands that apply the transitions, the one event that announces a state change and the proof of the whole transition table. Every transition increments the version of the aggregate, is guarded by optimistic concurrency and writes one EnvironmentStateChanged record with environmentId, tenantId, fromState, toState and class, the policy class of the environment announced beside its state (D117), to the outbox in the same transaction as the state change, so publication is never the proof of a transition and a transition that rolls back leaves no event (ADR-0014). A request for a change the transition table does not hold, such as freezing a Draft environment or changing a Retired one, is rejected by the aggregate and changes nothing. Freeze and Unfreeze are reached through the REST operations of AIFACTORY-US-411. The model declares Activate and Retire as transitions and names no REST operation, command or handler that performs them, so this PBI delivers them as operations of the aggregate with their events and proves them at the level of the domain and the outbox; which caller performs them is an open point this PBI does not decide. The dispatcher of the environment messaging profile publishes the event on projects.environments.v1.environment-state-changed under the run event envelope of the contracts package with the tenant in the envelope, retries a transport outage with backoff and publishes each record once under its event id. The consumers act in their own PBIs: RunControlService holds the runs of a frozen environment, releases them when it is active again, fails every non-terminal run of a retired environment and keeps the announced state and, beside it, the announced class of the environment in its GateStates; ToolAdapterService refuses shared-write and production calls that target a Frozen environment; EnvironmentPromotionService gates promotions; StudioBff refreshes its view; AuditService records the change as evidence. A Retire from Frozen lowers connectsoft.factory.environments.frozen by one for the tenant and class of the environment. The aggregate of the model has four invariants. The service enforces three: names are unique within a project, a Frozen environment stays Frozen until it is unfrozen or retired, and every EnvironmentStateChanged announces the class of the environment beside its state (D117). The remaining one, that a Production-class environment cannot be targeted by a run whose release is not Published, cannot be enforced inside the aggregate, because the service knows no run and no release state. The service contributes the class: in the payload of EnvironmentStateChanged and of EnvironmentCreated, and through EnvironmentService/Environments.GetPolicyClass, which the model has PolicyEngineService call for class raising and ToolAdapterService call before a tool call. The refusal is made by RunControlService at submission, as its model states: it keeps the class that EnvironmentStateChanged announces beside the state of the environment in GateStates, and SubmitRun answers 409 with a problem body that names the gate when the run targets an environment of production class and its pinned release is not Published (D117). That refusal is proven by feature run-control-service and not here; this PBI proves that every state event carries the class. In the first increment every release is a seeded Draft, so a run of the first outcome that targets a Production-class environment meets this refusal.
Acceptance criteria
| AC1 | Given the EnvironmentService/Environment aggregate, when each of the five transitions of model/services/control-plane/EnvironmentService.yaml is applied from its source state (Activate from Draft, Freeze from Active, Unfreeze from Frozen, Retire from Active and from Frozen), then the state changes, the version increments and one EnvironmentService/EnvironmentStateChanged record with the matching fromState and toState and the class of the environment is written in the same transaction, and a Retire from Frozen lowers connectsoft.factory.environments.frozen by one for the tenant and class of the environment (SCN-EnvironmentService-007, ADR-0014). |
| AC2 | Given a pair of states that is not one of the five transitions, such as Draft to Frozen, Draft to Retired or Retired to Active, when the change is requested, then the aggregate rejects it, the state and the version are unchanged and no outbox record is written; given a transaction that rolls back after a transition, when the outbox is read, then neither the state change nor the record exists (SCN-EnvironmentService-007, ADR-0014). |
| AC3 | Given a committed transition, when the outbox dispatcher of the environment messaging profile publishes EnvironmentService/EnvironmentStateChanged on projects.environments.v1.environment-state-changed, then the event is sent under the run event envelope with environmentId, tenantId, fromState, toState and class and with the tenant in the envelope, so that the event of a Production environment states class Production on each of its transitions, and a transport outage is retried with backoff so the event is neither lost nor published twice under its event id (SCN-EnvironmentService-007, ADR-0012). |
| AC4 | Given two concurrent transitions of one environment, when both commit, then one succeeds and the other fails the version check and writes nothing, so the sequence of EnvironmentService/EnvironmentStateChanged records of an environment is the sequence of its committed states (SCN-EnvironmentService-007, model/services/control-plane/EnvironmentService.yaml). |
| Traces: services | EnvironmentService |
| Traces: aggregates | EnvironmentService/Environment |
| Traces: events | EnvironmentService/EnvironmentStateChanged |
| Traces: descriptors | run-event-envelope-v1 |
| Traces: adrs | ADR-0012, ADR-0014 |
| Traces: requirements | NFR-04 |
| Traces: scenarios | SCN-EnvironmentService-007 |
| Depends on | AIFACTORY-US-409, feature:contracts-package, feature:component-base-template-factory-profile |
| Sources | model/services/control-plane/EnvironmentService.yaml, model/services/control-plane/RunControlService.yaml, docs/planes/control/services/environment-service/index.md#domain-model, docs/reference/schemas/run-event-envelope.schema.json |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-1701 Transition commands Activate and Retire with the outbox record of every transition and the frozen gauge |
implementation | The application layer applies Activate and Retire as commands on the aggregate of AIFACTORY-TASK-011 under the tenant row filter and the version check, writes one EnvironmentStateChanged outbox record with fromState, toState and the class of the environment per committed transition in the same transaction, lowers connectsoft.factory.environments.frozen by one for tenant and class when Retire leaves Frozen, and hosts no REST route for the two commands, since the model names none; a rejected pair of states and a transaction that rolls back write no record. | ConnectSoft.AI.SoftwareFactory.EnvironmentService |
AIFACTORY-TASK-1678 Contract of EnvironmentStateChanged against the run event envelope of the contracts package |
contract | A golden file fixes EnvironmentStateChanged on the topic projects.environments.v1.environment-state-changed under run-event-envelope-v1 with environmentId, tenantId, fromState, toState and class (D117) and with the tenant in the envelope, once per transition; a contract test fails when the serialised event differs from the file or from docs/reference/schemas/run-event-envelope.schema.json. | ConnectSoft.AI.SoftwareFactory.EnvironmentService |
AIFACTORY-TASK-1679 Verify the state machine and the publication of EnvironmentStateChanged |
verification | Run dotnet test -c Release --filter "Category=Acceptance&Scenario=SCN-EnvironmentService-007" and the unit tests of the aggregate; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-412: the five transitions with their records, the class of the environment in every record, the gauge after a Retire from Frozen, the rejected pairs, the rollback, the dispatch with a stopped transport and two concurrent transitions; consumer handling is proven by the suites of the consumers. |
ConnectSoft.AI.SoftwareFactory.EnvironmentService |
AIFACTORY-US-413: EnvironmentService handles once and inside the tenant what other services announce about an environment¶
behavior · persona platform-admin
As a platform admin, I want every event another service announces about an environment handled once and inside its tenant, and no handler registered before the increment that can prove it, so that a publisher of a later increment is served by the handlers built here, and a deletion order is executed and acknowledged only where the service that issues it exists.
The model lists seven consumed events of EnvironmentService, and every one of them is published by a service of a later increment. EnvironmentPromotionService announces PromotionCompleted and RollbackCompleted, for which the handler RecordCurrentRelease records the release now running in the environment or the restored one. IaCProvisioningService announces ProvisioningApplied, for which RecordProvisionedState records the outputs of the applied provisioning on the environment. RuntimeEnvironmentService announces ObservedStateChanged, for which RecordObservedHealth keeps the last observed health of the environment. RetentionResidencyService announces RetentionRuleChanged, DeletionOrderIssued and LegalHoldChanged. For the first and the third, ApplyRetentionRule and ApplyLegalHold apply the retention period to the records the service owns and suspend or resume deletion and retention expiry for a held scope. The second is not handled in this increment (D119). The model gives its handler ExecuteDeletionOrder two duties, to delete the ordered scope from environment-sql and to acknowledge the order with a receipt through the operation AcknowledgeOrderTask of RetentionResidencyService, and it assigns that handler to I4: it is built and proven there together with RetentionResidencyService, the service that issues the order and receives the acknowledgement. This feature therefore registers no subscription and no handler for DeletionOrderIssued, builds no client of the acknowledgement operation and proves nothing against a fake of it. No governance order is left waiting by that, because before I4 no service exists that could issue one. What stays observable here is that nothing deletes an environment: the two retention handlers record the effective retention period and the hold for the rows of the tenant of the envelope and remove no row, so ListEnvironments keeps returning every environment of a project and Environments.GetPolicyClass keeps answering for each; the period and the hold they record are what ExecuteDeletionOrder reads when it arrives. The service registers the six subscriptions of this increment in the OrleansMessaging section of its own messaging profile with the service name environment. Its inbox deduplicates each delivery on the event id, and each handler reads the tenant from the envelope and never from the payload: a message without a tenant is not handled and goes to the poison handling of the profile, and a message for an environment that does not exist in that tenant is acknowledged without effect. A handler that fails is retried with backoff and poisoned at the attempt limit of the profile. The handlers are proven against contract fixtures of the six events built from the model, since no publisher exists yet; the publishers prove their side in their own features. The gateway consumes none of these events (ADR-0028 amendment on gateways and events). The Environment aggregate of the model has no field for the current release, the provisioned outputs or the observed health, so where the three recording handlers keep what they record is an open point this PBI does not decide: it delivers the subscriptions, the idempotent inbox, the tenant guard and the two retention handlers, and the recording follows the model once it names the fields; until then RecordCurrentRelease, RecordProvisionedState and RecordObservedHealth acknowledge their deliveries, leave the inbox record of the event id and change no row. The failure mode of the model stands: when the provisioning reconciler sends no observed state, the environment keeps its desired references and reconciliation resumes later.
Acceptance criteria
| AC1 | Given the messaging profile of the service, when it starts, then the OrleansMessaging section declares one subscription with its handler for each of the six consumed events this increment handles, that is every consumed event of model/services/control-plane/EnvironmentService.yaml except DeletionOrderIssued, whose handler the model assigns to I4 with RetentionResidencyService (D119), it declares none for that event, startup fails when a consumed event listed in the service descriptor file of the repository has no subscription, and ControlPlaneApi subscribes to none of them (ADR-0028). |
| AC2 | Given a contract fixture of each of the six handled events under the run event envelope, when it is delivered twice with the same event id, then the inbox holds exactly one record of that event id, which is the proof of a handled delivery, the effect of the handler exists once and the second delivery is acknowledged without effect; RecordCurrentRelease, RecordProvisionedState and RecordObservedHealth acknowledge their deliveries and change no row until the model names the fields they record; given a fixture without a tenant in the envelope, when it is delivered, then it is not handled, leaves no handled inbox record and is poisoned with its reason (ADR-0014, ADR-0012). |
| AC3 | Given a RetentionRuleChanged fixture and a LegalHoldChanged fixture for a scope that holds environments of one tenant, when both are handled, then the effective retention period and the hold are recorded once per event id for the rows of that tenant, rows of another tenant are never touched and no row is deleted, so EnvironmentService/ListEnvironments still returns every environment of the scope and EnvironmentService/Environments.GetPolicyClass still answers for each; and given a DeletionOrderIssued message published on its topic, then the service holds no subscription for it, so nothing is handled, deleted or acknowledged in this increment, the handler ExecuteDeletionOrder with its deletion and its acknowledgement through AcknowledgeOrderTask being delivered and proven in I4 with RetentionResidencyService (D119, ADR-0015, model/services/control-plane/EnvironmentService.yaml). |
| AC4 | Given a handler that throws, when the delivery is retried, then it is retried with backoff and poisoned for this subscriber at the attempt limit of the profile, the other subscriptions keep delivering, and the EnvironmentService/Environment rows are unchanged by the failed deliveries (ADR-0012). |
| Traces: services | EnvironmentService |
| Traces: aggregates | EnvironmentService/Environment |
| Traces: apis | EnvironmentService/ListEnvironments, EnvironmentService/Environments.GetPolicyClass |
| Traces: adrs | ADR-0012, ADR-0014, ADR-0015, ADR-0028 |
| Depends on | AIFACTORY-US-409, AIFACTORY-US-410, feature:contracts-package, feature:component-base-template-factory-profile |
| Sources | model/services/control-plane/EnvironmentService.yaml, model/services/data-event/RetentionResidencyService.yaml, docs/planes/control/services/environment-service/index.md#messages, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-014 Messaging wiring of the environment profile: outbox for 2 published events and inbox subscriptions for 6 of the 7 consumed events |
implementation | The OrleansMessaging section declares the service name environment, the two published events EnvironmentCreated and EnvironmentStateChanged with their topics and the six subscriptions this increment handles with their handlers, and none for DeletionOrderIssued, whose handler is delivered in I4 with RetentionResidencyService (D119); the outbox writer enlists in the unit of work of each command, the inbox deduplicates on the event id and each handler reads the tenant from the run event envelope and refuses a message without one. | ConnectSoft.AI.SoftwareFactory.EnvironmentService |
AIFACTORY-TASK-1680 Contract fixtures of the six consumed events this increment handles, built from the model |
fixture | The acceptance suite holds one fixture per consumed event of model/services/control-plane/EnvironmentService.yaml that this increment handles, that is every one except DeletionOrderIssued, under run-event-envelope-v1 with the payload fields its producer declares in the model, a duplicate of each with the same event id and a variant without a tenant in the envelope; it holds no fake of the acknowledgement operation of RetentionResidencyService, because the deletion order and its acknowledgement are proven in I4 against the service itself (D119). | ConnectSoft.AI.SoftwareFactory.EnvironmentService |
AIFACTORY-TASK-1681 Retention handlers: ApplyRetentionRule and ApplyLegalHold over the rows the service owns |
implementation | The two handlers apply the effective retention period to the rows of environment-sql and suspend or resume deletion and retention expiry for a held scope, inside the tenant of the envelope; each is idempotent on the event id, never touches rows of another tenant and deletes no row. ExecuteDeletionOrder is not built here: the deletion of an ordered scope and the acknowledgement of the order through AcknowledgeOrderTask of model/services/data-event/RetentionResidencyService.yaml are delivered and proven in I4 with RetentionResidencyService (D119), and until then the service registers no subscription for DeletionOrderIssued and holds no client of the acknowledgement operation. | ConnectSoft.AI.SoftwareFactory.EnvironmentService |
AIFACTORY-TASK-1682 Verify the inbox handlers against the contract fixtures |
verification | Run dotnet test -c Release --filter "Category=Acceptance&Feature=InboxHandlers"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-413: the six subscriptions of this increment out of the seven consumed events of model/services/control-plane/EnvironmentService.yaml and none for DeletionOrderIssued, the duplicate delivery with its one inbox record, the three recording handlers that change no row, the message without a tenant, the retention rule and the legal hold recorded once inside the tenant with no environment deleted and both reads unchanged, a DeletionOrderIssued message that is neither handled nor acknowledged, and the poisoned delivery. |
ConnectSoft.AI.SoftwareFactory.EnvironmentService |