AIFACTORY-FEAT-041: PipelineExecutionService: thin delivery for the first outcome¶
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 I1 Generate a microservice · State elaborated · Route backend-developer · Build order 73 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). In this increment it is delivered thin: The ChangeProposal aggregate and the path that opens a proposal in the system of record; no pipeline runs. Its own repository is ConnectSoft.AI.SoftwareFactory.PipelineExecutionService.
| Delivers | PipelineExecutionService (thin): The ChangeProposal aggregate and the path that opens a proposal in the system of record; no pipeline runs. |
| Stubs | — |
| Realizes | adrs: ADR-0014 |
| Requirements | FR-07, FUX-05, FUX-06, NFR-08, NFR-12, XL-04, XL-10 |
| Depends on | — |
| 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-017: Approve the exact change set and open the change proposal¶
behavior · persona reviewer
As a reviewer, I want to approve the exact change set a run produced before it reaches the repository, so that nothing is written to the system of record that a person did not approve.
This is the integration PBI of the thin delivery of PipelineExecutionService, the receipts service of bounded context BC-23. The thin scope stated in model/backlog/features/devops-gitops.yaml is the ChangeProposal aggregate and the path that opens a proposal in the system of record, and the delivery holds exactly that and nothing more. When generate-product reaches its Human step approve-proposal, RunControlService opens an approval request whose subject is the run and the step (D129), bound to the hash of the change set the run recorded; the request appears in the approvals list of an eligible Reviewer, the requester of the run never decides, and a regenerated change set makes the pending request Stale. Until I4 this human approval always runs, whatever the project policy answers (D133). The approval itself, its list and its decision are delivered by feature run-control-service, the step by feature wf-generate-product and the approvals list command by feature command-line-client-commands; this feature consumes them. When the Reviewer approved, the tool propose-change-set executes in ToolAdapterService under the run's workload identity. In I1 the opening path is the one the owner decided (D135): the tool opens the pull request through the Azure DevOps connection that IntegrationService/Connections.Resolve returns for the project, with a credential from the Secret Broker (feature connector-registry-service-thin, AIFACTORY-US-066), and records it through the internal Pipelines.RecordProposal with the request descriptor change-proposal-record-v1, which carries the change set, the run, the attempt, the agent release, the pull-request reference and the tool receipt, under the service scope factory.delivery.propose (AIFACTORY-US-1277). One ChangeProposal then exists per run and change set, with its provenance to the run, the attempt, the agent release and the change-set artifact, in state PullRequestOpen, and ChangeProposalOpened is published once in the transaction of that transition (AIFACTORY-US-1278). OpenChangeProposal, the REST route that pushes the branch from this service, is not in the thin scope: it stays the route of a person and arrives with a connector path of PipelineExecutionService in feature pipeline-execution-service-complete (AIFACTORY-US-1276, D135). The thin delivery reads no proposal over REST, mirrors no review or merge, records no pipeline run, reconciles nothing and handles no consumed event: those arrive with feature pipeline-execution-service-complete in I2. A step's own compensation runs only after its effect is confirmed (D133), so a failed recording withdraws nothing; no modelled operation withdraws a confirmed proposal, so the declared compensation of propose-change-set stays an open point of the model. Repository: ConnectSoft.AI.SoftwareFactory.PipelineExecutionService.
Acceptance criteria
| AC1 | Given the outputs of the run are recorded, when the run reaches generate-product/approve-proposal, then RunControlService opens through RunControlService/RunControl.RequestApproval an approval request that names the run and the step as its subject and is bound to the hash of the change set, RunControlService/ApprovalRequested is published, and the request appears in RunControlService/ListApprovals of an eligible Reviewer with the bound hash (ADR-0015). |
| AC2 | Given I requested the run, when I try to decide the approval through RunControlService/DecideApproval, then I am refused because the requester never decides; given the change set is regenerated while the RunControlService/ApprovalRequest is pending, then the request is Stale and an approval of it never reaches generate-product/propose-change-set. |
| AC3 | Given I approved the exact hash, when generate-product/propose-change-set runs the tool propose-change-set and ToolAdapterService opened the pull request through the connection of IntegrationService/Connections.Resolve, then a PipelineExecutionService/ChangeProposal in state PullRequestOpen exists once for the run and the change set, recorded through PipelineExecutionService/Pipelines.RecordProposal with a change-proposal-record-v1 request carrying branch, pull-request reference, tool receipt and provenance, and PipelineExecutionService/ChangeProposalOpened is published once (XL-10, ADR-0014, D135). |
| AC4 | Given the thin delivery is deployed on an I1 instance, when its surface is inspected, then it serves PipelineExecutionService/Pipelines.RecordProposal, publishes PipelineExecutionService/ChangeProposalOpened and nothing else, every other operation, event, worker and handler of model/services/devops-gitops/PipelineExecutionService.yaml arriving with feature pipeline-execution-service-complete, and the contracts it serves match the model so that the complete delivery replaces it without a contract change. |
| Traces: services | PipelineExecutionService, RunControlService, ToolAdapterService, IntegrationService, ConnectorRegistryService, AuditService |
| Traces: aggregates | RunControlService/ApprovalRequest, PipelineExecutionService/ChangeProposal |
| Traces: apis | RunControlService/RunControl.RequestApproval, RunControlService/DecideApproval, RunControlService/ListApprovals, PipelineExecutionService/Pipelines.RecordProposal, IntegrationService/Connections.Resolve |
| Traces: events | RunControlService/ApprovalRequested, PipelineExecutionService/ChangeProposalOpened |
| Traces: steps | generate-product/approve-proposal, generate-product/propose-change-set |
| Traces: tools | propose-change-set |
| Traces: descriptors | pull-request-proposal-v1, change-set-v1, change-proposal-record-v1 |
| Traces: adrs | ADR-0014, ADR-0015, ADR-0027 |
| Traces: requirements | FR-07, XL-10 |
| Relates: screens | proposals |
| Depends on | AIFACTORY-US-1277, AIFACTORY-US-1278, AIFACTORY-US-1279, feature:run-control-service, feature:tool-adapter-service, feature:wf-generate-product, feature:command-line-client-commands, feature:integration-service-thin, feature:connector-registry-service-thin, feature:secret-broker-service |
| Sources | model/services/devops-gitops/PipelineExecutionService.yaml, model/backlog/features/devops-gitops.yaml, model/workflows/generate-product.yaml, docs/planes/execution/delivery-engine/services/pipeline-execution-service/index.md#purpose-and-responsibilities |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-226 Fixture of a recorded change set and the proposal the tool opened for it |
fixture | The acceptance suite of the service holds a fixture of a change set the tool proposed: a change-proposal-record-v1 request whose change-set-v1 document has its hash and diff reference stored in a fake of ArtifactService, with the run, the attempt and the agent release of the provenance, the pull-request reference and the receipt of propose-change-set for a pull request opened in a sandbox Azure DevOps project, as the oracle of SCN-PipelineExecutionService-007 and SCN-PipelineExecutionService-008; the fixture holds no approval request, because no operation of PipelineExecutionService reads one, and the approval is proven by the suites of feature run-control-service. | ConnectSoft.AI.SoftwareFactory.PipelineExecutionService |
AIFACTORY-TASK-228 Verify that approvals list shows the bound change-set hash of approve-proposal |
verification | The acceptance suite of the client repository runs approvals list of feature command-line-client-commands (AIFACTORY-US-376) against a fixture approval request of generate-product/approve-proposal and finds the change-set hash the request is bound to in the printed row, which proves the reviewer-facing half of AC1 of AIFACTORY-US-017; no command is written here. |
ConnectSoft.AI.SoftwareFactory.Cli |
AIFACTORY-TASK-710 Verify approve-and-propose by running the declared command |
verification | Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-PipelineExecutionService-007\|Scenario=SCN-PipelineExecutionService-008)"; a zero-match filter counts as a failure; the tests prove AC3 and AC4 of AIFACTORY-US-017 on the fixture of AIFACTORY-TASK-226. AC1 is proven by AIFACTORY-TASK-879 (request-an-approval, AIFACTORY-US-165) and AC2 by AIFACTORY-TASK-883 (decide-an-approval, AIFACTORY-US-166) of feature run-control-service, together with AIFACTORY-TASK-228 for the hash shown to the Reviewer. |
ConnectSoft.AI.SoftwareFactory.PipelineExecutionService |
AIFACTORY-US-1277: Record a proposal that the propose-change-set tool opened, with its receipt, exactly once¶
behavior
ToolAdapterService, the inbound caller the model names for this method, calls the internal gRPC method PipelineExecutionService/Pipelines.RecordProposal with its workload identity after the tool propose-change-set opened a pull request through the connection that IntegrationService/Connections.Resolve returned for the project with a credential from the Secret Broker, and sends the request descriptor change-proposal-record-v1 (D135): the trusted scope, the change set as change-set-v1 (changeSetId, repository, baseRevision, branch, hash, diffRef, build and test results), changeSetRef, runId, the optional stepId, the optional stepRunId of the requesting step (D141), attemptId, agentReleaseId, the pullRequest (system, repository, branch, target branch and pullRequestRef) and the toolReceipt of the invocation. This is the path through which the thin delivery opens a proposal in the system of record. The service records one ChangeProposal with its provenance to the run, the attempt, the agent release and the change-set artifact, applies the transitions Proposed, BranchCreated (BranchPushed) and PullRequestOpen (PullRequestOpened) in one transaction, records the commits in ProposalCommits with their trailers, writes the ChangeProposalOpened outbox record in that transaction (AIFACTORY-US-1278) and replies ack-v1. The side effect of this shared-write method happens once: a repeated call for the same run and change-set hash replies the same acknowledgement and writes nothing; from I2 the same rule keeps one proposal when the change set also arrives through OpenChangeProposal (AIFACTORY-US-1276). A caller without a workload identity is refused with UNAUTHENTICATED, a workload whose token does not hold the service scope factory.delivery.propose with PERMISSION_DENIED, and a request that fails the validation of change-proposal-record-v1 or carries no provenance with INVALID_ARGUMENT, because a proposal without provenance is not Factory-authored; nothing is written on any refusal. When ArtifactService, a fail-fast dependency, is unavailable the call fails with UNAVAILABLE and writes nothing, and the caller repeats it. Tenant and project are read from the forwarded scope only under the service scope that names them (ADR-0015 amendment D114). The proposal records the pull-request reference, the tool receipt and the provenance from the members of change-proposal-record-v1, and keeps the stepRunId beside the runId in the nullable column StepRunId of ChangeProposals, because no request of this service starts a pipeline run: the pipeline run of the merged commit takes both from this proposal and PipelineRunCompleted echoes them (AIFACTORY-US-1283 of feature pipeline-execution-service-complete, D141).
Acceptance criteria
| AC1 | Given ToolAdapterService with a workload identity holding factory.delivery.propose and a change-proposal-record-v1 request for a proposal the tool opened, when PipelineExecutionService/Pipelines.RecordProposal is called, then the reply carries ack-v1, one PipelineExecutionService/ChangeProposal exists in state PullRequestOpen with its provenance (run, attempt, agent release), its pull-request reference, its tool receipt and its commits, and the PipelineExecutionService/ChangeProposalOpened outbox record is written in the same transaction (SCN-PipelineExecutionService-007, ADR-0014, D135). |
| AC2 | Given the same run and change-set hash recorded before, when PipelineExecutionService/Pipelines.RecordProposal is called again, then the same acknowledgement is returned, no second proposal or commit row is written and no second event is published (SCN-PipelineExecutionService-007). |
| AC3 | Given a caller without a workload identity, a token without the service scope factory.delivery.propose, or a request that fails the validation of change-proposal-record-v1 or names no provenance, when PipelineExecutionService/Pipelines.RecordProposal is called, then the call is refused with UNAUTHENTICATED, PERMISSION_DENIED or INVALID_ARGUMENT respectively and no state changes (SCN-PipelineExecutionService-007, ADR-0015). |
| AC4 | Given ArtifactService is unavailable, when PipelineExecutionService/Pipelines.RecordProposal is called, then the call fails with UNAVAILABLE, nothing is written or published, and the repeat after recovery records the proposal once (SCN-PipelineExecutionService-007, model/services/devops-gitops/PipelineExecutionService.yaml). |
| Traces: services | PipelineExecutionService, ToolAdapterService, ArtifactService |
| Traces: aggregates | PipelineExecutionService/ChangeProposal |
| Traces: apis | PipelineExecutionService/Pipelines.RecordProposal |
| Traces: events | PipelineExecutionService/ChangeProposalOpened |
| Traces: descriptors | change-proposal-record-v1, change-set-v1, ack-v1 |
| Traces: adrs | ADR-0014, ADR-0015 |
| Traces: requirements | FR-07 |
| Traces: scenarios | SCN-PipelineExecutionService-007 |
| Depends on | AIFACTORY-US-1279, feature:tool-adapter-service, feature:artifact-service |
| Sources | model/services/devops-gitops/PipelineExecutionService.yaml, model/descriptors.yaml, docs/planes/execution/delivery-engine/services/pipeline-execution-service/index.md#apis |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-5103 Pipelines.RecordProposal with one effect per run and change-set hash |
implementation | The gRPC method checks the service scope factory.delivery.propose, validates change-proposal-record-v1 and the provenance, records the proposal with its pull-request reference and tool receipt, the runId and the optional stepRunId of the requesting step (D141), with BranchPushed and PullRequestOpened applied in one transaction with the ChangeProposalOpened outbox record, writes ProposalCommits, replies ack-v1, deduplicates on run and change-set hash and refuses with UNAUTHENTICATED, PERMISSION_DENIED, INVALID_ARGUMENT or UNAVAILABLE without writing anything. | ConnectSoft.AI.SoftwareFactory.PipelineExecutionService |
AIFACTORY-TASK-5104 Verify record-a-proposal-receipt through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&Scenario=SCN-PipelineExecutionService-007"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-1277 on the fixture of AIFACTORY-TASK-226, including one proposal when the same run and change-set hash are recorded twice. |
ConnectSoft.AI.SoftwareFactory.PipelineExecutionService |
AIFACTORY-US-1278: Publish ChangeProposalOpened once for every opened proposal through the outbox¶
behavior
When a ChangeProposal reaches PullRequestOpen through the opening path, in I1 through Pipelines.RecordProposal (AIFACTORY-US-1277) and from I2 also through OpenChangeProposal (AIFACTORY-US-1276 of feature pipeline-execution-service-complete), the service writes the outbox record of ChangeProposalOpened in the same transaction as the transition (ADR-0014), under the messaging profile of the service named pipeline-execution by OrleansMessaging:ServiceName, whose inbox and outbox belong to this service alone (ADR-0028). The dispatcher publishes the event on pipelines.proposals.v1.change-proposal-opened under the run event envelope of the contracts package (ADR-0014 amendment D114) with the payload proposalId, tenantId, projectId, runId, repository and the optional pullRequestRef, and with the run, step and attempt of the provenance in the envelope. A transport outage is retried with backoff, so the event is neither lost nor published twice under its event id (ADR-0012); one proposal yields one event whichever entry point opened it. Publication is not proof of the transition: the state is in the store, the event announces it. The consumers the model names, WorkflowEngineService, which correlates it with the run, RunControlService, which binds the proposal to the run, AuditService, which records it as evidence, StudioBff and DashboardService in their increments, prove their handling in their own suites; this PBI proves what the publisher can prove. A refused or failed recording publishes nothing.
Acceptance criteria
| AC1 | Given a PipelineExecutionService/ChangeProposal moved to PullRequestOpen through PipelineExecutionService/Pipelines.RecordProposal, when the transaction commits, then exactly one outbox record of PipelineExecutionService/ChangeProposalOpened was written in that transaction, and none is written for a refused or failed call (SCN-PipelineExecutionService-008, ADR-0014). |
| AC2 | Given the outbox record, when the dispatcher of the pipeline-execution profile publishes PipelineExecutionService/ChangeProposalOpened on pipelines.proposals.v1.change-proposal-opened, then the event is sent under the run event envelope with proposalId, tenantId, projectId, runId, repository and pullRequestRef, and the run, step and attempt of the provenance (SCN-PipelineExecutionService-008, ADR-0028). |
| AC3 | Given the transport is unavailable when the record is dispatched, when it recovers, then the event is published with backoff, neither lost nor duplicated under its event id, and a redelivery to a consumer carries the same event id so the consumer can deduplicate (SCN-PipelineExecutionService-008, ADR-0012). |
| Traces: services | PipelineExecutionService |
| Traces: aggregates | PipelineExecutionService/ChangeProposal |
| Traces: apis | PipelineExecutionService/Pipelines.RecordProposal |
| Traces: events | PipelineExecutionService/ChangeProposalOpened |
| Traces: adrs | ADR-0012, ADR-0014, ADR-0028 |
| Traces: scenarios | SCN-PipelineExecutionService-008 |
| Depends on | AIFACTORY-US-1279, feature:contracts-package |
| 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-5105 Outbox publication of ChangeProposalOpened under the run event envelope |
implementation | The outbox writer of the pipeline-execution profile enlists in the transaction of the PullRequestOpened transition, and the dispatcher publishes ChangeProposalOpened on pipelines.proposals.v1.change-proposal-opened under the run event envelope of the contracts package with the modelled payload, retrying with backoff on a transport outage. | ConnectSoft.AI.SoftwareFactory.PipelineExecutionService |
AIFACTORY-TASK-5106 Verify publish-change-proposal-opened through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&Scenario=SCN-PipelineExecutionService-008"; a zero-match filter counts as a failure; the tests prove AC1 to AC3 of AIFACTORY-US-1278 with a transport that can be stopped; consumer handling is proven by the consumers' own suites. |
ConnectSoft.AI.SoftwareFactory.PipelineExecutionService |
AIFACTORY-US-1279: Scaffold PipelineExecutionService with the ChangeProposal aggregate and its store for the thin scope¶
enabling
PipelineExecutionService has its own repository, ConnectSoft.AI.SoftwareFactory.PipelineExecutionService, its own deployable and its own store (ADR-0028). The repository is created and scaffolded in I0 by AIFACTORY-TASK-092 of feature repository-and-pipeline-conventions (D140), by the steps of its repository checklist, and this feature starts from that scaffold; it is scaffolded once from the pinned base template package with UseFactoryProfile (feature component-base-template-factory-profile, consumed by its pinned version), so token validation, scope enforcement, problem responses, the tenant row filter, health, readiness and the telemetry wiring come from the profile and are not written again. The thin scope adds the ChangeProposal aggregate with its fields, its invariants and the transitions BranchPushed and PullRequestOpened that the recording path uses, the tables ChangeProposals and ProposalCommits of the store pipeline-execution-sql with their keys, indexes and tenant filters, the outbox of the Orleans messaging profile under the service name pipeline-execution, the options Delivery:Pipelines:CommitTrailerKeys, whose keys the recorded commits carry in ProposalCommits, and Delivery:Systems:DefaultSystemOfRecord, the gauge connectsoft.factory.delivery.proposals, and the workload check of the gRPC method. No REST route is served in I1. The other transitions of ProposalState, the PipelineRun aggregate with its tables, the REST routes, the inbox handlers, the workers and the other operations are left to feature pipeline-execution-service-complete; the contracts that the thin delivery serves already match the model, so the complete delivery replaces the thin one without a contract change.
Acceptance criteria
| AC1 | Given the repository created and scaffolded in I0 by AIFACTORY-TASK-092 of feature repository-and-pipeline-conventions, whose first commit is the unchanged output of dotnet new connectsoft-base -n ConnectSoft.AI.SoftwareFactory.PipelineExecutionService --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 and the tests pass (ADR-0028, model/services/devops-gitops/PipelineExecutionService.yaml). |
| AC2 | Given the domain model of the thin scope, when its unit tests run, then the PipelineExecutionService/ChangeProposal holds its fields and invariants, applies BranchPushed and PullRequestOpened from the states the model draws and refuses any other move, and a proposal without provenance cannot be created (ADR-0014). |
| AC3 | Given the store pipeline-execution-sql, when the mapping tests run against an isolated test database, then ChangeProposals and ProposalCommits are mapped with their keys, the indexes IX_Proposals_Run and IX_Proposals_Repo_State and the tenant filter, and a row of another tenant is never read (ADR-0015). |
| Traces: services | PipelineExecutionService |
| Traces: aggregates | PipelineExecutionService/ChangeProposal |
| Traces: adrs | ADR-0014, ADR-0015, ADR-0028 |
| Depends on | feature:repository-and-pipeline-conventions, feature:component-base-template-factory-profile |
| Sources | model/services/devops-gitops/PipelineExecutionService.yaml, docs/planes/execution/delivery-engine/services/pipeline-execution-service/index.md#data-model-and-storage |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-093 Implement the thin scope of PipelineExecutionService for the first outcome |
implementation | The ChangeProposal aggregate with BranchPushed and PullRequestOpened, the tables ChangeProposals and ProposalCommits with tenant filters, the outbox of the pipeline-execution profile, the two options of the recording path and the workload check of Pipelines.RecordProposal; no REST route and no pipeline runs. The contracts of the method and the event the chain uses match model/services/devops-gitops/PipelineExecutionService.yaml, so the complete delivery replaces the thin one without a contract change. | ConnectSoft.AI.SoftwareFactory.PipelineExecutionService |
AIFACTORY-TASK-094 Contract tests for the method and the event of PipelineExecutionService that the chain uses |
verification | Contract tests of PipelineExecutionService/Pipelines.RecordProposal and PipelineExecutionService/ChangeProposalOpened pass against the request and response descriptors of model/descriptors.yaml, and AC1 to AC3 of AIFACTORY-US-1279 pass in the repository pipeline; callers can run against this service without a fake. | ConnectSoft.AI.SoftwareFactory.PipelineExecutionService |