AIFACTORY-FEAT-005: ProjectService: complete delivery¶
Generated from the architecture model
This page is rendered from model/**/*.yaml by tools/docs_model during mkdocs build. Edit the YAML, not this page; hand-written design lives on the linked service, platform and plane pages.
A design artefact, not a tracker
This backlog is generated from model/backlog/ and validated against the architecture model. No work item exists in any tracker, and no item carries a date, an estimate or an assignee (ADR-0029).
Epic Control Plane (PF-01) · Increment I1 Generate a microservice · State elaborated · Route backend-developer · Build order 54 of 185 (Factory code)
ProjectService is the service of bounded context BC-01 (Project & Environment). Owns projects (workspaces) inside a tenant, their memberships and role assignments, source scope and project-level policy overrides; the scope ids every run carries (BC-01). Its own repository is ConnectSoft.AI.SoftwareFactory.ProjectService.
| Delivers | ProjectService (complete) |
| Stubs | — |
| Realizes | adrs: ADR-0015, ADR-0019 |
| Requirements | FR-01, FUX-01, NFR-01, NFR-03, XL-01, XL-13 |
| Depends on | — |
| Sources | model/services/control-plane/ProjectService.yaml |
Scenarios to trace (17, catalog): SCN-ProjectService-001 ✓, SCN-ProjectService-002 ✓, SCN-ProjectService-003 ✓, SCN-ProjectService-004 ✓, SCN-ProjectService-005 ✓, SCN-ProjectService-006 ✓, SCN-ProjectService-007 ✓, SCN-ProjectService-008 ✓, SCN-ProjectService-015 ✓, SCN-ProjectService-016 ✓, SCN-ProjectService-009 ✓, SCN-ProjectService-017 ✓, SCN-ProjectService-010 ✓, SCN-ProjectService-011 ✓, SCN-ProjectService-012 ✓, SCN-ProjectService-013 ✓, SCN-ProjectService-014 ✓
AIFACTORY-US-056: ProjectService serves its scope end to end¶
behavior · persona platform-admin
As a platform admin, I want one service to own the projects of my tenant, who may act in each of them in which role, and what a run of a project may touch, so that every run, approval, usage record and artifact of the Factory carries a project scope that one owner answers for.
This is the integration PBI of the feature: it proves that the behaviours of ProjectService work together on a deployed instance, in the order a tenant uses them. A Platform admin creates a project and becomes its first Workspace admin (AIFACTORY-US-443); the Workspace admin grants a project role to a second member (AIFACTORY-US-446) and the membership projection follows from the events of the Identity service (AIFACTORY-US-458); the Workspace admin delegates a role for a bounded period and revokes it (AIFACTORY-US-447), and sets what a run of the project may touch (AIFACTORY-US-448); a service with a workload identity resolves the roles and the source scope of a subject through ProjectService/Projects.ResolveScope (AIFACTORY-US-445), and the members who hold a role in the project are listed through ProjectService/Projects.ListRoleHolders (AIFACTORY-US-1494, D136); members list and read their projects (AIFACTORY-US-444); the Workspace admin suspends the project with a reason and resumes it (AIFACTORY-US-550); the Workspace admin closes the project and the off-boarding brings it to Closed once RunControlService has confirmed that its runs are settled and ArtifactService that its data was exported or deleted (AIFACTORY-US-449). The repository and the store come from AIFACTORY-US-441 and the hosted surface from AIFACTORY-US-442. The Identity service is the system of record of role assignments and delegations (ADR-0015 amendments of D114 and D115): the chain runs against an Identity service generated from the identity template with the Factory role catalogue, to which ProjectService writes with its own workload token and a named actor, and from whose events it keeps the Memberships and Delegations projection. The service is deployed as its own workload with its own store project-sql and its own messaging service name project, and it is reached through the routes of the platform gateway (ADR-0028). Every call carries a trusted tenant: a project of another tenant is answered 404 by every route and NOT_FOUND over gRPC, a missing scope inside the tenant of the caller 403. The five events of the service are written to the outbox in the transaction of the change they announce and published in the run event envelope of the contracts package. What this delivery does not hold is stated here and in the PBI it belongs to. The handlers of the three retention events are not built, because their producer RetentionResidencyService is first delivered in I4, and the legal-hold and deletion-order handlers are built in this repository in I4 by feature retention-residency-service (D137). No command of the model sets policyOverrideRevision: the field stays empty, the validation call to PolicyEngineService that the model lists as a required dependency is not built, and the aggregate enforces the fourth invariant as empty or validated. budgetId stays empty and the optional gRPC dependency on CostUsageService is not used: the budget of a project is opened by CostUsageService from ProjectService/ProjectCreated, CostUsageService has no method that creates a budget, and ProjectService consumes no event that would bring the budget id back. The points about policyOverrideRevision and budgetId are gaps of the model that are reported to the owner and are not decided in this feature. Repository: ConnectSoft.AI.SoftwareFactory.ProjectService.
Acceptance criteria
| AC1 | Given ProjectService deployed from the repository of AIFACTORY-US-441 behind the platform gateway and an Identity service generated from the identity template with the Factory role catalogue, when a Platform admin calls ProjectService/CreateProject and then, as the Workspace admin of the new project, ProjectService/SetMembership for a second member with the role Reviewer, then ProjectService/Projects.ResolveScope for that member returns the role Reviewer, and ProjectService/ProjectCreated and ProjectService/MembershipChanged are each published once in the run event envelope (ADR-0015, FR-01). |
| AC2 | Given the same project, when the Workspace admin calls ProjectService/SetSourceScope with one repository and one tool, ProjectService/Delegate for a third member with an expiry and a reason, and then ProjectService/RevokeDelegation, then ProjectService/Projects.ResolveScope returns the stated source scope, returns the delegated role only between the grant and the revocation, and ProjectService/SourceScopeChanged and two ProjectService/DelegationChanged events are published (ADR-0015, XL-01). |
| AC3 | Given projects of two tenants, when a member of the first tenant calls ProjectService/ListProjects and addresses a project of the second tenant through ProjectService/GetProject, ProjectService/SetMembership, ProjectService/SetSourceScope and ProjectService/CloseProject, then the list holds projects of the first tenant only, every addressed call is answered 404, the same answer as for a project that does not exist, and a call without the scope of its route inside the own tenant is answered 403 (ADR-0015, NFR-01). |
| AC4 | Given the project of AC1 with an unexpired delegation, when the Workspace admin calls ProjectService/CloseProject, then the response is 202, ProjectService/ProjectStateChanged announces Closing, the delegation is revoked through the Identity service, the ProjectService/Project stays Closing until RunControlService/ProjectRunsSettled and ArtifactService/ProjectDataOffboarded have both arrived, and it then reaches Closed with a second ProjectService/ProjectStateChanged (XL-13). |
| AC5 | Given the acceptance suite of the repository, when it runs against the deployed instance, then each of the seventeen scenarios of model/scenarios/ProjectService.yaml is executed by at least one test that carries its scenario id, a filter that matches no test counts as a failure, and the suite passes. |
| Traces: services | ProjectService, ControlPlaneApi |
| Traces: aggregates | ProjectService/Project |
| Traces: apis | ProjectService/CreateProject, ProjectService/ListProjects, ProjectService/GetProject, ProjectService/SetMembership, ProjectService/Delegate, ProjectService/RevokeDelegation, ProjectService/SetSourceScope, ProjectService/CloseProject, ProjectService/SuspendProject, ProjectService/ResumeProject, ProjectService/Projects.ResolveScope, ProjectService/Projects.ListRoleHolders |
| Traces: events | ProjectService/ProjectCreated, ProjectService/ProjectStateChanged, ProjectService/MembershipChanged, ProjectService/DelegationChanged, ProjectService/SourceScopeChanged, RunControlService/ProjectRunsSettled, ArtifactService/ProjectDataOffboarded |
| Traces: adrs | ADR-0015, ADR-0019, ADR-0028 |
| Traces: requirements | FR-01, XL-01, XL-13, NFR-01 |
| Relates: screens | project-overview, project-settings |
| Relates: nfrs | NFR-01 |
| Depends on | AIFACTORY-US-441, AIFACTORY-US-442, AIFACTORY-US-443, AIFACTORY-US-444, AIFACTORY-US-445, AIFACTORY-US-446, AIFACTORY-US-447, AIFACTORY-US-448, AIFACTORY-US-449, AIFACTORY-US-458, AIFACTORY-US-550, AIFACTORY-US-1494, feature:control-plane-api, feature:component-identity-template-factory-roles, feature:run-control-service, feature:artifact-service |
| Sources | model/services/control-plane/ProjectService.yaml, model/scenarios/ProjectService.yaml, docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md, docs/planes/control/services/project-service/index.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-1801 Deploy ProjectService as its own workload with its store, its messaging service name and its gateway routes |
operations | ProjectService runs as its own workload from the manifests the template generates, with its own relational store project-sql, the messaging service name project, the transport credential read from the secret reference messaging-transport, the address of the Identity service and the workload credential it writes with; the ten REST routes are reachable through the platform gateway and readiness answers ready only after the store is migrated and the messaging profile has started (ADR-0028). |
ConnectSoft.AI.SoftwareFactory.ProjectService |
AIFACTORY-TASK-701 Verify project-service-serves-its-scope through the end-to-end chain of the acceptance suite |
verification | Run dotnet build -c Release and dotnet test -c Release --no-build --filter "Category=Acceptance" against the deployed instance and the generated Identity service; a filter that matches no test counts as a failure; the chain create, grant, delegate, set scope, resolve, read, suspend, resume and close passes, the close reaching Closed only after the confirmations of RunControlService and ArtifactService of the same environment, and every scenario id of model/scenarios/ProjectService.yaml is carried by at least one passing test, which proves AC1 to AC5 of AIFACTORY-US-056. |
ConnectSoft.AI.SoftwareFactory.ProjectService |
AIFACTORY-US-441: ProjectService repository: scaffolded from the base template with the Factory profile, with the Project aggregate and its store project-sql¶
enabling
The repository ConnectSoft.AI.SoftwareFactory.ProjectService is created and scaffolded in I0 by AIFACTORY-TASK-016 of feature repository-and-pipeline-conventions (D140), and this feature starts from that scaffold, made with the scaffold command of ADR-0028 and its amendment on the Factory profile switch (D114): dotnet new connectsoft-base -n ConnectSoft.AI.SoftwareFactory.ProjectService --UseFactoryProfile true, from the template package at the version the gate of feature component-base-template-factory-profile published (AIFACTORY-US-230), after the findings of feature component-base-template-findings are closed (AIFACTORY-US-235). The generated output is committed unchanged and the repository records the version of the template package it was generated from. What the profile generates, that is the Orleans messaging profile with an outbox and an inbox of the service, the propagation of the trusted tenant and project scope, the role policies, the REST and gRPC hosts from a service descriptor, health and telemetry, is the work of the template feature; it is consumed by that version pin and is neither rewritten nor forked here. The run event envelope and the event type names come from the contracts package by a version pin as well. On that scaffold this PBI adds the domain and the store. The Project aggregate holds projectId, tenantId, key, name, state, region, the optional policyOverrideRevision, retentionDays, the optional budgetId and a version, with the entities Membership, Delegation and SourceScopeEntry and the value object ProjectKey, a lower-case key of 3 to 32 characters. The region of a project is the region of its tenant, whose source is the options DataEvent:Stores:DefaultRegion and DataEvent:Stores:AllowedRegions, bound by StoreProfileService in I4 (AIFACTORY-US-049); in I1 to I3 those two values are owner inputs of the I1 precondition register of AIFACTORY-US-1339 (D140). It enforces the invariants the aggregate can hold on its own: a key is unique within a tenant and immutable after creation, and policyOverrideRevision is empty or is set through an operation that demands a validation result. No command of the model calls that operation, so the field stays empty in this delivery, and so does budgetId, which nothing sets. The invariants that span services are enforced where they act: a membership or a delegation exists as a row only for a record the Identity service announced (AIFACTORY-US-458, AIFACTORY-US-447), and closing follows the off-boarding of AIFACTORY-US-449. The state machine has exactly five transitions: Active to Suspended (Suspend), Suspended to Active (Resume), Active to Closing and Suspended to Closing (Close), and Closing to Closed (OffboardingCompleted). The store project-sql is owned by this service alone, and this PBI migrates four of the five tables of the model, Projects, Memberships, Delegations and SourceScopes, with the unique index over tenant and key, the filtered index over grantee and expiry for unrevoked delegations, a row version on Projects and the tenant filter in every mapping. Memberships and Delegations are a projection of the records of the Identity service (ADR-0015 amendment of D114): no command writes them, only the inbox handlers of AIFACTORY-US-458 and AIFACTORY-US-447 do. The fifth table, the off-boarding journal OffboardingJournal, and the columns ClosedBy and CloseRequestedAt of the closing actor, which the model holds since D117, are added by the migration task of AIFACTORY-US-449. Nothing is observable for a caller yet; the routes and the messaging profile are hosted by AIFACTORY-US-442.
Acceptance criteria
| AC1 | Given the repository created and scaffolded in I0 by AIFACTORY-TASK-016 of feature repository-and-pipeline-conventions with dotnet new connectsoft-base -n ConnectSoft.AI.SoftwareFactory.ProjectService --UseFactoryProfile true from the base template package at the version the gate of feature component-base-template-factory-profile published, when its pipeline runs, then the committed output equals the generated output, the solution builds in Release, the generated tests pass, a container image is published and the repository records the template version (ADR-0028, model/template-parameters/connectsoft-base.yaml). |
| AC2 | Given the ProjectService/Project aggregate, when its unit tests run, then a key outside 3 to 32 lower-case characters and a change of the key after creation are refused, policyOverrideRevision is accepted only empty or together with a validation result, as the fourth invariant of model/services/control-plane/ProjectService.yaml demands, the five transitions Active to Suspended, Suspended to Active, Active to Closing, Suspended to Closing and Closing to Closed are accepted, and every other transition, among them Closed to Active and Closing to Active, is refused. |
| AC3 | Given project-sql created by the migrations of the repository on an isolated test database, when the mapping tests run, then the tables Projects, Memberships, Delegations and SourceScopes exist with their keys and indexes, a second project with the same key in one tenant violates the unique index while the same key in another tenant is accepted, and a query made for one tenant never returns a row of another (ADR-0015, NFR-01). |
| Traces: services | ProjectService |
| Traces: aggregates | ProjectService/Project |
| Traces: adrs | ADR-0015, ADR-0019, ADR-0028 |
| Traces: requirements | NFR-01 |
| Depends on | feature:repository-and-pipeline-conventions, feature:component-base-template-factory-profile, feature:component-base-template-findings, feature:contracts-package |
| Sources | model/services/control-plane/ProjectService.yaml, model/template-parameters/connectsoft-base.yaml, model/stores.yaml, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md, docs/planes/control/services/project-service/index.md#domain-model |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-017 Domain model: Project with Membership, Delegation, SourceScopeEntry and ProjectKey |
implementation | The Project aggregate with its entities and the ProjectKey value object enforces the key invariants of the model, accepts policyOverrideRevision only empty or together with a validation result, and exposes the operations Suspend, Resume, Close and OffboardingCompleted, which are the only transitions between Active, Suspended, Closing and Closed; unit tests cover the key rules, the override rule, each of the five transitions and the refusal of every other one. | ConnectSoft.AI.SoftwareFactory.ProjectService |
AIFACTORY-TASK-018 Persistence in project-sql: Projects, Memberships, Delegations, SourceScopes |
migration | Mappings and migrations for these four tables of the model, the fifth, OffboardingJournal, being migrated by AIFACTORY-TASK-1845, with the unique index UX_Projects_Tenant_Key, the filtered index IX_Delegations_Grantee_Active, the row version of Projects and the tenant filter in every mapping; Memberships and Delegations are written by the projection handlers only; mapping tests run against an isolated test database, never a shared one. | ConnectSoft.AI.SoftwareFactory.ProjectService |
AIFACTORY-TASK-1802 Verify the scaffold, the Project aggregate and the store of ProjectService |
verification | Run dotnet build -c Release and dotnet test -c Release --no-build in the repository pipeline; the generated tests, the unit tests of the aggregate and the mapping tests on an isolated database pass, and a diff of the committed tree against a fresh generation at the recorded template version shows only the files this PBI added, which proves AC1 to AC3 of AIFACTORY-US-441 (ADR-0028). |
ConnectSoft.AI.SoftwareFactory.ProjectService |
AIFACTORY-US-442: ProjectService host: ten REST routes and two gRPC methods behind scope policies, the project messaging profile, the Identity contracts and write client, tenancy and telemetry¶
enabling
This PBI turns the scaffold of AIFACTORY-US-441 into a host on which the behaviour PBIs of the feature land. From the service descriptor the host exposes the ten REST operations of the model, SuspendProject and ResumeProject among them (D117), for the platform gateway (GW-03) and the two internal gRPC methods Projects.ResolveScope and Projects.ListRoleHolders (D136), with their contract documents, an OpenAPI document and a proto. Tokens are validated through the resource-server library the profile wires, and each route requires its scope: factory.projects.read for the two reads, factory.projects.write for creation, factory.projects.admin for memberships, source scope, close, suspend and resume, and factory.projects.delegate for the two delegation routes; each gRPC method requires a workload identity whose token holds the service scope that names ProjectService. The tenant comes from the token. Eight of the ten routes address a project by projectId, and such a route admits the call only when the role claims of the token name that project or carry a tenant-wide role; CreateProject and ListProjects address no project. A resource of another tenant is invisible under the tenant row filter and is answered 404, over gRPC NOT_FOUND, while a missing scope inside the tenant of the caller is answered 403 (ADR-0015 amendments of D113 and D114); the filter is wired here and the 404 is proven by the behaviour PBIs that read a project. Every modelled refusal code has a problem response. The two operations with a key-header idempotency rule, CreateProject and Delegate, pass an idempotency filter: the same Idempotency-Key with the same input returns the stored result, the same key with a different input is a conflict (ADR-0014 decision 3). The messaging profile of the service is named project: the outbox writer enlists in the unit of work of a command, the dispatcher publishes the five events of the model in the run event envelope of the contracts package with their routes declared in the OrleansMessaging section, and the inbox subscribes, with deduplication on the event id, to the assignment and delegation events of the Identity service and to the two confirmations of a closing project, ProjectRunsSettled of RunControlService and ProjectDataOffboarded of ArtifactService (D117); what each handler does is delivered by AIFACTORY-US-458, AIFACTORY-US-447 and AIFACTORY-US-449. The host also brings what every command that writes roles needs. The repository pins the ServiceModel package of the identity template at the version the gate AIFACTORY-US-243 of feature component-identity-template-factory-roles published and takes the role assignment and delegation requests, responses and events from it. That feature publishes contracts and no client for these writes, the only HTTP client it names being the claims client of the authorization server template, so the write client is built in this repository on the pinned contracts: it sends the workload token of ProjectService, names the acting member on every write and never forwards a user token (ADR-0015 amendment of D115). The options Projects:Retention:DefaultRetentionDays, Projects:Delegation:MaxDelegationDays, Multitenancy:DeploymentKind and OrleansMessaging:ServiceName are bound and validated at start, the transport credential is read from the secret reference messaging-transport, the metrics connectsoft.factory.projects.active and connectsoft.factory.projects.delegations_active are registered with the tenant dimension, and readiness reports the store, the messaging profile and the Identity service. The model also lists three consumed events of RetentionResidencyService (RetentionRuleChanged, DeletionOrderIssued, LegalHoldChanged). Their handlers are not part of this delivery: that service is first delivered in I4, and the owner decided that the legal-hold and deletion-order handlers of each owning service are built in its repository in I4 by feature retention-residency-service (D137), so nothing of a later increment is built against here.
Acceptance criteria
| AC1 | Given the hosted service, when each of the ten REST operations of model/services/control-plane/ProjectService.yaml is called without a token and with a token that lacks the scope of the route, then the answers are 401 and 403 with a problem response; when one of the eight operations that address a projectId is called with a token of the tenant whose role claims neither name that project nor carry a tenant-wide role, then the answer is 403; a gRPC call without a workload identity or without the service scope is refused with Unauthenticated or PermissionDenied; no state changes (ADR-0015). |
| AC2 | Given an operation with the key-header idempotency rule, when two requests carry the same Idempotency-Key and the same input, then the second returns the stored result and the handler runs once; when the second carries a different input, then it is answered 409 (ADR-0014). |
| AC3 | Given a handler that changes a ProjectService/Project and publishes one of the five declared events, when its unit of work commits, then one outbox record in run-event-envelope-v1 with event id, tenant id, project id, correlation id and payload is committed in the same transaction; when the unit of work rolls back, neither the change nor the record exists; a publish of an event the OrleansMessaging section does not declare throws (ADR-0012, ADR-0014). |
| AC4 | Given the service starts, when liveness and readiness are probed, then readiness answers ready only after project-sql is migrated and the messaging profile has started and names the dependency while it is unready, the four options of model/services/control-plane/ProjectService.yaml are bound and an invalid value stops the start with the key named, and traces and logs carry the tenant and project scope of the call (ADR-0015). |
| AC5 | Given the write client of the role assignment and delegation API built on the pinned ServiceModel contracts, when it sends a grant, a removal, a delegation or a revocation, then the request carries the workload token of ProjectService and the acting member and no user token, and an answer of the Identity service that the record already exists, a refused actor, a record that is not found and an unavailable service each come back as their own typed result, on which the commands of AIFACTORY-US-443, AIFACTORY-US-446, AIFACTORY-US-447 and AIFACTORY-US-449 decide (ADR-0015). |
| Traces: services | ProjectService |
| Traces: aggregates | ProjectService/Project |
| Traces: descriptors | run-event-envelope-v1, execution-scope-v1 |
| Traces: adrs | ADR-0012, ADR-0014, ADR-0015, ADR-0028 |
| Traces: requirements | FR-01, NFR-01 |
| Depends on | AIFACTORY-US-441, feature:component-base-template-factory-profile, feature:contracts-package, feature:component-identity-template-factory-roles |
| Sources | model/services/control-plane/ProjectService.yaml, model/gateways.yaml, docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md, docs/architecture/adr/0014-run-and-lifecycle-envelopes.md, docs/planes/control/services/project-service/index.md#apis, docs/planes/control/services/project-service/index.md#security |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-019 API hosting skeleton: REST and gRPC hosts, scope enforcement, problem responses and contract documents for the 10 REST operations and 2 gRPC methods |
implementation | The ten REST routes and the gRPC methods Projects.ResolveScope and Projects.ListRoleHolders are hosted from the service descriptor with token validation, scope enforcement per route, the workload identity and service scope check on each gRPC method, problem responses for every modelled refusal code, the Idempotency-Key filter of CreateProject and Delegate, and the OpenAPI and proto documents; the behaviour of each operation is delivered by AIFACTORY-US-443 to AIFACTORY-US-449, AIFACTORY-US-550 and AIFACTORY-US-1494, not here. | ConnectSoft.AI.SoftwareFactory.ProjectService |
AIFACTORY-TASK-020 Messaging skeleton: outbox and inbox wiring of the project profile for 5 published events, the Identity events of the projection and the two confirmations of a closing project |
implementation | The outbox writer enlists in the unit of work and the dispatcher of the project messaging profile publishes ProjectCreated, ProjectStateChanged, MembershipChanged, DelegationChanged and SourceScopeChanged in the run event envelope of the pinned contracts package, each declared with its route in the OrleansMessaging section; the inbox subscribes, with deduplication on the event id, to the assignment and delegation events of the Identity service and to ProjectRunsSettled of RunControlService and ProjectDataOffboarded of ArtifactService; the three retention events of RetentionResidencyService are not subscribed in this delivery; what each handler does is delivered by the behaviour PBIs of this feature. | ConnectSoft.AI.SoftwareFactory.ProjectService |
AIFACTORY-TASK-1813 Pin of the role and delegation contracts and events of the Identity service |
contract | The repository pins the ServiceModel package of the identity template at the version the gate AIFACTORY-US-243 of feature component-identity-template-factory-roles published and takes from it the role assignment and delegation requests, responses and events; it copies no type, and the workload credential of ProjectService holds the service scope of the role writes. | ConnectSoft.AI.SoftwareFactory.ProjectService |
AIFACTORY-TASK-1843 Write client of the role assignment and delegation API of the Identity service |
implementation | An HTTP client of the role assignment and delegation write API of the Identity service, built in this repository on the pinned ServiceModel contracts because the identity feature publishes no client for these writes: it sends the workload token of ProjectService and names the acting member on every grant, removal, delegation and revocation, never forwards a user token, and returns a typed result for accepted, already exists, refused actor (403), not found (404) and unavailable; unit tests cover the 403, the 404, the conflict and the unavailable answer. | ConnectSoft.AI.SoftwareFactory.ProjectService |
AIFACTORY-TASK-022 Security, tenancy and telemetry of ProjectService |
implementation | The four scopes of the model are enforced, a route that addresses a projectId admits a call only when the role claims of the token name the project or carry a tenant-wide role, every query is tenant-filtered, the transport credential comes from the secret reference messaging-transport, the four options are bound and validated at start, readiness reports the store, the messaging profile and the Identity service, and the metrics connectsoft.factory.projects.active and connectsoft.factory.projects.delegations_active are registered with the tenant dimension under the observability conventions; the 404 that follows from the tenant filter is proven by the behaviour PBIs that read a project. | ConnectSoft.AI.SoftwareFactory.ProjectService |
AIFACTORY-TASK-1803 Verify the hosted surface of ProjectService with a two-tenant fixture |
verification | Run dotnet test -c Release --no-build --filter "Category=Acceptance&Area=Hosting"; a filter that matches no test counts as a failure; the tests call every route without a token and without its scope, call the eight routes that address a projectId with a token that does not admit the project, repeat a keyed request with the same and with a different input, commit and roll back a publishing handler, probe readiness with the store stopped, and drive the write client against an Identity double that answers accepted, already exists, 403, 404 and unavailable, which proves AC1 to AC5 of AIFACTORY-US-442 (ADR-0015, ADR-0014). |
ConnectSoft.AI.SoftwareFactory.ProjectService |
AIFACTORY-US-443: Create a project in the tenant of the caller with its first Workspace admin and announce it¶
behavior · persona platform-admin
As a platform admin, I want to create a project in my tenant and become its first Workspace admin, so that the people of the project can be given roles and its runs have a scope, a budget and a retention from the first day.
A caller whose scope carries factory.projects.write creates a project through the gateway route of ProjectService/CreateProject with an Idempotency-Key. The tenant comes from the trusted scope of the authenticated context, never from the body (ADR-0015); the body names the key, a lower-case key of 3 to 32 characters that is unique within the tenant and immutable after creation, and the name. The caller becomes the first Workspace admin of the project. The Identity service is the system of record of role assignments (ADR-0015 amendments of D114 and D115), so the command writes to two systems, and its order and its failure branches are fixed here. First, everything ProjectService can decide alone is decided before the Identity service is called: the scope of the caller, the validation of the body, the idempotency filter and the uniqueness of the key in the tenant. Second, the projectId is derived deterministically from the tenant and the Idempotency-Key, so a repeat of the request, also after a crash, addresses the same project and the same assignment. Third, ProjectService writes the Workspace admin assignment of the caller for that projectId through the role assignment API of the Identity service with its own workload token and names the caller as the acting member; the user token of the caller is not forwarded. The Identity service decides from its own records whether that actor may manage assignments in the scope; a new project has no Workspace admin yet, so only a Platform admin of the tenant passes, as AIFACTORY-US-240 of feature component-identity-template-factory-roles delivers, and this PBI restates none of its rules. An answer of the Identity service that this same assignment already exists counts as accepted, which is the case of a repeat after a crash. Fourth, the Project is committed in state Active with the tenant of the trusted scope, key, name, the region of the tenant (ADR-0019), retentionDays from Projects:Retention:DefaultRetentionDays and no policy override, together with its ProjectCreated outbox record in one transaction, and the answer is 201 with the project. The region of the tenant is read through one tenant region reader whose source is the options DataEvent:Stores:DefaultRegion and DataEvent:Stores:AllowedRegions, bound by StoreProfileService in I4 (AIFACTORY-US-049); in I1 to I3 those two values are owner inputs of the I1 precondition register of AIFACTORY-US-1339, supplied by the owner before the I1 run (D140), and the acceptance suite supplies the value. The answer is 201 only when the project and the assignment both stand. When the Identity service refuses the actor the answer is 403, and when it is unavailable the command is rejected with 503 as the failure mode of the model states; nothing was written in either system. When the commit of the project fails after the Identity service accepted the assignment, because a concurrent request took the key or the store is unavailable, ProjectService removes the assignment again through the Identity service and answers the failure, 409 or 503, never 201. When that removal cannot be completed either, a repeat with the same Idempotency-Key converges after a transient failure, since it derives the same projectId, meets the assignment that exists and commits; an assignment left for a projectId that holds no project grants nothing, because every route answers 404 for it, and it is written to the operator log with its projectId. A repeated call with the same key and the same input returns the same project and changes nothing; the same Idempotency-Key with a different input, or a key that already exists in the tenant, is refused with 409 before the Identity service is called; a body that fails validation is refused with 400 and a caller without the scope with 403. ProjectCreated is published by the outbox dispatcher of the project messaging profile on projects.projects.v1.project-created in the run event envelope of the contracts package with projectId, tenantId, key and region; CostUsageService opens the default budget of the project, WorkflowEngineService correlates the signal, StudioBff refreshes its view and AuditService records the evidence in their own PBIs. The membership row of the creator appears in the projection when the assignment event of the Identity service is handled (AIFACTORY-US-458); that event can reach the inbox before the project is committed and is then redelivered until the project row exists. connectsoft.factory.projects.active rises by one for the tenant.
Acceptance criteria
| AC1 | Given a Platform admin of a tenant whose scope carries factory.projects.write and a valid body, when ProjectService/CreateProject is called with an Idempotency-Key, then the projectId is the value derived from the tenant and that key, the Identity service receives one Workspace admin assignment for that projectId, written with the workload token of ProjectService and naming the caller as actor, the response is 201, the ProjectService/Project is Active with the tenant of the trusted scope, the region the tenant region reader of the fixture supplies and retentionDays from Projects:Retention:DefaultRetentionDays, and the ProjectService/ProjectCreated outbox record is written in the same transaction as the project (SCN-ProjectService-001, ADR-0015). |
| AC2 | Given the same request repeated with the same Idempotency-Key and the same input, when it arrives at ProjectService/CreateProject, then the same project is returned and no second project, assignment or outbox record exists; given a different input under the same key, or a key another project of the tenant already uses, then the answer is 409 and the Identity service received no write, while the same key in another tenant is accepted; given a first attempt that stopped after the Identity service accepted the assignment and before the project was committed, when the request is repeated, then the same projectId is derived, the answer of the Identity service that the assignment already exists counts as accepted, and one project with one assignment stands (SCN-ProjectService-001, ADR-0014). |
| AC3 | Given a body whose key is not 3 to 32 lower-case characters, a caller without factory.projects.write, an actor the Identity service refuses because by its records the caller is not Platform admin of the tenant, or an Identity service that is unavailable, when ProjectService/CreateProject is called, then the answer is 400, 403, 403 or 503 respectively with a problem response, the first two are answered before the Identity service is called, no ProjectService/Project row and no assignment is written and nothing is published (SCN-ProjectService-001, ADR-0015). |
| AC4 | Given the Identity service accepted the assignment and the commit of the ProjectService/Project then fails, once because a concurrent request took the key and once because project-sql is unavailable, when ProjectService/CreateProject ends, then the Identity service received the removal of that assignment with the caller named as actor, the answer is 409 or 503 respectively and never 201, and no project row and no ProjectService/ProjectCreated record exists; when the removal fails as well, then the answer is the same failure and the assignment is named in the operator log with its projectId (SCN-ProjectService-001, ADR-0015). |
| AC5 | Given the project was created, when the outbox dispatcher of the project messaging profile publishes ProjectService/ProjectCreated on projects.projects.v1.project-created, then the event is sent in run-event-envelope-v1 with projectId, tenantId, key and region, and a transport outage is retried with backoff so the event is neither lost nor duplicated under its event id (SCN-ProjectService-010, ADR-0012). |
| Traces: services | ProjectService |
| Traces: aggregates | ProjectService/Project |
| Traces: apis | ProjectService/CreateProject |
| Traces: events | ProjectService/ProjectCreated |
| Traces: descriptors | run-event-envelope-v1 |
| Traces: adrs | ADR-0012, ADR-0014, ADR-0015, ADR-0019 |
| Traces: requirements | FR-01, XL-01 |
| Traces: scenarios | SCN-ProjectService-001, SCN-ProjectService-010 |
| Relates: nfrs | NFR-01 |
| Depends on | AIFACTORY-US-441, AIFACTORY-US-442, feature:component-identity-template-factory-roles |
| Sources | model/services/control-plane/ProjectService.yaml, model/scenarios/ProjectService.yaml, docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md, docs/planes/control/services/project-service/index.md#apis |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-1804 CreateProject with the first Workspace admin assignment written through the Identity service, in a fixed order with its failure branches |
implementation | CreateProject checks the scope, the body, the idempotency filter and the uniqueness of the key in the tenant before it calls the Identity service, derives the projectId from the tenant and the Idempotency-Key, writes the Workspace admin assignment of the caller through the client of AIFACTORY-TASK-1843 with the workload token of ProjectService and the caller named as actor, counts the answer that this assignment already exists as accepted, and commits the Project in Active with the region from the tenant region reader, whose source is DataEvent:Stores DefaultRegion and AllowedRegions (owner inputs of the I1 precondition register of AIFACTORY-US-1339 in I1 to I3, bound by StoreProfileService in I4, D140), retentionDays and its ProjectCreated outbox record in one transaction; when that commit fails it removes the assignment through the Identity service and answers 409 or 503, and writes the projectId to the operator log when the removal fails; it answers 201 only when the project and the assignment both stand, 403 when the Identity service refuses the actor, 503 when it is unavailable, 400 for an invalid body and 409 for a key conflict or a reused idempotency key with another input, and connectsoft.factory.projects.active rises by one. | ConnectSoft.AI.SoftwareFactory.ProjectService |
AIFACTORY-TASK-1805 Acceptance fixture of an Identity service generated from the identity template with the Factory role catalogue |
fixture | The acceptance suite starts an Identity service generated from the identity template at the version the gate of feature component-identity-template-factory-roles published, seeded with the Factory role catalogue, two tenants, a bootstrapped Platform admin, a tenant-wide Observer and further members in each, and a workload credential that holds the service scope of the role writes; the fixture can be stopped to prove the 503 path, can be stopped between two writes of one command, records every write it receives with its actor, and the suite supplies the region of each tenant through the tenant region reader and can make the commit of a project fail after the assignment was accepted. | ConnectSoft.AI.SoftwareFactory.ProjectService |
AIFACTORY-TASK-1806 Verify create-a-project through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-ProjectService-001\|Scenario=SCN-ProjectService-010)"; a filter that matches no test counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-443, that is the creation with its derived projectId, the assignment the Identity fixture received, the idempotent repeat, the repeat after an interrupted first attempt, the 400, 403, 409 and 503 refusals, the removal of the assignment after a failed commit, and the publication and payload of ProjectCreated; consumer handling is proven by the suites of the consumers. |
ConnectSoft.AI.SoftwareFactory.ProjectService |
AIFACTORY-US-444: List the projects a caller holds a role in and read one project with its members, delegations and source scope¶
behavior · persona requester
As a requester, I want to see the projects I belong to and, for one of them, who holds which role and what its runs may touch, so that I pick the right project for my work and know who can decide in it.
A caller whose scope carries factory.projects.read lists projects through ProjectService/ListProjects and reads one through ProjectService/GetProject. Both read project-sql only: the Projects rows and the Memberships, Delegations and SourceScopes rows of a project, of which Memberships and Delegations are the projection ProjectService keeps from the events of the Identity service (ADR-0015 amendment of D114). ListProjects returns the projects of the trusted tenant in which the caller holds a membership row or a delegation that is neither expired nor revoked, each with projectId, key, name, state and region, paged. Two roles are held for the whole tenant and come from the role claims of the token, never from a membership row (ADR-0015 decision 5): Platform admin, and Observer when it was assigned with the tenant scope, which the decision allows for a project or the tenant. A caller with either claim receives every project of the tenant from ListProjects and may read each of them through GetProject. For the tenant-wide Observer this stays read-only, because both routes are reads and the Observer role admits no command. GetProject returns one project with its state, region and retention, its memberships (subject, role, who granted it and when), its delegations (grantor, grantee, role, expiry, reason and revocation) and its source scope entries. Every query runs under the tenant row filter of the service, so a project of another tenant is never listed and is answered 404 when addressed, the same answer as for a projectId that does not exist; the response never confirms that the project exists (ADR-0015 amendment of D113). A caller without factory.projects.read, or a member of the tenant who holds neither a role in the addressed project nor one of the two tenant-wide roles by claim, is refused with 403. Neither read writes anything. When project-sql is unavailable or the token cannot be validated the call fails fast with a problem response. The summary of GetProject in the model also names environments. EnvironmentService owns them, and the project overview screen reads them through its own list beside GetProject, so this PBI returns no environment data.
Acceptance criteria
| AC1 | Given three projects in the tenant of the caller and one in another tenant, where the caller holds a membership in the first and an unexpired, unrevoked delegation in the second, when ProjectService/ListProjects is called with a page cursor, then the response is 200 with exactly the first and the second project, each with projectId, key, name, state and region; a Platform admin of the tenant and an Observer assigned with the tenant scope, each by the role claims of the token and without any membership row, receive all three, and the project of the other tenant never appears (SCN-ProjectService-002, ADR-0015). |
| AC2 | Given a caller with factory.projects.read who holds a role in a project with two memberships, one delegation and two source scope entries, when ProjectService/GetProject is called, then the response is 200 with the state, region and retention of the ProjectService/Project, both memberships with grantedBy and grantedAt, the delegation with grantor, grantee, role, expiresAt and reason, and both entries, and nothing is written (SCN-ProjectService-003). |
| AC3 | Given a caller without factory.projects.read, a member of the tenant who holds neither a role in the addressed project nor a tenant-wide role by claim, or a projectId that exists only in another tenant, when ProjectService/GetProject is called, then the answer is 403, 403 or 404 respectively, the 404 being the same answer as for a projectId that does not exist, each with a problem response and no state change; given an Observer assigned with the tenant scope or a Platform admin, then the answer is 200 for every project of the tenant (SCN-ProjectService-003, ADR-0015). |
| AC4 | Given project-sql is unavailable, when ProjectService/ListProjects is called, then the call fails fast with a problem response and no state changes (SCN-ProjectService-002). |
| Traces: services | ProjectService |
| Traces: aggregates | ProjectService/Project |
| Traces: apis | ProjectService/ListProjects, ProjectService/GetProject |
| Traces: adrs | ADR-0015 |
| Traces: requirements | FR-01, FUX-01 |
| Traces: scenarios | SCN-ProjectService-002, SCN-ProjectService-003 |
| Relates: screens | project-overview, project-settings |
| Relates: nfrs | NFR-01 |
| Depends on | AIFACTORY-US-441, AIFACTORY-US-442 |
| Sources | model/services/control-plane/ProjectService.yaml, model/scenarios/ProjectService.yaml, model/ux/screens.yaml, docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md, docs/planes/control/services/project-service/index.md#apis |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-1807 Contract of the project list item and the project view |
contract | The OpenAPI document of the service holds the paged project list with projectId, key, name, state and region and the project view with state, region, retention, memberships, delegations and source scope entries, named after the fields of model/services/control-plane/ProjectService.yaml; the view holds no environment data. | ConnectSoft.AI.SoftwareFactory.ProjectService |
AIFACTORY-TASK-1808 ListProjects and GetProject read model over project-sql with the tenant row filter and paging |
implementation | ListProjects returns the projects of the trusted tenant in which the caller holds a membership row or a valid delegation, and every project of the tenant for a caller whose role claims carry Platform admin or an Observer assignment with the tenant scope, paged; GetProject returns the project view from the Projects, Memberships, Delegations and SourceScopes rows to a caller with a role in the project or with one of those two tenant-wide claims; both apply the tenant row filter so a project of another tenant is answered 404 like an unknown one, answer 403 for a missing scope or a caller without a role in the project and without a tenant-wide claim, and write nothing. | ConnectSoft.AI.SoftwareFactory.ProjectService |
AIFACTORY-TASK-1809 Verify read-projects through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-ProjectService-002\|Scenario=SCN-ProjectService-003)"; a filter that matches no test counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-444 with projects of two tenants, a membership, a delegation, a Platform admin by claim and an Observer with the tenant scope by claim. |
ConnectSoft.AI.SoftwareFactory.ProjectService |
AIFACTORY-US-445: Resolve the roles, the source scope and the policy context of a subject in a project for every service that asks¶
behavior
A service of the Factory with a workload identity calls the internal gRPC method ProjectService/Projects.ResolveScope at request time to build the trusted scope of a command: RunControlService calls it at submission and at decision time, and every module that accepts a command for a project may call it. The request is an execution-scope-v1, whose schema requires tenantId, projectId, callerId, callerKind and a policyContext with policyRevision. The subject whose roles are resolved is callerId when callerKind is user, and delegatedUserId when a workload or a partner agent acts on behalf of a user; a workload or a system caller without delegatedUserId holds no project role, because project roles are held by members. The workload token of the calling service carries the service scope that names ProjectService and no tenant claim, and ProjectService reads the forwarded tenant and project only because the token holds that service scope (ADR-0015 amendment of D114). The reply is the same execution-scope-v1 completed from project-sql and valid against its schema. tenantId, projectId, callerId, callerKind, delegatedUserId and environmentId are returned as sent. roles holds the roles of the membership rows of the subject in the project together with the roles of the delegations to the subject that are neither revoked nor past expiresAt at the moment of the call. sourceScope holds the repositories, documentCollections and toolIds of the SourceScopes rows. policyContext.region is the region of the project, and policyContext.policyRevision is the value the caller sent, that is the platform revision it pinned. The schema has one policyRevision and no field for a project override, and no command of the model sets policyOverrideRevision, so at this increment the reply never carries an override; how an override travels once a command sets it is reported to the owner and not decided here. Validity of a delegation is decided at read, so an expired delegation contributes no role even before its expiry reached the projection. The two tenant-scope roles, Platform admin and an Observer assigned for the tenant, are never resolved from a row: they travel as role claims of the token of the subject, which the calling service already holds, and the reply adds nothing for them. The method answers for a project in any state, Active, Suspended, Closing or Closed: whether a run may start in the project is the gate RunControlService keeps in its GateStates from the state events of the project, not a refusal of this method. The method is of the read class: it writes nothing and publishes nothing. Its result is valid for the request it was resolved for; neither ProjectService nor a caller caches it across requests, because a cross-request cache would keep a revoked delegation effective longer than the audit says, as the service page states. A caller without a workload identity is refused with Unauthenticated, a workload token without the service scope with PermissionDenied, a request that fails validation against the schema with InvalidArgument, and an unknown project and a project of another tenant alike with NOT_FOUND, which never confirms that a foreign project exists (ADR-0015 amendments of D113 and D114).
Acceptance criteria
| AC1 | Given a subject with a membership role and an unexpired, unrevoked delegated role in a project that has repository, document and tool entries and no policy override, when ProjectService/Projects.ResolveScope is called by a workload identity whose token holds the service scope, with an execution-scope-v1 that names the subject as callerId with callerKind user and a policyContext.policyRevision, then the reply validates against docs/reference/schemas/execution-scope.schema.json, returns callerId, callerKind and that policyRevision as sent, carries both roles, the three lists of sourceScope and the region of the ProjectService/Project, and nothing is written or published; a workload caller that names the subject as delegatedUserId receives the same roles (SCN-ProjectService-009). |
| AC2 | Given a delegation to the subject that is past expiresAt although its expiry has not reached the projection yet, or one whose row carries revokedAt, when ProjectService/Projects.ResolveScope is called, then the role of that delegation is absent from roles; given a subject who is Platform admin or tenant-wide Observer by claim and holds no membership row, then roles of the reply holds no row-resolved role for that subject (SCN-ProjectService-009, ADR-0015). |
| AC3 | Given a caller without a workload identity, a workload token without the service scope, a request without callerId, callerKind or policyContext.policyRevision, an unknown project or a project of another tenant, when ProjectService/Projects.ResolveScope is called, then the call is refused with Unauthenticated, PermissionDenied, InvalidArgument, NOT_FOUND and NOT_FOUND respectively and no state changes (SCN-ProjectService-009, ADR-0015). |
| AC4 | Given two consecutive calls for the same subject and project between which a membership row of the projection changed, when the second ProjectService/Projects.ResolveScope is answered, then it reflects the change, which shows that no result is cached across requests, as docs/planes/control/services/project-service/index.md requires; given a project that is Closing or Closed, then the method answers as for an Active one. |
| Traces: services | ProjectService |
| Traces: aggregates | ProjectService/Project |
| Traces: apis | ProjectService/Projects.ResolveScope |
| Traces: descriptors | execution-scope-v1 |
| Traces: adrs | ADR-0015 |
| Traces: requirements | FR-01, NFR-01 |
| Traces: scenarios | SCN-ProjectService-009 |
| Relates: nfrs | NFR-01 |
| Depends on | AIFACTORY-US-441, AIFACTORY-US-442 |
| Sources | model/services/control-plane/ProjectService.yaml, model/scenarios/ProjectService.yaml, model/descriptors.yaml, docs/reference/schemas/execution-scope.schema.json, docs/planes/control/services/project-service/index.md#apis |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-1810 Contract of Projects.ResolveScope over the execution scope descriptor |
contract | The proto of the service declares Projects.ResolveScope with a request and a reply that match docs/reference/schemas/execution-scope.schema.json as model/descriptors.yaml records execution-scope-v1; the contract document states that the subject is callerId for callerKind user and delegatedUserId for a workload or a partner agent that acts for a user, that tenantId, projectId, callerId, callerKind, delegatedUserId and environmentId are returned as sent, that policyContext.policyRevision of the reply is the value the caller sent and policyContext.region the region of the project, that roles and sourceScope are filled from the store, and that the method answers for a project in any state; the type comes from the pinned contracts package and is not copied. | ConnectSoft.AI.SoftwareFactory.ProjectService |
AIFACTORY-TASK-1811 ResolveScope from the membership and delegation projection with validity decided at read |
implementation | Projects.ResolveScope resolves the subject from callerId, callerKind and delegatedUserId, reads the membership rows, the delegations that are neither revoked nor past expiresAt at the call, the SourceScopes rows and the region of the project under the forwarded tenant, returns the policy revision the caller sent, resolves no tenant-scope role from a row, answers for a project in any state, admits the forwarded tenant and project only for a workload token with the service scope, caches nothing across requests, and answers Unauthenticated, PermissionDenied, InvalidArgument or NotFound, the gRPC status NOT_FOUND, for an unknown and for a foreign project alike. | ConnectSoft.AI.SoftwareFactory.ProjectService |
AIFACTORY-TASK-1812 Verify resolve-execution-scope through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&Scenario=SCN-ProjectService-009"; a filter that matches no test counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-445 with a reply of a project without an override validated against docs/reference/schemas/execution-scope.schema.json, a user caller and a workload caller with delegatedUserId, a controlled clock for the expired delegation, a projection change between two calls and a Closed project. |
ConnectSoft.AI.SoftwareFactory.ProjectService |
AIFACTORY-US-1494: List the members of a project who hold a role, by membership or by a delegation in force, for the services that route approvals and notifications¶
behavior
Two services need to know who holds a role in a project rather than which roles one subject holds. ApprovalPolicyService needs the eligible approvers of a request when it routes it and the eligibility of a decider when the decision is taken, and StudioNotificationService needs the recipients of a notification addressed to a role of a project (D126, D136). The internal gRPC method ProjectService/Projects.ListRoleHolders answers them. It is of the read class and takes an execution-scope-v1 that names the tenant, the project and the caller, with the role asked in roles; as a design choice of this PBI a request that names no role or more than one is refused with InvalidArgument. The method answers the members of the project who hold that role, each with its subject id and whether the role comes from a membership row or from a delegation, from the projection of memberships and delegations the service keeps from the events of the Identity service (AIFACTORY-US-458) and without a call to the Identity service. A delegation counts while it is in force, that is neither revoked nor past expiresAt at the moment of the call, decided at read as for Projects.ResolveScope, so an expired delegation names no holder even before its expiry reached the projection. A member who holds the role both ways is named once, by membership. The two tenant-scope roles, Platform admin and an Observer assigned for the tenant, travel as role claims of a token and are held in no row, so the method never lists them. A role nobody holds in the project is answered with an empty list. The method answers for a project in any state, Active, Suspended, Closing or Closed, because whether an approval may be decided or a notification sent is decided by the caller. The model declares no reply schema for the method; the contract document of this PBI fixes the reply members it names, and the missing descriptor is reported to the owner. The result is valid for the request it was resolved for and is cached across requests neither by ProjectService nor by a caller. The caller holds a workload identity whose token carries the service scope that names ProjectService, and ProjectService reads the forwarded tenant and project only for such a token (ADR-0015 amendment of D114). A caller without a workload identity is refused with Unauthenticated, a workload token without the service scope with PermissionDenied, and an unknown project and a project of another tenant alike with NOT_FOUND, which never confirms that a foreign project exists. The method writes nothing and publishes nothing.
Acceptance criteria
| AC1 | Given a project with one member who holds the role Reviewer by membership, one who holds it by a delegation in force, one who holds it both ways and one who holds another role, when ProjectService/Projects.ListRoleHolders is called by a workload identity whose token holds the service scope, with an execution-scope-v1 that names the project and the role Reviewer, then the reply names the first three members once each with the source of the role, membership for the third, does not name the fourth, and nothing is written or published; the ProjectService/Project is read from the projection without a call to the Identity service (SCN-ProjectService-017, D136). |
| AC2 | Given a delegation of the role that is past expiresAt although its expiry has not reached the projection yet, or one whose row carries revokedAt, when ProjectService/Projects.ListRoleHolders is called for that role, then its delegate is not named; given a subject who is Platform admin or tenant-wide Observer by claim only, then it is never named; given a role nobody holds, then the reply is an empty list; given a project that is Closing or Closed, then the method answers as for an Active one (SCN-ProjectService-017, ADR-0015). |
| AC3 | Given a caller without a workload identity, a workload token without the service scope, a request that names no role or more than one, an unknown project or a project of another tenant, when ProjectService/Projects.ListRoleHolders is called, then the call is refused with Unauthenticated, PermissionDenied, InvalidArgument, NOT_FOUND and NOT_FOUND respectively and no state changes (SCN-ProjectService-017, ADR-0015). |
| AC4 | Given two consecutive calls for the same role and project between which a membership row of the projection changed, when the second ProjectService/Projects.ListRoleHolders is answered, then it reflects the change, which shows that no result is cached across requests (SCN-ProjectService-017, docs/planes/control/services/project-service/index.md). |
| Traces: services | ProjectService |
| Traces: aggregates | ProjectService/Project |
| Traces: apis | ProjectService/Projects.ListRoleHolders |
| Traces: descriptors | execution-scope-v1 |
| Traces: adrs | ADR-0015 |
| Traces: requirements | FR-01, NFR-01 |
| Traces: scenarios | SCN-ProjectService-017 |
| Depends on | AIFACTORY-US-442, AIFACTORY-US-458 |
| Sources | model/services/control-plane/ProjectService.yaml, model/services/governance/ApprovalPolicyService.yaml, docs/reference/schemas/execution-scope.schema.json, docs/planes/control/services/project-service/index.md#apis |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-6073 Contract of Projects.ListRoleHolders with its request over the execution scope descriptor and its reply members |
contract | The proto of the service declares Projects.ListRoleHolders with a request that matches docs/reference/schemas/execution-scope.schema.json as model/descriptors.yaml records execution-scope-v1, the role asked carried in roles, and a reply that lists the holders, each with its subject id and the source of the role, membership or delegation; the contract document states that the reply is read from the projection, that a delegation counts while it is in force at the call, that tenant-scope roles are never listed and that the method answers for a project in any state, and names the missing reply descriptor as reported to the owner. | ConnectSoft.AI.SoftwareFactory.ProjectService |
AIFACTORY-TASK-6074 ListRoleHolders from the membership and delegation projection with validity decided at read |
implementation | Projects.ListRoleHolders reads, under the forwarded tenant, the membership rows that hold the role asked in the project and the delegations of that role that are neither revoked nor past expiresAt at the call, names each holder once with membership preferred over delegation, lists no tenant-scope role, calls no Identity service, caches nothing across requests, admits the forwarded tenant and project only for a workload token with the service scope, and answers Unauthenticated, PermissionDenied, InvalidArgument for a request with no role or more than one, or NOT_FOUND for an unknown and for a foreign project alike. | ConnectSoft.AI.SoftwareFactory.ProjectService |
AIFACTORY-TASK-6075 Verify list-the-holders-of-a-role-in-a-project through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&Scenario=SCN-ProjectService-017"; a filter that matches no test counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-1494 with a projection of members who hold a role by membership, by delegation and both ways, a controlled clock for the expired delegation, a revoked delegation, a claim-only Platform admin, a role nobody holds, a Closed project, each refusal and a projection change between two calls. |
ConnectSoft.AI.SoftwareFactory.ProjectService |
AIFACTORY-US-446: Grant, change and remove the project roles of a member through the Identity service, one write at a time and convergent on repeat¶
behavior · persona workspace-admin
As a workspace admin, I want to state which roles a member holds in my project, so that people can act in the project in the role they have and every change of access is recorded where roles are held.
A Workspace admin whose scope carries factory.projects.admin states the roles a subject holds in a project through ProjectService/SetMembership, a PUT on the member the path addresses by subjectId. The body names the project roles the subject shall hold, taken from MembershipRole (Requester, Reviewer, AssetMaintainer, Operator, WorkspaceAdmin, Observer). A body that names Platform admin, which is tenant-wide and lives in the Identity service, or any other value outside MembershipRole is refused with 400 before the Identity service is called. ProjectService compares the stated roles with the membership projection of the subject and writes the difference through the role assignment API of the Identity service: a grant for each role the subject does not hold yet and a removal for each role that is no longer stated, so a statement without roles removes the subject from the project. The writes are sent one by one, grants before removals, each with the workload token of ProjectService and the caller named as the acting member; the user token of the caller is not forwarded (ADR-0015 amendment of D115). The Identity service is the system of record of role assignments (D114): it decides from its own records whether the actor is Workspace admin of the project or Platform admin, checks that the subject is a member of the tenant, stores the assignment and raises its event, as AIFACTORY-US-240 of feature component-identity-template-factory-roles delivers. ProjectService changes no membership row in the command; the projection and MembershipChanged follow from the events of the Identity service (AIFACTORY-US-458). The projection lags behind the system of record, so the computed difference can be stale, and the command is built to converge: the answer of the Identity service that a granted assignment already exists and its answer that a removed assignment is not found both count as accepted. The answer is 200 once every write was accepted. A repeat that states the roles the projection already holds sends nothing; a repeat that arrives before the events of the first statement were handled sends the same writes again, receives those two answers and is answered 200 as well. A statement is not atomic across its writes, and this PBI does not claim it is: when a later write fails, the answer is that failure, 503 for an unavailable Identity service or the refusal it gave, the writes accepted before it stand in the Identity service and reach the projection through their events, and the same PUT repeated converges on the stated set. A caller without the scope is refused with 403; an actor the Identity service refuses, whatever role the token states, is answered 403; a project of another tenant is answered 404 like one that does not exist, and so is a subjectId that is not a member of the tenant; when the Identity service is unavailable the command is rejected with 503. In none of these cases does ProjectService hold a membership row that the Identity service did not announce, because a row is written by the projection handler only. The model lists the codes 200, 400, 403, 404 and 503 for this route (D117), the 400 for an invalid role and the 503 for its own failure mode.
Acceptance criteria
| AC1 | Given a Workspace admin of a project whose scope carries factory.projects.admin and a subject who is a member of the tenant, when ProjectService/SetMembership states the role Reviewer for that subject, then the Identity service receives one grant written with the workload token of ProjectService and naming the caller as actor, the response is 200, and the command itself writes no Memberships row (SCN-ProjectService-004, ADR-0015). |
| AC2 | Given the subject holds the role Reviewer in the projection, when ProjectService/SetMembership states the role Operator only, then the Identity service receives a grant of Operator and then a removal of Reviewer; when it states no role, then it receives a removal of every role the subject holds in the project; when it states the roles the projection already holds, then it receives nothing; when the same PUT is repeated before the events of the first were handled, then the same writes are sent again, the answers that the assignment already exists and that the removed assignment is not found count as accepted, and the response is 200 (SCN-ProjectService-004). |
| AC3 | Given a statement that needs a grant and a removal and an Identity service that becomes unavailable after it accepted the grant, when ProjectService/SetMembership ends, then the answer is 503, the accepted grant stands in the Identity service and reaches the projection through its event, ProjectService holds no row that the Identity service did not announce, and the same PUT repeated after the Identity service is back sends the grant again, which counts as accepted, sends the removal and is answered 200 (SCN-ProjectService-004, ADR-0015). |
| AC4 | Given a body that names PlatformAdmin or another value outside MembershipRole, a caller without factory.projects.admin, an actor who by the records of the Identity service is neither Workspace admin of the project nor Platform admin although the token states the role, a project of another tenant, a subjectId that is not a member of the tenant, or an Identity service that is unavailable, when ProjectService/SetMembership is called, then the answer is 400, 403, 403, 404, 404 or 503 respectively with a problem response, the 400 is answered before the Identity service is called, no projection row changes and nothing is published (SCN-ProjectService-004, ADR-0015). |
| Traces: services | ProjectService |
| Traces: aggregates | ProjectService/Project |
| Traces: apis | ProjectService/SetMembership |
| Traces: adrs | ADR-0015 |
| Traces: requirements | FR-01, XL-01, XL-13 |
| Traces: scenarios | SCN-ProjectService-004 |
| Relates: screens | project-settings |
| Relates: nfrs | NFR-01 |
| Depends on | AIFACTORY-US-441, AIFACTORY-US-442, AIFACTORY-US-443, AIFACTORY-US-458, feature:component-identity-template-factory-roles |
| Sources | model/services/control-plane/ProjectService.yaml, model/scenarios/ProjectService.yaml, docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md, docs/planes/control/services/project-service/index.md#failure-and-recovery |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-1814 SetMembership writing grants and removals through the Identity service one by one with a named actor |
implementation | SetMembership refuses with 400 a role outside MembershipRole before any call, compares the stated roles of the subject with the membership projection and sends one grant per new role and then one removal per role no longer stated through the client of AIFACTORY-TASK-1843, one by one, with the workload token of ProjectService and the caller named as actor; an answer that the assignment already exists on a grant and an answer of not found on a removal count as accepted; it writes no Memberships row, answers 200 when every write was accepted, stops at the first write that fails and answers 503 or the refusal while the accepted writes stand, so that the same PUT repeated converges on the stated set; it answers 403 without the scope or when the Identity service refuses the actor and 404 for a foreign or unknown project and for a subject outside the tenant. | ConnectSoft.AI.SoftwareFactory.ProjectService |
AIFACTORY-TASK-1816 Verify set-project-membership through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&Scenario=SCN-ProjectService-004"; a filter that matches no test counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-446 against the Identity fixture of AIFACTORY-TASK-1805, including the writes it received with their actor and their order, a repeat before the events arrived, the fixture stopped between the grant and the removal with the convergent repeat, and the 400, 403, 404 and 503 refusals. |
ConnectSoft.AI.SoftwareFactory.ProjectService |
AIFACTORY-US-458: Keep the membership projection from the assignment events of the Identity service and publish MembershipChanged after it changed¶
behavior
The Memberships rows of ProjectService are a projection of the role assignments the Identity service holds, the system of record (ADR-0015 amendment of D114). No command writes them. The inbox of the project messaging profile receives the assignment granted and assignment removed events of the Identity service, deduplicated on the event id, and the handler of this PBI applies them. A grant for a project scope writes the row of project, subject and role with grantedBy and grantedAt taken from the event, a removal deletes it, and the MembershipChanged outbox record with projectId, tenantId, subjectId, role and change is written in the transaction of that projection change. MembershipChanged is therefore published after the projection changed, on projects.memberships.v1.membership-changed in the run event envelope of the contracts package; ApprovalPolicyService re-evaluates eligibility, StudioBff refreshes its view and AuditService records the access change in their own PBIs. A change of role arrives as a grant and a removal and is announced as two events, each with its change. An event whose scope is the tenant changes no row and publishes nothing. That is how the two tenant-wide roles are held, Platform admin and an Observer assigned for the tenant: they travel as role claims of the token and are never a membership row (AIFACTORY-US-444, AIFACTORY-US-445). An event can overtake the project it belongs to. CreateProject writes the first Workspace admin assignment to the Identity service before it commits the project (AIFACTORY-US-443), so the event of that assignment can reach the inbox while project-sql holds no such project yet. Such an event is neither acknowledged nor dropped: the handler fails it, the inbox redelivers it with backoff until the project row exists, and when its retries are exhausted it is parked with the reason named, where an operator sees it and can release it. The events of an assignment whose project was never committed end the same way. A redelivery of an event that was already applied changes no row and writes no record. Projects.ResolveScope and the two reads return the projection as it stands, so a role is effective in the Factory from the moment its event was applied.
Acceptance criteria
| AC1 | Given the Identity service raised the assignment event of a grant for a project the store holds, when the inbox handler of ProjectService runs, then the projection row of project, subject and role exists with grantedBy and grantedAt from the event and the ProjectService/MembershipChanged outbox record is written in the same transaction; given the removal event of that assignment, then the row is deleted and a second record with its change is written; a redelivery of an applied event id changes no row and writes no record (SCN-ProjectService-012, ADR-0014). |
| AC2 | Given the assignment event of the first Workspace admin reaches the inbox before project-sql holds the project, when the handler runs, then the event is not acknowledged, no row and no ProjectService/MembershipChanged record is written and the inbox redelivers it; when the project row exists at a later delivery, then the membership row and the record are written once; given a project that is never committed, then the event is parked with the reason named after its retries are exhausted and no row exists (SCN-ProjectService-012, ADR-0012). |
| AC3 | Given an assignment event whose scope is the tenant, once for Platform admin and once for Observer, when the handler runs, then no Memberships row changes and no ProjectService/MembershipChanged record is written, because tenant-scope roles travel as claims (SCN-ProjectService-012, ADR-0015). |
| AC4 | Given a projection row changed, when the outbox dispatcher of the project messaging profile publishes ProjectService/MembershipChanged on projects.memberships.v1.membership-changed, then the event is sent in run-event-envelope-v1 with projectId, tenantId, subjectId, role and change, and a transport outage is retried with backoff so the event is neither lost nor duplicated under its event id (SCN-ProjectService-012, ADR-0012). |
| Traces: services | ProjectService |
| Traces: aggregates | ProjectService/Project |
| Traces: events | ProjectService/MembershipChanged |
| Traces: descriptors | run-event-envelope-v1 |
| Traces: adrs | ADR-0012, ADR-0014, ADR-0015 |
| Traces: requirements | FR-01, XL-01 |
| Traces: scenarios | SCN-ProjectService-012 |
| Relates: screens | project-settings |
| Relates: nfrs | NFR-01 |
| Depends on | AIFACTORY-US-441, AIFACTORY-US-442, feature:component-identity-template-factory-roles |
| Sources | model/services/control-plane/ProjectService.yaml, model/scenarios/ProjectService.yaml, docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md, docs/planes/control/services/project-service/index.md#messages |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-1815 Membership projection handler publishing MembershipChanged after the projection changed |
implementation | The inbox handler of the assignment granted and assignment removed events of the Identity service writes or deletes the Memberships row of project, subject and role with grantedBy and grantedAt from the event and writes the MembershipChanged outbox record in the same transaction, idempotently on the event id; an event for a tenant scope, which holds Platform admin and a tenant-wide Observer, changes no row; an event for a project the store does not hold is not acknowledged and is redelivered with backoff until the project row exists, and is parked with the reason named when its retries are exhausted. | ConnectSoft.AI.SoftwareFactory.ProjectService |
AIFACTORY-TASK-1844 Verify the membership projection through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&Scenario=SCN-ProjectService-012"; a filter that matches no test counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-458 with the events of the Identity fixture of AIFACTORY-TASK-1805, including a redelivered event, an assignment event delivered before the project row exists and applied after it, an event parked for a project that is never committed, tenant-scope events of Platform admin and Observer, and the publication and payload of MembershipChanged; consumer handling is proven by the suites of the consumers. |
ConnectSoft.AI.SoftwareFactory.ProjectService |
AIFACTORY-US-447: Delegate the same or a lesser role for a bounded period, revoke it at any time and let it expire on its own¶
behavior · persona workspace-admin
As a workspace admin, I want to hand one of my roles or a lesser one to another member for a bounded period with a reason, and to take it back at any time, so that work continues while I am away and every hand-over is recorded, limited and ends without anyone acting.
A role holder whose scope carries factory.projects.delegate hands a role to another member through ProjectService/Delegate with an Idempotency-Key: the body names the grantee, the role, the expiry and a reason (D18). Before it calls anyone, ProjectService refuses with 400 a delegation without a reason, without an expiry, with an expiry later than Projects:Delegation:MaxDelegationDays from the moment of the call, or with a role outside MembershipRole, among them Platform admin, which a delegation never grants. It then writes the delegation through the delegation API of the Identity service, the system of record of delegations (ADR-0015 amendment of D114), with its own workload token and with the caller named as the acting member and grantor (D115). The Identity service decides from its own records, never from a role the request states, whether the grantor holds in that project the delegated role or a higher one under the order of the amendment: Observer is below every role; Requester, Reviewer, Asset maintainer and Operator are not comparable with each other and each is below Workspace admin; every role is below Platform admin. It also checks that the grantee is a member of the tenant, and a grantee who is not is answered 404, as in SetMembership. AIFACTORY-US-241 of feature component-identity-template-factory-roles delivers these rules and this PBI restates none of their internals. The answer is 201 with the delegationId the Identity service assigned; a repeat with the same key and the same input returns the same delegation, and the same key with a different input is refused with 409. ProjectService/RevokeDelegation ends a delegation immediately. ProjectService checks that the project of the path exists in the trusted tenant and then lets the Identity service resolve the delegation under that tenant and project. It does not look the delegation up in its own projection, which lags behind the system of record and may not hold a delegation yet that was granted a moment ago, so a revocation right after the 201 of Delegate works. The revocation is written with the workload token of ProjectService and the caller as actor; the Identity service admits the grantor, the Workspace admin of the project and a Platform admin, and the answer is 204. A revocation the Identity service answers as already revoked counts as accepted and is answered 204. The 404 for an unknown delegation, for a delegation of another project and for one of another tenant is the answer of the Identity service, passed on unchanged. ProjectService changes no Delegations row in either command. The inbox handlers of the grant, revocation and expiry events of the Identity service keep the Delegations projection (grantor, grantee, role, expiresAt, reason, revokedAt) and write the DelegationChanged outbox record in the transaction of each projection change, idempotently on the event id, so the event is published after the projection changed, on projects.delegations.v1.delegation-changed in the run event envelope with delegationId, projectId, tenantId, granteeId, role and change. The DelegationExpiryReconciler runs every ten minutes over projection rows past expiresAt whose revokedAt is empty, two tenants in parallel, with three attempts at a fixed backoff of 60 seconds: it announces the expiry by writing DelegationChanged once under the idempotency key delegationId plus expiresAt, so the reconciler and the expiry event of the Identity service never announce one expiry twice, whichever comes first. It writes nothing to the Identity service, where validity is decided when claims are read. connectsoft.factory.projects.delegations_active follows the unexpired, unrevoked rows per tenant. A caller without the scope is refused with 403, a grantor or a revoking actor the Identity service refuses with 403, a project of another tenant with 404 like one that does not exist, and an unavailable Identity service rejects the command with 503 and leaves no row. The model lists the codes 201, 400, 403, 404, 409 and 503 for Delegate (D117), and this PBI answers each of them. ApprovalPolicyService, StudioBff and AuditService consume DelegationChanged in their own PBIs.
Acceptance criteria
| AC1 | Given a Workspace admin of a project whose scope carries factory.projects.delegate, when ProjectService/Delegate is called with a grantee of the tenant, the role Reviewer, an expiry within Projects:Delegation:MaxDelegationDays, a reason and an Idempotency-Key, then the Identity service receives one delegation written with the workload token of ProjectService and naming the caller as actor and grantor, and the response is 201 with the delegationId; a repeat with the same key and input returns the same delegation without a second write, and the same key with another input is answered 409 (SCN-ProjectService-005, ADR-0014). |
| AC2 | Given a body without a reason, without an expiry, with an expiry beyond Projects:Delegation:MaxDelegationDays or with a role outside MembershipRole, among them PlatformAdmin, when ProjectService/Delegate is called, then the answer is 400 with a problem response that names the rule and the Identity service is not called; given a caller without the scope, a grantor who by the records of the Identity service holds neither the delegated role nor a higher one under the order of ADR-0015 although the request states it, a grantee who is not a member of the tenant, a project of another tenant, or an unavailable Identity service, then the answer is 403, 403, 404, 404 or 503 respectively; no Delegations row is written and nothing is published (SCN-ProjectService-005). |
| AC3 | Given a valid delegation, when ProjectService/RevokeDelegation is called by its grantor, by the Workspace admin of the project or by a Platform admin, then the Identity service receives the revocation with the caller named as actor and the response is 204, also when the call follows the 201 of ProjectService/Delegate before the grant event reached the projection; a revocation the Identity service answers as already revoked is answered 204; any other actor is answered 403; and an unknown delegation and a delegation of another tenant alike are answered 404, which is the answer of the Identity service passed on (SCN-ProjectService-006, ADR-0015). |
| AC4 | Given the Identity service raised a grant, a revocation or an expiry event of a delegation, when the inbox handler runs, then the Delegations projection row is written or updated and the ProjectService/DelegationChanged outbox record with change is written in the same transaction, a redelivery of the event id changes nothing, and the dispatcher publishes the event on projects.delegations.v1.delegation-changed in run-event-envelope-v1 with delegationId, projectId, tenantId, granteeId and role, retried with backoff on a transport outage without loss or duplicate (SCN-ProjectService-013, ADR-0012). |
| AC5 | Given a projection row past expiresAt with an empty revokedAt whose expiry event has not arrived, when the DelegationExpiryReconciler runs, then ProjectService/DelegationChanged announcing the expiry is written once under the key delegationId plus expiresAt, a later run and a late expiry event of the Identity service announce nothing more, nothing is written to the Identity service, and connectsoft.factory.projects.delegations_active falls by one (SCN-ProjectService-013). |
| Traces: services | ProjectService |
| Traces: aggregates | ProjectService/Project |
| Traces: apis | ProjectService/Delegate, ProjectService/RevokeDelegation |
| Traces: events | ProjectService/DelegationChanged |
| Traces: descriptors | run-event-envelope-v1 |
| Traces: adrs | ADR-0012, ADR-0014, ADR-0015 |
| Traces: requirements | FR-01, XL-13 |
| Traces: scenarios | SCN-ProjectService-005, SCN-ProjectService-006, SCN-ProjectService-013 |
| Relates: screens | project-settings |
| Relates: nfrs | NFR-01 |
| Depends on | AIFACTORY-US-441, AIFACTORY-US-442, AIFACTORY-US-446, feature:component-identity-template-factory-roles |
| Sources | model/services/control-plane/ProjectService.yaml, model/scenarios/ProjectService.yaml, docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md, docs/planes/control/services/project-service/index.md#workers-and-jobs |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-1817 Delegate and RevokeDelegation writing through the Identity service with a named actor |
implementation | Delegate answers 400, before the Identity service is called, for a body without a reason, without an expiry, with an expiry beyond Projects:Delegation:MaxDelegationDays or with a role outside MembershipRole, among them PlatformAdmin; it then writes the delegation through the client of AIFACTORY-TASK-1843 with the workload token of ProjectService and the caller named as actor and grantor and answers 201 with the delegationId, idempotent on the Idempotency-Key with 409 for another input, 403 when the Identity service refuses the grantor and 404 for a grantee outside the tenant; RevokeDelegation checks the project of the path in the trusted tenant, lets the Identity service resolve the delegation without requiring a projection row, writes the revocation with the caller named as actor and answers 204, also when the Identity service answers already revoked, and passes on its 403 and its 404; neither command writes a Delegations row, and an unavailable Identity service is answered 503. | ConnectSoft.AI.SoftwareFactory.ProjectService |
AIFACTORY-TASK-1818 Delegation projection handlers publishing DelegationChanged after the projection changed |
implementation | The inbox handlers of the delegation granted, revoked and expired events of the Identity service write the Delegations row with grantor, grantee, role, expiresAt and reason, set revokedAt on a revocation, and write the DelegationChanged outbox record with the change in the same transaction, idempotently on the event id; connectsoft.factory.projects.delegations_active follows the unexpired, unrevoked rows per tenant. | ConnectSoft.AI.SoftwareFactory.ProjectService |
AIFACTORY-TASK-1819 DelegationExpiryReconciler announcing an expiry once |
implementation | The worker runs on the schedule of the model every ten minutes over Delegations rows past expiresAt with an empty revokedAt, partitioned by tenant with two partitions in parallel and three attempts at a fixed backoff of 60 seconds, writes DelegationChanged for the expiry under the idempotency key delegationId plus expiresAt, shares that key with the handler of the expiry event of the Identity service so one expiry is announced once, and writes nothing to the Identity service. | ConnectSoft.AI.SoftwareFactory.ProjectService |
AIFACTORY-TASK-1820 Verify delegate-a-project-role through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-ProjectService-005\|Scenario=SCN-ProjectService-006\|Scenario=SCN-ProjectService-013)"; a filter that matches no test counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-447 against the Identity fixture of AIFACTORY-TASK-1805 with a controlled clock, including the four 400 refusals with PlatformAdmin as the role among them, a grantee who is not a member of the tenant answered 404, a refused pair of the role order, a revocation sent before the grant event reached the projection, the revocation by each admitted actor, the expiry announced once by the reconciler and by the event in either order, and the publication and payload of DelegationChanged; consumer handling is proven by the suites of the consumers. |
ConnectSoft.AI.SoftwareFactory.ProjectService |
AIFACTORY-US-448: Replace the repositories, document collections and tools a run of the project may touch and announce the change¶
behavior · persona workspace-admin
As a workspace admin, I want to state which repositories, document collections and tools the runs of my project may touch, so that no run reads or changes a source the project did not admit.
A Workspace admin whose scope carries factory.projects.admin replaces the source scope of a project through ProjectService/SetSourceScope, a PUT whose body is the complete list of entries. An entry has a kind (repository, documents or tool), a reference of at most 512 characters and, when credentials are needed, the connectionId of a connection of the integration context, which ProjectService stores as an opaque reference and does not resolve. The stated list replaces the SourceScopes rows of the project in one transaction: rows that are no longer stated are deleted, new ones are inserted, and the SourceScopeChanged outbox record with projectId, tenantId and the resulting entries is written in the same transaction (ADR-0014 decision 4). The event carries entries as a list of strings, so each entry is rendered in one documented form: its kind and its reference joined by a colon, the kind first; a kind never holds a colon, so the first colon separates the two. The connectionId is not published. The command is naturally idempotent: a PUT that states the set already stored changes no row and publishes nothing. The answer is 200 with the stored scope. From then on Projects.ResolveScope returns the new set (AIFACTORY-US-445); RunControlService uses it for runs accepted from now on while the snapshot a running run pinned is unchanged, and KnowledgeIngestionService registers or disables sources, each in its own PBI. The command also leaves evidence. SourceScopeChanged names no actor and AuditService does not consume it, so the Factory sink of the audit library, consumed by a version pin from feature component-audit-factory-evidence, writes an audit-evidence-v1 record that names the actor, the project, the replaced set and the new set to the outbox in the transaction of the command, on the topic audit.evidence.v1.evidence-submitted in the run event envelope; a command that rolls back leaves no evidence (D115). Who may call is decided from the token: the route needs the scope, and the role claims of the token must name the caller Workspace admin of the project or Platform admin. This command writes no role, so it does not ask the Identity service as the membership commands do. A caller without the scope, or a member of the tenant who by those claims is neither, is refused with 403; a project of another tenant is answered 404 like one that does not exist (ADR-0015 amendment of D113); an entry with an unknown kind, an empty reference, a reference longer than 512 characters or a duplicate of kind and reference is refused with 400, and in every refusal no row changes and nothing is published. The model lists the codes 200, 400, 403 and 404 for this route (D117).
Acceptance criteria
| AC1 | Given a Workspace admin whose scope carries factory.projects.admin and a project with two source scope entries, when ProjectService/SetSourceScope states three entries of which one is already stored, then the response is 200 with the three entries, the rows of the project are replaced in one transaction, and the ProjectService/SourceScopeChanged outbox record with the resulting entries is written in the same transaction (SCN-ProjectService-007, ADR-0014). |
| AC2 | Given the stored set of AC1, when ProjectService/SetSourceScope states the same three entries again, then the response is 200, no row changes and no outbox record is written (SCN-ProjectService-007). |
| AC3 | Given a caller without factory.projects.admin, a member of the tenant who by the role claims of the token is neither Workspace admin of the project nor Platform admin, a project of another tenant, or a body with an unknown kind, an empty reference or a duplicate entry, when ProjectService/SetSourceScope is called, then the answer is 403, 403, 404 or 400 respectively with a problem response, no SourceScopes row changes and nothing is published (SCN-ProjectService-007, ADR-0015). |
| AC4 | Given the source scope changed, when the outbox dispatcher of the project messaging profile publishes ProjectService/SourceScopeChanged on projects.scope.v1.source-scope-changed, then the event is sent in run-event-envelope-v1 with projectId, tenantId and entries, each entry rendered as its kind and its reference joined by a colon and without its connection id, and a transport outage is retried with backoff so the event is neither lost nor duplicated under its event id (SCN-ProjectService-014, ADR-0012). |
| AC5 | Given the command of AC1 commits, when its outbox is read, then it holds one audit-evidence-v1 record in run-event-envelope-v1 for the topic audit.evidence.v1.evidence-submitted that names the actor, the project, the replaced set and the new set, and a command that rolls back leaves neither rows nor evidence (ADR-0014). |
| Traces: services | ProjectService |
| Traces: aggregates | ProjectService/Project |
| Traces: apis | ProjectService/SetSourceScope |
| Traces: events | ProjectService/SourceScopeChanged |
| Traces: descriptors | run-event-envelope-v1, audit-evidence-v1 |
| Traces: adrs | ADR-0012, ADR-0014, ADR-0015 |
| Traces: requirements | FR-01, XL-01 |
| Traces: scenarios | SCN-ProjectService-007, SCN-ProjectService-014 |
| Relates: screens | project-settings |
| Relates: nfrs | NFR-01 |
| Depends on | AIFACTORY-US-441, AIFACTORY-US-442, feature:component-audit-factory-evidence |
| Sources | model/services/control-plane/ProjectService.yaml, model/scenarios/ProjectService.yaml, model/services/governance/AuditService.yaml, docs/reference/schemas/audit-evidence.schema.json, docs/planes/control/services/project-service/index.md#apis |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-1821 SetSourceScope replacing the entries of a project with SourceScopeChanged in one transaction |
implementation | SetSourceScope validates every entry (kind repository, documents or tool, a reference of at most 512 characters, no duplicate of kind and reference) and answers 400 for a body that fails, replaces the SourceScopes rows of the project and writes the SourceScopeChanged outbox record in one transaction, with each entry rendered as its kind and its reference joined by a colon and the connection id left out, changes nothing and publishes nothing when the stated set is the stored one, answers 200 with the stored scope, 403 for a missing scope or a caller who by the role claims of the token is neither Workspace admin of the project nor Platform admin, and 404 for a foreign or unknown project; the contract document of the event states the string form of an entry. | ConnectSoft.AI.SoftwareFactory.ProjectService |
AIFACTORY-TASK-1822 Evidence of a source scope change through the Factory sink of the audit library |
implementation | The repository pins the audit library at the version feature component-audit-factory-evidence published and opens an audit scope in SetSourceScope, so that one audit-evidence-v1 record with the actor, the project, the replaced set and the new set is written to the outbox in the transaction of the command on the topic audit.evidence.v1.evidence-submitted in the run event envelope; the topic and the event type name are constants of the pinned contracts package. | ConnectSoft.AI.SoftwareFactory.ProjectService |
AIFACTORY-TASK-1823 Verify set-project-source-scope through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-ProjectService-007\|Scenario=SCN-ProjectService-014)"; a filter that matches no test counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-448, including the replaced rows, the unchanged repeat, the 400, 403 and 404 refusals, the evidence record in the outbox and the publication and payload of SourceScopeChanged with the string form of its entries; consumer handling is proven by the suites of the consumers. |
ConnectSoft.AI.SoftwareFactory.ProjectService |
AIFACTORY-US-449: Close a project through a journaled off-boarding that waits for the confirmations of its runs and of its data, and announce every state change of the project¶
behavior · persona workspace-admin
As a workspace admin, I want to close a project and see when its off-boarding has really finished, so that its runs stop, delegated access ends and its data is exported or deleted as my tenant decided.
A Workspace admin whose scope carries factory.projects.admin starts the off-boarding of a project through ProjectService/CloseProject, an operation of the production side-effect class. The project moves from Active or from Suspended to Closing (trigger Close); the member who closed it and the time of the close are recorded with the project in closedBy and closeRequestedAt, and the ProjectStateChanged outbox record with fromState, toState and the closing member in changedBy is written in the same transaction. The answer is 202: Closing is a real state because off-boarding is a procedure with external effects (XL-13). A project that is already Closing or Closed is refused with 409; a caller without the scope, or one who by the role claims of the token is neither Workspace admin of the project nor Platform admin, with 403; and a project of another tenant is answered 404 like one that does not exist (ADR-0015 amendment of D113). The ProjectOffboardingWorker is triggered by the ProjectStateChanged that announces Closing and by the two confirmations named below, one project at a time per tenant, and runs a journaled procedure. The journal is the table OffboardingJournal of the model, with one row per project and step that holds when the step completed or, for a step that failed, when and why; the table and the two columns of the closing actor are added by the migration task of this PBI. A restart resumes at the first step the journal does not hold as completed and repeats none. The worker is idempotent on projectId plus Closing and retries ten times with exponential backoff from 60 seconds. The owner decided that a project stays Closing until two other services have confirmed their part (D117), so the procedure has five journaled steps. First, the Closing announcement is confirmed as published. It is the signal on which RunControlService refuses new runs with 409 and cancels the open runs of the project, IntegrationService revokes the project grants, and ArtifactService and KnowledgeIngestionService export or delete the artifacts and sources of the project per tenant policy, each in its own PBI. Second, every delegation of the project that is neither revoked nor expired is revoked through the Identity service, written with the workload token of ProjectService and naming the recorded closing member as actor; the projection follows from the revocation events (AIFACTORY-US-447). When the Identity service refuses that actor, for example because the member lost the role after closing the project, the step fails, the journal names the step and the refusal, and the project stays Closing. Third, the confirmation of RunControlService: when RunControlService/ProjectRunsSettled arrives, the inbox handler RecordRunsSettled writes to the journal that no non-terminal run of the project remains. Fourth, the confirmation of ArtifactService: when ArtifactService/ProjectDataOffboarded arrives with the outcome exported or deleted, the inbox handler RecordDataOffboarded writes to the journal that the data of the project was exported or deleted. The two confirmations arrive in any order and may arrive before the revocations have finished; each handler is idempotent on the event id, writes its journal row once and ignores a confirmation for a project that is not Closing. Fifth, when the journal holds the four earlier steps as completed, the project moves from Closing to Closed (trigger OffboardingCompleted) with its ProjectStateChanged outbox record in the same transaction, and connectsoft.factory.projects.active falls by one. Until both confirmations are journaled the project stays Closing, however long that takes; the worker neither assumes a confirmation nor calls RunControlService or ArtifactService for it, because the model gives it these two events and no call. A project that stays Closing is the failure mode Off-boarding interrupted of the model: the worker resumes from the journal, and exhausted retries leave the project Closing with the failed step named in the journal, never Closed. The aggregate has two more transitions, Active to Suspended (trigger Suspend) and Suspended to Active (trigger Resume); the commands SuspendProject and ResumeProject that raise them are delivered by AIFACTORY-US-550, and each writes ProjectStateChanged in its transaction like the transitions of this PBI. ProjectStateChanged is published on projects.projects.v1.project-state-changed in the run event envelope with projectId, tenantId, fromState and toState, with changedBy when a member caused the transition and with the reason stated for a suspension or a resumption; RunControlService, IntegrationService, ArtifactService, KnowledgeIngestionService, StudioBff and AuditService consume it in their own PBIs.
Acceptance criteria
| AC1 | Given a Workspace admin whose scope carries factory.projects.admin and a project that is Active or Suspended, when ProjectService/CloseProject is called, then the response is 202, the ProjectService/Project is Closing, the closing member and the time of the close are recorded with it, and the ProjectService/ProjectStateChanged outbox record with fromState and toState is written in the same transaction (SCN-ProjectService-008). |
| AC2 | Given a caller without factory.projects.admin or who by the role claims of the token is neither Workspace admin of the project nor Platform admin, a project of another tenant, or a project that is already Closing or Closed, when ProjectService/CloseProject is called, then the answer is 403, 404 or 409 respectively, the 404 being the same answer as for a project that does not exist, with a problem response and no state change (SCN-ProjectService-008, ADR-0015). |
| AC3 | Given a Closing project with two delegations that are neither revoked nor expired, when the ProjectOffboardingWorker runs and neither confirmation has arrived, then the off-boarding journal holds a completed row for the confirmed Closing announcement and one for the revocations, the Identity service received one revocation per delegation written with the workload token of ProjectService and naming the recorded closing member as actor, and the ProjectService/Project is still Closing; when RunControlService/ProjectRunsSettled and ArtifactService/ProjectDataOffboarded then arrive, in either order, then the handlers RecordRunsSettled and RecordDataOffboarded each write their journal row once, and only after both the project moves to Closed with a second ProjectService/ProjectStateChanged in the same transaction as the last journal row; a duplicate trigger or a redelivered confirmation has no second effect (SCN-ProjectService-008, SCN-ProjectService-011, XL-13). |
| AC4 | Given the worker stops after its first journaled step, the Identity service is unavailable during the second, the Identity service refuses the recorded closing actor, or only one of the two confirmations has arrived, when the worker runs again, then it resumes at the first step the journal does not hold as completed and repeats none, the journal names a failed step with its reason, a project without both confirmations stays Closing, and after its retries are exhausted the project is still Closing and never Closed, as the failure mode of docs/planes/control/services/project-service/index.md states (SCN-ProjectService-008, SCN-ProjectService-011). |
| AC5 | Given any of the five transitions of the ProjectService/Project (Active to Suspended, Suspended to Active, Active to Closing, Suspended to Closing, Closing to Closed), when the outbox dispatcher publishes ProjectService/ProjectStateChanged on projects.projects.v1.project-state-changed, then the outbox record was written in the transaction of the transition, the event is sent in run-event-envelope-v1 with projectId, tenantId, fromState and toState, with changedBy when a member caused the transition and with the reason of a suspension or a resumption, and a transport outage is retried with backoff so the event is neither lost nor duplicated under its event id (SCN-ProjectService-011, ADR-0012). |
| Traces: services | ProjectService, RunControlService, ArtifactService |
| Traces: aggregates | ProjectService/Project |
| Traces: apis | ProjectService/CloseProject |
| Traces: events | ProjectService/ProjectStateChanged, RunControlService/ProjectRunsSettled, ArtifactService/ProjectDataOffboarded |
| Traces: descriptors | run-event-envelope-v1 |
| Traces: adrs | ADR-0012, ADR-0014, ADR-0015, ADR-0019 |
| Traces: requirements | FR-01, XL-13, NFR-03 |
| Traces: scenarios | SCN-ProjectService-008, SCN-ProjectService-011 |
| Relates: nfrs | NFR-03 |
| Depends on | AIFACTORY-US-441, AIFACTORY-US-442, AIFACTORY-US-447, feature:component-identity-template-factory-roles, feature:run-control-service, feature:artifact-service |
| Sources | model/services/control-plane/ProjectService.yaml, model/scenarios/ProjectService.yaml, model/services/control-plane/RunControlService.yaml, model/services/knowledge/ArtifactService.yaml, docs/planes/control/services/project-service/index.md#sagas-and-long-running-flows, docs/planes/control/services/project-service/index.md#failure-and-recovery, docs/architecture/data-governance.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-1845 Migration of the off-boarding journal and of the closing actor of a project |
migration | A migration of project-sql adds the table OffboardingJournal of the model, tenant-filtered and keyed by project and step with the time the step completed and, for a failed step, the time and the reason of the failure, and adds to Projects the nullable columns ClosedBy and CloseRequestedAt of the model for the member who closed the project and the time of the close; mapping tests on an isolated test database prove both. | ConnectSoft.AI.SoftwareFactory.ProjectService |
AIFACTORY-TASK-1824 CloseProject and the ProjectStateChanged record of every transition of the project |
implementation | CloseProject applies the trigger Close to an Active or a Suspended project, records the closing member and the time of the close in closedBy and closeRequestedAt and writes the ProjectStateChanged outbox record with fromState, toState and the closing member in changedBy in the same transaction, answers 202, 409 for a project that is Closing or Closed, 403 for a missing scope or a caller who by the role claims of the token is neither Workspace admin of the project nor Platform admin, and 404 for a foreign or unknown project; every transition of the project writes ProjectStateChanged in its transaction, the commands that raise Suspend and Resume being delivered by AIFACTORY-TASK-2208 of AIFACTORY-US-550; connectsoft.factory.projects.active follows the projects that are not Closed. | ConnectSoft.AI.SoftwareFactory.ProjectService |
AIFACTORY-TASK-021 ProjectOffboardingWorker as a journaled procedure from Closing to Closed that waits for the two confirmations |
implementation | The worker is triggered by the ProjectStateChanged that announces Closing and by ProjectRunsSettled and ProjectDataOffboarded, runs one project at a time per tenant, is idempotent on projectId plus Closing and retries ten times with exponential backoff from 60 seconds; it writes one row of the off-boarding journal of AIFACTORY-TASK-1845 per completed step of its own (the confirmed Closing announcement, the revocation of every unexpired delegation through the Identity service with the recorded closing member named as actor), reads the rows of the two confirmations that AIFACTORY-TASK-2205 writes, and applies OffboardingCompleted with its ProjectStateChanged record and the last journal row in one transaction only when the journal holds the announcement, the revocations, the confirmation of RunControlService and the confirmation of ArtifactService as completed; it resumes at the first step the journal does not hold as completed, writes the failed step with its reason when the Identity service is unavailable or refuses the recorded actor, leaves the project Closing while a confirmation is missing and when its retries are exhausted, and calls neither RunControlService nor ArtifactService; a duplicate trigger has no second effect. | ConnectSoft.AI.SoftwareFactory.ProjectService |
AIFACTORY-TASK-2205 RecordRunsSettled and RecordDataOffboarded inbox handlers writing the two confirmations to the off-boarding journal |
implementation | The handler of ProjectRunsSettled writes the journal row of the confirmation of RunControlService and the handler of ProjectDataOffboarded writes the journal row of the confirmation of ArtifactService with the outcome exported or deleted, each for the Closing project the event names in the tenant of the event, once and idempotently on the event id; a confirmation for a project that is not Closing, or that is unknown in that tenant, writes nothing and is acknowledged; each written row triggers the ProjectOffboardingWorker. | ConnectSoft.AI.SoftwareFactory.ProjectService |
AIFACTORY-TASK-2206 Acceptance fixture publishing ProjectRunsSettled and ProjectDataOffboarded for a closing project |
fixture | The acceptance suite publishes ProjectRunsSettled and ProjectDataOffboarded for a stated project and tenant through fixture publishers, in a stated order and with a stated outcome, and can withhold either, so that the waiting in Closing, both orders of arrival, a redelivery and a confirmation for a project that is not Closing are reproducible without RunControlService and ArtifactService. | ConnectSoft.AI.SoftwareFactory.ProjectService |
AIFACTORY-TASK-1825 Verify close-a-project through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-ProjectService-008\|Scenario=SCN-ProjectService-011)"; a filter that matches no test counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-449 against the Identity fixture of AIFACTORY-TASK-1805 and the fixture publishers of AIFACTORY-TASK-2206, including the recorded closing member, the 403, 404 and 409 refusals, the journal rows after a complete and after an interrupted run, the failed step named when the fixture refuses the recorded actor, the revocations the fixture received, the project that stays Closing with no confirmation and with one confirmation, the two confirmations in either order, a redelivered confirmation, and the publication and payload of ProjectStateChanged for each of the five transitions; consumer handling is proven by the suites of the consumers. |
ConnectSoft.AI.SoftwareFactory.ProjectService |
AIFACTORY-US-550: Suspend an active project and resume a suspended one with a stated reason, and announce both with the actor and the reason¶
behavior · persona workspace-admin
As a workspace admin, I want to suspend my project with a reason and to resume it later, so that no run starts or goes on in a project I had to stop, and everyone can see who stopped it and why.
The owner decided that a project is suspended and resumed by command (D117), so the transitions Active to Suspended (trigger Suspend) and Suspended to Active (trigger Resume) of the Project, which the domain model of AIFACTORY-US-441 already enforces, are raised by two routes. A caller whose scope carries factory.projects.admin suspends a project through ProjectService/SuspendProject, a POST on the project of the path with a body that states a reason, and resumes it through ProjectService/ResumeProject, a POST with a reason as well. Both are operations of the production side-effect class with natural idempotency. Who may call is decided as for CloseProject: the route needs the scope, and the role claims of the token must name the caller Workspace admin of the project or Platform admin. The reason is required: a body without a reason, or with a blank one, is refused with 400. SuspendProject applies to an Active project only and ResumeProject to a Suspended one only; a project in any other state is refused with 409, which is also the answer to a repeated suspension of a project that is already Suspended and to a repeated resumption of one that is Active again. A caller without the scope, or one who by the role claims of the token is neither Workspace admin of the project nor Platform admin, is refused with 403, and a project of another tenant is answered 404 like one that does not exist (ADR-0015 amendment of D113). On success the project changes state and the ProjectStateChanged outbox record with projectId, tenantId, fromState, toState, the caller in changedBy and the stated reason is written in the same transaction, and the answer is 200 with the project. That event is also how the command is audited: it names the actor and the reason, and AuditService, which consumes ProjectStateChanged, records it as evidence in its own PBI; a command that is refused or rolls back writes no event. The event is published on projects.projects.v1.project-state-changed in the run event envelope. Its effect on runs belongs to RunControlService: on the announcement of Suspended its handler GateRunsByProject keeps the state in the table GateStates, from which SubmitRun refuses new runs of the project with 409 and a problem body that names the gate, and records a cancellation intent for every open run of the project; on the announcement of Active after a resumption new runs are accepted again, and the runs that were cancelled stay Cancelled, since a resumption restarts nothing. With these two routes the suspended-project gate of RunControlService is reachable on a deployed instance. A Suspended project is not being off-boarded: its delegations stay, nothing is exported or deleted, and it can be closed from Suspended through CloseProject (AIFACTORY-US-449). The model restricts no other route for a Suspended project, so memberships, delegations, the source scope and the reads answer as before, and Projects.ResolveScope answers for a project in any state (AIFACTORY-US-445). StudioBff, IntegrationService, ArtifactService and KnowledgeIngestionService also consume the event, to refresh a view or to act on Closing only, each in its own PBI.
Acceptance criteria
| AC1 | Given a Workspace admin of an Active project whose scope carries factory.projects.admin, or a Platform admin, when ProjectService/SuspendProject is called with a reason, then the response is 200, the ProjectService/Project is Suspended, and the ProjectService/ProjectStateChanged outbox record with fromState Active, toState Suspended, the caller in changedBy and the stated reason is written in the same transaction (SCN-ProjectService-015). |
| AC2 | Given the Suspended project, when ProjectService/ResumeProject is called with a reason by a Workspace admin of the project or a Platform admin, then the response is 200, the project is Active again, and the ProjectService/ProjectStateChanged outbox record with fromState Suspended, toState Active, the caller in changedBy and the stated reason is written in the same transaction (SCN-ProjectService-016). |
| AC3 | Given a body without a reason or with a blank one, a caller without factory.projects.admin or who by the role claims of the token is neither Workspace admin of the project nor Platform admin, a project of another tenant, or a project that is not Active for ProjectService/SuspendProject or not Suspended for ProjectService/ResumeProject, when the route is called, then the answer is 400, 403, 404 or 409 respectively, the 404 being the same answer as for a project that does not exist, with a problem response, no state change and no event (SCN-ProjectService-015, SCN-ProjectService-016, ADR-0015). |
| AC4 | Given a project was suspended or resumed, when the outbox dispatcher of the project messaging profile publishes ProjectService/ProjectStateChanged on projects.projects.v1.project-state-changed, then the event is sent in run-event-envelope-v1 with projectId, tenantId, fromState, toState, changedBy and reason, and a transport outage is retried with backoff so the event is neither lost nor duplicated under its event id (SCN-ProjectService-015, SCN-ProjectService-016, ADR-0012). |
| Traces: services | ProjectService |
| Traces: aggregates | ProjectService/Project |
| Traces: apis | ProjectService/SuspendProject, ProjectService/ResumeProject |
| Traces: events | ProjectService/ProjectStateChanged |
| Traces: descriptors | run-event-envelope-v1 |
| Traces: adrs | ADR-0012, ADR-0014, ADR-0015 |
| Traces: requirements | FR-01, NFR-01 |
| Traces: scenarios | SCN-ProjectService-015, SCN-ProjectService-016 |
| Relates: screens | project-settings |
| Relates: nfrs | NFR-01 |
| Depends on | AIFACTORY-US-441, AIFACTORY-US-442, AIFACTORY-US-449 |
| Sources | model/services/control-plane/ProjectService.yaml, model/scenarios/ProjectService.yaml, docs/planes/control/services/project-service/index.md#apis |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-2207 Contract of SuspendProject and ResumeProject and of the actor and the reason in ProjectStateChanged |
contract | The OpenAPI document of the service holds SuspendProject and ResumeProject, each a POST on the project of the path with a body that requires a reason, the answer 200 with the project and the answers 400, 403, 404 and 409 as problem responses, as model/services/control-plane/ProjectService.yaml lists them; the contract of ProjectStateChanged holds the optional fields changedBy and reason beside projectId, tenantId, fromState and toState. | ConnectSoft.AI.SoftwareFactory.ProjectService |
AIFACTORY-TASK-2208 SuspendProject and ResumeProject with a required reason and ProjectStateChanged in the transaction of the transition |
implementation | SuspendProject applies the trigger Suspend to an Active project and ResumeProject the trigger Resume to a Suspended one, each writing the ProjectStateChanged outbox record with fromState, toState, the caller in changedBy and the stated reason in the same transaction and answering 200 with the project; both answer 400 for a missing or blank reason, 403 for a missing scope or a caller who by the role claims of the token is neither Workspace admin of the project nor Platform admin, 404 for a foreign or unknown project and 409 for a project in any other state, a repeated call included, and a refused command writes no event. | ConnectSoft.AI.SoftwareFactory.ProjectService |
AIFACTORY-TASK-2209 Verify suspend-and-resume-a-project through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-ProjectService-015\|Scenario=SCN-ProjectService-016)"; a filter that matches no test counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-550 with projects of two tenants, including the suspension and the resumption by a Workspace admin and by a Platform admin, the 400 for a missing and for a blank reason, the 403, the 404 for a foreign project, the 409 for a repeated suspension, for a resumption of an Active project and for a Closing project, and the publication and payload of ProjectStateChanged with changedBy and reason; the refusal of new runs and the cancellation of open ones are proven by the suite of RunControlService. |
ConnectSoft.AI.SoftwareFactory.ProjectService |