Skip to content

AIFACTORY-FEAT-063: ApprovalPolicyService: 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 Governance (PF-12) · Increment I4 Trust and accountability · State elaborated · Route backend-developer · Build order 129 of 185 (Factory code)

ApprovalPolicyService is the service of bounded context BC-20 (Approval Policy). The rules of human decisions — which roles may approve which action class in which scope, separation of duties (never the requester, never the author), quorum, expiry, break-glass conditions — and the routing evaluations that tell Run Control who may decide a given request and whether a given decision is valid; instances and decisions stay in BC-03 (BC-20, ADR-0015). Its own repository is ConnectSoft.AI.SoftwareFactory.ApprovalPolicyService.

Delivers ApprovalPolicyService (complete)
Stubs —
Realizes adrs: ADR-0014, ADR-0015
Requirements FR-06, FUX-05, NFR-04, XL-02, XL-05
Depends on —
Sources model/services/governance/ApprovalPolicyService.yaml

Scenarios to trace (8, catalog): SCN-ApprovalPolicyService-001 ✓, SCN-ApprovalPolicyService-002 ✓, SCN-ApprovalPolicyService-003 ✓, SCN-ApprovalPolicyService-004 ✓, SCN-ApprovalPolicyService-005 ✓, SCN-ApprovalPolicyService-006 ✓, SCN-ApprovalPolicyService-007 ✓, SCN-ApprovalPolicyService-008 ✓

AIFACTORY-US-043: An approval reaches the reviewers the rule names, never the requester

behavior · persona reviewer As a reviewer, I want approvals routed by the rules of my project for the class of the action, so that the right people decide and nobody approves their own work.

This is the integration PBI of the feature. Approvals are split in two by the ownership map. The instances, the votes and the decisions live in RunControlService, in the aggregate ApprovalRequest with its kinds approval and operator-decision. The policy of human decisions lives here, in bounded context BC-20: ApprovalPolicyService holds the rules per scope and action class (shared-write, external, production, publication, spend), which roles may approve, the separation of duties, never the requester and never the author, the quorum, the expiry, what happens on expiry and whether a Platform admin may break glass. The rules are authored in the policy bundles and in no other place: for the policy revision a request names, the service asks Policy.Decide of PolicyEngineService with the action kind approval-eligibility, takes the rule from the obligations of the decision and keeps it per revision as it was read (D126, D127, D136). The holders of a role in a project are read through Projects.ListRoleHolders of ProjectService, at routing for the eligible approvers and at decision time for the eligibility of the decider (D126, D136). At request time the service routes, naming the rule, the eligible approvers, the quorum and the expiry; at decision time it validates that the decider is eligible now. It decides nothing itself and stores no approval request, no vote and no decision. The service arrives in I4, and RunControlService depends on it from I4, as model/services/control-plane/RunControlService.yaml states. Until then the earlier increments work without it, as their own PBIs state and the model says: RunControlService resolves the approver rule and checks the eligibility of a decider through PolicyEngineService under the policy revision the run pinned, applies the requester exclusion itself, and every request carries the quorum one, onExpiry fail and reRequestsLeft 0 while no approval rule is supplied (D115, D127). No feature of an earlier increment depends on this one. With this feature RunControlService asks ApprovalPolicy.Route when it opens an approval request of kind approval and ApprovalPolicy.ValidateDecision before it records a decision on one, through the gateway GovernanceHost with a workload token that holds the service scope that names ApprovalPolicyService, copies the quorum, onExpiry and maxReRequests of the routed rule onto the request and keeps the evaluation id with it (AIFACTORY-TASK-545). A request is routed for every subject of the closed list of approval-request-v1, a run, a provisioning run, an evaluation run, an asset release and a promotion: routing and validation read the subject, the project and the requester from the request and need no run, a request of another subject is routed and validated under the same rules as a run request, and its requester is never eligible (D129, D131, D135). Only a request that keeps an evaluation id is validated here. When ApprovalPolicy.Route answers FAILED_PRECONDITION, because the decision of PolicyEngineService for the pinned revision carries no approval rule for the action class, RunControlService opens the request as in the earlier increments, with the approver rule of the policy decision, the quorum one, onExpiry fail, reRequestsLeft 0 and no evaluation id. For a request without an evaluation id it does not call ApprovalPolicy.ValidateDecision, which answers NOT_FOUND for an approval that was never routed: it checks the approver rule through PolicyEngineService and applies the requester exclusion itself, exactly as in I1, so such a request can always be decided. The quorum is held by votes (D127): RunControlService records each approve of an eligible approver as one vote in ApprovalVotes, one per approver and request, passes the count of the votes already recorded to ApprovalPolicy.ValidateDecision, keeps the request Pending until the votes reach the quorum and ends it Approved with the vote that reaches it; one reject of an eligible approver ends it Rejected, and a second vote of the same approver is answered 409; what ApprovalPolicyService replies for each count is proven in AIFACTORY-US-926. A request of kind operator-decision is not routed here. Its approver rule names the Operator of the project, the enum ApproverRole holds Reviewer, Workspace admin and Platform admin and no Operator, and the member who requested a run may take the operator decision of that run (D121), so RunControlService keeps applying that rule itself. The member who requested a run therefore never decides an approval of a proposal or of spend, and may take the operator decision. The publication gate of AgentRegistryService arrives in the same increment, so the author exclusion of a publication approval has its first caller with it. The repository ConnectSoft.AI.SoftwareFactory.ApprovalPolicyService is created by the first task of this feature, by the steps of the repository checklist of feature repository-and-pipeline-conventions, and scaffolded once from the pinned base template package with UseFactoryProfile (features component-base-template-factory-profile and component-base-template-findings). The service writes its three events in the run event envelope of the pinned contracts package through the Orleans outbox of the messaging profile approval-policy, in the transaction of the command that causes them. The feature is delivered by five further PBIs: the rules put in force from an activated policy revision (AIFACTORY-US-923), the reads of rules and the validation of project rules (AIFACTORY-US-924), the routing of a request (AIFACTORY-US-925), the validation of a decision with break-glass (AIFACTORY-US-926) and the inbox handlers for membership, delegation and deletion orders (AIFACTORY-US-927). This PBI proves the chain with the acceptance suites of the two repositories, in which Policy.Decide and Projects.ListRoleHolders are bound to fakes: a rule is in force, an approval request that a run opens is routed to the reviewers of the rule, the requester and the author are refused, a request for which no rule exists is opened and decided by the path of the earlier increments, a request with a quorum of two is approved by the second eligible vote, and weaker project rules are refused. On a deployed installation both reads are bound to the operations the model names (D126, D136). Two points of the model are reported as corrections: the model names approval-v1 as the descriptor of both gRPC methods, which model/descriptors.yaml does not list, and the evaluation id a routed request keeps is a field the model of ApprovalRequest does not list. Two further corrections are reported with the PBIs that meet them: the project of a routing evaluation (AIFACTORY-US-925) and the cache store of the service (AIFACTORY-US-927). A resource of another tenant is answered 404, over gRPC NOT_FOUND, and a missing scope inside the tenant 403 (ADR-0015 amendment D113). Telemetry follows ADR-0019: tenant and project on metrics by default, run on activities and log records where a request names it, and no reason text, proposal content or rule content in telemetry.

Acceptance criteria

AC1 Given a rule in force for the class shared-write in a project and an approval request of that class that RunControlService opens for a run, when ApprovalPolicyService/ApprovalPolicy.Route is called, then the reply names the rule and the eligible approvers without the requester and without the author, ApprovalPolicyService/ApprovalRouted announces the evaluation with the outcome Eligible and the expiry, and the RunControlService/ApprovalRequest keeps the quorum, the onExpiry, the re-request limit of the rule and the evaluation id; when no member is eligible, then the outcome is NoEligibleApprover and the request stays Pending; when the reply is FAILED_PRECONDITION because no rule exists, then the request is opened with onExpiry fail and no evaluation id, a decision on it is checked through PolicyEngineService and the requester exclusion of RunControlService without a call to ApprovalPolicyService/ApprovalPolicy.ValidateDecision, and the approval of an eligible reviewer is recorded (FR-06, ADR-0014).
AC2 Given the requester of the run or the author of the proposal, with whatever role, when the decision is submitted through RunControlService/DecideApproval, then ApprovalPolicyService/ApprovalPolicy.ValidateDecision answers RequesterExcluded or AuthorExcluded, ApprovalPolicyService/ApprovalDecisionValidated records the refused attempt, RunControlService answers 403 and the request stays Pending; given a request of kind operator-decision, then the member who requested the run may decide it and ApprovalPolicyService is not asked (ADR-0015, XL-05).
AC3 Given a routed rule with a quorum of two, when two eligible reviewers approve one after the other through RunControlService/DecideApproval, then ApprovalPolicyService/ApprovalPolicy.ValidateDecision, asked with the count of the votes already recorded, answers Eligible with the quorum not met for the first and met for the second, the first approve is recorded as a vote and the request stays Pending, and the second ends the RunControlService/ApprovalRequest Approved; a second approve of the same reviewer is answered 409 and records nothing, and a reject by one eligible reviewer ends the request Rejected (FUX-05, model/services/control-plane/RunControlService.yaml).
AC4 Given project rules that are weaker than the rules of the tenant, when ApprovalPolicyService/ValidateProjectApprovalRules is called, then the result is not valid and names every rule that loosens; and when a policy revision that carries such rules is activated, then no ApprovalPolicyService/ApprovalRule of it comes into force and the rules of the previous revision stay (model/services/governance/ApprovalPolicyService.yaml).
AC5 Given the repository ConnectSoft.AI.SoftwareFactory.ApprovalPolicyService, whose first commit is the unchanged output of dotnet new connectsoft-base -n ConnectSoft.AI.SoftwareFactory.ApprovalPolicyService --UseFactoryProfile true from the pinned template package, when its pipeline runs with the work of this feature, then no second scaffold was run, the solution builds, the tests pass with complete reports, a container image is published, and the telemetry conformance test finds the three metrics of the model with tenant and project and no reason text, proposal content or rule content in a metric, an activity or a log record (ADR-0019, ADR-0028).
Traces: services ApprovalPolicyService, RunControlService, PolicyEngineService, ProjectService, GovernanceHost
Traces: aggregates ApprovalPolicyService/ApprovalRule, ApprovalPolicyService/RoutingEvaluation, RunControlService/ApprovalRequest
Traces: apis ApprovalPolicyService/ApprovalPolicy.Route, ApprovalPolicyService/ApprovalPolicy.ValidateDecision, ApprovalPolicyService/ValidateProjectApprovalRules, RunControlService/DecideApproval, PolicyEngineService/Policy.Decide, ProjectService/Projects.ListRoleHolders
Traces: events ApprovalPolicyService/ApprovalRouted, ApprovalPolicyService/ApprovalDecisionValidated, RunControlService/ApprovalRequested
Traces: descriptors approval-request-v1, policy-decision-request-v1
Traces: adrs ADR-0014, ADR-0015, ADR-0019, ADR-0028
Traces: requirements FR-06, FUX-05, NFR-04, XL-05
Relates: screens approvals-list, approval-card, approval-policy
Depends on AIFACTORY-US-923, AIFACTORY-US-924, AIFACTORY-US-925, AIFACTORY-US-926, AIFACTORY-US-927, feature:run-control-service, feature:policy-engine-service, feature:project-service, feature:governance-host, feature:repository-and-pipeline-conventions, feature:component-base-template-factory-profile, feature:component-base-template-findings, feature:contracts-package, feature:component-observability-factory-conventions
Sources model/services/governance/ApprovalPolicyService.yaml, model/services/control-plane/RunControlService.yaml, docs/reference/schemas/approval.schema.json, docs/planes/control/approvals.md, docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md, docs/planes/trust-operations/governance/services/approval-policy-service/index.md#purpose-and-responsibilities

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-545 Decision validation in Run Control implementation For a request of kind approval RunControlService calls ApprovalPolicy.Route through the gateway GovernanceHost when it opens the request, for every subject of the closed list of approval-request-v1, with the subject, the project and the requester of the request, copies the rule id, the quorum, the expiry, onExpiry and maxReRequests of the reply onto the request and keeps the evaluation id with it; for a request that keeps an evaluation id it calls ApprovalPolicy.ValidateDecision before it records a decision, with the count of the votes already recorded in ApprovalVotes, records an approve of an eligible decider as one vote, ends the request Approved with the vote that reaches the quorum and keeps it Pending before, ends it Rejected on one reject of an eligible decider, records a request for changes of an eligible decider, answers a second vote of the same approver with 409 and records nothing, and answers 403 for the outcomes RequesterExcluded, AuthorExcluded and Invalid and 410 for Expired; both calls carry a workload token that holds the service scope that names ApprovalPolicyService; when the routing reply is FAILED_PRECONDITION because the decision of PolicyEngineService carries no approval rule for the action class, the request is opened as in the earlier increments, with the approver rule of the policy decision, the quorum one, onExpiry fail, reRequestsLeft 0 and no evaluation id, and a decision on a request without an evaluation id is never sent to ApprovalPolicy.ValidateDecision: RunControlService checks the approver rule through PolicyEngineService and applies the requester exclusion itself, exactly as in I1, and records the decision; a request of kind operator-decision is neither routed nor validated there; when ApprovalPolicyService or the gateway does not answer, or a call ends UNAVAILABLE, no request is opened, and for a request with an evaluation id no decision is recorded; where the evaluation id is kept on the request is a field the model of ApprovalRequest does not list and is reported with the corrections of AIFACTORY-US-043. ConnectSoft.AI.SoftwareFactory.RunControlService
AIFACTORY-TASK-752 Verify approval-routed-by-rule by running the declared command verification Run dotnet test -c Release --filter Category=Acceptance in the pipelines of ConnectSoft.AI.SoftwareFactory.ApprovalPolicyService and ConnectSoft.AI.SoftwareFactory.RunControlService; a run that discovers no test counts as a failure; the runs pass and prove AC1 to AC5 of AIFACTORY-US-043 with PolicyEngineService/Policy.Decide bound to the fake of AIFACTORY-TASK-3715 and ProjectService/Projects.ListRoleHolders to the fake of AIFACTORY-TASK-3720, and in the suite of RunControlService with a fake of the two gRPC methods: a request routed by ApprovalPolicyService/ApprovalPolicy.Route with the fields and the evaluation id copied onto RunControlService/ApprovalRequest, a request opened after FAILED_PRECONDITION without an evaluation id and decided through PolicyEngineService and the requester exclusion with no call to ApprovalPolicyService/ApprovalPolicy.ValidateDecision, the refused requester and author, the operator decision that is not routed, a request with a quorum of two kept Pending after the first vote and Approved by the second, the 409 of a second vote of the same reviewer, the reject that ends the request Rejected, the refused weaker project rules, the scaffold and the telemetry conformance test. ConnectSoft.AI.SoftwareFactory.ApprovalPolicyService
AIFACTORY-TASK-457 Create the repository ConnectSoft.AI.SoftwareFactory.ApprovalPolicyService and scaffold it from the ConnectSoft.BaseTemplate template with the Factory profile implementation The repository exists by the repository checklist of feature repository-and-pipeline-conventions, the output of dotnet new connectsoft-base -n ConnectSoft.AI.SoftwareFactory.ApprovalPolicyService --UseFactoryProfile true from the pinned template package is committed unchanged with the messaging service name approval-policy, the repository records the template version, the solution builds and the template tests pass in the repository pipeline, which publishes the container image. ConnectSoft.AI.SoftwareFactory.ApprovalPolicyService
AIFACTORY-TASK-458 Domain model: ApprovalRule and RoutingEvaluation implementation The two aggregates carry the fields and the invariants of model/services/governance/ApprovalPolicyService.yaml: excludeRequester is always true, a project rule only tightens the tenant rule, the expiry never exceeds the platform maximum and an expired request is never revived, a decision by the requester or the author is invalid regardless of role, a break-glass decision of a Platform admin is valid only with a reason and where the rule allows it, eligibility is evaluated at decision time, and a request of any subject of the closed list is routed and validated without a run; the enums ApproverRole and RoutingOutcome are closed; a rule is kept per policy revision as it was read from the obligations of a decision of PolicyEngineService, activated and retired and never edited, and a routing evaluation is written once and never changed; the field projectId of RoutingEvaluation, the reported correction, is added once the model carries it; unit tests cover every invariant and both transitions of a rule. ConnectSoft.AI.SoftwareFactory.ApprovalPolicyService
AIFACTORY-TASK-459 Persistence in approval-policy-sql: ApprovalRules and RoutingEvaluations migration Mappings and migrations for the two modelled tables with their tenant columns under the row filter, the defaults of the model (ExcludeRequester 1, ExcludeAuthor 1, Quorum 1, OnExpiry fail, MaxReRequests 0, BreakGlassAllowed 0, Active 1), the index IX_ApprovalRules_Scope_Class on tenant, scope, action class and active flag and the index IX_Routing_Approval; the rules of a revision are stored per revision as they were read, under the tenant of the revision; the column ProjectId of RoutingEvaluations, filled from the project metadata of ApprovalPolicy.Route, is added with its migration once the model carries it, and until then the table is mapped as modelled, without a project; no column holds a reason text or proposal content; the mapping of RoutingEvaluations allows insert and delete and no update; mapping tests run against an isolated test database, never a shared one. ConnectSoft.AI.SoftwareFactory.ApprovalPolicyService
AIFACTORY-TASK-460 API hosting skeleton: REST and gRPC hosts, scope enforcement, problem responses and contract documents for the 3 REST and 2 gRPC operations implementation The three REST routes (ListApprovalRules, ValidateProjectApprovalRules, GetApprovalRouting) and the two gRPC methods of the service ApprovalPolicy (Route, ValidateDecision) are hosted with JWT validation, the scope of each route (factory.policies.read, factory.policies.write, factory.approvals.read), problem responses for every modelled refusal code and for the 404 of a resource of another tenant, workload identity and service scope checks on the two gRPC methods, which read the tenant and the project of the call metadata only under the service scope that names ApprovalPolicyService, and the OpenAPI and proto documents; the proto fixes the request and reply messages of both methods, because the descriptor approval-v1 the model names is not listed in model/descriptors.yaml; a REST route admits no workload token; the behaviour of each operation is delivered by AIFACTORY-US-924 to AIFACTORY-US-926, not here. ConnectSoft.AI.SoftwareFactory.ApprovalPolicyService
AIFACTORY-TASK-461 Messaging skeleton: outbox and inbox wiring of the approval-policy profile for 3 published and 4 consumed events implementation The outbox writer enlists in the transaction of the rule activation and of the commands Route and ValidateDecision, and the dispatcher of the approval-policy messaging profile publishes the three modelled events in the run event envelope of the pinned contracts package (ApprovalRuleActivated, ApprovalRouted, ApprovalDecisionValidated) on their modelled topics; the inbox registers the four consumed events of the model with idempotency on the event id (PolicyRevisionActivated, MembershipChanged, DelegationChanged and DeletionOrderIssued, whose handler is built in this increment with the order contract of RetentionResidencyService); what each handler does is delivered by AIFACTORY-US-923 and AIFACTORY-US-927. ConnectSoft.AI.SoftwareFactory.ApprovalPolicyService
AIFACTORY-TASK-462 Security, tenancy and telemetry of ApprovalPolicyService implementation Scopes and roles of the model are enforced, every query is tenant-filtered, a resource of another tenant is answered 404 and NOT_FOUND, the secret messaging-transport comes from its secret reference, and the three metrics of the model (connectsoft.factory.approval_policy.routings, connectsoft.factory.approval_policy.invalid_decisions, connectsoft.factory.approval_policy.break_glass) are recorded through the helper of the pinned observability packages with their modelled dimensions and with tenant and project; activities and log records carry the run where a request names it, and a conformance test fails when a reason text, proposal content or rule content reaches a metric, an activity or a log record (ADR-0019). ConnectSoft.AI.SoftwareFactory.ApprovalPolicyService
AIFACTORY-TASK-3713 Deployment values of the service: replica range, options, probes and the addresses of its dependencies operations The deployment manifest of the service states the replica range 3 to 10 of model/services/governance/ApprovalPolicyService.yaml, the liveness and readiness probes, the options Governance:Approvals:MaxExpiryMinutes and Governance:Approvals:BreakGlassRequiresReason at the defaults of the model, OrleansMessaging:ServiceName approval-policy, the addresses of PolicyEngineService and ProjectService, the authority of the identity platform and the store bindings approval-policy-sql and cache from configuration, the second being the shared cache of the eligibility cache, which the stores of the model do not list for this service and which is reported as a correction of the service file; readiness reports the store, PolicyEngineService, ProjectService and the identity platform; health reports the cache as degraded when it does not answer, which does not turn readiness unready; the manifest holds no secret value and fixes no cache lifetime in code; the same image runs in the saas-default, hybrid, on-prem and hybrid-compute topologies. ConnectSoft.AI.SoftwareFactory.ApprovalPolicyService

AIFACTORY-US-923: Put the approval rules of an activated policy revision in force and announce each rule

behavior · persona platform-admin As a platform admin, I want the approval rules of a policy revision to come into force as one validated set when the revision is activated, so that the rules that route and validate approvals always belong to an exact policy revision and never loosen the rules above them.

Approval rules are part of a policy bundle revision and are authored in the policy bundles and in no other place (D126, D127, D136). When PolicyEngineService activates a revision it publishes PolicyRevisionActivated with revision, tenantId, scope, scopeId and rulesHash, and the inbox handler LoadApprovalRules of this service puts the approval rules of that revision in force. The event carries no rule content, so the handler reads the rules through Policy.Decide of PolicyEngineService with the workload token of this service: for each of the five action classes, shared-write, external, production, publication and spend, it asks a decision with the action kind approval-eligibility, which pairs with the domain RunAcceptance, the target approval, the action class and the activated revision, and takes the rule from the obligations of the decision: the approver rule reference, the approver roles, excludeAuthor, quorum, expiryMinutes, onExpiry, maxReRequests and breakGlassAllowed. PolicyEngineService evaluates a revision along the chain of its bundles and refuses at activation a bundle that loosens its parent, so the rule a decision returns is the rule in force for that revision and this service follows no parent chain of its own. A decision whose obligations carry no approval rule, a deny among them, means that the revision holds no rule for that action class, and the handler writes none for it. A rule is one ApprovalRule for one scope, platform, tenant or a project with its id, and one action class, optionally narrowed by an action pattern to a tool, a workflow or an environment class, with the fields above, excludeRequester and the policy revision it belongs to. The handler validates every rule of the revision before it writes one. excludeRequester is always true, and obligations that state it false are refused (ADR-0015 point 6). The approver roles are values of ApproverRole. The quorum is at least one. expiryMinutes does not exceed Governance:Approvals:MaxExpiryMinutes. maxReRequests is 0 when onExpiry is fail (D114). A valid set is written in one transaction: the rules of the revision are inserted with active true, the rules of the revision that was in force for the same scope are set to active false, and one ApprovalRuleActivated outbox record per rule in force (ruleId, tenantId, scope, actionClass, policyRevision) is written with them. An invalid set is refused whole: no rule is written, the rules of the previous revision stay in force, the refusal is logged with the revision and the rule ids, and the event is acknowledged, because a set that can never become valid must not be redelivered. The handler is idempotent on the event id through the inbox and on the revision: a redelivered event and a revision already in force change nothing and publish nothing. A rule set belongs to its revision for good. An approval request names the policy revision its run pinned, and routing and validation use the rules of that revision, so a retired rule stays readable and usable for the requests that name its revision and is never deleted by a later activation. A seeded tenant bundle publishes no event (D127), so the rules of a revision this handler never saw are read by ApprovalPolicy.Route through the same decision and kept per revision as they were read (AIFACTORY-US-925). When PolicyEngineService does not answer, or a decision ends UNAVAILABLE, the handler fails without a write and the inbox retries with backoff, and the rules of the previous revision stay in force meanwhile. The acceptance suite binds Policy.Decide to a fake that answers per revision and action class. This PBI proves what the publisher of ApprovalRuleActivated can prove: the outbox record in the transaction of the activation, the run event envelope, the payload and a transport outage retried with backoff without loss or duplicate under the event id (ADR-0012). StudioBff refreshes its view and AuditService records the evidence in their own PBIs.

Acceptance criteria

AC1 Given PolicyEngineService/PolicyRevisionActivated for a tenant revision for which PolicyEngineService/Policy.Decide, asked with the action kind approval-eligibility per action class, returns approval rules in its obligations, when LoadApprovalRules handles it, then one active ApprovalPolicyService/ApprovalRule exists per rule with its roles, exclusions, quorum, expiry, on-expiry rule, re-request limit, break-glass allowance and policy revision, no rule exists for an action class whose decision carries none, the rules of the previous revision of that scope are inactive and still stored, and one ApprovalPolicyService/ApprovalRuleActivated outbox record per rule is written in the same transaction (SCN-ApprovalPolicyService-006, ADR-0014).
AC2 Given a revision one of whose rules states excludeRequester false, names a role outside ApproverRole, has a quorum below one, an expiry above Governance:Approvals:MaxExpiryMinutes or re-requests with the on-expiry rule fail, when LoadApprovalRules handles the event, then the whole set is refused, no ApprovalPolicyService/ApprovalRule and no outbox record is written, the rules of the previous revision stay in force and the log names the revision and the rule ids (SCN-ApprovalPolicyService-006, ADR-0015, model/services/governance/ApprovalPolicyService.yaml).
AC3 Given a redelivered event, a revision already in force and two replicas that handle the same event, when the handler runs, then nothing changes and nothing is published; given PolicyEngineService/Policy.Decide that does not answer or ends UNAVAILABLE, then the handler fails without a write, the inbox retries with backoff, the rules of the previous revision stay in force and, once the decision answers, the rules of the revision are in force once (SCN-ApprovalPolicyService-006).
AC4 Given the outbox records of an activation and a transport that is unavailable, when the dispatcher of the approval-policy messaging profile runs, then each ApprovalPolicyService/ApprovalRuleActivated is published on approval-policy.rules.v1.approval-rule-activated in the run event envelope with ruleId, tenantId, scope, actionClass and policyRevision, the outage is retried with backoff, and no event is lost or published twice under its event id (SCN-ApprovalPolicyService-006, ADR-0012).
Traces: services ApprovalPolicyService, PolicyEngineService, AuditService
Traces: aggregates ApprovalPolicyService/ApprovalRule
Traces: apis PolicyEngineService/Policy.Decide
Traces: events ApprovalPolicyService/ApprovalRuleActivated, PolicyEngineService/PolicyRevisionActivated
Traces: descriptors run-event-envelope-v1, policy-decision-request-v1
Traces: adrs ADR-0012, ADR-0014, ADR-0015
Traces: requirements FR-06, NFR-04
Traces: scenarios SCN-ApprovalPolicyService-006
Depends on feature:policy-engine-service, feature:contracts-package
Sources model/services/governance/ApprovalPolicyService.yaml, model/services/governance/PolicyEngineService.yaml, docs/architecture/adr/0012-messaging-port-and-transport-profiles.md, docs/planes/trust-operations/governance/services/approval-policy-service/index.md#messages

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-543 Rules per action class and scope implementation One rule validator and one tightening comparer of the repository check a set of approval rules: each rule names an action class of the five, approver roles of ApproverRole, excludeRequester true, a quorum of at least one, an expiry within Governance:Approvals:MaxExpiryMinutes and maxReRequests 0 with onExpiry fail, and a narrower scope only tightens a wider one (no role added, no exclusion dropped, no lower quorum, no longer expiry, no more re-requests, no break-glass the wider rule forbids); the result lists every offending rule with the member that offends; LoadApprovalRules and ValidateProjectApprovalRules use the same validator, so one rule gets one verdict, and ValidateProjectApprovalRules uses the comparer against the tenant rules in force. ConnectSoft.AI.SoftwareFactory.ApprovalPolicyService
AIFACTORY-TASK-3714 LoadApprovalRules handler that reads the rules of a revision through Policy.Decide and activates the rule set implementation The inbox handler of PolicyRevisionActivated reads the approval rules of the revision through a typed client of PolicyEngineService/Policy.Decide, one decision per action class with the action kind approval-eligibility, the target approval and the activated revision, takes each rule from the obligations of its decision and writes none for a class whose decision carries none, validates the set with the validator of AIFACTORY-TASK-543, and in one transaction inserts the rules as active, sets the rules of the previous revision of the scope inactive without deleting them and writes one ApprovalRuleActivated outbox record per rule; an invalid set is refused whole, logged and acknowledged; a redelivered event and a revision already in force change nothing; a decision that does not answer or ends UNAVAILABLE fails the handler without a write so that the inbox retries. ConnectSoft.AI.SoftwareFactory.ApprovalPolicyService
AIFACTORY-TASK-3715 Fake of Policy.Decide, publisher of PolicyRevisionActivated and the invalid rule sets of the acceptance suite fixture The acceptance suite holds a fake of PolicyEngineService/Policy.Decide that answers a decision with the action kind approval-eligibility per revision and action class with an approval rule in its obligations or with none, can be made to fail and counts its calls, a publisher that builds PolicyRevisionActivated in the run event envelope from the pinned contracts package, valid rule sets of the platform, of two tenants and of two projects, a revision whose decisions carry a rule for some action classes only, and one invalid set per refusal of AIFACTORY-US-923 (requester exclusion off, unknown role, quorum of zero, expiry above the maximum, re-requests with fail), and project candidate sets with one per kind of loosening for AIFACTORY-US-924. ConnectSoft.AI.SoftwareFactory.ApprovalPolicyService
AIFACTORY-TASK-3716 Verify the activation of approval rules through the acceptance suite verification Run dotnet test -c Release --filter "Category=Acceptance&Scenario=SCN-ApprovalPolicyService-006"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-923 with the fixtures of AIFACTORY-TASK-3715: a rule set read through PolicyEngineService/Policy.Decide and put in force with its predecessor kept inactive, an action class without a rule, every refused set with the table and the outbox unchanged, the redelivered event, the two replicas, the decision that fails and recovers, and the publication of ApprovalPolicyService/ApprovalRuleActivated with its payload under a transport outage. ConnectSoft.AI.SoftwareFactory.ApprovalPolicyService

AIFACTORY-US-924: Read the approval rules in force and validate project rules against the tenant rules

behavior · persona workspace-admin As a workspace admin, I want to read the approval rules that apply to my project and to check the rules I plan against the rules of my tenant, so that I know who may approve what and never propose rules that will be refused as weaker.

ListApprovalRules, GET /factory/approval-rules, returns the rules per scope and action class with their approver roles, exclusions, quorum, expiry, on-expiry rule, re-request limit, break-glass allowance, policy revision and active flag. It is of class read and needs factory.policies.read. The callers are Reviewer, Workspace admin, Platform admin and Observer, and the Studio screen approval-policy reads it. Every caller with the scope sees the platform rules and the tenant rules of the tenant of the token; a project rule is listed only for a caller who holds a role in that project or the tenant-wide Platform admin role. The list is paged and may be filtered by action class and by the active flag. The model names no parameter for a project on it, so the gateway forwards the call under the tenant of the token and the service filters by the role claims, and the gap is reported as a correction of the service file. ValidateProjectApprovalRules, POST /factory/projects/{projectId}/approval-rules/validate, checks candidate rules of a project against the tenant rules in force before they are published with a policy revision. It is of class sandbox and needs factory.policies.write. The callers are the Workspace admin of the project and the Platform admin; the gateway admits the project of the path against the roles of the token, and the service compares the path with the project roles of the forwarded token again. The check is the validator and the comparer of the activation (AIFACTORY-TASK-543). Each candidate rule is validated on its own: requester exclusion true, known roles, a quorum of at least one, an expiry within the platform maximum, and re-requests consistent with the on-expiry rule. It is then compared with the tenant rule of the same action class, the rule of the active tenant revision that the service holds or, when it holds none, as for a seeded tenant bundle, reads through Policy.Decide with the action kind approval-eligibility (D127, D136), which it may only tighten: more roles excluded, a shorter expiry, a higher quorum, break-glass disabled, and never the opposite. The response is 200 with the result: valid, or not valid with every offending rule listed with its action class, the member that loosens and the tenant value it loosens. The model lists the codes 200, 400 and 403 and does not say which of them answers weaker rules. This PBI fixes 200 with a not valid result for readable rules that loosen, and 400 for a body that cannot be read as rules, that names an unknown action class or role or that names a scope other than the project of the path; it is the same reading as for ValidateProjectPolicy of PolicyEngineService, and it is reported. Nothing is stored, no rule changes and no event is published, so a validated rule is not in force until a policy revision that carries it is activated (AIFACTORY-US-923). A call without a token or with an expired token is answered 401; a token without the scope of the operation, a caller without the role and a workload token 403; a Platform admin who names a project that does not exist in the tenant 404 (ADR-0015 amendment D113), a code the list of the model lacks and that is reported; and a store that does not answer 503. Rules of another tenant are never listed and never used as the parent of a validation. Both routes are public routes of the gateway GovernanceHost, which forwards the user token unchanged, and the service accepts the audience of its own gateway (ADR-0015 amendment D117).

Acceptance criteria

AC1 Given rules in force for the platform, a tenant and two of its projects and a caller with factory.policies.read and a role in one of the projects, when ApprovalPolicyService/ListApprovalRules is called, then the response is 200 with the platform rules, the tenant rules and the rules of that one project, each ApprovalPolicyService/ApprovalRule with scope, action class, roles, exclusions, quorum, expiry, on-expiry rule, re-request limit, break-glass allowance, policy revision and active flag, paged; a Platform admin of the tenant is served the rules of every project of the tenant; nothing is written (SCN-ApprovalPolicyService-001, FUX-05).
AC2 Given tenant rules in force and candidate project rules each of which tightens its tenant rule, when ApprovalPolicyService/ValidateProjectApprovalRules is called by the Workspace admin of the project of the path, then the response is 200 with the result valid; given candidates one of which adds an approver role, drops an exclusion, lowers the quorum, lengthens the expiry or enables break-glass against the tenant rule, then the response is 200 with the result not valid and each offending rule listed with its action class, the member and the tenant value; in both cases no rule, evaluation or outbox record is written (SCN-ApprovalPolicyService-002, model/services/governance/ApprovalPolicyService.yaml).
AC3 Given a body that cannot be read as rules or that names an unknown action class, a caller who is neither Workspace admin of the project nor Platform admin, a token without the scope of the operation or a workload token, a call without a token, a Platform admin who names a project that does not exist in the tenant, and approval-policy-sql stopped, when either operation is called, then the answers are 400, 403, 403, 401, 404 and 503 with a problem response and no state changes (SCN-ApprovalPolicyService-001, SCN-ApprovalPolicyService-002, ADR-0015).
AC4 Given rules of two tenants, when ApprovalPolicyService/ListApprovalRules and ApprovalPolicyService/ValidateProjectApprovalRules are called with a token of one tenant, then no rule of the other tenant is listed or used as the parent of the validation; and one rule sent to the validation and to the activation of AIFACTORY-US-923 gets the same verdict from the validator (SCN-ApprovalPolicyService-001, SCN-ApprovalPolicyService-002, NFR-04).
Traces: services ApprovalPolicyService, GovernanceHost
Traces: aggregates ApprovalPolicyService/ApprovalRule
Traces: apis ApprovalPolicyService/ListApprovalRules, ApprovalPolicyService/ValidateProjectApprovalRules
Traces: adrs ADR-0015
Traces: requirements FR-06, FUX-05, NFR-04
Traces: scenarios SCN-ApprovalPolicyService-001, SCN-ApprovalPolicyService-002
Relates: screens approval-policy
Depends on AIFACTORY-US-923, feature:governance-host, feature:component-base-template-factory-profile
Sources model/services/governance/ApprovalPolicyService.yaml, docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md, docs/planes/trust-operations/governance/services/approval-policy-service/index.md#apis

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-3717 ListApprovalRules and ValidateProjectApprovalRules implementation ListApprovalRules returns, paged and filterable by action class and by the active flag, the platform rules, the tenant rules of the tenant of the token and the project rules of the projects in which the token holds a role, all project rules of the tenant for the Platform admin; ValidateProjectApprovalRules checks that the scope of the candidates is the project of the path and that the caller is Workspace admin of that project or Platform admin of the tenant, runs the validator and the comparer of AIFACTORY-TASK-543 against the tenant rules in force and answers 200 with valid or with not valid and every offending rule; it answers 400, 401, 403, 404 and 503 as AIFACTORY-US-924 states and stores, activates and publishes nothing; a workload token is refused with 403. ConnectSoft.AI.SoftwareFactory.ApprovalPolicyService
AIFACTORY-TASK-3718 Verify the reads and the validation of approval rules through the acceptance suite verification Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-ApprovalPolicyService-001\|Scenario=SCN-ApprovalPolicyService-002)"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-924 with the rule sets of AIFACTORY-TASK-3715 and the token matrix of AIFACTORY-TASK-3720: the list for a member of one project and for a Platform admin, the paging and the filters, a valid set, each kind of loosening set with its listed rules, every refusal, the two-tenant case, the equal verdict of validation and activation, and the tables and the outbox unchanged after every call. ConnectSoft.AI.SoftwareFactory.ApprovalPolicyService

AIFACTORY-US-925: Route an approval request to the approvers its rule makes eligible and show who may decide

behavior · persona reviewer As a reviewer, I want an approval request routed to the members the rule of its action class makes eligible, with its expiry, so that the request reaches people who may decide it, and I can see who they are and until when.

When a gated action reaches its approval, RunControlService opens an approval request and asks who may decide it. ApprovalPolicy.Route is that question: an internal gRPC method called through the gateway GovernanceHost with a workload token that holds the service scope that names ApprovalPolicyService, with the tenant and the project in the call metadata. The request names the approval id, the subject of the closed list of approval-request-v1 with its kind and id, a run, a provisioning run, an evaluation run, an asset release or a promotion, the run where the subject is or belongs to one, the action class, the action, the scope, the policy revision the request names, the requester and, for a publication, the author of the asset. Routing reads the subject, the project and the requester from the request and needs no run, and a request of another subject is routed under the same rules as a run request (D129, D131, D135). The model names approval-v1 as the request and reply descriptor, which model/descriptors.yaml does not list; the proto of this feature fixes both messages and the descriptor is reported. The service takes the rule of the pinned revision and the action class. When it holds rules of that revision, put in force by LoadApprovalRules (AIFACTORY-US-923), it takes the rule of the action class, one whose action pattern matches before one without a pattern. For a revision it does not hold, which is the case of every seeded tenant bundle because a seeded bundle publishes no event (D127), it asks Policy.Decide of PolicyEngineService with the action kind approval-eligibility, the target approval, the action class and the pinned revision, takes the rule from the obligations of the decision and keeps it in ApprovalRules under that revision as it was read, in the transaction of the evaluation (D126, D136). PolicyEngineService evaluates the revision along the chain of its bundles, so the rule is the rule in force for the revision the request names, and the rules of a newer revision are never used, even when they are active for the tenant now. It then resolves the eligible approvers through Projects.ListRoleHolders of ProjectService, which lists the members of the project who hold one of the approver roles of the rule, directly or by a delegation in force (D126, D136), without the requester, because excludeRequester is always set, and without the author when excludeAuthor is set. A Platform admin is not listed as an approver; the role decides only as break-glass (AIFACTORY-US-926). The expiry is expiryMinutes of the rule from now and never beyond Governance:Approvals:MaxExpiryMinutes. The service writes one RoutingEvaluation with evaluation id, tenant, approval id, the run where the request names one, rule id, action class, requester, author, the eligible approvers, the outcome, expiresAt and evaluatedAt, and the ApprovalRouted outbox record (evaluationId, approvalId, tenantId, outcome, expiresAt) in one transaction, and replies with the rule id, the eligible approvers, the quorum, the expiry, onExpiry and maxReRequests, which RunControlService copies onto its request. The evaluation also needs the project of the approval, which the call metadata carry and the aggregate of the model does not hold: RoutingEvaluation and its table have no project, and a tenant rule may route an approval of any project, so neither the project check of the read below nor the project-scoped delete of AIFACTORY-US-927 can be met from the modelled table. This feature reports a field projectId with its column ProjectId as a correction of the model, filled from the project metadata of ApprovalPolicy.Route; the domain and persistence tasks add it once the model carries it, and the two criteria that rest on it are worded against that column and are accepted with it. The outcome is Eligible when at least as many approvers are eligible as the quorum needs. When fewer are, the outcome is NoEligibleApprover: the evaluation and the event are written all the same, the reply says so, and the request stays Pending in RunControlService. StudioNotificationService, which consumes ApprovalRouted, raises the task for the Workspace admin to grant a Reviewer, and the expiry of the request fails the run, as the failure mode of the model states. A repeat of the call for the same approval id returns the evaluation already written and writes and publishes nothing, so a caller that retries after a lost reply receives one routing; a new routing of the same approval is written only when the request asks for a re-route (AIFACTORY-US-927). When the decision of PolicyEngineService carries no approval rule for the action class, a deny among them, the reply is FAILED_PRECONDITION and nothing is written. A pinned revision the tenant of the call does not hold is answered the same, so the answer never confirms a foreign revision, and the method, which addresses no stored resource by id, has no NOT_FOUND answer. RunControlService then opens the request as in the earlier increments, with the approver rule of the policy decision, the quorum one, onExpiry fail and no evaluation id, which is what the model states for a request without a supplied rule, and decides it without ApprovalPolicy.ValidateDecision (AIFACTORY-US-043). A call without a workload identity is refused with UNAUTHENTICATED; a token without the service scope, and a user token, with PERMISSION_DENIED; and a request without an approval id, a subject, a requester or an action class, with a subject kind outside the closed list or with an action class outside the five, with INVALID_ARGUMENT. PolicyEngineService and ProjectService are required dependencies that fail fast: when either does not answer the call ends UNAVAILABLE, nothing is written and RunControlService does not open the request. The same holds when approval-policy-sql does not answer or the transaction of the evaluation fails: the call ends UNAVAILABLE, no evaluation, no kept rule and no event exist and RunControlService opens no request. The service retries nothing on its own. GetApprovalRouting, GET /factory/approvals/{approvalId}/routing, shows a person who may decide a request: the latest routing evaluation of the approval with the rule applied, the eligible approvers, the quorum, the expiry and the outcome. It is of class read and needs factory.approvals.read; the Studio screens approval-card and approval-policy read it. A caller without a role in the project the evaluation holds in ProjectId, the column of the reported correction, is refused with 403, and an approval id for which the tenant of the token holds no evaluation is answered 404, whether it belongs to another tenant or was never routed (ADR-0015 amendment D113); an approval opened after FAILED_PRECONDITION has no evaluation and is answered 404 here, and its approver rule is read from the request in RunControlService. When approval-policy-sql does not answer the response is 503. connectsoft.factory.approval_policy.routings counts every routing by tenant, action class and outcome. This PBI proves what the publisher of ApprovalRouted can prove; consumer handling is proven by the suites of StudioNotificationService and AuditService.

Acceptance criteria

AC1 Given a pinned tenant revision that the service does not hold and for which PolicyEngineService/Policy.Decide, asked with the action kind approval-eligibility, returns a rule for the class shared-write in its obligations, and a workload token that holds the service scope that names ApprovalPolicyService, when ApprovalPolicyService/ApprovalPolicy.Route is called for an approval of the class shared-write in a project of that tenant, then the rule of the decision is applied and kept as an ApprovalPolicyService/ApprovalRule of that revision, a second routing under the same revision uses the kept rule without a new decision, a rule of a newer revision is not used, the reply names the rule id, the eligible approvers, the quorum, the expiry, onExpiry and maxReRequests, one ApprovalPolicyService/RoutingEvaluation with the outcome Eligible is written, and the ApprovalPolicyService/ApprovalRouted outbox record with evaluationId, approvalId, tenantId, outcome and expiresAt is written in the same transaction (SCN-ApprovalPolicyService-004, SCN-ApprovalPolicyService-007, ADR-0014).
AC2 Given a rule with the approver roles Reviewer and Workspace admin, a requester who holds Reviewer, an author who holds Workspace admin and a member who holds Reviewer by a delegation in force, as ProjectService/Projects.ListRoleHolders lists them, when ApprovalPolicyService/ApprovalPolicy.Route is called for a publication, then the eligible approvers hold the delegate and neither the requester nor the author nor a Platform admin, and the expiry is expiryMinutes of the rule from now and never beyond Governance:Approvals:MaxExpiryMinutes; given a request whose subject is a provisioning run and that names no run, then it is routed under the same rule and its requester is excluded (SCN-ApprovalPolicyService-004, ADR-0015).
AC3 Given a project in which fewer members are eligible than the quorum needs, when ApprovalPolicyService/ApprovalPolicy.Route is called, then the evaluation and ApprovalPolicyService/ApprovalRouted are written with the outcome NoEligibleApprover and the reply says so; given the same call repeated for the same approval id, then the first evaluation is returned and nothing is written or published; connectsoft.factory.approval_policy.routings counts each routing once by tenant, action class and outcome (SCN-ApprovalPolicyService-004, SCN-ApprovalPolicyService-007, model/services/governance/ApprovalPolicyService.yaml).
AC4 Given a call without a workload identity, a token without the service scope or a user token, a request without a requester, with a subject kind outside the closed list or with an action class outside the five, a decision of PolicyEngineService/Policy.Decide that carries no approval rule for the action class or a pinned revision the tenant of the call does not hold, and PolicyEngineService stopped, ProjectService stopped, or approval-policy-sql stopped or its transaction failing, when ApprovalPolicyService/ApprovalPolicy.Route is called, then the answers are UNAUTHENTICATED, PERMISSION_DENIED, INVALID_ARGUMENT, FAILED_PRECONDITION and UNAVAILABLE, no evaluation, no kept rule and no event exist, the service retried nothing, and RunControlService opens no request except after FAILED_PRECONDITION (SCN-ApprovalPolicyService-004, ADR-0015).
AC5 Given a routed approval whose evaluation holds the project of the routing call in ProjectId, the column this feature reports as a correction of model/services/governance/ApprovalPolicyService.yaml, and a caller with factory.approvals.read and a role in that project, when ApprovalPolicyService/GetApprovalRouting is called, then the response is 200 with the latest routing of the approval, the rule applied, the eligible approvers, the quorum, the expiry and the outcome; a call without a token is answered 401, a token without the scope or a caller without a role in the project of that column 403, and an approval id without an evaluation in the tenant of the token, which includes an approval of another tenant, 404; and under a transport outage the dispatcher publishes ApprovalPolicyService/ApprovalRouted on approval-policy.routing.v1.approval-routed with retry and without loss or duplicate (SCN-ApprovalPolicyService-003, SCN-ApprovalPolicyService-007, ADR-0012).
Traces: services ApprovalPolicyService, RunControlService, PolicyEngineService, ProjectService, StudioNotificationService, GovernanceHost
Traces: aggregates ApprovalPolicyService/RoutingEvaluation, ApprovalPolicyService/ApprovalRule
Traces: apis ApprovalPolicyService/ApprovalPolicy.Route, ApprovalPolicyService/GetApprovalRouting, PolicyEngineService/Policy.Decide, ProjectService/Projects.ListRoleHolders
Traces: events ApprovalPolicyService/ApprovalRouted
Traces: descriptors run-event-envelope-v1, approval-request-v1, policy-decision-request-v1
Traces: adrs ADR-0012, ADR-0014, ADR-0015
Traces: requirements FR-06, FUX-05, XL-05
Traces: scenarios SCN-ApprovalPolicyService-003, SCN-ApprovalPolicyService-004, SCN-ApprovalPolicyService-007
Relates: screens approval-card, approval-policy
Depends on AIFACTORY-US-923, feature:policy-engine-service, feature:project-service, feature:run-control-service, feature:governance-host, feature:contracts-package
Sources model/services/governance/ApprovalPolicyService.yaml, model/services/governance/PolicyEngineService.yaml, model/services/control-plane/ProjectService.yaml, model/services/control-plane/RunControlService.yaml, docs/planes/control/approvals.md, docs/planes/trust-operations/governance/services/approval-policy-service/index.md#sagas-and-long-running-flows

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-544 Routing evaluation on each request implementation ApprovalPolicy.Route takes the rule of the pinned revision and the action class from ApprovalRules, with a matching action pattern first, and for a revision the service does not hold asks PolicyEngineService/Policy.Decide through a typed client with the action kind approval-eligibility, the target approval, the action class and the pinned revision, takes the rule from the obligations of the decision and keeps it in ApprovalRules under that revision in the transaction of the evaluation; it never uses a rule of another revision; it answers FAILED_PRECONDITION and writes nothing when the decision carries no approval rule for the action class or the pinned revision is not held by the tenant of the call; with a rule found it resolves the eligible approvers through a typed client of ProjectService/Projects.ListRoleHolders without the requester, without the author where the rule excludes the author and without a Platform admin, for every subject of the closed list of approval-request-v1 and without a run, sets the expiry within Governance:Approvals:MaxExpiryMinutes, writes the RoutingEvaluation, with the project of the call metadata once the model carries the column ProjectId, and the ApprovalRouted outbox record in one transaction and replies with evaluation id, rule id, approvers, quorum, expiry, onExpiry and maxReRequests, so that Run Control stores the evaluation id with its request; the outcome is Eligible or NoEligibleApprover; a repeat for the same approval id returns the first evaluation; it ends UNAVAILABLE, with nothing written and no event, when PolicyEngineService or ProjectService does not answer and when approval-policy-sql does not answer or the transaction fails; the refusals UNAUTHENTICATED, PERMISSION_DENIED and INVALID_ARGUMENT write nothing, and the method has no NOT_FOUND answer; the metric routings is recorded. ConnectSoft.AI.SoftwareFactory.ApprovalPolicyService
AIFACTORY-TASK-3719 GetApprovalRouting read of the latest routing of an approval implementation GetApprovalRouting returns the latest routing evaluation of an approval id under the tenant filter with the rule applied, the eligible approvers, the quorum, the expiry and the outcome; it answers 403 for a caller without a role in the project the evaluation holds in the column ProjectId of the reported correction, a check that is built with that column once the model carries it and cannot be made from the modelled table, 404 for an approval id without an evaluation in the tenant of the token, 401, 403 for a token without factory.approvals.read and for a workload token, and 503 while the store does not answer; it writes nothing. ConnectSoft.AI.SoftwareFactory.ApprovalPolicyService
AIFACTORY-TASK-3720 Fakes of Projects.ListRoleHolders and of the identity platform, and the token matrix of the acceptance suite fixture The acceptance suite holds a fake of ProjectService/Projects.ListRoleHolders that lists the holders of a role in a project, by membership and by a delegation in force, can change them between two calls and can be stopped, a fake of the identity platform that confirms or denies the Platform admin role and can be stopped, a switch that fails the transaction of approval-policy-sql, requests of every subject kind of the closed list of approval-request-v1, with and without a run, and tokens for the matrix: no token, a workload token with and without the service scope that names ApprovalPolicyService, and user tokens of each role, of two tenants and with a role in one project and none in another. ConnectSoft.AI.SoftwareFactory.ApprovalPolicyService
AIFACTORY-TASK-3721 Verify the routing of an approval request through the acceptance suite verification Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-ApprovalPolicyService-003\|Scenario=SCN-ApprovalPolicyService-004\|Scenario=SCN-ApprovalPolicyService-007)"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-925 with the fixtures of AIFACTORY-TASK-3715 and AIFACTORY-TASK-3720: a routing under a rule read through PolicyEngineService/Policy.Decide and kept for its revision, a second routing that uses the kept rule, a rule of a newer revision that is not used, a request of a provisioning run without a run, the excluded requester and author, the delegate, the capped expiry, the outcome NoEligibleApprover, the repeated call, FAILED_PRECONDITION for a decision without a rule and for a revision of another tenant, UNAVAILABLE for PolicyEngineService stopped, for ProjectService stopped and for the failed transaction of approval-policy-sql, every refusal with the table and the outbox unchanged, the read of the latest routing with its refusals, the project check of which runs against the column ProjectId, and the publication of ApprovalPolicyService/ApprovalRouted under a transport outage. ConnectSoft.AI.SoftwareFactory.ApprovalPolicyService

AIFACTORY-US-926: Validate that a decider is eligible now, is neither requester nor author, decides in time and meets the quorum

behavior · persona reviewer As a reviewer, I want my decision accepted only when I am eligible at the moment I decide, and the decision of a requester, an author or a member whose role was revoked refused, so that nobody approves their own work and an approval always rests on a role that still holds.

A decision on an approval request is recorded by RunControlService, and before it records one it asks whether the decider may decide. ApprovalPolicy.ValidateDecision is that question: an internal gRPC method called through the gateway GovernanceHost with a workload token that holds the service scope that names ApprovalPolicyService. The request names the approval id, the decider, the decision (approve, reject or request changes), whether it is a break-glass decision and whether it carries a reason, and the count of valid approvals the request already holds. The service reads the routing evaluation of the approval and its rule and checks in a fixed order. The decider is not the requester of the run: a decision by the requester is invalid with the outcome RequesterExcluded, whatever role the decider holds (ADR-0015 point 6). The decider is not the author where the rule excludes the author: AuthorExcluded. The request is not past expiresAt of its routing: Expired, and an expired request is never revived. The decider holds one of the approver roles of the rule in the project now: eligibility is evaluated against the memberships and delegations at decision time, read through Projects.ListRoleHolders of ProjectService (D126, D136), and not against the list of routing time, so a role or a delegation revoked since the routing makes the decision Invalid, and a member granted the role since then is eligible. For an eligible decider the outcome is Eligible, and the reply states whether the quorum of the rule is met with this approval; RunControlService keeps the request Pending until it is. A reject or a request for changes by one eligible decider is valid without a quorum. A Platform admin decides only as break-glass. The decision is valid only when the rule sets breakGlassAllowed, the Platform admin role is confirmed by the claims and groups of the identity platform and, with Governance:Approvals:BreakGlassRequiresReason at its default, the request carries a reason; it is then Eligible with breakGlass true whatever the quorum, and otherwise Invalid. A break-glass decision by the requester of the run stays RequesterExcluded. Every validation, valid or not, writes one RoutingEvaluation of the decision with the decider, the outcome, breakGlass and evaluatedAt, and the ApprovalDecisionValidated outbox record (evaluationId, approvalId, tenantId, deciderId, outcome, breakGlass) in one transaction. Every attempt to decide, the refused ones included, therefore reaches AuditService as evidence through its handler, and a break-glass decision is always audited. The reason of a break-glass decision is kept by RunControlService with the decision; the evaluation holds no free text. connectsoft.factory.approval_policy.invalid_decisions counts the refused validations by tenant and outcome and connectsoft.factory.approval_policy.break_glass the break-glass decisions by tenant. A repeat of the call for the same approval, decider and decision returns the evaluation already written and writes nothing. The service validates and records its evaluation; it does not record the decision, change the request or advance the run, which stay in RunControlService. A request of kind operator-decision is not validated here, and neither is a request that keeps no evaluation id because it was opened after ApprovalPolicy.Route answered FAILED_PRECONDITION: RunControlService decides such a request through PolicyEngineService and its own requester exclusion, exactly as in I1, so a request without a routing can always be decided (AIFACTORY-US-043). The count of valid approvals is the count of the votes RunControlService recorded on the request in ApprovalVotes, one per eligible approver, and RunControlService ends the request Approved with the vote that meets the quorum (D127). Validation reads the subject, the project and the requester from the request and needs no run, so a request of any subject of the closed list of approval-request-v1 is validated under the same rules (D129, D131, D135). A call without a workload identity is refused with UNAUTHENTICATED; a token without the service scope, and a user token, with PERMISSION_DENIED; a request without an approval id, a decider or a decision with INVALID_ARGUMENT; and an approval that was never routed in the tenant of the call, which includes an approval of another tenant, with NOT_FOUND. ProjectService and the identity platform are required dependencies that fail fast: when ProjectService does not answer, or the identity platform does not answer for a break-glass decision, the call ends UNAVAILABLE, no evaluation is written and RunControlService records no decision, so a decision is never accepted on an eligibility that could not be checked. The same holds when approval-policy-sql does not answer or the transaction of the evaluation fails: the call ends UNAVAILABLE, no evaluation and no event exist and RunControlService records no decision. The service retries nothing on its own. This PBI proves what the publisher of ApprovalDecisionValidated can prove; consumer handling is proven by the suite of AuditService.

Acceptance criteria

AC1 Given a routed approval and a decider who holds an approver role of its rule in the project now, when ApprovalPolicyService/ApprovalPolicy.ValidateDecision is called with a workload token that holds the service scope, then the outcome is Eligible, one ApprovalPolicyService/RoutingEvaluation of the decision is written with the decider and evaluatedAt, and the ApprovalPolicyService/ApprovalDecisionValidated outbox record with evaluationId, approvalId, tenantId, deciderId, outcome and breakGlass is written in the same transaction (SCN-ApprovalPolicyService-005, SCN-ApprovalPolicyService-008, ADR-0014).
AC2 Given the requester of the run, the author under a rule that excludes the author, a request past the expiresAt of its routing, and a member whose role or delegation was revoked after the routing, when ApprovalPolicyService/ApprovalPolicy.ValidateDecision is called for each, then the outcomes are RequesterExcluded, AuthorExcluded, Expired and Invalid, each is written as an evaluation with its ApprovalPolicyService/ApprovalDecisionValidated record, and connectsoft.factory.approval_policy.invalid_decisions counts each by tenant and outcome; a member granted the role after the routing is Eligible (SCN-ApprovalPolicyService-005, SCN-ApprovalPolicyService-008, ADR-0015).
AC3 Given a rule with a quorum of two, when ApprovalPolicyService/ApprovalPolicy.ValidateDecision is called for an approve by an eligible decider while the request holds no valid approval, then the reply is Eligible with the quorum not met, and with one valid approval of another decider it is Eligible with the quorum met; a reject by one eligible decider is valid without a quorum; a repeat for the same approval, decider and decision returns the first evaluation and writes nothing (SCN-ApprovalPolicyService-005, FR-06).
AC4 Given a rule that allows break-glass and a decider whose Platform admin role the identity platform confirms, when ApprovalPolicyService/ApprovalPolicy.ValidateDecision is called for a break-glass decision that carries a reason, then the outcome is Eligible with breakGlass true whatever the quorum, the ApprovalPolicyService/ApprovalDecisionValidated record carries breakGlass true and connectsoft.factory.approval_policy.break_glass is incremented; without a reason, under a rule that forbids break-glass or for a role the identity platform does not confirm the outcome is Invalid, and for the requester of the run it is RequesterExcluded (SCN-ApprovalPolicyService-005, SCN-ApprovalPolicyService-008, model/services/governance/ApprovalPolicyService.yaml).
AC5 Given a call without a workload identity, a token without the service scope or a user token, a request without a decider, an approval never routed in the tenant of the call, and ProjectService stopped, the identity platform stopped for a break-glass decision, or approval-policy-sql stopped or its transaction failing, when ApprovalPolicyService/ApprovalPolicy.ValidateDecision is called, then the answers are UNAUTHENTICATED, PERMISSION_DENIED, INVALID_ARGUMENT, NOT_FOUND and UNAVAILABLE, no evaluation and no event exist and RunControlService records no decision; and under a transport outage the dispatcher publishes ApprovalPolicyService/ApprovalDecisionValidated on approval-policy.routing.v1.approval-decision-validated with retry and without loss or duplicate (SCN-ApprovalPolicyService-005, SCN-ApprovalPolicyService-008, ADR-0012).
Traces: services ApprovalPolicyService, RunControlService, ProjectService, AuditService, GovernanceHost
Traces: aggregates ApprovalPolicyService/RoutingEvaluation, ApprovalPolicyService/ApprovalRule
Traces: apis ApprovalPolicyService/ApprovalPolicy.ValidateDecision, ProjectService/Projects.ListRoleHolders
Traces: events ApprovalPolicyService/ApprovalDecisionValidated
Traces: descriptors run-event-envelope-v1
Traces: adrs ADR-0012, ADR-0014, ADR-0015
Traces: requirements FR-06, FUX-05, NFR-04, XL-05
Traces: scenarios SCN-ApprovalPolicyService-005, SCN-ApprovalPolicyService-008
Relates: screens approval-card
Depends on AIFACTORY-US-923, AIFACTORY-US-925, feature:project-service, feature:run-control-service, feature:governance-host, feature:contracts-package
Sources model/services/governance/ApprovalPolicyService.yaml, model/services/control-plane/RunControlService.yaml, docs/planes/control/approvals.md, docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md, docs/planes/trust-operations/governance/services/approval-policy-service/index.md#sagas-and-long-running-flows

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-3722 ApprovalPolicy.ValidateDecision with eligibility at decision time and the quorum implementation ApprovalPolicy.ValidateDecision reads the routing evaluation and the rule of the approval and checks, in this order, the requester exclusion, the author exclusion, the expiry of the routing and the roles and delegations of the decider now through a typed client of Projects.ListRoleHolders; it answers Eligible with the quorum met or not met from the count of the votes RunControlService recorded on the request, treats a reject and a request for changes as valid without a quorum, writes the RoutingEvaluation of the decision and the ApprovalDecisionValidated outbox record in one transaction for every outcome, returns the first evaluation for a repeat, records the metric invalid_decisions, and writes nothing for the refusals UNAUTHENTICATED, PERMISSION_DENIED, INVALID_ARGUMENT, NOT_FOUND and UNAVAILABLE; it ends UNAVAILABLE with no evaluation and no event when ProjectService or approval-policy-sql does not answer or the transaction fails. ConnectSoft.AI.SoftwareFactory.ApprovalPolicyService
AIFACTORY-TASK-3723 Break-glass decision of a Platform admin with the identity platform check implementation A break-glass decision is valid only when the rule sets breakGlassAllowed, the Platform admin role of the decider is confirmed through the client of the identity platform and, with Governance:Approvals:BreakGlassRequiresReason true, the request states that it carries a reason; it is then Eligible with breakGlass true whatever the quorum, and Invalid otherwise; the requester of the run stays RequesterExcluded; the evaluation and the event carry breakGlass and no reason text; the metric break_glass is recorded; when the identity platform does not answer the call ends UNAVAILABLE and nothing is written. ConnectSoft.AI.SoftwareFactory.ApprovalPolicyService
AIFACTORY-TASK-3724 Verify the validation of a decision through the acceptance suite verification Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-ApprovalPolicyService-005\|Scenario=SCN-ApprovalPolicyService-008)"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-926 with the fixtures of AIFACTORY-TASK-3720 and the clock of the suite: an eligible decider, the requester, the author, an expired routing, a role revoked and a role granted between routing and decision, a quorum of two before and after it is met, a reject, the repeated call, break-glass with and without a reason, under a rule that forbids it and for an unconfirmed role, every refusal with the table and the outbox unchanged, UNAVAILABLE with the transaction of approval-policy-sql failed by the switch of AIFACTORY-TASK-3720, and the publication of ApprovalPolicyService/ApprovalDecisionValidated under a transport outage. ConnectSoft.AI.SoftwareFactory.ApprovalPolicyService

AIFACTORY-US-927: Follow membership and delegation changes of a project and execute a deletion order on the stores of the service

behavior · persona workspace-admin As a workspace admin, I want a role or a delegation I revoke to stop counting for approvals at once, and the approval data of a deleted scope removed on order, so that access I took away never decides an approval and nothing of a deleted project stays behind.

Three consumed events keep the service right after the fact. MembershipChanged and DelegationChanged of ProjectService say that a role was granted, changed or removed and that a delegation was granted, expired or revoked (D18). The service caches what it read from ProjectService about the roles of a subject in a project, in the shared cache and never as the authority, and the inbox handler InvalidateEligibilityCache removes the entries of the project and the subject the event names, so the next routing or validation reads the memberships again. The handler is idempotent on the event id and writes no row and no event. It closes the failure mode of the model, a membership revoked while a decision is pending: a validation after the event finds the decider no longer eligible and answers Invalid (AIFACTORY-US-926), and the request is routed again. The model does not say which side starts the re-route. This PBI delivers the routing side: a re-route flag on the request of ApprovalPolicy.Route, with which the service writes a new routing evaluation and a new ApprovalRouted for the same approval, with the approvers eligible now and the expiry of the first routing unchanged, where a plain repeat returns the first evaluation. The trigger in RunControlService, which holds the Pending requests, is reported to the owner. A cache entry also ends on its own after a lifetime taken from the configuration of the deployment, so an event that was lost delays a change and never keeps a revoked role eligible for good; the lifetime is a deployment value and none is fixed here. When the cache does not answer, the service reads ProjectService on every call and stays correct. DeletionOrderIssued of RetentionResidencyService orders every owning service to delete a scope from the stores it owns and to acknowledge. The handlers of the services of earlier increments are built in I4 with that service. ApprovalPolicyService is created in I4, so its handler ExecuteDeletionOrder is built here against the order contract of feature retention-residency-service. For an order of tenant scope it deletes the rows of that tenant in ApprovalRules and RoutingEvaluations of approval-policy-sql. For an order of project scope it deletes the rules of project scope whose scope id is that project and the routing evaluations whose column ProjectId names that project. That column is the correction AIFACTORY-US-925 reports: the modelled RoutingEvaluation holds no project, so the project-scoped delete of evaluations is built with the column once the model carries it, and until then a project order deletes the project rules only and its receipt states that the evaluations of the project were not deleted, which is reported to the owner. The handler removes the cache entries of the scope and acknowledges its task through AcknowledgeOrderTask, an internal operation of RetentionResidencyService that needs the scope factory.data.acknowledge, called with the workload token of this service, with a receipt that names the order, the service, the tables and the row counts. An answer 403 or 404 of the acknowledgement leaves the task unacknowledged: the handler logs it with the order id and without content, deletes nothing a second time and fails, so the inbox retries with backoff, and the order stays open in RetentionResidencyService, which marks it overdue after its deletion window, so the failure is surfaced and never hidden. The handler is idempotent on the order id: a redelivered order deletes nothing more and acknowledges with the same receipt, and a failure before the acknowledgement is retried by the inbox, so an order is neither lost nor half acknowledged. Every delete carries the tenant of the order, so an order never touches the rows of another tenant. The model keeps RoutingEvaluations seven years as audit evidence and lists no retention worker for this service. The evidence itself is held by AuditService, which records every evaluation from the events of this service. The handler deletes exactly what an order names and nothing by a schedule of its own, and how an order relates to the evidence retention of the table is decided by the order rules of RetentionResidencyService; the missing retention worker is reported to the owner.

Acceptance criteria

AC1 Given a cached eligibility of a reviewer and ProjectService/MembershipChanged that removes the role, when InvalidateEligibilityCache handles it, then the cache entries of that project and subject are removed and the next ApprovalPolicyService/ApprovalPolicy.ValidateDecision for that decider answers Invalid from a fresh read of ProjectService; a redelivered event changes nothing, and the handler writes no row and no event (model/services/governance/ApprovalPolicyService.yaml).
AC2 Given ProjectService/DelegationChanged that grants a delegation of the Reviewer role, when the next validation runs for the delegate, then the delegate is Eligible; given the same event for an expired or a revoked delegation, then the delegate is Invalid; given the cache does not answer, then the service reads ProjectService on every call and gives the same answers (ADR-0015, XL-13).
AC3 Given a Pending approval whose routing lists a subject whose membership was revoked, when ApprovalPolicyService/ApprovalPolicy.Route is called for the same approval id with the re-route flag, then a new ApprovalPolicyService/RoutingEvaluation and a new ApprovalPolicyService/ApprovalRouted are written for the approval with the approvers eligible now and the expiry of the first routing; without the flag the first evaluation is returned and nothing is written (model/services/governance/ApprovalPolicyService.yaml).
AC4 Given RetentionResidencyService/DeletionOrderIssued for a project of a tenant, when ExecuteDeletionOrder handles it, then the rules of project scope of that project in ApprovalRules are deleted and, against the column ProjectId this feature reports as a correction of model/services/governance/ApprovalPolicyService.yaml, the routing evaluations of that project in RoutingEvaluations, while the receipt of an order handled before that column exists states that the evaluations were not deleted; the rows of other projects and of other tenants are untouched, the cache entries of the scope are removed and the task is acknowledged through RetentionResidencyService/AcknowledgeOrderTask with a workload token that holds factory.data.acknowledge and a receipt that names the order, the service, the tables and the row counts; given an order of tenant scope, then every row of the tenant in both tables is deleted; a redelivered order deletes nothing more and acknowledges with the same receipt, and a failure before the acknowledgement or an answer 403 or 404 of the acknowledgement leaves the task unacknowledged, is logged with the order id, deletes nothing a second time and is retried by the inbox (ADR-0019, XL-14).
Traces: services ApprovalPolicyService, ProjectService, RetentionResidencyService, RunControlService
Traces: aggregates ApprovalPolicyService/RoutingEvaluation, ApprovalPolicyService/ApprovalRule
Traces: apis ApprovalPolicyService/ApprovalPolicy.Route, ApprovalPolicyService/ApprovalPolicy.ValidateDecision, RetentionResidencyService/AcknowledgeOrderTask
Traces: events ProjectService/MembershipChanged, ProjectService/DelegationChanged, RetentionResidencyService/DeletionOrderIssued, ApprovalPolicyService/ApprovalRouted
Traces: adrs ADR-0015, ADR-0019, ADR-0028
Traces: requirements NFR-04, XL-13, XL-14
Depends on AIFACTORY-US-925, AIFACTORY-US-926, feature:project-service, feature:retention-residency-service
Sources model/services/governance/ApprovalPolicyService.yaml, model/services/control-plane/ProjectService.yaml, model/services/data-event/RetentionResidencyService.yaml, docs/architecture/adr/0019-data-governance.md, docs/planes/trust-operations/governance/services/approval-policy-service/index.md#failure-and-recovery

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-3725 Eligibility cache with the InvalidateEligibilityCache handler and the re-route flag of Route implementation The roles and delegations the service read from ProjectService are cached in the shared cache per tenant, project and subject with a lifetime from the configuration of the deployment, through the store binding cache that the stores of model/services/governance/ApprovalPolicyService.yaml do not list and that is reported as a correction of the service file; the inbox handler of MembershipChanged and DelegationChanged removes the entries of the project and the subject the event names, idempotent on the event id, and writes no row and no event; when the cache does not answer the service reads ProjectService on every call; ApprovalPolicy.Route accepts a re-route flag with which it writes a new RoutingEvaluation and a new ApprovalRouted for the same approval with the approvers eligible now and the expiry of the first routing. ConnectSoft.AI.SoftwareFactory.ApprovalPolicyService
AIFACTORY-TASK-3726 ExecuteDeletionOrder handler with the acknowledgement of the order task implementation The inbox handler of DeletionOrderIssued deletes, for an order of tenant scope, every row of the tenant in ApprovalRules and RoutingEvaluations of approval-policy-sql and, for an order of project scope, the rules of project scope of that project and the routing evaluations whose column ProjectId names it, a delete built with that column once the model carries it, the receipt stating until then that the evaluations of the project were not deleted; it removes the cache entries of the scope, every delete carrying the tenant of the order, and acknowledges its task through a typed client of AcknowledgeOrderTask, called with the workload token of the service that holds the scope factory.data.acknowledge, with a receipt that names the order, the service, the tables and the row counts; an answer 403 or 404 of the acknowledgement leaves the task unacknowledged, is logged with the order id and without content, deletes nothing a second time and fails the handler so that the inbox retries; it is idempotent on the order id, acknowledges a redelivered order with the same receipt and leaves a failure before the acknowledgement to the retry of the inbox; it deletes nothing by a schedule of its own. ConnectSoft.AI.SoftwareFactory.ApprovalPolicyService
AIFACTORY-TASK-3727 Verify the inbox handlers of the service through the acceptance suite verification Run dotnet test -c Release --filter "Category=Acceptance&Feature=InboxHandlers"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-927 with events built from the pinned contracts package and the fakes of AIFACTORY-TASK-3720: ProjectService/MembershipChanged and ProjectService/DelegationChanged that revoke and grant, the stopped cache, the re-route of a Pending approval with and without the flag, RetentionResidencyService/DeletionOrderIssued for a project and for a tenant over a two-tenant fixture with a fake of AcknowledgeOrderTask that records the receipt and the scope of the token and can answer 403 and 404, the receipt of a project order that states the evaluations not deleted while the column ProjectId is absent, the redelivered order and the failure before the acknowledgement. ConnectSoft.AI.SoftwareFactory.ApprovalPolicyService