AIFACTORY-FEAT-044: PipelineExecutionService: 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 DevOps / GitOps (PF-08) · Increment I2 Deliver it · State elaborated · Route backend-developer · Build order 96 of 185 (Factory code)
PipelineExecutionService is the service of bounded context BC-23 (Source & Pipelines). Receipts for everything the Factory does in a system of record: change proposals that became branches and pull requests with their review state, pipeline runs with stages, build, test, coverage, security and package results, and the provenance that ties every commit and run back to the Factory run, agent release and change set that produced it (BC-23; BuildResultService merged). This feature completes the service after its thin delivery in I1: every aggregate, operation, event and worker of the model. Repository ConnectSoft.AI.SoftwareFactory.PipelineExecutionService.
| Delivers | PipelineExecutionService (complete) |
| Stubs | — |
| Realizes | adrs: ADR-0014 |
| Requirements | FR-07, FUX-05, FUX-06, NFR-08, NFR-12, XL-04, XL-10 |
| Depends on | AIFACTORY-FEAT-041 PipelineExecutionService: thin delivery for the first outcome |
| Sources | model/services/devops-gitops/PipelineExecutionService.yaml |
Scenarios to trace (12, catalog): SCN-PipelineExecutionService-001 ✓, SCN-PipelineExecutionService-002 ✓, SCN-PipelineExecutionService-003 ✓, SCN-PipelineExecutionService-004 ✓, SCN-PipelineExecutionService-005 ✓, SCN-PipelineExecutionService-006 ✓, SCN-PipelineExecutionService-007 ✓, SCN-PipelineExecutionService-008 ✓, SCN-PipelineExecutionService-009 ✓, SCN-PipelineExecutionService-010 ✓, SCN-PipelineExecutionService-011 ✓, SCN-PipelineExecutionService-012 ✓
AIFACTORY-US-022: A merged change produces a recorded pipeline run¶
behavior · persona operator
As an operator, I want the pipeline run of a merged change recorded with its typed results, so that delivery decisions rest on receipts and never on an assumption that a build passed.
This is the integration PBI of the complete delivery of PipelineExecutionService, which replaces the thin delivery of I1 in the same repository without a contract change and serves every aggregate, operation, event, worker and handler of model/services/devops-gitops/PipelineExecutionService.yaml. OpenChangeProposal, the REST route that pushes a change set as a branch and opens its pull request from this service, arrives here (AIFACTORY-US-1276) beside the recording path of I1. A proposal opened in I1 now lives on in the system of record: verified deliveries of Azure DevOps and GitHub, announced by DeliveryReceived of ConnectorRegistryService, move it through review to Merged or Abandoned with ChangeProposalStateChanged and ChangeProposalMerged (AIFACTORY-US-1281, AIFACTORY-US-1282). The pipeline of the repository runs on the merged commit; its run is mirrored as a PipelineRun with stages and typed results, build, unit and integration tests, coverage, static analysis, security scan, SBOM, packages, images and attestations, each a receipt with an artifact reference, and announced by PipelineRunStarted and PipelineRunCompleted (AIFACTORY-US-1283). A missed delivery is never assumed: the RunReconciler polls the system of record for runs and proposals still open after Delivery:Pipelines:ReconcileAfterMinutes, and an Operator can ask for the same read through ReconcilePipelineRun (AIFACTORY-US-1285). Readers with factory.delivery.read list and read proposals and runs of their own tenant and projects only, a resource of another tenant being answered 404 (ADR-0015; AIFACTORY-US-1280, AIFACTORY-US-1284). A run takes the state the system of record reported, never one the service assumes or derives; each failed result is recorded with passed false, its kind and its summary, and consumers judge readiness from the typed results: ReleaseService assembles a release only from a succeeded run and the delivery run evaluates the typed results in their own features, while RunControlService settles the step of a run that waits for the pipeline run of its merged commit through its handler SettleWaitingStep, which this feature delivers in the repository of RunControlService (AIFACTORY-US-1608, D140). The public routes are reached through the DeliveryHost gateway of this increment. DeliveryReceived, the verified inbound deliveries of Azure DevOps with the webhook ingress they need, and the reads Connectors.ReadPipelineRun and Connectors.ReadPullRequest that the applier and the reconciler use for an unknown run or pull request are delivered in I2 by feature connector-registry-service-deliveries (D135), so on a deployed I2 instance review states, merges and pipeline runs reach ApplyDelivery. The branch push through a connector, which OpenChangeProposal needs, is not in the I2 scope of ConnectorRegistryService; that path is proven against a fake connector and stays an open point of the model. Repository: ConnectSoft.AI.SoftwareFactory.PipelineExecutionService.
Acceptance criteria
| AC1 | Given a change proposal was merged and the pipeline of the repository ran on the merged commit, when the deliveries of that run, announced by ConnectorRegistryService/DeliveryReceived of feature connector-registry-service-deliveries, are applied, then PipelineExecutionService/PipelineRunStarted and PipelineExecutionService/PipelineRunCompleted are published for one PipelineExecutionService/PipelineRun with the commit, the proposal and the tests, scans and quality gates as typed results (ADR-0014). |
| AC2 | Given a webhook delivery of a run was missed, when the reconciler runs after Delivery:Pipelines:ReconcileAfterMinutes, then the run is read from the system of record through ConnectorRegistryService/Connectors.ReadPipelineRun and recorded once, and its completion is published once (model/services/devops-gitops/PipelineExecutionService.yaml). |
| AC3 | Given a pipeline run with a failed result, when its results are read through PipelineExecutionService/GetPipelineRun, then the run carries the state the system of record reported and each failed result is recorded with passed false, its kind and its summary, so that a consumer judges readiness from the typed results and not from the run state alone (FR-07). |
| AC4 | Given I list the pipeline runs through PipelineExecutionService/ListPipelineRuns, when the project is not in my trusted scope or belongs to another tenant, then I see none of its runs, and reading one of them by id is answered 404 (ADR-0015). |
| AC5 | Given the complete delivery is deployed in place of the thin one, when ToolAdapterService calls PipelineExecutionService/Pipelines.RecordProposal as in I1, then it is served unchanged and PipelineExecutionService/ChangeProposalOpened keeps its contract, PipelineExecutionService/OpenChangeProposal is served beside it, and the fakes and static answers of the first outcome are gone from the repository. |
| Traces: services | PipelineExecutionService, IntegrationService, ConnectorRegistryService, DeliveryHost |
| Traces: aggregates | PipelineExecutionService/PipelineRun, PipelineExecutionService/ChangeProposal |
| Traces: apis | PipelineExecutionService/ListPipelineRuns, PipelineExecutionService/GetPipelineRun, PipelineExecutionService/ReconcilePipelineRun, PipelineExecutionService/OpenChangeProposal, PipelineExecutionService/Pipelines.RecordProposal, ConnectorRegistryService/Connectors.ReadPipelineRun, ConnectorRegistryService/Connectors.ReadPullRequest |
| Traces: events | PipelineExecutionService/ChangeProposalOpened, PipelineExecutionService/ChangeProposalMerged, PipelineExecutionService/PipelineRunStarted, PipelineExecutionService/PipelineRunCompleted, ConnectorRegistryService/DeliveryReceived |
| Traces: adrs | ADR-0014, ADR-0015 |
| Traces: requirements | FR-07, FUX-05, FUX-06 |
| Relates: screens | pipeline-runs, proposals |
| Depends on | AIFACTORY-US-1276, AIFACTORY-US-1280, AIFACTORY-US-1281, AIFACTORY-US-1282, AIFACTORY-US-1283, AIFACTORY-US-1284, AIFACTORY-US-1285, AIFACTORY-US-1286, AIFACTORY-US-1287, AIFACTORY-US-1608, feature:pipeline-execution-service-thin, feature:delivery-host, feature:connector-registry-service-thin, feature:connector-registry-service-deliveries |
| Sources | model/services/devops-gitops/PipelineExecutionService.yaml, docs/planes/execution/delivery-engine/services/pipeline-execution-service/index.md#purpose-and-responsibilities |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-319 Pipeline commands in the command-line client |
implementation | The client lists the pipeline runs of a project through PipelineExecutionService/ListPipelineRuns and shows the typed results of one run through PipelineExecutionService/GetPipelineRun, naming every failed result. | ConnectSoft.AI.SoftwareFactory.Cli |
AIFACTORY-TASK-261 Retire the thin scope and the stubs of PipelineExecutionService |
implementation | Callers run against the complete service; the fakes and static answers of the first outcome are deleted, the contracts of Pipelines.RecordProposal and ChangeProposalOpened stay unchanged, and no stub remains that this feature does not declare. | ConnectSoft.AI.SoftwareFactory.PipelineExecutionService |
AIFACTORY-TASK-709 Verify pipeline-run-recorded by running the declared command |
verification | Run dotnet test -c Release --filter Category=Acceptance; a zero-match filter counts as a failure; it passes and proves AC1 to AC5 of AIFACTORY-US-022 over recorded deliveries of a merged proposal and its pipeline run, a missed completion delivery, a run that failed its security scan and a two-tenant fixture. |
ConnectSoft.AI.SoftwareFactory.PipelineExecutionService |
AIFACTORY-US-1276: Open a change proposal as a branch and a pull request in the system of record¶
behavior · persona reviewer
As a reviewer, I want the change set I approved pushed as a branch and opened as a pull request with its provenance, so that the system of record holds exactly what I approved and every commit names the run that produced it.
OpenChangeProposal is the route of a person; the tool propose-change-set opens its pull request through the connection itself and records it with Pipelines.RecordProposal (D135). A caller whose scope carries factory.delivery.propose posts to PipelineExecutionService/OpenChangeProposal under an Idempotency-Key a pull-request-proposal-v1 body with exactly the members of PullRequestProposal in docs/reference/schemas/change-set.schema.json: changeSetId, changeSetHash, targetBranch, title, body and the optional reviewers, labels and linkedWorkItems. Tenant and project come from the trusted scope of the call, never from the body (ADR-0015). The service reads the change set by changeSetId from ArtifactService, takes changeSetRef and the repository from it and refuses, with a problem response and no state change, a changeSetHash that is not the hash of the stored change set, the hash the approval was bound to; which of the codes the model lists answers that refusal is reported. A ChangeProposal carries its provenance runId, attemptId, agentReleaseId and changeSetRef, and a proposal without provenance is not Factory-authored, but neither OpenChangeProposal, pull-request-proposal-v1 nor execution-scope-v1 carries a run, an attempt or an agent release, so the carrier of the provenance on the route of a person stays an open point of the model, change-proposal-record-v1 carrying it only for the recording path, and this PBI invents no body member. The service records the proposal in state Proposed with the system of record of the tenant connection (Delivery:Systems:DefaultSystemOfRecord, Azure DevOps by default) and answers 202 with the location of the proposal; the push and the pull request follow the answer. It pushes the change set as a branch, every commit carrying the trailers of Delivery:Pipelines:CommitTrailerKeys (Factory-Run, Factory-ChangeSet, Factory-Agent), records the commits in ProposalCommits and moves the proposal to BranchCreated (BranchPushed); it then opens the pull request, records pullRequestRef and moves to PullRequestOpen (PullRequestOpened), writing ChangeProposalOpened in the same transaction (AIFACTORY-US-1278). A repeat under the same key and body returns the same proposal and changes nothing; a different body under the same key is refused with 409 (ADR-0014); a run and change-set hash already recorded through Pipelines.RecordProposal return that proposal and push nothing. A caller without the scope is refused with 403. Because the answer precedes the push, a push that the branch policy refuses is not answered with a status: the proposal stays Proposed with the reason, visible through GetChangeProposal, nothing is published and the attempt of the tool records a failed shared-write, as the failure mode of the model states. When the system of record is unreachable the proposal stays Proposed and nothing is marked done without a receipt; the pending push of a Proposed proposal is kept and retried once the connector is healthy again, opening the proposal once (D135, a reading the owner may overturn). The model lists 412 without naming its condition, so this PBI asserts no meaning for it and reports it. When ArtifactService is unavailable the call fails fast and records nothing. The connector path of this route is not modelled: feature connector-registry-service-deliveries gives this service the reads Connectors.ReadPullRequest and Connectors.ReadPipelineRun but no operation through which it pushes a branch or opens a pull request, so the behaviour is proven against a fake Azure DevOps connector and the path stays an open point. No modelled operation merges, and the model forbids an auto-merge to a protected branch without a shared-write approval recorded by the service. The gauge connectsoft.factory.delivery.proposals moves with the state of every proposal.
Acceptance criteria
| AC1 | Given a person whose scope carries factory.delivery.propose and a pull-request-proposal-v1 body with only the members of PullRequestProposal whose changeSetHash is the hash of the change set stored in ArtifactService, when PipelineExecutionService/OpenChangeProposal is called with an Idempotency-Key, then the response is 202 with the location of the proposal, the PipelineExecutionService/ChangeProposal is recorded Proposed with tenant and project from the trusted scope and changeSetRef from the stored change set, and after the answer it moves to BranchCreated (BranchPushed) and PullRequestOpen (PullRequestOpened) with pullRequestRef recorded (SCN-PipelineExecutionService-003, ADR-0015). |
| AC2 | Given the branch was pushed, when its commits are read from the system of record and from ProposalCommits, then every commit carries the trailers Factory-Run, Factory-ChangeSet and Factory-Agent with the run id, the change-set hash and the agent release, so that the proposal is Factory-authored (SCN-PipelineExecutionService-003, XL-10). |
| AC3 | Given the same body repeated under the same Idempotency-Key, a different body under that key, a changeSetHash that does not match the stored change set, a run and hash already recorded through PipelineExecutionService/Pipelines.RecordProposal, or a caller without factory.delivery.propose, when PipelineExecutionService/OpenChangeProposal is called, then the repeat and the recorded change set return the same proposal and push nothing, the different body is refused with 409, the hash mismatch is refused with a problem response, and the missing scope with 403, each refusal with no state change (SCN-PipelineExecutionService-003, ADR-0014). |
| AC4 | Given the 202 was answered and then the branch policy refuses the push or the system of record is unreachable, when the push runs against a fake Azure DevOps connector, then the PipelineExecutionService/ChangeProposal stays Proposed with the reason read through PipelineExecutionService/GetChangeProposal, PipelineExecutionService/ChangeProposalOpened is not published, and for the unreachable system the pending push is kept and retried once the connector is healthy again and the proposal is opened once (SCN-PipelineExecutionService-003, D135). |
| AC5 | Given ArtifactService is unavailable, when PipelineExecutionService/OpenChangeProposal is called, then the call fails fast, no PipelineExecutionService/ChangeProposal is written and nothing is pushed, and a repeat under the same key after recovery opens the proposal once (SCN-PipelineExecutionService-003). |
| Traces: services | PipelineExecutionService, ArtifactService, ConnectorRegistryService |
| Traces: aggregates | PipelineExecutionService/ChangeProposal |
| Traces: apis | PipelineExecutionService/OpenChangeProposal, PipelineExecutionService/GetChangeProposal, PipelineExecutionService/Pipelines.RecordProposal |
| Traces: events | PipelineExecutionService/ChangeProposalOpened |
| Traces: descriptors | pull-request-proposal-v1, change-set-v1 |
| Traces: adrs | ADR-0014, ADR-0015 |
| Traces: requirements | FR-07, XL-10 |
| Traces: scenarios | SCN-PipelineExecutionService-003 |
| Relates: screens | proposals |
| Depends on | AIFACTORY-US-1280, AIFACTORY-US-1286, AIFACTORY-US-1287, feature:pipeline-execution-service-thin, feature:artifact-service, feature:connector-registry-service-thin |
| Sources | model/services/devops-gitops/PipelineExecutionService.yaml, model/tools/propose-change-set.yaml, docs/reference/schemas/change-set.schema.json, docs/reference/schemas/execution-scope.schema.json, docs/planes/execution/delivery-engine/services/pipeline-execution-service/index.md#apis |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-227 OpenChangeProposal with an asynchronous push and provenance trailers |
implementation | OpenChangeProposal validates the PullRequestProposal body, reads the change set from ArtifactService, refuses a changeSetHash that does not match it, records the proposal Proposed and answers 202; after the answer it pushes the branch with the commit trailers of Delivery:Pipelines:CommitTrailerKeys through the connector port, records ProposalCommits, opens the pull request and applies BranchPushed and PullRequestOpened, the second in the transaction of the ChangeProposalOpened outbox record; a refused push leaves the proposal Proposed with the reason, a push pending on an unreachable system of record is retried when the connector is healthy again, and the idempotent repeat, the 409, the 403, the hash mismatch and the fail-fast on an unavailable ArtifactService are covered by acceptance tests. | ConnectSoft.AI.SoftwareFactory.PipelineExecutionService |
AIFACTORY-TASK-5101 Contract of OpenChangeProposal with its body and problem responses |
contract | The OpenAPI document of the service exposes POST /factory/delivery/proposals with the PullRequestProposal body of docs/reference/schemas/change-set.schema.json and no other member, the Idempotency-Key header, the 202 answer with the proposal location and the problem responses 403, 409 and 412 as model/services/devops-gitops/PipelineExecutionService.yaml lists them, without a stated condition for 412 until the owner names it. | ConnectSoft.AI.SoftwareFactory.PipelineExecutionService |
AIFACTORY-TASK-5102 Verify open-a-change-proposal through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&Scenario=SCN-PipelineExecutionService-003"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-1276 against a fake Azure DevOps connector that can accept, refuse by branch policy or be unreachable and recover, and a fake ArtifactService that holds the change set or is unavailable. |
ConnectSoft.AI.SoftwareFactory.PipelineExecutionService |
AIFACTORY-US-1280: List and read change proposals with their commits, reviews, runs and provenance¶
behavior · persona reviewer
As a reviewer, I want to list the change proposals of my projects and read one with its commits, reviews, pipeline runs and provenance, so that I can follow what the Factory proposed in the system of record without leaving the Factory.
A caller whose scope carries factory.delivery.read (Requester, Reviewer, Operator, Platform admin or Observer) lists change proposals through PipelineExecutionService/ListChangeProposals, filtered by project, run, repository and state, each with its pull-request reference, and reads one proposal through PipelineExecutionService/GetChangeProposal with its commits and their trailers, its reviewers, the pipeline runs that name it and its provenance to the run, the attempt, the agent release and the change-set artifact. The tenant comes from the trusted scope of the call and the list holds only the proposals of that tenant and of the projects in scope; the index IX_Proposals_Repo_State serves the repository and state filter and IX_Proposals_Run the run filter. Every query runs under the tenant row filter, so a proposal of another tenant never appears in a list and is not found when addressed: the read answers 404, the same answer as for a proposalId that does not exist, and never confirms that it exists (ADR-0015). A caller without the scope is refused with 403. Nothing is written by these reads and no event is published. The routes are reached through the DeliveryHost gateway; StudioBff renders them in its own increment and the CLI reads them.
Acceptance criteria
| AC1 | Given proposals of several projects, runs, repositories and states in my tenant and in another tenant, when PipelineExecutionService/ListChangeProposals is called with a project, a run, a repository or a state filter, then the response is 200 with only the matching proposals of my tenant and projects in scope, each with its state and pull-request reference, and proposals of the other tenant never appear (SCN-PipelineExecutionService-001, ADR-0015). |
| AC2 | Given a PipelineExecutionService/ChangeProposal of my tenant and project with commits, reviewers and pipeline runs, when PipelineExecutionService/GetChangeProposal is called, then the response is 200 with its commits and trailers, its reviewers, the runs that name it and the provenance runId, attemptId, agentReleaseId and changeSetRef (SCN-PipelineExecutionService-002). |
| AC3 | Given a caller without factory.delivery.read, or a proposalId that exists only in another tenant or not at all, when PipelineExecutionService/ListChangeProposals or PipelineExecutionService/GetChangeProposal is called, then the response is 403 for the missing scope and 404 for the foreign or unknown proposal, each with a problem response and no state change (SCN-PipelineExecutionService-001, SCN-PipelineExecutionService-002, ADR-0015). |
| Traces: services | PipelineExecutionService |
| Traces: aggregates | PipelineExecutionService/ChangeProposal |
| Traces: apis | PipelineExecutionService/ListChangeProposals, PipelineExecutionService/GetChangeProposal |
| Traces: adrs | ADR-0015 |
| Traces: requirements | FUX-05 |
| Traces: scenarios | SCN-PipelineExecutionService-001, SCN-PipelineExecutionService-002 |
| Relates: screens | proposals |
| Depends on | AIFACTORY-US-1286, AIFACTORY-US-1287 |
| Sources | model/services/devops-gitops/PipelineExecutionService.yaml, docs/planes/execution/delivery-engine/services/pipeline-execution-service/index.md#apis |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-5107 ListChangeProposals and GetChangeProposal under the tenant row filter |
implementation | ListChangeProposals filters by project, run, repository and state over the indexes of ChangeProposals and returns pull-request references; GetChangeProposal returns commits, reviewers, linked pipeline runs and provenance; both apply the tenant row filter so a foreign proposal is answered 404 like an unknown one, and a missing scope is 403. | ConnectSoft.AI.SoftwareFactory.PipelineExecutionService |
AIFACTORY-TASK-5108 Verify read-change-proposals through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-PipelineExecutionService-001\|Scenario=SCN-PipelineExecutionService-002)"; a zero-match filter counts as a failure; the tests prove AC1 to AC3 of AIFACTORY-US-1280 over a two-tenant fixture. |
ConnectSoft.AI.SoftwareFactory.PipelineExecutionService |
AIFACTORY-US-1281: Mirror the review state of a proposal from verified deliveries and announce every change¶
behavior · persona reviewer
As a reviewer, I want the review and pull-request state of a Factory proposal to follow the system of record, so that an approval bound to a superseded proposal version becomes stale and nobody reads an outdated state.
The system of record is the truth of branches, commits and pull requests; the proposal mirrors it and never the other way round. The inbox handler ApplyDelivery takes DeliveryReceived of ConnectorRegistryService, the verified webhooks of Azure DevOps and GitHub, which feature connector-registry-service-deliveries delivers for Azure DevOps in I2 (D135), and the DeliveryApplier worker maps a pull-request, review or push delivery to the proposal it names; an unknown reference is looked up through Connectors.ReadPullRequest of that feature. The worker is idempotent on deliveryId, retries exponentially five times with a backoff of 30 seconds and runs at most four in parallel, partitioned by repository, so a repeated delivery changes nothing. From PullRequestOpen a review that requests changes moves the proposal to ChangesRequested (ReviewRequestedChanges), new commits move it back to PullRequestOpen (NewCommits) and are recorded in ProposalCommits with their trailers, an approving review moves it to Approved (ReviewApproved), and a closed pull request moves it to Abandoned (Closed). Every such transition writes ChangeProposalStateChanged with proposalId, tenantId, runId, fromState and toState in the same transaction, and the dispatcher publishes it on pipelines.proposals.v1.change-proposal-state-changed under the run event envelope, retrying with backoff so it is neither lost nor duplicated (ADR-0012, ADR-0014). RunControlService marks a pending approval bound to a superseded version Stale from this event, and StudioBff and DashboardService project it, each in its own suite. A delivery whose transition the model does not draw from the current state changes no state. The inbox handler LinkValidation takes ArtifactValidated of ArtifactService, the local validator results of a change set before it is proposed, idempotent on the event id. In the modelled order these results arrive before any proposal exists: they are kept by change set and attached to the proposal whose changeSetRef names that change set when it is opened, and results that arrive after the opening are linked at once. No modelled table stores validation results before a proposal exists, an open point reported to the owner. The opening transitions and ChangeProposalOpened stay as the thin delivery built them, and the merge is AIFACTORY-US-1282. The deliveries and the pull-request read reach this service from ConnectorRegistryService in I2, so the behaviour is proven against recorded deliveries and the connector read of that feature.
Acceptance criteria
| AC1 | Given a PipelineExecutionService/ChangeProposal in PullRequestOpen, when ConnectorRegistryService/DeliveryReceived announces a review that requests changes, new commits after it, an approving review, or a closed pull request, then the proposal moves to ChangesRequested, back to PullRequestOpen with the new commits recorded, to Approved, or to Abandoned, and PipelineExecutionService/ChangeProposalStateChanged with fromState and toState is written in the same transaction as each move (SCN-PipelineExecutionService-009, ADR-0014). |
| AC2 | Given the outbox record, when the dispatcher publishes PipelineExecutionService/ChangeProposalStateChanged on pipelines.proposals.v1.change-proposal-state-changed, then the event is sent under the run event envelope with proposalId, tenantId, runId, fromState and toState, and a transport outage is retried with backoff so the event is neither lost nor duplicated under its event id (SCN-PipelineExecutionService-009, ADR-0012). |
| AC3 | Given the same delivery delivered twice, a delivery that names a transition the model does not draw from the current state, or a delivery that names an unknown pull request, when the DeliveryApplier runs, then the repeat changes nothing, the undrawn transition changes no state and publishes nothing, and the unknown reference is looked up through ConnectorRegistryService/Connectors.ReadPullRequest before it is applied or dropped (SCN-PipelineExecutionService-009, D135). |
| AC4 | Given ArtifactService/ArtifactValidated for a change set that no PipelineExecutionService/ChangeProposal names yet, when LinkValidation runs and the proposal of that change set is opened later, then the validator results are kept by change set and attached to the proposal whose changeSetRef names it at its opening; given the proposal already exists, they are linked at once; and a redelivery of the same event id links nothing twice (model/services/devops-gitops/PipelineExecutionService.yaml). |
| Traces: services | PipelineExecutionService, ConnectorRegistryService, ArtifactService |
| Traces: aggregates | PipelineExecutionService/ChangeProposal |
| Traces: apis | ConnectorRegistryService/Connectors.ReadPullRequest |
| Traces: events | PipelineExecutionService/ChangeProposalStateChanged, ConnectorRegistryService/DeliveryReceived, ArtifactService/ArtifactValidated |
| Traces: adrs | ADR-0012, ADR-0014 |
| Traces: requirements | FR-07, XL-04 |
| Traces: scenarios | SCN-PipelineExecutionService-009 |
| Relates: screens | proposals |
| Depends on | AIFACTORY-US-1286, AIFACTORY-US-1287, feature:connector-registry-service-thin, feature:connector-registry-service-deliveries, feature:artifact-service |
| Sources | model/services/devops-gitops/PipelineExecutionService.yaml, model/services/integration/ConnectorRegistryService.yaml, docs/planes/execution/delivery-engine/services/pipeline-execution-service/index.md#workers-and-jobs |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-5109 DeliveryApplier for pull-request, review and push deliveries |
implementation | The ApplyDelivery handler and the DeliveryApplier worker apply ReviewRequestedChanges, NewCommits, ReviewApproved and Closed from the states the model draws, record new commits in ProposalCommits, write ChangeProposalStateChanged in the transaction of each transition, look up unknown references through Connectors.ReadPullRequest and deduplicate on deliveryId with the modelled retry and partitioning. | ConnectSoft.AI.SoftwareFactory.PipelineExecutionService |
AIFACTORY-TASK-5110 LinkValidation inbox handler for ArtifactValidated |
implementation | The handler of ArtifactValidated keeps the validator results of a change set that no proposal names yet and attaches them to the proposal whose changeSetRef names it when that proposal is opened, links them at once to an existing proposal, and is idempotent on the event id through the inbox of the pipeline-execution profile. | ConnectSoft.AI.SoftwareFactory.PipelineExecutionService |
AIFACTORY-TASK-5111 Verify mirror-proposal-review-state through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&Scenario=SCN-PipelineExecutionService-009"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-1281 over recorded DeliveryReceived and ArtifactValidated events, ArtifactValidated before and after the opening of the proposal, a duplicate delivery and a recorded answer of Connectors.ReadPullRequest for an unknown reference. |
ConnectSoft.AI.SoftwareFactory.PipelineExecutionService |
AIFACTORY-US-1282: Record the merge of an approved proposal with its merged commit and announce it¶
behavior · persona reviewer
A merge is a decision taken in the system of record by a person or a branch policy: no modelled operation of the service merges, and the model forbids an auto-merge to a protected branch without an approval of class shared-write recorded by the service. When DeliveryReceived of ConnectorRegistryService announces that the pull request of an Approved ChangeProposal was merged, the DeliveryApplier moves the proposal to Merged (trigger Merged), records mergedCommit, and writes in the same transaction ChangeProposalStateChanged from Approved to Merged and ChangeProposalMerged with proposalId, tenantId, projectId, runId and mergedCommit. The dispatcher publishes ChangeProposalMerged on pipelines.proposals.v1.change-proposal-merged under the run event envelope and retries a transport outage with backoff, so the event is neither lost nor duplicated (ADR-0012). The histogram connectsoft.factory.delivery.merge_lead_time records the time from proposal to merge, the agent-success signal for code changes. ReleaseService links the merged proposal to the next release (LinkProposal), RunControlService records the merged commit on the binding of the proposal to its run (BindChangeProposal, AIFACTORY-US-1606 of feature run-control-service), and WorkflowEngineService, GenerationRecipeService, RepositoryIntelligenceService, AuditService, FeedbackService and StudioBff consume it, each proven in its own suite. A merge delivered twice changes nothing. The model draws the merge only from Approved: a merge that the system of record reports for a proposal still in PullRequestOpen or ChangesRequested, as when a branch policy needs no review, has no transition, changes no state and is reported to the owner as an open point.
Acceptance criteria
| AC1 | Given an Approved PipelineExecutionService/ChangeProposal, when ConnectorRegistryService/DeliveryReceived announces the merge of its pull request, then the proposal moves to Merged with mergedCommit, and PipelineExecutionService/ChangeProposalStateChanged and PipelineExecutionService/ChangeProposalMerged are written in the same transaction (SCN-PipelineExecutionService-010, ADR-0014). |
| AC2 | Given the outbox record, when the dispatcher publishes PipelineExecutionService/ChangeProposalMerged on pipelines.proposals.v1.change-proposal-merged, then the event is sent under the run event envelope with proposalId, tenantId, projectId, runId and mergedCommit, and a transport outage is retried with backoff so the event is neither lost nor duplicated under its event id (SCN-PipelineExecutionService-010, ADR-0012). |
| AC3 | Given a merge delivery repeated, or a merge reported for a proposal in PullRequestOpen or ChangesRequested, when the DeliveryApplier runs, then the repeat changes nothing and the undrawn merge changes no state and publishes nothing, and no operation of the service ever merges a pull request (SCN-PipelineExecutionService-010, model/services/devops-gitops/PipelineExecutionService.yaml). |
| Traces: services | PipelineExecutionService, ConnectorRegistryService |
| Traces: aggregates | PipelineExecutionService/ChangeProposal |
| Traces: events | PipelineExecutionService/ChangeProposalMerged, PipelineExecutionService/ChangeProposalStateChanged, ConnectorRegistryService/DeliveryReceived |
| Traces: adrs | ADR-0012, ADR-0014 |
| Traces: requirements | FR-07, XL-10 |
| Traces: scenarios | SCN-PipelineExecutionService-010 |
| Depends on | AIFACTORY-US-1281, feature:connector-registry-service-deliveries |
| Sources | model/services/devops-gitops/PipelineExecutionService.yaml, docs/planes/execution/delivery-engine/services/pipeline-execution-service/index.md#messages |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-5112 Merged transition with ChangeProposalMerged and the merge lead time |
implementation | The DeliveryApplier applies Merged only from Approved, records mergedCommit, writes ChangeProposalStateChanged and ChangeProposalMerged in one transaction, publishes ChangeProposalMerged on its topic under the run event envelope and records connectsoft.factory.delivery.merge_lead_time; a merge reported from another state changes nothing. | ConnectSoft.AI.SoftwareFactory.PipelineExecutionService |
AIFACTORY-TASK-5113 Verify record-a-merged-proposal through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&Scenario=SCN-PipelineExecutionService-010"; a zero-match filter counts as a failure; the tests prove AC1 to AC3 of AIFACTORY-US-1282 with a transport that can be stopped; consumer handling is proven by the consumers' own suites. |
ConnectSoft.AI.SoftwareFactory.PipelineExecutionService |
AIFACTORY-US-1283: Mirror pipeline runs with stages and typed results and announce their start and completion¶
behavior · persona operator
When DeliveryReceived of ConnectorRegistryService announces a pipeline-run delivery, the DeliveryApplier records a PipelineRun once per tenant, system and external run reference (unique index UX_PipelineRuns_External) with its definitionRef, the pipeline definition the Factory generated from the pipeline blueprint, its commit, the proposal whose commits contain that commit and its stages, and writes PipelineRunStarted with pipelineRunId, tenantId, projectId, commit and the optional proposalId in the same transaction. When the run ends, the delivery sets the state Succeeded, Failed, Cancelled or PartiallySucceeded and completedAt, records one PipelineResult per result kind with passed, a summary of counts, percentages or severities and the artifact reference of the report, and writes PipelineRunCompleted with state and results in the same transaction. No request of the service starts a pipeline run, so the run correlation comes from the proposal: the PipelineRun takes the runId and the stepRunId that Pipelines.RecordProposal recorded on the proposal whose commits contain its commit (AIFACTORY-US-1277 of feature pipeline-execution-service-thin), and PipelineRunCompleted echoes them as optional members, absent when no run requested the proposal (D141). Results are receipts: logs and reports live in ArtifactService, never in the store. Both events are published under the run event envelope on pipelines.runs.v1.pipeline-run-started and pipelines.runs.v1.pipeline-run-completed, retried with backoff so neither is lost nor duplicated (ADR-0012). The run takes the state the system of record reported, because a run's state comes from a verified delivery or a connector read and is never assumed; a run may report Succeeded with a failed result, for example a failed step allowed to continue, so each failed result is recorded with passed false, its kind and its summary, and consumers judge readiness from the typed results. ReleaseService assembles a candidate from a succeeded run, RunControlService settles the step that waits for the pipeline run (SettleWaitingStep, AIFACTORY-US-1608 of this feature), WorkflowEngineService correlates it for the delivery run, and TemplateRegistryService, QualityScoreService, AuditService, StudioBff and DashboardService consume it, each in its own suite. The counter connectsoft.factory.delivery.pipeline_runs and the histogram connectsoft.factory.delivery.pipeline_duration record every completion. A repeated delivery changes nothing. The model gives PipelineRun no drawn transitions, so the order Queued or Running before a terminal state is read from PipelineRunState; DeliveryReceived with the pipeline-run deliveries of Azure DevOps arrives in I2 with feature connector-registry-service-deliveries (D135).
Acceptance criteria
| AC1 | Given a pipeline-run delivery for a commit of a merged proposal, when the DeliveryApplier applies it, then one PipelineExecutionService/PipelineRun exists for the tenant, system and external run reference with its definition, commit, proposal and stages, and PipelineExecutionService/PipelineRunStarted is written in the same transaction and published under the run event envelope with pipelineRunId, tenantId, projectId, commit and proposalId (SCN-PipelineExecutionService-011, ADR-0014). |
| AC2 | Given the completion delivery of that run, when it is applied, then the run takes its terminal state and completedAt, one result per kind is recorded with passed, summary and artifact reference, and PipelineExecutionService/PipelineRunCompleted is written in the same transaction and published with pipelineRunId, tenantId, projectId, commit, state and results, and with the runId and the stepRunId of the proposal of the commit when a run requested it and without them otherwise (SCN-PipelineExecutionService-012, D141). |
| AC3 | Given a run whose security scan or tests failed, when its completion is applied, then the run takes the state the system of record reported, each failed result is recorded with passed false, its kind and its summary, and PipelineExecutionService/PipelineRunCompleted carries those results so that consumers judge readiness from them (SCN-PipelineExecutionService-012, FR-07). |
| AC4 | Given a delivery repeated or the transport unavailable at dispatch, when the worker and the dispatcher run, then no second run, result or event is written, and each event is published once after recovery, neither lost nor duplicated under its event id (SCN-PipelineExecutionService-011, SCN-PipelineExecutionService-012, ADR-0012). |
| Traces: services | PipelineExecutionService, ConnectorRegistryService, ArtifactService |
| Traces: aggregates | PipelineExecutionService/PipelineRun |
| Traces: events | PipelineExecutionService/PipelineRunStarted, PipelineExecutionService/PipelineRunCompleted, ConnectorRegistryService/DeliveryReceived |
| Traces: adrs | ADR-0012, ADR-0014 |
| Traces: requirements | FR-07, XL-04 |
| Traces: scenarios | SCN-PipelineExecutionService-011, SCN-PipelineExecutionService-012 |
| Relates: screens | pipeline-runs |
| Depends on | AIFACTORY-US-1286, AIFACTORY-US-1287, feature:connector-registry-service-deliveries |
| Sources | model/services/devops-gitops/PipelineExecutionService.yaml, docs/planes/execution/delivery-engine/services/pipeline-execution-service/index.md#workers-and-jobs |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-317 Pipeline run intake from the system of record |
implementation | Verified pipeline-run deliveries become PipelineRuns with stages and one PipelineResult per kind with artifact references, with the RunId and StepRunId of the proposal of the commit when the proposal names them (D141); PipelineRunStarted and PipelineRunCompleted are written in the transaction of the change they announce; the run state is the one the delivery reported and every failed result carries passed false; a repeated delivery changes nothing. | ConnectSoft.AI.SoftwareFactory.PipelineExecutionService |
AIFACTORY-TASK-5114 Verify mirror-pipeline-runs through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-PipelineExecutionService-011\|Scenario=SCN-PipelineExecutionService-012)"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-1283 over recorded deliveries of a passing run and of a run with a failed security scan, and PipelineRunCompleted with and without the runId and stepRunId of a proposal (D141); consumer handling is proven by the consumers' own suites. |
ConnectSoft.AI.SoftwareFactory.PipelineExecutionService |
AIFACTORY-US-1284: List and read pipeline runs with their stages and typed results¶
behavior · persona operator
A caller whose scope carries factory.delivery.read lists pipeline runs through PipelineExecutionService/ListPipelineRuns, filtered by project, commit, proposal and state, and reads one run through PipelineExecutionService/GetPipelineRun with its stages and its typed results, each with kind, passed, summary and the artifact reference of its report or log in ArtifactService. The tenant comes from the trusted scope and the list holds only the runs of that tenant and of the projects in scope; the index IX_PipelineRuns_Commit serves the commit filter. Every query runs under the tenant row filter, so a run of another tenant never appears and is answered 404 when addressed, the same answer as for a pipelineRunId that does not exist (ADR-0015). A caller without the scope is refused with 403. A failed result is named so that a reader never takes a failed gate for a pass. Nothing is written and nothing is published by these reads. The routes are reached through the DeliveryHost gateway and read by the CLI; StudioBff renders them in its own increment.
Acceptance criteria
| AC1 | Given runs of several projects, commits, proposals and states in my tenant and in another tenant, when PipelineExecutionService/ListPipelineRuns is called with a filter, then the response is 200 with only the matching runs of my tenant and projects in scope and runs of the other tenant never appear (SCN-PipelineExecutionService-004, ADR-0015). |
| AC2 | Given a PipelineExecutionService/PipelineRun of my tenant and project with stages and results, when PipelineExecutionService/GetPipelineRun is called, then the response is 200 with its stages and each typed result with kind, passed, summary and artifact reference, a failed result named (SCN-PipelineExecutionService-005). |
| AC3 | Given a caller without factory.delivery.read, or a pipelineRunId that exists only in another tenant or not at all, when either route is called, then the response is 403 for the missing scope and 404 for the foreign or unknown run, each with a problem response and no state change (SCN-PipelineExecutionService-004, SCN-PipelineExecutionService-005, ADR-0015). |
| Traces: services | PipelineExecutionService |
| Traces: aggregates | PipelineExecutionService/PipelineRun |
| Traces: apis | PipelineExecutionService/ListPipelineRuns, PipelineExecutionService/GetPipelineRun |
| Traces: adrs | ADR-0015 |
| Traces: requirements | FUX-06 |
| Traces: scenarios | SCN-PipelineExecutionService-004, SCN-PipelineExecutionService-005 |
| Relates: screens | pipeline-runs |
| Depends on | AIFACTORY-US-1283 |
| Sources | model/services/devops-gitops/PipelineExecutionService.yaml, docs/planes/execution/delivery-engine/services/pipeline-execution-service/index.md#apis |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-5115 ListPipelineRuns and GetPipelineRun under the tenant row filter |
implementation | ListPipelineRuns filters by project, commit, proposal and state; GetPipelineRun returns stages and every PipelineResult with kind, passed, summary and artifact reference; both apply the tenant row filter so a foreign run is answered 404 like an unknown one, and a missing scope is 403. | ConnectSoft.AI.SoftwareFactory.PipelineExecutionService |
AIFACTORY-TASK-5116 Verify read-pipeline-runs through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-PipelineExecutionService-004\|Scenario=SCN-PipelineExecutionService-005)"; a zero-match filter counts as a failure; the tests prove AC1 to AC3 of AIFACTORY-US-1284 over a two-tenant fixture. |
ConnectSoft.AI.SoftwareFactory.PipelineExecutionService |
AIFACTORY-US-1285: Reconcile runs and proposals whose deliveries were missed, on schedule and on an Operator request¶
behavior · persona operator
As an operator, I want a run or a proposal whose delivery was missed read again from the system of record, so that no state is assumed and a missing completion never blocks a release silently.
A missing final delivery is reconciled by a read, never assumed. The RunReconciler worker runs every ten minutes, partitioned by tenant with at most four in parallel, and polls through Connectors.ReadPipelineRun and Connectors.ReadPullRequest of the Azure DevOps connector, read-class calls delivered in I2 by feature connector-registry-service-deliveries (D135), every run still non-terminal after Delivery:Pipelines:ReconcileAfterMinutes (60 by default, reloadable) and every proposal without a terminal state older than that threshold. A run found ended takes its terminal state and results and writes PipelineRunCompleted; a proposal found moved takes the transitions the model draws and writes ChangeProposalStateChanged, each in the transaction of its change. The worker is idempotent on pipelineRunId and window and retries three times with a fixed backoff of 120 seconds. An Operator whose scope carries factory.delivery.operate asks for the same read of one run through PipelineExecutionService/ReconcilePipelineRun; the answer is 202 and the result is observed through the run, not assumed. A run already terminal is read again and changes nothing, so a repeated request has one effect at most. A caller without the scope is refused with 403; a run of another tenant is answered 404, the same answer as for a run that does not exist (ADR-0015). When the system of record is unreachable the run and the proposal keep their state, nothing is marked done without a receipt and the next schedule tries again. The reconciler is proven against recorded answers of the two connector reads.
Acceptance criteria
| AC1 | Given a PipelineExecutionService/PipelineRun still Running after Delivery:Pipelines:ReconcileAfterMinutes whose completion delivery was missed, when the RunReconciler runs, then the run is read through ConnectorRegistryService/Connectors.ReadPipelineRun, takes its terminal state and results, and PipelineExecutionService/PipelineRunCompleted is written once in the transaction of the change; a second pass in the same window writes nothing (SCN-PipelineExecutionService-006, ADR-0014). |
| AC2 | Given a PipelineExecutionService/ChangeProposal without a terminal state older than the threshold whose review delivery was missed, when the RunReconciler runs, then the transitions the model draws are applied from the read and PipelineExecutionService/ChangeProposalStateChanged is written for each (model/services/devops-gitops/PipelineExecutionService.yaml). |
| AC3 | Given an Operator with factory.delivery.operate and a run of the Operator's tenant and project, when PipelineExecutionService/ReconcilePipelineRun is called, then the response is 202, the run is read from the system of record and its observed state is recorded once, PipelineExecutionService/PipelineRunCompleted is written once in the transaction of the change when the reconciled run is found ended, and a run already terminal changes nothing and publishes nothing (SCN-PipelineExecutionService-006). |
| AC4 | Given a caller without factory.delivery.operate, a run of another tenant or an unknown run, or a system of record that is unreachable, when PipelineExecutionService/ReconcilePipelineRun is called or the worker runs, then the answer is 403, 404 for the foreign and the unknown run alike, and for the unreachable system no state changes and nothing is published until a later read succeeds (SCN-PipelineExecutionService-006, ADR-0015). |
| Traces: services | PipelineExecutionService, ConnectorRegistryService |
| Traces: aggregates | PipelineExecutionService/PipelineRun, PipelineExecutionService/ChangeProposal |
| Traces: apis | PipelineExecutionService/ReconcilePipelineRun, ConnectorRegistryService/Connectors.ReadPipelineRun, ConnectorRegistryService/Connectors.ReadPullRequest |
| Traces: events | PipelineExecutionService/PipelineRunCompleted, PipelineExecutionService/ChangeProposalStateChanged |
| Traces: adrs | ADR-0014, ADR-0015 |
| Traces: requirements | NFR-08 |
| Traces: scenarios | SCN-PipelineExecutionService-006 |
| Relates: screens | pipeline-runs |
| Depends on | AIFACTORY-US-1281, AIFACTORY-US-1283, feature:connector-registry-service-deliveries |
| Sources | model/services/devops-gitops/PipelineExecutionService.yaml, docs/planes/execution/delivery-engine/services/pipeline-execution-service/index.md#failure-and-recovery |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-318 Reconciler for missed deliveries |
implementation | The RunReconciler reads, every ten minutes and per tenant, the runs and proposals still open after Delivery:Pipelines:ReconcileAfterMinutes through the connector, applies only the transitions the model draws, writes PipelineRunCompleted or ChangeProposalStateChanged with each change, keys its work by pipelineRunId and window and leaves state unchanged when the system of record is unreachable. | ConnectSoft.AI.SoftwareFactory.PipelineExecutionService |
AIFACTORY-TASK-5117 ReconcilePipelineRun route for the Operator |
implementation | POST /factory/delivery/pipeline-runs/{pipelineRunId}/reconcile reads the run through the connector under factory.delivery.operate, answers 202, records the observed state once, changes nothing for a terminal run and answers 403 or 404 as the model lists, a foreign run like an unknown one. | ConnectSoft.AI.SoftwareFactory.PipelineExecutionService |
AIFACTORY-TASK-5118 Verify reconcile-missed-deliveries through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&Scenario=SCN-PipelineExecutionService-006"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-1285 with recorded answers of Connectors.ReadPipelineRun and Connectors.ReadPullRequest that report a finished run, a moved proposal or nothing, and a clock moved past the threshold. |
ConnectSoft.AI.SoftwareFactory.PipelineExecutionService |
AIFACTORY-US-1286: Complete the domain model and the store of PipelineExecutionService¶
enabling
The complete delivery extends the thin domain model and store in the same repository. The ChangeProposal aggregate gains every transition of ProposalState the model draws, ReviewRequestedChanges, NewCommits, ReviewApproved, Merged and Closed, beside the opening transitions BranchPushed and PullRequestOpened, and keeps its three invariants: the system of record is the truth, a Factory-authored commit carries its trailers, and the Factory never merges without a recorded approval. The PipelineRun aggregate arrives with its PipelineResult entities, the states of PipelineRunState, the result kinds of ResultKind and its two invariants: results are receipts with artifact references, and a state comes from a verified delivery or a connector read and is never assumed. The store pipeline-execution-sql gains the tables PipelineRuns and PipelineResults with the unique index UX_PipelineRuns_External, the index IX_PipelineRuns_Commit, the foreign key from a run to its proposal and the tenant filter on every table; a migration adds them to the store of the thin delivery without touching its rows. Mapping tests run against an isolated test database. When the store is lost it is restored from backup within the recovery point of 15 minutes and receipts can be re-pulled from the system of record through the connectors.
Acceptance criteria
| AC1 | Given the domain model, when its unit tests run, then the PipelineExecutionService/ChangeProposal applies each of its seven drawn transitions from its source state only and refuses every other move, and the PipelineExecutionService/PipelineRun refuses a result without a kind or a state that no delivery or read announced (ADR-0014). |
| AC2 | Given the store of the thin delivery with proposals in it, when the migration of the complete delivery runs, then PipelineRuns and PipelineResults exist with their keys, indexes, foreign key and tenant filter, the existing proposal rows are unchanged, and the mapping tests pass against an isolated test database (ADR-0015, model/services/devops-gitops/PipelineExecutionService.yaml). |
| Traces: services | PipelineExecutionService |
| Traces: aggregates | PipelineExecutionService/ChangeProposal, PipelineExecutionService/PipelineRun |
| Traces: adrs | ADR-0014, ADR-0015 |
| Depends on | feature:pipeline-execution-service-thin |
| Sources | model/services/devops-gitops/PipelineExecutionService.yaml, docs/planes/execution/delivery-engine/services/pipeline-execution-service/index.md#domain-model |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-255 Domain model: ChangeProposal, PipelineRun |
implementation | Aggregates with their invariants and state transitions as modelled; unit tests cover every invariant and every transition. | ConnectSoft.AI.SoftwareFactory.PipelineExecutionService |
AIFACTORY-TASK-256 Persistence in pipeline-execution-sql: ChangeProposals, ProposalCommits, PipelineRuns, PipelineResults |
migration | Mappings and migrations for the modelled tables with tenant filters and indexes; the migration adds PipelineRuns and PipelineResults beside the thin tables without changing their rows; mapping tests run against an isolated test database, never a shared one. | ConnectSoft.AI.SoftwareFactory.PipelineExecutionService |
AIFACTORY-TASK-5119 Verify the complete domain and store of PipelineExecutionService |
verification | Run dotnet test -c Release --filter "Category=Unit\|Category=Mapping"; a zero-match filter counts as a failure; the tests prove AC1 and AC2 of AIFACTORY-US-1286 against model/services/devops-gitops/PipelineExecutionService.yaml. |
ConnectSoft.AI.SoftwareFactory.PipelineExecutionService |
AIFACTORY-US-1287: Host every operation, event and handler of PipelineExecutionService with its security and telemetry¶
enabling
The complete delivery hosts the six REST routes and the gRPC method of the model behind the scopes factory.delivery.read, factory.delivery.propose and factory.delivery.operate, with problem responses for every modelled code, the Idempotency-Key filter of OpenChangeProposal and the workload check of Pipelines.RecordProposal under its service scope factory.delivery.propose (D135); the behaviour of each operation is delivered by its own PBI. The messaging profile pipeline-execution publishes the five events of the service under the run event envelope through its outbox and registers the two consumed events, DeliveryReceived of ConnectorRegistryService and ArtifactValidated of ArtifactService, in its inbox with idempotency on the event id; the gauge connectsoft.factory.delivery.inbox_lag reports the age of the oldest unprocessed message. The workers DeliveryApplier and RunReconciler are hosted with their modelled triggers, retry policies, partitioning and idempotency keys, while their behaviour belongs to AIFACTORY-US-1281, AIFACTORY-US-1282, AIFACTORY-US-1283 and AIFACTORY-US-1285. Tenant isolation is a row filter on every query; the only secret, the messaging transport, comes from Key Vault by reference with a rotation of 90 days; the data classification is internal and the highest side-effect class is shared-write. A user token reaches the service with the audience of its gateway, DeliveryHost, which the service accepts (ADR-0015 amendment D117). Traces, the five metrics of the model and health checks follow the observability conventions, and readiness stays unready while the store is unavailable.
Acceptance criteria
| AC1 | Given the hosted service, when each of the six REST routes and PipelineExecutionService/Pipelines.RecordProposal is called without a token, with a token lacking its scope or without a workload identity, then it is refused with the modelled problem response or gRPC status before any handler runs (ADR-0015, model/services/devops-gitops/PipelineExecutionService.yaml). |
| AC2 | Given the messaging profile pipeline-execution, when the contract tests run, then the five published events, among them PipelineExecutionService/ChangeProposalStateChanged, carry their modelled payload under the run event envelope, and ConnectorRegistryService/DeliveryReceived and ArtifactService/ArtifactValidated are registered in the inbox with idempotency on the event id (ADR-0012, ADR-0014). |
| AC3 | Given a query of any route, when it runs, then it is filtered by the trusted tenant, the five metrics of the model are emitted with their dimensions, and no secret value reaches a log record, an event or a reply (ADR-0015). |
| Traces: services | PipelineExecutionService |
| Traces: apis | PipelineExecutionService/Pipelines.RecordProposal |
| Traces: events | PipelineExecutionService/ChangeProposalStateChanged, ConnectorRegistryService/DeliveryReceived, ArtifactService/ArtifactValidated |
| Traces: adrs | ADR-0012, ADR-0014, ADR-0015 |
| Traces: requirements | NFR-12 |
| Depends on | AIFACTORY-US-1286, feature:delivery-host, feature:connector-registry-service-deliveries, feature:artifact-service |
| Sources | model/services/devops-gitops/PipelineExecutionService.yaml, docs/planes/execution/delivery-engine/services/pipeline-execution-service/index.md#security |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-257 API surface: 6 REST and 1 gRPC operations (ListChangeProposals, GetChangeProposal, OpenChangeProposal, ListPipelineRuns, GetPipelineRun, ReconcilePipelineRun and 1 more) |
implementation | Every modelled operation is hosted with its scope, side-effect class, idempotency rule and problem responses, and the OpenAPI and proto documents match the model; the behaviour of each operation is delivered by AIFACTORY-US-1276, AIFACTORY-US-1277, AIFACTORY-US-1280, AIFACTORY-US-1284 and AIFACTORY-US-1285. | ConnectSoft.AI.SoftwareFactory.PipelineExecutionService |
AIFACTORY-TASK-258 Messaging: publishes 5 events, handles 2 |
implementation | Events are published through the outbox of the service with the run envelope (ChangeProposalOpened, ChangeProposalStateChanged, ChangeProposalMerged, PipelineRunStarted, PipelineRunCompleted); consumed events are handled idempotently through its inbox. | ConnectSoft.AI.SoftwareFactory.PipelineExecutionService |
AIFACTORY-TASK-259 Hosting of the workers DeliveryApplier and RunReconciler |
implementation | The DeliveryApplier is hosted on DeliveryReceived with exponential retry of five attempts, partitioning by repository and the idempotency key deliveryId, and the RunReconciler on its ten-minute schedule with fixed retry of three attempts, partitioning by tenant and the idempotency key pipelineRunId and window; a duplicate trigger has no second effect. Only the trigger, retry, partitioning and idempotency key wiring is done here; the behaviour of each worker is implemented by AIFACTORY-TASK-5109, AIFACTORY-TASK-5112, AIFACTORY-TASK-317 and AIFACTORY-TASK-318. | ConnectSoft.AI.SoftwareFactory.PipelineExecutionService |
AIFACTORY-TASK-260 Security, tenancy and telemetry of PipelineExecutionService |
implementation | Scopes and roles of the model are enforced, every query is tenant-filtered, secrets come from secret references, and traces, metrics and health checks follow the observability conventions. | ConnectSoft.AI.SoftwareFactory.PipelineExecutionService |
AIFACTORY-TASK-5120 Verify the hosting of PipelineExecutionService through the contract suite |
verification | Run dotnet test -c Release --filter "Category=Contract"; a zero-match filter counts as a failure; the tests prove AC1 to AC3 of AIFACTORY-US-1287 against model/services/devops-gitops/PipelineExecutionService.yaml and model/descriptors.yaml. |
ConnectSoft.AI.SoftwareFactory.PipelineExecutionService |
AIFACTORY-US-1608: RunControlService settles the step of a run that waits for the pipeline run of its merged commit with the reference of the typed results¶
behavior · persona operator
As an operator, I want the step of a run that waits for the pipeline run of its merged change settled once that pipeline run completed, so that the run goes on with the receipt of the pipeline run and never waits on a run that has already ended.
The inbox handler SettleWaitingStep of RunControlService takes PipelineExecutionService/PipelineRunCompleted, which carries pipelineRunId, tenantId, projectId, commit, state and results and the optional runId and stepRunId of the requesting step. RunControlService itself is delivered in I1 by feature run-control-service, but the complete producer of this event arrives with this feature in I2, so the handler for it is delivered here and its tasks are written in the repository ConnectSoft.AI.SoftwareFactory.RunControlService (D140); the same handler of PromotionCompleted and PromotionFailed is delivered by feature environment-promotion-service (AIFACTORY-US-1621). The handler registers the event in the inbox of the messaging profile run-control, idempotent on the event id. The requesting step passes its runId and its stepRunId with the proposal it records through Pipelines.RecordProposal, the pipeline run of the merged commit takes them from that proposal, and the event echoes them, absent when no run requested the pipeline run (D141, AIFACTORY-US-1283). The handler looks up the waiting step directly by them: under the tenant of the event it takes the Step whose step run id is the stepRunId of the event in the Run that runId names, and it ignores an event without them; it no longer finds the run through the merged commit of a change proposal binding. When that run is neither terminal nor Cancelling, the step moves to Succeeded with the pipeline run as its result reference, whatever state the system of record reported: results are receipts, readiness is judged from the typed results by WorkflowEngineService and by the steps that read them and never from the run state alone (FR-07, AIFACTORY-US-1283), and the purpose the model gives the handler names a settlement with the reference of the typed results and no failed settlement. RunControlService/StepSettled is written in the transaction that moves the step, with the step run id of the engine, the stepId, the final state Succeeded, the number of attempts and, in outputRef, the reference of the pipeline run (D119, D121); WorkflowEngineService advances the run on that event in its own PBI. No workflow definition of the model has a step that waits for a pipeline run yet, delivery-run, release and debt-review taking PipelineRunCompleted as a readiness signal of WorkflowEngineService; this PBI also reads outputRef, which the model describes as a reference in ArtifactService, as able to hold the reference of the pipeline run, a reading reported to the owner. An event without runId and stepRunId, an event whose runId names a run of another tenant or no run, an event whose stepRunId names no step of that run, a run that is terminal or Cancelling, a step already in a final state and a redelivered event change nothing and publish nothing. When run-control-sql does not answer, the inbox keeps the event and retries it, and the event is applied once.
Acceptance criteria
| AC1 | Given a Running RunControlService/Run of tenant A and its open RunControlService/Step that requested the pipeline run, when PipelineExecutionService/PipelineRunCompleted names the runId of that run and the stepRunId of that step with the state Succeeded and SettleWaitingStep handles it (D141), then the step moves to Succeeded with the pipeline run as its result reference and RunControlService/StepSettled is written in the same transaction with the step run id of the engine, the stepId, the final state Succeeded, the number of attempts and the reference of the pipeline run in outputRef; a redelivery under the same event id changes nothing (model/services/control-plane/RunControlService.yaml, ADR-0014). |
| AC2 | Given the same waiting step, when PipelineExecutionService/PipelineRunCompleted names the same runId and stepRunId with the state Failed and a failed security scan among its results, then the step is settled Succeeded with the reference of the pipeline run in the same way and RunControlService/StepSettled is written, and the failed result is left to the reader of the typed results (FR-07, model/services/devops-gitops/PipelineExecutionService.yaml). |
| AC3 | Given an event without runId and stepRunId, an event of tenant B whose runId names a run of tenant A, an event whose stepRunId names no step of the run, a run that is Completed or Cancelling, or run-control-sql stopped while the event arrives (D141), when PipelineExecutionService/PipelineRunCompleted is handled, then the first four change no step and write no RunControlService/StepSettled, and the last is retried by the inbox until the store answers and is applied once under its event id (ADR-0012, ADR-0015). |
| Traces: services | RunControlService, PipelineExecutionService, WorkflowEngineService |
| Traces: aggregates | RunControlService/Run, RunControlService/Step |
| Traces: events | PipelineExecutionService/PipelineRunCompleted, RunControlService/StepSettled |
| Traces: adrs | ADR-0012, ADR-0014, ADR-0015 |
| Traces: requirements | FR-07 |
| Depends on | AIFACTORY-US-1283, feature:run-control-service, feature:contracts-package |
| Sources | model/services/control-plane/RunControlService.yaml, model/services/devops-gitops/PipelineExecutionService.yaml, model/workflows/delivery-run.yaml |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-6506 SettleWaitingStep of RunControlService for PipelineRunCompleted |
implementation | The inbox of the RunControlService messaging profile registers PipelineRunCompleted with idempotency on the event id; SettleWaitingStep looks up the waiting step directly by the runId and stepRunId the event echoes, under the tenant of the event, and ignores an event without them (D141); in a run that is neither terminal nor Cancelling it moves the step to Succeeded with the pipeline run as its result reference whatever state the event reports, and writes StepSettled with the step run id, the stepId, the final state, the number of attempts and the reference of the pipeline run in outputRef in the same transaction; an event without runId and stepRunId, of a run of another tenant or of no run, of a step run the run does not hold, for a terminal or Cancelling run or for a step in a final state changes nothing. | ConnectSoft.AI.SoftwareFactory.RunControlService |
AIFACTORY-TASK-6507 Fixture pipeline run events and waiting steps of the settlement suite |
fixture | The acceptance suite of RunControlService holds fixture events PipelineRunCompleted with the states Succeeded and Failed and with a failed security scan in their results for two tenants, built from the event types of the pinned contracts package under the run event envelope, with the runId and stepRunId of a waiting step, with an unknown stepRunId and without both (D141), runs with a waiting step, a Completed run, a Cancelling run, and a switch that stops run-control-sql while an event arrives. | ConnectSoft.AI.SoftwareFactory.RunControlService |
AIFACTORY-TASK-6508 Verify settle-the-step-waiting-for-a-pipeline-run through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&Feature=SettleWaitingStepOnPipelineRun" in the repository of RunControlService; a zero-match filter counts as a failure; the tests prove AC1 to AC3 of AIFACTORY-US-1608 with the fixture of AIFACTORY-TASK-6507: the waiting step settled Succeeded with the reference of the pipeline run on a Succeeded and on a Failed pipeline run, RunControlService/StepSettled in the transaction of the move, the events that change nothing, and the retry while the store is stopped with one application under the event id. |
ConnectSoft.AI.SoftwareFactory.RunControlService |