AIFACTORY-FEAT-050: RuntimeEnvironmentService: 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 Runtime Cloud (PF-09) · Increment I2 Deliver it · State elaborated · Route backend-developer · Build order 101 of 185 (Factory code)
RuntimeEnvironmentService is the service of bounded context BC-25 (Provisioning & Reconciliation). The inventory of what actually runs where — workloads, versions, replicas, configuration and secret bindings by reference, endpoints — observed from the clusters and cloud APIs, compared with the declared specification to produce drift findings, and turned into reviewable reconciliation proposals, never automatic writes (BC-25; drift detection and runtime service catalog rows merged). Its own repository is ConnectSoft.AI.SoftwareFactory.RuntimeEnvironmentService.
| Delivers | RuntimeEnvironmentService (complete) |
| Stubs | — |
| Realizes | adrs: ADR-0004 |
| Requirements | FR-09, FUX-05, NFR-06, NFR-09, XL-10, XL-14 |
| Depends on | — |
| Sources | model/services/runtime-cloud/RuntimeEnvironmentService.yaml |
Scenarios to trace (10, catalog): SCN-RuntimeEnvironmentService-001 ✓, SCN-RuntimeEnvironmentService-002 ✓, SCN-RuntimeEnvironmentService-003 ✓, SCN-RuntimeEnvironmentService-004 ✓, SCN-RuntimeEnvironmentService-005 ✓, SCN-RuntimeEnvironmentService-006 ✓, SCN-RuntimeEnvironmentService-007 ✓, SCN-RuntimeEnvironmentService-008 ✓, SCN-RuntimeEnvironmentService-009 ✓, SCN-RuntimeEnvironmentService-010 ✓
AIFACTORY-US-026: RuntimeEnvironmentService shows what runs where and turns drift into a reviewable proposal end to end¶
behavior · persona operator
As an operator, I want an inventory of what actually runs in each environment and a finding when it differs from the declared state, so that I act on observed facts, and a difference is corrected by a decision, never silently.
This is the integration PBI of RuntimeEnvironmentService in the bounded context Provisioning and Reconciliation (BC-25). The service keeps the inventory of what actually runs in each environment, the workloads with their versions, replicas, endpoints, health and configuration and secret bindings by reference, observed from the clusters and cloud APIs through the IaC runner (ADR-0004); it compares each observation with the declared specification of IaCProvisioningService, records the differences as drift findings and groups them into reviewable reconciliation proposals, and it never writes to infrastructure itself: an accepted proposal is handed to IaCProvisioningService as an event and becomes a provisioning run there. The repository ConnectSoft.AI.SoftwareFactory.RuntimeEnvironmentService is created by the first task of this feature by the steps of the repository checklist of feature repository-and-pipeline-conventions: it is scaffolded once from the pinned base template package with UseFactoryProfile (features component-base-template-factory-profile and component-base-template-findings, consumed by pin), so token validation, the role policies, the scope chain with its 401, 403 and 404 answers, the tenant row filter, the Orleans messaging profile with the service name runtime-environment, the scheduler, health and the telemetry wiring come from the profile. Every integration event is written as the run event envelope of the pinned contracts package to the Orleans outbox in the transaction of its command (ADR-0014). The public REST operations are reached through RuntimeCloudHost, which forwards the user token unchanged; the service accepts the audience of its own gateway (ADR-0015 amendment D117). A resource of another tenant is answered 404, over gRPC NOT_FOUND, the same answer as for an unknown identifier, and a missing scope or project role inside the tenant 403 (ADR-0015 amendment D113). The environment routes name the environment in the path and the proposal routes name the proposal, never a project: the service checks the role of the caller in the project of the environment, and the list of proposals returns the rows of the projects in which the token holds a role, every project of the tenant for a Platform admin. The feature is delivered by five further PBIs: observing an environment (AIFACTORY-US-1077), reading the inventory and the drift (AIFACTORY-US-1078), detecting drift (AIFACTORY-US-1079), raising and listing proposals (AIFACTORY-US-1080) and deciding a proposal (AIFACTORY-US-1081). Secret bindings are references; a secret value never enters the inventory, a finding, an event, a log record or telemetry. The inbox registers the four consumed events of the model, SpecificationDeclared, ProvisioningApplied and ProvisioningFailed of IaCProvisioningService and EnvironmentCreated of EnvironmentService; the feature builds and registers no handler of a deletion order, which is built in I4 with RetentionResidencyService. Telemetry carries tenant and project on metrics by default and run, step and attempt on activities and log records where the work has them, and no observed configuration content reaches telemetry by default (ADR-0019).
Acceptance criteria
| AC1 | Given the repository ConnectSoft.AI.SoftwareFactory.RuntimeEnvironmentService created by the steps of the repository checklist, whose first commit is the unchanged output of dotnet new connectsoft-base -n ConnectSoft.AI.SoftwareFactory.RuntimeEnvironmentService --UseFactoryProfile true from the pinned template package, when its pipeline runs with the work of this feature, then no second scaffold was run, the solution builds, the unit and acceptance tests pass with complete reports and a container image is published (ADR-0028, model/services/runtime-cloud/RuntimeEnvironmentService.yaml). |
| AC2 | Given the service descriptor of the repository, when the contract test compares it with the hosted surface, then RuntimeEnvironmentService/GetRuntimeInventory, RuntimeEnvironmentService/ListDrift, RuntimeEnvironmentService/ObserveEnvironment, RuntimeEnvironmentService/ListReconciliationProposals, RuntimeEnvironmentService/DecideReconciliation and RuntimeEnvironmentService/Inventory.GetObservedState are hosted with the scope, side-effect class, idempotency and response codes of model/services/runtime-cloud/RuntimeEnvironmentService.yaml, and the test fails on an operation the file does not name. |
| AC3 | Given inventories and proposals of two tenants and a caller of one, when an operation addresses an environment or a proposal 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 of the environment, then 403; given no token, then 401; in no case a state changes; a user token that RuntimeCloudHost forwards unchanged is accepted without a token exchange (ADR-0015). |
| AC4 | Given the outbox and the inbox of the service after the acceptance suite, when their records are read, then RuntimeEnvironmentService/ObservedStateChanged, RuntimeEnvironmentService/RuntimeDriftDetected, RuntimeEnvironmentService/ReconciliationProposed and RuntimeEnvironmentService/ReconciliationDecided are the only event types the outbox holds, each written in the transaction of its command under the run event envelope, and the inbox registers the four consumed events and no handler of a deletion order (ADR-0014). |
| AC5 | Given the service starts, when liveness and readiness are probed and the acceptance suite has run, then readiness is unready until runtime-environment-sql is migrated and while the outbox check of the messaging profile is unhealthy, the four metrics of the model are emitted with tenant and project from the instrument helper, and a scan of the captured log records, activities, metrics, events and stored rows finds no secret value (ADR-0019, model/services/runtime-cloud/RuntimeEnvironmentService.yaml). |
| Traces: services | RuntimeEnvironmentService, IaCProvisioningService, EnvironmentService, RuntimeCloudHost, PolicyEngineService |
| Traces: aggregates | RuntimeEnvironmentService/RuntimeInventory, RuntimeEnvironmentService/DriftFinding, RuntimeEnvironmentService/ReconciliationProposal |
| Traces: apis | RuntimeEnvironmentService/GetRuntimeInventory, RuntimeEnvironmentService/ListDrift, RuntimeEnvironmentService/ObserveEnvironment, RuntimeEnvironmentService/ListReconciliationProposals, RuntimeEnvironmentService/DecideReconciliation, RuntimeEnvironmentService/Inventory.GetObservedState |
| Traces: events | RuntimeEnvironmentService/ObservedStateChanged, RuntimeEnvironmentService/RuntimeDriftDetected, RuntimeEnvironmentService/ReconciliationProposed, RuntimeEnvironmentService/ReconciliationDecided |
| Traces: descriptors | run-event-envelope-v1 |
| Traces: adrs | ADR-0004, ADR-0014, ADR-0015, ADR-0019, ADR-0028 |
| Traces: requirements | FR-09, NFR-06, NFR-09, XL-10 |
| Relates: screens | inventory |
| Depends on | AIFACTORY-US-1077, AIFACTORY-US-1078, AIFACTORY-US-1079, AIFACTORY-US-1080, AIFACTORY-US-1081, feature:repository-and-pipeline-conventions, feature:component-base-template-factory-profile, feature:component-base-template-findings, feature:component-extensions-ai, feature:component-observability-factory-conventions, feature:contracts-package |
| Sources | model/services/runtime-cloud/RuntimeEnvironmentService.yaml, docs/planes/execution/environments/services/runtime-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-298 Create the repository ConnectSoft.AI.SoftwareFactory.RuntimeEnvironmentService and scaffold it from the ConnectSoft.BaseTemplate template with the Factory profile |
implementation | The repository exists, created by the steps of the repository checklist of feature repository-and-pipeline-conventions; its first commit is the unchanged output of dotnet new connectsoft-base -n ConnectSoft.AI.SoftwareFactory.RuntimeEnvironmentService --UseFactoryProfile true from the pinned template package, whose version the repository records, with the messaging service name runtime-environment; the solution builds and the template tests pass in the repository pipeline, which publishes the container image. |
ConnectSoft.AI.SoftwareFactory.RuntimeEnvironmentService |
AIFACTORY-TASK-299 Domain model: RuntimeInventory, DriftFinding and ReconciliationProposal with the four transitions of ProposalState |
implementation | The RuntimeInventory aggregate holds its observed workloads with bindings as references only and its staleness; the DriftFinding aggregate is resolved only by a re-observation that no longer shows it, never by hand; the ReconciliationProposal aggregate holds the transitions Proposed to Accepted, Proposed to Rejected, Accepted to Applied and Proposed to Superseded and no other, and never writes to infrastructure; unit tests cover every transition, every rejected pair of states and every invariant of model/services/runtime-cloud/RuntimeEnvironmentService.yaml. | ConnectSoft.AI.SoftwareFactory.RuntimeEnvironmentService |
AIFACTORY-TASK-300 Persistence in runtime-environment-sql: RuntimeInventories, ObservedWorkloads, DriftFindings, ReconciliationProposals |
migration | Mappings and migrations for the four modelled tables with the tenant column and row filter, the indexes IX_Drift_Env_Open and IX_Reconcile_Env_State and a row version as optimistic concurrency token on a proposal; mapping tests run against an isolated test database, never a shared one. | ConnectSoft.AI.SoftwareFactory.RuntimeEnvironmentService |
AIFACTORY-TASK-301 API hosting skeleton: service descriptor, REST and gRPC hosts, scope policies and problem responses of the 5 REST and 1 gRPC operations |
contract | The service descriptor file lists GetRuntimeInventory, ListDrift, ObserveEnvironment, ListReconciliationProposals, DecideReconciliation and Inventory.GetObservedState with scope, side-effect class, idempotency and response codes; the five REST routes and the gRPC method are hosted with the scope policy of each route, problem responses for every modelled refusal code and the workload scope check of the gRPC method; the behaviour of each operation is delivered by AIFACTORY-US-1077, AIFACTORY-US-1078, AIFACTORY-US-1080 and AIFACTORY-US-1081, not here. | ConnectSoft.AI.SoftwareFactory.RuntimeEnvironmentService |
AIFACTORY-TASK-302 Messaging skeleton: outbox and inbox wiring of the runtime-environment profile for 4 published and 4 consumed events |
implementation | The outbox writer enlists in the unit of work of a command, a handler and a worker step, and the dispatcher of the runtime-environment messaging profile publishes ObservedStateChanged, RuntimeDriftDetected, ReconciliationProposed and ReconciliationDecided under the run event envelope of the pinned contracts package; the inbox registers SpecificationDeclared, ProvisioningApplied, ProvisioningFailed and EnvironmentCreated with idempotency on the event id and no handler of a deletion order; what each handler does is delivered by AIFACTORY-US-1077, AIFACTORY-US-1079 and AIFACTORY-US-1081. | ConnectSoft.AI.SoftwareFactory.RuntimeEnvironmentService |
AIFACTORY-TASK-303 Worker hosting skeleton: triggers, partitioning and retry policies of Observer and DriftComparer |
implementation | The Observer is hosted on its schedule with the key of environment and observation window and the DriftComparer on ObservedStateChanged with the key of environment and observation time, each with its fixed retry policy and partitioned by environment; a duplicate trigger has no second effect; what each worker does is delivered by AIFACTORY-US-1077 and AIFACTORY-US-1079. | ConnectSoft.AI.SoftwareFactory.RuntimeEnvironmentService |
AIFACTORY-TASK-304 Security, tenancy and telemetry of RuntimeEnvironmentService |
implementation | The scopes factory.runtime.read and factory.runtime.operate and the roles Operator, Platform admin, Workspace admin and Observer are enforced per route; a user token forwarded by RuntimeCloudHost is accepted with the audience of that gateway; every query is tenant-filtered so a resource of another tenant is answered 404; the messaging-transport secret comes from a secret reference of the key vault; environments_stale, drift_open, reconciliation_proposals and inbox_lag are created through the instrument helper of the observability library with tenant and project; a redaction test fails when a log record, an activity or a metric holds a secret value or observed configuration content. | ConnectSoft.AI.SoftwareFactory.RuntimeEnvironmentService |
AIFACTORY-TASK-785 Verify observed-state-and-drift 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-026, that is the scaffold, the hosted surface against the service descriptor, the two-tenant matrix with its 404, 403 and 401 answers, the event types of the outbox and the inbox, readiness and the redaction scan. |
ConnectSoft.AI.SoftwareFactory.RuntimeEnvironmentService |
AIFACTORY-US-1077: Observe an environment on a schedule, after an apply or on request, keep its inventory and mark it stale when it cannot be observed¶
behavior · persona operator
As an operator, I want the inventory of an environment refreshed on a schedule, right after every apply and when I ask for it, so that what I read is observed, never assumed, and an environment that cannot be reached shows as stale.
The Observer reads the clusters and cloud APIs of every environment in scope on its schedule through the IaC runner and updates the RuntimeInventory of the environment: every workload with its kind, image or package version, ready and desired replicas, endpoints, configuration and secret bindings by reference and health, the current release and the observation time. When the observation changed something, versions, replicas, health, release or staleness, ObservedStateChanged is written to the outbox in the same transaction with environmentId, tenantId, projectId, currentReleaseId, changes and stale; an observation that changed nothing writes no event. Secret bindings are references and a value never enters the inventory or changes. The service holds no credential of a cloud account; the model gives it no dependency on SecretBrokerService, so how the runner reads a cloud account for an observation is reported to the owner. A caller whose scope carries factory.runtime.operate and whose role in the project of the environment is Operator or a role above it in the role order of ADR-0015 amendment D114, Workspace admin or Platform admin, triggers an observation now through ObserveEnvironment; the answer is 202 and the observation runs under the key of the environment and the observation window, so a second call in the same window joins the pending observation and starts no second one. An environment of another tenant is answered 404, the same answer as for an environment without an inventory (ADR-0015 amendment D113); a caller without the scope, or whose role in the project of the environment is only one below Operator or not comparable with it, Observer, Requester, Reviewer or Asset maintainer, is refused with 403. Three consumed events drive the inventory too, each idempotent on the event id: EnvironmentCreated of EnvironmentService opens the inventory of the new environment with no workloads, stale until its first observation (TrackDeclared); ProvisioningApplied of IaCProvisioningService records the applied specificationVersion and re-observes the environment at once (ObserveAfterApply); ProvisioningFailed re-observes at once to capture the partial state of the failed apply (ObserveAfterFailure). When the cluster or cloud API cannot be reached, the observation fails after its fixed retry, the last observed state is kept and its observation time is not refreshed, no finding is raised from the failed observation, and an environment whose last successful observation is older than the window of the option RuntimeCloud:Inventory:StalenessMinutes is marked stale, announced by ObservedStateChanged with stale true and counted in connectsoft.factory.runtime.environments_stale; the alert rule on that signal belongs to AlertRuleService in its own increment. ObservedStateChanged is the input of EnvironmentService, EnvironmentPromotionService, FleetInventoryService, SloService, StudioBff and DashboardService, each in its own increment and PBIs; this PBI proves what the publisher can prove.
Acceptance criteria
| AC1 | Given an environment whose fake cluster reports a new version of one workload, when the Observer observes it, then the RuntimeEnvironmentService/RuntimeInventory holds every workload with version, replicas, endpoints, health and bindings as references, and the RuntimeEnvironmentService/ObservedStateChanged outbox record is written in the same transaction; a second observation without a change writes no record (SCN-RuntimeEnvironmentService-007, ADR-0014). |
| AC2 | Given an observed environment, when the dispatcher of the runtime-environment messaging profile publishes RuntimeEnvironmentService/ObservedStateChanged on provisioning.inventory.v1.observed-state-changed, then it is sent under the run event envelope with environmentId, tenantId, projectId, currentReleaseId, changes and stale, no secret value is in it, and a transport outage is retried with backoff so the event is neither lost nor published twice under its event id (SCN-RuntimeEnvironmentService-007, ADR-0012). |
| AC3 | Given a caller with factory.runtime.operate and the Operator role in the project of an environment, when RuntimeEnvironmentService/ObserveEnvironment is called twice in one observation window, then both answers are 202 and one observation runs, and a Workspace admin and a Platform admin are admitted alike; given a caller without the scope, a caller whose only role in the project is Observer or Reviewer, an environment of another tenant and an unknown environment, then the answers are 403, 403, 404 and 404, each with a problem response and no observation (SCN-RuntimeEnvironmentService-003, ADR-0015). |
| AC4 | Given a fake cluster that stops answering, when observations fail past the staleness window, then no finding is raised, the last observed workloads are kept, the inventory is marked stale and RuntimeEnvironmentService/ObservedStateChanged announces stale true once (SCN-RuntimeEnvironmentService-007, model/services/runtime-cloud/RuntimeEnvironmentService.yaml). |
| AC5 | Given fixture events EnvironmentService/EnvironmentCreated, IaCProvisioningService/ProvisioningApplied and IaCProvisioningService/ProvisioningFailed, when they are handled, then the first opens an inventory with no workloads that is stale until observed, the second records the applied specificationVersion and observes at once, the third observes at once, and each event delivered again changes nothing (model/services/runtime-cloud/RuntimeEnvironmentService.yaml). |
| Traces: services | RuntimeEnvironmentService, EnvironmentService, IaCProvisioningService |
| Traces: aggregates | RuntimeEnvironmentService/RuntimeInventory |
| Traces: apis | RuntimeEnvironmentService/ObserveEnvironment |
| Traces: events | RuntimeEnvironmentService/ObservedStateChanged, EnvironmentService/EnvironmentCreated, IaCProvisioningService/ProvisioningApplied, IaCProvisioningService/ProvisioningFailed |
| Traces: descriptors | run-event-envelope-v1 |
| Traces: adrs | ADR-0004, ADR-0012, ADR-0014, ADR-0015 |
| Traces: requirements | FR-09, NFR-06 |
| Traces: scenarios | SCN-RuntimeEnvironmentService-003, SCN-RuntimeEnvironmentService-007 |
| Relates: screens | inventory |
| Depends on | feature:ia-cprovisioning-service, feature:environment-service, feature:contracts-package, feature:component-base-template-factory-profile |
| Sources | model/services/runtime-cloud/RuntimeEnvironmentService.yaml, docs/planes/execution/environments/services/runtime-environment-service/index.md#workers-and-jobs, docs/planes/execution/environments/services/runtime-environment-service/index.md#failure-and-recovery |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-330 Observer and inventory with staleness |
implementation | The Observer reads the cluster and cloud APIs of each environment through the IaC runner under the key of environment and observation window, stores the workloads with bindings as references, writes ObservedStateChanged only when something changed, keeps the last state and raises no finding when an observation fails, and marks an environment stale once its last successful observation is older than the window of RuntimeCloud:Inventory:StalenessMinutes. | ConnectSoft.AI.SoftwareFactory.RuntimeEnvironmentService |
AIFACTORY-TASK-4329 ObserveEnvironment and the handlers of EnvironmentCreated, ProvisioningApplied and ProvisioningFailed |
implementation | ObserveEnvironment admits the Operator role and the roles above it in the order of D114, Workspace admin and Platform admin, answers 202 and joins the observation of the current window, 404 for an environment of another tenant or without an inventory and 403 for a missing scope or a project role below Operator or not comparable with it; TrackDeclared on EnvironmentCreated opens an empty stale inventory, ObserveAfterApply records the applied specificationVersion and observes at once, ObserveAfterFailure observes at once; each handler is idempotent on the event id and takes its event type from the pinned contracts package. | ConnectSoft.AI.SoftwareFactory.RuntimeEnvironmentService |
AIFACTORY-TASK-4330 Fake cluster, contract of ObservedStateChanged and the fixture events of the observation suite |
fixture | The acceptance suite holds a fake cluster and cloud API behind the runner port that reports configured workloads, versions, replicas and health and can stop answering, fixture events EnvironmentCreated, ProvisioningApplied and ProvisioningFailed under the run event envelope, and a golden file that fixes ObservedStateChanged on provisioning.inventory.v1.observed-state-changed with the payload of model/services/runtime-cloud/RuntimeEnvironmentService.yaml. | ConnectSoft.AI.SoftwareFactory.RuntimeEnvironmentService |
AIFACTORY-TASK-4331 Verify observe-an-environment through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-RuntimeEnvironmentService-003\|Scenario=SCN-RuntimeEnvironmentService-007)"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-1077, including the observation joined within one window, the stale marking without findings and the publication and payload of ObservedStateChanged; consumer handling is proven by the suites of the consumers. |
ConnectSoft.AI.SoftwareFactory.RuntimeEnvironmentService |
AIFACTORY-US-1078: Read the runtime inventory and the drift of an environment, and serve the observed state to the services that verify and inventory¶
behavior · persona operator
As an operator, I want to read what runs in an environment with its staleness and the drift found there, so that I judge an environment by what was observed and when, never by what was declared.
An Operator, a Workspace admin, a Platform admin or an Observer whose scope carries factory.runtime.read reads the inventory of an environment through GetRuntimeInventory and receives its observed workloads with kind, version, ready and desired replicas, endpoints, health and configuration and secret bindings as references, the current release, the specification version last applied, the observation time and whether the inventory is stale. The same caller lists the drift findings of the environment through ListDrift, open and resolved, each with its kind, resource, declared and observed values, detection time, resolution time and the proposal it belongs to; declared and observed values of a secret binding are references, never values. An environment of another tenant is answered 404, the same answer as for an unknown environment (ADR-0015 amendment D113); a caller without the scope, or without a role in the project of the environment, is refused with 403; both reads write nothing. A workload calls the internal Inventory.GetObservedState with execution-scope-v1 naming the tenant, the project and the environment and receives the observed state of the environment, its workloads, current release, applied specification version, observation time and staleness; EnvironmentPromotionService reads it in this increment for promotion verification, and FleetInventoryService in its own increment. The token must be a workload token holding the service scope the method names, and the forwarded tenant and project are read only under it (ADR-0015 amendment D114); a call without workload identity is answered UNAUTHENTICATED, a token without the scope PERMISSION_DENIED, a request that fails validation INVALID_ARGUMENT, and an environment of another tenant NOT_FOUND, as for an unknown environment. A stale inventory is answered with stale true and never as fresh. The method is a read and writes nothing. The model names ack-v1 as its reply, a descriptor without a member for an observed state; the proto carries the reply in the shape of that schema and adds the observed state beside it, and a contract test states the difference, reported as a correction of the descriptor row of the model.
Acceptance criteria
| AC1 | Given an observed environment and a caller with factory.runtime.read and a role in its project, when RuntimeEnvironmentService/GetRuntimeInventory is called, then the response is 200 with every workload of the RuntimeEnvironmentService/RuntimeInventory, its bindings as references, the current release, the applied specification version, the observation time and the staleness (SCN-RuntimeEnvironmentService-001). |
| AC2 | Given open and resolved findings of an environment, when RuntimeEnvironmentService/ListDrift is called by a caller with the scope and a role, then the response is 200 with both, each with kind, resource, declared and observed values, detection and resolution time and its proposal, and no secret value (SCN-RuntimeEnvironmentService-002, ADR-0019). |
| AC3 | Given a caller without factory.runtime.read or without a role in the project, an environment of another tenant and an unknown environment, when RuntimeEnvironmentService/GetRuntimeInventory and RuntimeEnvironmentService/ListDrift are called, then the answers are 403, 404 and 404, each with a problem response and no state change (SCN-RuntimeEnvironmentService-001, SCN-RuntimeEnvironmentService-002, ADR-0015). |
| AC4 | Given a workload token with the service scope of the method, when RuntimeEnvironmentService/Inventory.GetObservedState is called for a fresh and for a stale environment, then each reply holds the observed state with its observation time and stale false or true and nothing is written; given no workload identity, a token without the scope, an invalid request or an environment of another tenant, then the call is refused with UNAUTHENTICATED, PERMISSION_DENIED, INVALID_ARGUMENT or NOT_FOUND and no state changes (SCN-RuntimeEnvironmentService-006, ADR-0015). |
| Traces: services | RuntimeEnvironmentService |
| Traces: aggregates | RuntimeEnvironmentService/RuntimeInventory, RuntimeEnvironmentService/DriftFinding |
| Traces: apis | RuntimeEnvironmentService/GetRuntimeInventory, RuntimeEnvironmentService/ListDrift, RuntimeEnvironmentService/Inventory.GetObservedState |
| Traces: descriptors | execution-scope-v1, ack-v1 |
| Traces: adrs | ADR-0015, ADR-0019 |
| Traces: requirements | FR-09, XL-14 |
| Traces: scenarios | SCN-RuntimeEnvironmentService-001, SCN-RuntimeEnvironmentService-002, SCN-RuntimeEnvironmentService-006 |
| Relates: screens | inventory |
| Depends on | AIFACTORY-US-1077, feature:component-base-template-factory-profile |
| Sources | model/services/runtime-cloud/RuntimeEnvironmentService.yaml, docs/planes/execution/environments/services/runtime-environment-service/index.md#apis |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-4332 GetRuntimeInventory, ListDrift and Inventory.GetObservedState with the tenant filter and the project rule |
implementation | GetRuntimeInventory returns the workloads, release, applied version, observation time and staleness; ListDrift the open and resolved findings with references only; both apply the tenant row filter and the project roles of the token, answer 404 for an environment of another tenant as for an unknown one and 403 for a missing scope or role; Inventory.GetObservedState admits a workload token with its service scope only, reads the forwarded scope under it and answers NOT_FOUND for an environment of another tenant. | ConnectSoft.AI.SoftwareFactory.RuntimeEnvironmentService |
AIFACTORY-TASK-4333 Contract of the inventory view, the drift list and the proto reply of GetObservedState |
contract | The OpenAPI document describes the inventory view and the drift list as model/services/runtime-cloud/RuntimeEnvironmentService.yaml names them; the proto of Inventory.GetObservedState carries the shape of ack-v1 and adds the observed state beside it, and a contract test states the difference reported as a correction of the descriptor row of the model. | ConnectSoft.AI.SoftwareFactory.RuntimeEnvironmentService |
AIFACTORY-TASK-4334 Verify read-runtime-inventory-and-drift through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-RuntimeEnvironmentService-001\|Scenario=SCN-RuntimeEnvironmentService-002\|Scenario=SCN-RuntimeEnvironmentService-006)"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-1078, including the stale reply and the four gRPC refusals. |
ConnectSoft.AI.SoftwareFactory.RuntimeEnvironmentService |
AIFACTORY-US-1079: Compare each fresh observation with the applied specification, raise a drift finding per difference and resolve it only by re-observation¶
behavior · persona operator
As an operator, I want every difference between what runs and what was declared recorded as a finding, so that drift is visible as a fact with its declared and observed values and disappears only when it is no longer observed.
The DriftComparer runs on every ObservedStateChanged of a fresh observation, under the key of the environment and the observation time, so a duplicate trigger has no second effect. It reads the specifications last applied to the environment, one per specification kind, through Provisioning.GetCurrentSpecification of IaCProvisioningService, reads the declared values of those program versions through the IaC runner and the configuration references through the Config Platform, and compares them with the observed workloads. Each difference becomes a DriftFinding of one of the kinds VersionMismatch, ReplicaMismatch, ConfigMismatch, MissingResource, UnmanagedResource or SecretBindingMismatch, with the resource, the declared and the observed values and the detection time; a difference already open for the same resource and kind raises no second finding. Each new finding writes RuntimeDriftDetected to the outbox in the same transaction with findingId, tenantId, environmentId, kind and resource, and connectsoft.factory.runtime.drift_open counts the open findings by tenant and kind. A SecretBindingMismatch compares references and never a value. A finding is resolved only by a re-observation that no longer shows it: the Observer sets its resolution time and nothing resolves a finding by hand. No finding is raised from a stale or failed observation. SpecificationDeclared of IaCProvisioningService is handled by TrackDeclared, idempotent on the event id: it records that a newer declared version exists for the environment, so the next comparison reads the current specification again and never compares against a cached one. IaCProvisioningService is a fail-fast dependency: while it does not answer, the comparison is retried with its fixed policy and raises no finding, and the next fresh observation compares again. The Config Platform is optional: while it does not answer, configuration is not compared and no ConfigMismatch is raised from the missing source. RuntimeDriftDetected is the input of StudioBff, AuditService, AlertRuleService and DashboardService, each in its own increment and PBIs; this PBI proves what the publisher can prove.
Acceptance criteria
| AC1 | Given a fresh observation whose workload version, replica count and one secret binding reference differ from the applied specification read through IaCProvisioningService/Provisioning.GetCurrentSpecification, when the DriftComparer runs, then three RuntimeEnvironmentService/DriftFinding rows of kinds VersionMismatch, ReplicaMismatch and SecretBindingMismatch are written with declared and observed values as references, each with its RuntimeEnvironmentService/RuntimeDriftDetected outbox record in the same transaction; the same observation compared again raises nothing (SCN-RuntimeEnvironmentService-008, ADR-0014). |
| AC2 | Given a new finding, when the dispatcher publishes RuntimeEnvironmentService/RuntimeDriftDetected on provisioning.inventory.v1.runtime-drift-detected, then it is sent under the run event envelope with findingId, tenantId, environmentId, kind and resource, and a transport outage is retried with backoff so the event is neither lost nor published twice under its event id (SCN-RuntimeEnvironmentService-008, ADR-0012). |
| AC3 | Given open findings, when a later observation no longer shows one of them, then that finding has its resolution time set by the observation and the others stay open; no operation resolves a finding by hand (SCN-RuntimeEnvironmentService-008, model/services/runtime-cloud/RuntimeEnvironmentService.yaml). |
| AC4 | Given IaCProvisioningService/Provisioning.GetCurrentSpecification does not answer, a stale observation, and the Config Platform does not answer, when the DriftComparer runs, then no finding is raised from the first two and no ConfigMismatch from the third; given a fixture IaCProvisioningService/SpecificationDeclared, when it is handled, then the next comparison reads the current specification again and the event delivered again changes nothing (SCN-RuntimeEnvironmentService-008). |
| Traces: services | RuntimeEnvironmentService, IaCProvisioningService |
| Traces: aggregates | RuntimeEnvironmentService/DriftFinding |
| Traces: apis | IaCProvisioningService/Provisioning.GetCurrentSpecification |
| Traces: events | RuntimeEnvironmentService/RuntimeDriftDetected, IaCProvisioningService/SpecificationDeclared |
| Traces: descriptors | run-event-envelope-v1 |
| Traces: adrs | ADR-0004, ADR-0012, ADR-0014 |
| Traces: requirements | FR-09, XL-10 |
| Traces: scenarios | SCN-RuntimeEnvironmentService-008 |
| Relates: screens | inventory |
| Depends on | AIFACTORY-US-1077, feature:ia-cprovisioning-service, feature:contracts-package |
| Sources | model/services/runtime-cloud/RuntimeEnvironmentService.yaml, model/services/runtime-cloud/IaCProvisioningService.yaml, docs/planes/execution/environments/services/runtime-environment-service/index.md#domain-model |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-331 Drift comparison and findings |
implementation | The DriftComparer reads the applied specification through Provisioning.GetCurrentSpecification, the declared values through the runner and the configuration references through the Config Platform, writes one DriftFinding per new difference of the six kinds with RuntimeDriftDetected in the same transaction, compares secret bindings by reference, raises nothing from a stale or failed observation or while IaCProvisioningService does not answer, and TrackDeclared on SpecificationDeclared invalidates the cached specification idempotently on the event id. | ConnectSoft.AI.SoftwareFactory.RuntimeEnvironmentService |
AIFACTORY-TASK-4335 Fake of GetCurrentSpecification, fake declared values and the contract of RuntimeDriftDetected |
fixture | The acceptance suite holds a fake of Provisioning.GetCurrentSpecification and a fake runner port for declared values, each configurable per environment and able to stop answering, a fake Config Platform that can stop answering, and a golden file that fixes RuntimeDriftDetected on provisioning.inventory.v1.runtime-drift-detected with the payload of model/services/runtime-cloud/RuntimeEnvironmentService.yaml. | ConnectSoft.AI.SoftwareFactory.RuntimeEnvironmentService |
AIFACTORY-TASK-4336 Verify detect-runtime-drift through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&Scenario=SCN-RuntimeEnvironmentService-008"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-1079, including one finding per difference, the resolution by re-observation, no finding while a source does not answer and the publication and payload of RuntimeDriftDetected; consumer handling is proven by the suites of the consumers. |
ConnectSoft.AI.SoftwareFactory.RuntimeEnvironmentService |
AIFACTORY-US-1080: Group drift findings into a reviewable reconciliation proposal, auto-accept only what the option and the policy allow, and list the proposals¶
behavior · persona operator
As an operator, I want the findings of an environment grouped into one proposal I can review, with what it would change and whether it is destructive, so that nothing is reconciled without a decision, and only harmless corrections outside production are accepted for me where the policy allows it.
After it records new findings, the DriftComparer groups the open findings of the environment that belong to no proposal or to a proposal still Proposed into one ReconciliationProposal in state Proposed: the findings it covers, the direction apply-declared, which brings the observed state back to the declared state, the specification version it would apply, a plan summary of the resources it would add, change or delete, and destructive true when it would delete a resource. It writes ReconciliationProposed to the outbox in the same transaction with proposalId, tenantId, environmentId, direction and destructive, and connectsoft.factory.runtime.reconciliation_proposals counts proposals by tenant, state and destructive. The direction adopt-observed, which declares what is observed, needs a change of the program in Git that the service cannot make; which findings are proposed that way is not decided by the model and is reported. The new proposal takes over the findings of every older proposal still Proposed, and each such older proposal moves to Superseded (NewerProposal) in the same transaction; the model gives that move no event. Findings that belong to an Accepted proposal are never taken over. A non-destructive proposal is accepted without an Operator only when the option RuntimeCloud:Inventory:AutoAcceptNonDestructiveOutsideProduction is true and PolicyEngineService answers allow through Policy.Decide for the environment. The request has the shape AIFACTORY-US-1073 of feature ia-cprovisioning-service fixes for a provisioning apply: the domain Deployment, the action kind publication with the fixed target reconciliation-auto-accept, the side-effect class production of DecideReconciliation, the environment of the proposal, the proposal as the resource, the hash of its findings and plan summary as the inputs hash, and as subject the workload identity of the service with the tenant and the project of the environment; the interim kind is reported with the same correction of the descriptor. The service does not hold the class of an environment and leaves it to the policy decision, which raises the class by it, and the seeded tenant bundle answers allow-with-approval for the classes production and external, so the acceptance stays with an Operator until the tenant bundle changes. An auto-accepted proposal moves Proposed to Accepted with a new provisioningRunId and is announced by ReconciliationDecided as AIFACTORY-US-1081 describes. Any other outcome leaves it Proposed: an allow-with-constraints is no allow for an auto-acceptance, because the service applies nothing it could constrain, and an allow-with-approval or a deny needs the decision of an Operator. A destructive proposal, or one the decision does not allow, is always reviewed by an Operator. PolicyEngineService is a fail-fast dependency: an answer INVALID_ARGUMENT, FAILED_PRECONDITION or UNAVAILABLE is treated as not allowed, nothing is auto-accepted and the proposal waits for an Operator. An Operator, a Workspace admin, a Platform admin or an Observer whose scope carries factory.runtime.read lists proposals through ListReconciliationProposals by environment and state with their plan summaries, filtered to the tenant of the token and the projects in which the token holds a role, every project of the tenant for a Platform admin; a caller without the scope is refused with 403 and the list writes nothing. ReconciliationProposed is the input of StudioBff, StudioNotificationService and AuditService, each in its own increment and PBIs; this PBI proves what the publisher can prove.
Acceptance criteria
| AC1 | Given new findings of an environment that belong to no proposal, one of kind UnmanagedResource, an older proposal still Proposed whose findings are open, and an Accepted proposal with open findings, when the DriftComparer groups them, then one new RuntimeEnvironmentService/ReconciliationProposal in state Proposed covers the new findings and those of the older Proposed proposal with direction apply-declared, a plan summary and destructive true, the older proposal is Superseded and the RuntimeEnvironmentService/ReconciliationProposed outbox record is written, both in the same transaction, and the findings of the Accepted proposal stay with it (SCN-RuntimeEnvironmentService-009, ADR-0014). |
| AC2 | Given a raised proposal, when the dispatcher publishes RuntimeEnvironmentService/ReconciliationProposed on provisioning.inventory.v1.reconciliation-proposed, then it is sent under the run event envelope with proposalId, tenantId, environmentId, direction and destructive, and a transport outage is retried with backoff so the event is neither lost nor published twice under its event id (SCN-RuntimeEnvironmentService-009, ADR-0012). |
| AC3 | Given a non-destructive proposal, the option true and fakes of PolicyEngineService/Policy.Decide answering allow, allow-with-constraints, allow-with-approval, deny, INVALID_ARGUMENT, FAILED_PRECONDITION and UNAVAILABLE, when the proposal is raised, then every request named the domain Deployment, the action kind publication with the target reconciliation-auto-accept, the class production, the environment and the hash of the proposal as inputs hash; only the allow moves it to Accepted with a new provisioningRunId and RuntimeEnvironmentService/ReconciliationDecided, and the others leave it Proposed for an Operator; a destructive proposal or the option false is never auto-accepted (SCN-RuntimeEnvironmentService-009, model/services/runtime-cloud/RuntimeEnvironmentService.yaml). |
| AC4 | Given proposals of two projects and two tenants in several states, when RuntimeEnvironmentService/ListReconciliationProposals is called with a filter of environment and state by a caller with factory.runtime.read and a role in one project, then the response is 200 with the matching proposals of that project and their plan summaries only; a caller without the scope is answered 403 with a problem response and no state changes (SCN-RuntimeEnvironmentService-004, ADR-0015). |
| Traces: services | RuntimeEnvironmentService, PolicyEngineService |
| Traces: aggregates | RuntimeEnvironmentService/ReconciliationProposal, RuntimeEnvironmentService/DriftFinding |
| Traces: apis | RuntimeEnvironmentService/ListReconciliationProposals, PolicyEngineService/Policy.Decide |
| Traces: events | RuntimeEnvironmentService/ReconciliationProposed, RuntimeEnvironmentService/ReconciliationDecided |
| Traces: descriptors | policy-decision-v1, run-event-envelope-v1 |
| Traces: adrs | ADR-0012, ADR-0014, ADR-0015 |
| Traces: requirements | FR-09, XL-10 |
| Traces: scenarios | SCN-RuntimeEnvironmentService-004, SCN-RuntimeEnvironmentService-009 |
| Relates: screens | inventory |
| Depends on | AIFACTORY-US-1079, feature:policy-engine-service, feature:contracts-package |
| Sources | model/services/runtime-cloud/RuntimeEnvironmentService.yaml, model/services/governance/PolicyEngineService.yaml, docs/planes/execution/environments/services/runtime-environment-service/index.md#options-and-configuration |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-4337 Proposal grouping, supersession and the auto-accept by option and policy decision |
implementation | The DriftComparer groups the open findings that belong to no proposal or to a proposal still Proposed into one new Proposed proposal with direction apply-declared, plan summary and destructive flag, takes those findings over and moves every older Proposed proposal whose findings it took to Superseded, writing ReconciliationProposed in the same transaction and never taking a finding of an Accepted proposal; it auto-accepts a non-destructive proposal with a new provisioningRunId only when RuntimeCloud:Inventory:AutoAcceptNonDestructiveOutsideProduction is true and Policy.Decide, asked with the domain Deployment, the action kind publication with the target reconciliation-auto-accept, the class production, the environment and the hash of the proposal, answers allow; allow-with-constraints, allow-with-approval, deny, INVALID_ARGUMENT, FAILED_PRECONDITION and UNAVAILABLE leave it Proposed. | ConnectSoft.AI.SoftwareFactory.RuntimeEnvironmentService |
AIFACTORY-TASK-4338 ListReconciliationProposals and the contract of ReconciliationProposed |
implementation | ListReconciliationProposals returns the proposals by environment and state with plan summaries under the tenant row filter and the project roles of the token and answers 403 for a missing scope; a golden file fixes ReconciliationProposed on provisioning.inventory.v1.reconciliation-proposed under run-event-envelope-v1 with the payload of model/services/runtime-cloud/RuntimeEnvironmentService.yaml. | ConnectSoft.AI.SoftwareFactory.RuntimeEnvironmentService |
AIFACTORY-TASK-4339 Verify raise-and-list-reconciliation-proposals through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-RuntimeEnvironmentService-004\|Scenario=SCN-RuntimeEnvironmentService-009)"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-1080 with a fake of Policy.Decide that answers each outcome and stops answering, including the takeover of the findings of an older Proposed proposal with its supersession, the findings of an Accepted proposal left with it, the request shape of the auto-accept and the publication and payload of ReconciliationProposed; consumer handling is proven by the suites of the consumers. |
ConnectSoft.AI.SoftwareFactory.RuntimeEnvironmentService |
AIFACTORY-US-1081: Accept or reject a reconciliation proposal, hand an accepted one to provisioning and mark it applied when its run is applied¶
behavior · persona operator
As an operator, I want to accept a proposal so that provisioning plans it, or reject it with a reason, so that a difference is corrected by my decision through the one provisioning path, never by a write of the inventory service.
A caller whose scope carries factory.runtime.operate and whose role in the project of the environment is Operator or a role above it in the role order of ADR-0015 amendment D114, Workspace admin or Platform admin, decides a proposal through DecideReconciliation with the decision accept or reject and, for a rejection, a reason. A rejection without a reason, a decision value other than accept or reject, or a malformed body is refused with 422 and a problem response, and no state changes; the code list of the model, 200, 403, 404 and 409, has no validation code, so 422 is reported as a code the model omits. A proposal in state Proposed moves to Accepted (OperatorAccepts) or to Rejected (OperatorRejects) with decidedBy, the response is 200 with the proposal, and ReconciliationDecided is written to the outbox in the same transaction with proposalId, tenantId, environmentId and state. On acceptance the service assigns a new provisioningRunId, stores it on the proposal, whose model holds that field, and publishes it in ReconciliationDecided; IaCProvisioningService creates the run of kind Reconciliation under that id when it handles the event (AIFACTORY-US-1076 of feature ia-cprovisioning-service). The model gives this service an outbound gRPC dependency on IaCProvisioningService to plan accepted proposals, but IaCProvisioningService has no gRPC method to plan, so the hand-off goes through the event and the missing method is reported as a gap. The operation is naturally idempotent: the decision that is already recorded, repeated, returns 200 with the same proposal and changes nothing, also once an accepted proposal is Applied; any other decision on a proposal that is no longer Proposed, a rejection of an Accepted or Applied proposal, an acceptance of a Rejected one or any decision on a Superseded one, is refused with 409 and a problem response that names its state. A proposal of another tenant is answered 404, the same answer as for an unknown proposalId (ADR-0015 amendment D113); a caller without the scope, or whose role in the project of the environment is only one below Operator or not comparable with it, Observer, Requester, Reviewer or Asset maintainer, is refused with 403. The acceptance of a production proposal is of class production but writes nothing to infrastructure: the apply it leads to is a provisioning run whose gate is the policy decision of PolicyEngineService, and the approval that decision may require, asked by IaCProvisioningService; this service neither decides nor requests an approval. When ProvisioningApplied of IaCProvisioningService arrives with the provisioningRunId stored on an Accepted proposal, the proposal moves Accepted to Applied (ProvisioningApplied), idempotently on the event id; an event of another provisioningRunId changes no proposal. A failed reconciliation run leaves the proposal Accepted with its findings still open and attached to it, and no new proposal is raised for them, because the grouping of AIFACTORY-US-1080 never takes a finding of an Accepted proposal; the model has no path back from Accepted to Proposed or Superseded, which is reported to the owner. ReconciliationDecided is the input of IaCProvisioningService, StudioBff and AuditService, each in its own PBIs; this PBI proves what the publisher can prove.
Acceptance criteria
| AC1 | Given a proposal in state Proposed and a caller with factory.runtime.operate and the Operator role in the project of its environment, when RuntimeEnvironmentService/DecideReconciliation is called with accept, then the response is 200, the RuntimeEnvironmentService/ReconciliationProposal is Accepted with decidedBy, and the RuntimeEnvironmentService/ReconciliationDecided outbox record is written in the same transaction; with reject and a reason, then it is Rejected; the same decision repeated returns 200 and changes nothing (SCN-RuntimeEnvironmentService-005, ADR-0014). |
| AC2 | Given a Rejected and a Superseded proposal called with accept, an Accepted proposal called with reject, a rejection without a reason, an unknown decision value, a malformed body, a caller without the scope, a caller whose only role in the project is Observer, a proposal of another tenant and an unknown proposalId, when RuntimeEnvironmentService/DecideReconciliation is called, then the answers are 409 naming the state for the first three, 422 for the next three, 403, 403, 404 and 404, each with a problem response and no state change; a Workspace admin is admitted like an Operator (SCN-RuntimeEnvironmentService-005, ADR-0015). |
| AC3 | Given an accepted and a rejected proposal, when the dispatcher publishes RuntimeEnvironmentService/ReconciliationDecided on provisioning.inventory.v1.reconciliation-decided, then each is sent under the run event envelope with proposalId, tenantId, environmentId and state, the accepted one with the provisioningRunId assigned on acceptance and stored on the proposal and the rejected one without it, and a transport outage is retried with backoff so the event is neither lost nor published twice under its event id (SCN-RuntimeEnvironmentService-010, ADR-0012). |
| AC4 | Given an Accepted proposal with its provisioningRunId, when a fixture IaCProvisioningService/ProvisioningApplied carrying that provisioningRunId arrives, then the proposal is Applied and the event delivered again changes nothing; given a IaCProvisioningService/ProvisioningApplied of another provisioningRunId or a IaCProvisioningService/ProvisioningFailed of the same, then the proposal stays Accepted with its findings open and attached to it, and no new proposal is raised for them (SCN-RuntimeEnvironmentService-010, model/services/runtime-cloud/RuntimeEnvironmentService.yaml). |
| Traces: services | RuntimeEnvironmentService, IaCProvisioningService |
| Traces: aggregates | RuntimeEnvironmentService/ReconciliationProposal |
| Traces: apis | RuntimeEnvironmentService/DecideReconciliation |
| Traces: events | RuntimeEnvironmentService/ReconciliationDecided, IaCProvisioningService/ProvisioningApplied, IaCProvisioningService/ProvisioningFailed |
| Traces: descriptors | run-event-envelope-v1 |
| Traces: adrs | ADR-0012, ADR-0014, ADR-0015 |
| Traces: requirements | FR-09, FUX-05 |
| Traces: scenarios | SCN-RuntimeEnvironmentService-005, SCN-RuntimeEnvironmentService-010 |
| Relates: screens | inventory |
| Depends on | AIFACTORY-US-1080, feature:ia-cprovisioning-service, feature:contracts-package |
| Sources | model/services/runtime-cloud/RuntimeEnvironmentService.yaml, docs/reference/schemas/run-event-envelope.schema.json, docs/planes/execution/environments/services/runtime-environment-service/index.md#sagas-and-long-running-flows |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-332 Reconciliation decisions with their refusals and the ReconciliationDecided outbox record |
implementation | DecideReconciliation admits the Operator role and the roles above it in the order of D114, Workspace admin and Platform admin, moves a Proposed proposal to Accepted or Rejected with decidedBy and a required reason for a rejection under the row version of the proposal, assigns a new provisioningRunId on acceptance and stores it on the proposal, writes ReconciliationDecided with that id for an accepted proposal in the same transaction, repeats the same decision idempotently, answers 422 for a rejection without a reason, an unknown decision value or a malformed body, 409 naming the state for a different decision, 404 for a proposal of another tenant as for an unknown id and 403 for a missing scope or a role below Operator or not comparable with it, and neither decides nor requests an approval. | ConnectSoft.AI.SoftwareFactory.RuntimeEnvironmentService |
AIFACTORY-TASK-4340 Transition Accepted to Applied from ProvisioningApplied by the provisioningRunId of the proposal |
implementation | The handler of ProvisioningApplied moves the Accepted proposal whose stored provisioningRunId equals the provisioningRunId of the event to Applied, idempotently on the event id; an event of another provisioningRunId or a ProvisioningFailed leaves the proposal Accepted with its findings open and attached to it, and raises no new proposal. | ConnectSoft.AI.SoftwareFactory.RuntimeEnvironmentService |
AIFACTORY-TASK-4341 Contract of ReconciliationDecided against the run event envelope |
contract | Golden files fix ReconciliationDecided on provisioning.inventory.v1.reconciliation-decided under run-event-envelope-v1 with proposalId, tenantId, environmentId and state, one for an accepted proposal with the provisioningRunId assigned on acceptance and one for a rejected proposal without it; a contract test fails when the serialised event differs from its file. | ConnectSoft.AI.SoftwareFactory.RuntimeEnvironmentService |
AIFACTORY-TASK-4342 Verify decide-a-reconciliation-proposal through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-RuntimeEnvironmentService-005\|Scenario=SCN-RuntimeEnvironmentService-010)"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-1081, including the idempotent repeat, the 422 of an invalid decision, the 409 naming the state, the admission of a Workspace admin, the provisioningRunId assigned on acceptance and matched by ProvisioningApplied, the proposal left Accepted after a failed run and the publication and payload of ReconciliationDecided; consumer handling is proven by the suites of the consumers. |
ConnectSoft.AI.SoftwareFactory.RuntimeEnvironmentService |