AIFACTORY-FEAT-083: GenerationRecipeService: 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 Template & Library (PF-15) · Increment I1 Generate a microservice · State elaborated · Route backend-developer · Build order 81 of 185 (Factory code)
GenerationRecipeService is the service of bounded context BC-15 (Generation Recipe). A generation recipe binds a Published blueprint version to Published template and library versions with a module plan and parameters, validated against manifests, switches and the compatibility matrix, and records the provenance of every generated output down to the commit; the scaffold commitment stays Q-22 (BC-15; template validation and pipeline generation rows merged). Its own repository is ConnectSoft.AI.SoftwareFactory.GenerationRecipeService.
| Delivers | GenerationRecipeService (complete) |
| Stubs | — |
| Realizes | adrs: ADR-0021 |
| Requirements | FR-03, FR-06, FR-07, FUX-01, FUX-03, NFR-11, NFR-13, XL-03, XL-07, XL-10 |
| Depends on | — |
| Sources | model/services/template-library/GenerationRecipeService.yaml |
Scenarios to trace (12, catalog): SCN-GenerationRecipeService-001 ✓, SCN-GenerationRecipeService-002 ✓, SCN-GenerationRecipeService-003 ✓, SCN-GenerationRecipeService-004 ✓, SCN-GenerationRecipeService-005 ✓, SCN-GenerationRecipeService-006 ✓, SCN-GenerationRecipeService-007 ✓, SCN-GenerationRecipeService-008 ✓, SCN-GenerationRecipeService-009 ✓, SCN-GenerationRecipeService-010 ✓, SCN-GenerationRecipeService-011 ✓, SCN-GenerationRecipeService-012 ✓
AIFACTORY-US-013: Approve a recipe that pins every design input¶
behavior · persona asset-maintainer
As an asset maintainer, I want to review and approve a generation recipe whose modules pin exact blueprint and design versions, so that generation runs on inputs I have seen and nothing newer replaces them silently.
This is the integration PBI of the feature: it proves that the behaviour PBIs of GenerationRecipeService compose into the one chain a person and a generation run need, on one deployed instance of the service. The service hears which inputs may be pinned: blueprint versions that are Submitted or Published, validated design inputs, template versions of the platform catalog that are discovered or Published, library versions and compatibility evidence (AIFACTORY-US-682). Until the evaluation gate of AgentRegistryService is delivered in I4 the Draft allowance applies (D123): a recipe may bind a Submitted blueprint version and a template version the platform catalog has discovered that is not yet Published, and it records in draftAllowanceUsed that the allowance was used; from I4 a recipe binds only Published versions. When BlueprintService announces a context map, the PlanProposer proposes a module plan, and a Requester or an Asset maintainer drafts a recipe from a blueprint version a recipe may bind with that plan, adjusted where needed (AIFACTORY-US-683). The recipe is read with its module plan, its pins and its evidence (AIFACTORY-US-684) and validated: every module names a template version a recipe may bind whose switches accept its parameters, every library is Published and compatible with every template that consumes it, and every design input a module kind needs is pinned by id, version and hash and resolves to a validated version (AIFACTORY-US-685, ADR-0027). The Asset maintainer approves the Validated recipe; from then on it is immutable, RecipeApproved is published, and a change is a new version that supersedes it (AIFACTORY-US-686). The readiness correlation of WorkflowEngineService submits the generate-product run on that event; the run reads the approved recipe through Recipes.GetApprovedRecipe and its provenance is recorded through Recipes.RecordOutput (AIFACTORY-US-687), and the end of the run completes the generation or, when the run fails or is cancelled, returns the recipe to Approved (AIFACTORY-US-688). The service is scaffolded from the base template with the Factory profile (AIFACTORY-US-679), hosts its routes, its messaging profile and its two workers (AIFACTORY-US-680) and enforces tenancy and the telemetry conventions (AIFACTORY-US-681). It never writes code, decides no approval of RunControlService and repeats no write on its own: the approval of a recipe is its own command under the scope factory.recipes.approve, and the approval of the generated change set is a separate approval in RunControlService, which the requester of the run never decides. A person reaches the REST operations through the gateway TemplateCatalogHost, which feature template-catalog-host delivers in this increment (D123): the command-line client shows a recipe and approves it by recipe id and version through that gateway with its typed client, which feature typed-gateway-clients publishes, by the commands recipe show and recipe approve of AIFACTORY-US-1507 of feature command-line-client-commands. The gateway feature and the command feature depend on this feature, so this feature states the route in words and depends on neither. A blueprint or template version becomes Published only through the publication path of AgentRegistryService, which arrives in I2 with feature agent-registry-service-publication (D140); until the evaluation gate of I4 the chain runs on a deployed instance under the Draft allowance, on a Submitted blueprint version that BlueprintService announces and on discovered template versions that TemplateRegistryService announces, and a library whose compatibility cell is still Unknown passes validation with a warning under the same allowance (D125). The provenance of the generated outputs is recorded in this increment: the tool record-generated-output, bound to the skill of the step record-outputs of generate-product, is executed by ToolAdapterService, which calls Recipes.RecordOutput with its workload identity, so the recipe reaches Generated and GenerationCompleted is published in I1 (D133). Repository: ConnectSoft.AI.SoftwareFactory.GenerationRecipeService.
Acceptance criteria
| AC1 | Given a blueprint version a recipe may bind, Submitted under the Draft allowance until I4 or Published, whose context map names two bounded contexts, when the PlanProposer has run and GenerationRecipeService/DraftRecipe is called, then the Draft GenerationRecipeService/GenerationRecipe has one module entry per context with a template version a recipe may bind, discovered or Published, its switches and its parameters, draftAllowanceUsed is true exactly when a Submitted blueprint version or a discovered template version is bound, and GenerationRecipeService/GetRecipe shows the plan with every pin (ADR-0027, model/services/template-library/GenerationRecipeService.yaml). |
| AC2 | Given that recipe with every module entry pinning the design inputs of its kind, when GenerationRecipeService/ValidateRecipe is called, then every pinned design input resolves to a validated version by id, version and hash, every library is compatible with every template that consumes it with evidence, the manifests are read through TemplateRegistryService/Catalog.ResolveManifest, the recipe is Validated and GenerationRecipeService/RecipeValidated is written with passed true in the same transaction (ADR-0027). |
| AC3 | Given a recipe with a pin that does not resolve, when it is validated and GenerationRecipeService/ApproveRecipe is then called, then the validation result names the unresolved pin, the recipe stays Draft, the approval is refused with 409 and nothing is published (ADR-0027). |
| AC4 | Given a Validated recipe, when the Asset maintainer approves it through GenerationRecipeService/ApproveRecipe, reached through the gateway TemplateCatalogHost directly or by the client command recipe approve of model/backlog/pbis/engineering-readiness/command-line-client-commands.yaml with the typed client of that gateway, then the recipe is Approved and immutable, approvedBy names the approver and GenerationRecipeService/RecipeApproved is written in the same transaction with recipeId, version and approvedBy; a change after that is a new version (FR-06). |
| AC5 | Given the approved recipe and a generation run, when the run reads the recipe, one output is recorded per module through GenerationRecipeService/Recipes.RecordOutput by ToolAdapterService for the tool record-generated-output and the run completes, then the read returned the recipe with every pin resolved, the outputs are listed with their provenance, the recipe is Generated and GenerationRecipeService/GenerationCompleted is written, the flow that docs/solution-packs/software-factory/templates/services/generation-recipe-service/index.md draws (D133). |
| Traces: services | GenerationRecipeService, TemplateRegistryService, BlueprintService, ArtifactService |
| Traces: aggregates | GenerationRecipeService/GenerationRecipe |
| Traces: apis | GenerationRecipeService/DraftRecipe, GenerationRecipeService/ValidateRecipe, GenerationRecipeService/ApproveRecipe, GenerationRecipeService/GetRecipe, GenerationRecipeService/Recipes.RecordOutput, TemplateRegistryService/Catalog.ResolveManifest |
| Traces: events | GenerationRecipeService/RecipeValidated, GenerationRecipeService/RecipeApproved, GenerationRecipeService/GenerationCompleted |
| Traces: tools | record-generated-output |
| Traces: adrs | ADR-0027 |
| Traces: requirements | FR-06 |
| Depends on | AIFACTORY-US-679, AIFACTORY-US-680, AIFACTORY-US-681, AIFACTORY-US-682, AIFACTORY-US-683, AIFACTORY-US-684, AIFACTORY-US-685, AIFACTORY-US-686, AIFACTORY-US-687, AIFACTORY-US-688, feature:template-registry-service, feature:blueprint-service, feature:artifact-service, feature:run-control-service, feature:typed-gateway-clients, feature:local-development-environment |
| Sources | model/services/template-library/GenerationRecipeService.yaml, model/workflows/generate-product.yaml, model/tools/record-generated-output.yaml, docs/architecture/adr/0027-generation-input-contract.md, docs/solution-packs/software-factory/templates/services/generation-recipe-service/index.md#sagas-and-long-running-flows |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-2721 Deployment values of GenerationRecipeService: replica range, secret reference and dependency addresses |
operations | The deployment manifest of the service carries the replica range 2 to 4 of the model, the key vault reference of the transport credential messaging-transport, the addresses of BlueprintService, TemplateRegistryService and ArtifactService, the messaging service name generation-recipe and the values of the two options of Templates:Recipes; the acceptance environment of feature local-development-environment starts the service with these values and its readiness answers ready. | ConnectSoft.AI.SoftwareFactory.GenerationRecipeService |
AIFACTORY-TASK-787 Verify approve-a-recipe by running the chain test of the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&Chain=approve-a-recipe"; a zero-match filter counts as a failure; one test announces the inputs as the services of this increment publish them, a Submitted blueprint version by BlueprintSubmitted, its derived models, a discovered template version by TemplateVersionDiscovered, a library version, its compatibility and the validated design inputs, then proposes, drafts, validates with a broken and with a resolved pin, approves, reads the approved recipe, records one output per module and completes the run, against fakes of BlueprintService, TemplateRegistryService, ArtifactService and the transport, and finds draftAllowanceUsed true on the recipe; a second pass announces the same blueprint and template versions as Published by event fixtures and finds draftAllowanceUsed false; together the passes prove AC1 to AC5 of AIFACTORY-US-013. |
ConnectSoft.AI.SoftwareFactory.GenerationRecipeService |
AIFACTORY-US-679: GenerationRecipeService repository: scaffolded from the base template with the Factory profile, with its two aggregates and the store generation-recipe-sql¶
enabling
The repository ConnectSoft.AI.SoftwareFactory.GenerationRecipeService is created and scaffolded in I0 by AIFACTORY-TASK-125 of feature repository-and-pipeline-conventions (D140), by the steps of its repository checklist, 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.GenerationRecipeService --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 shared descriptors come from the contracts package by a version pin. On that scaffold this PBI adds the domain and the store. The GenerationRecipe is the complete instruction set for generating a product or a module, identified by recipe id and an integer version: the blueprint version it is built on, the module plan of ModulePlanEntry entities (name, one of the twelve values of ModuleKind, context, template id and version, switches, parameters, path and the pinned design inputs), the library versions pinned for all modules, the repository layout, the compatibility evidence it was validated against, its state, its approver, the member draftAllowanceUsed and the reference and hash of its recipe document, documentRef and documentHash (D123). It has exactly nine transitions: Draft to Validated (PlanValidated), Validated to Draft (Changed), Validated to Approved (Approved), Approved to Executing (RunSubmitted), Executing to Generated (RunCompleted), Executing to Approved (RunFailed), Executing to Approved (RunCancelled), and Approved or Generated to Superseded (NewVersion). Its invariants are those of the model: every module references a template version whose switches accept its parameters; the blueprint version and every template version a recipe binds are Published, and until the evaluation gate of AgentRegistryService is delivered in I4 the Draft allowance lets a recipe also bind a Submitted blueprint version and a template version the catalog has discovered that is not yet Published, with draftAllowanceUsed recording that the allowance was used; a recipe binds catalog rows of the platform tenant; every library is Published and Compatible with every template that consumes it, with evidence; every module entry pins the design inputs its kind needs by id, version and hash; a recipe is immutable once Approved; and the service never writes code. The GeneratedOutput is the provenance of one generated module at one commit: recipe version, run and attempt, agent release, template version and manifest hash, the generated files with their hashes, the preserved paths, the change proposal and the commit. Generated files are listed with hashes so that a later scaffold can tell generated from hand-edited content, and a preserved path is never listed as generated. The store generation-recipe-sql is owned by this service alone (ADR-0028 decision 5). The model lists nine tables on that store (D123). This PBI migrates the three tables of the two aggregates, GenerationRecipes, ModulePlanEntries and GeneratedOutputs, with the keys, columns and indexes of the model, the columns DraftAllowanceUsed, DocumentRef and DocumentHash of GenerationRecipes among them, and the tenant row filter in every mapping; the five projection tables are migrated by AIFACTORY-US-682 with the handlers that fill them, and the table PlanProposals by AIFACTORY-US-683 with the worker that fills it. The retention of GeneratedOutputs, the lifetime of the product plus seven years, is recorded with the table; no deletion job and no deletion-order handler is built or registered here, because those arrive with RetentionResidencyService in I4.
Acceptance criteria
| AC1 | Given the repository created and scaffolded in I0 by AIFACTORY-TASK-125 of feature repository-and-pipeline-conventions with dotnet new connectsoft-base -n ConnectSoft.AI.SoftwareFactory.GenerationRecipeService --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 GenerationRecipeService/GenerationRecipe and GenerationRecipeService/GeneratedOutput aggregates, when their unit tests run, then the recipe accepts exactly the nine transitions of model/services/template-library/GenerationRecipeService.yaml, the return from Executing to Approved through RunCancelled among them, and refuses every other one, an approval of a Draft and a transition out of Superseded among them; an Approved recipe refuses every change of its modules, libraries, layout and evidence; a module entry without a template version or without the design input pins of its kind keeps the recipe from PlanValidated; and a generated output that lists one path as both generated and preserved is refused (ADR-0027). |
| AC3 | Given generation-recipe-sql created by the migrations of the repository on an isolated test database, when the mapping tests run, then the tables GenerationRecipes, ModulePlanEntries and GeneratedOutputs exist with their keys and the indexes IX_Recipes_Project_State, IX_Outputs_Project_Module and IX_Outputs_Run, GenerationRecipes holds the columns DraftAllowanceUsed, not nullable with the default 0, DocumentRef and DocumentHash, a query made for one tenant never returns a recipe, a module entry or an output of another, and the retention of GeneratedOutputs is recorded with the table (ADR-0015, model/stores.yaml). |
| Traces: services | GenerationRecipeService |
| Traces: aggregates | GenerationRecipeService/GenerationRecipe, GenerationRecipeService/GeneratedOutput |
| Traces: adrs | ADR-0015, ADR-0027, ADR-0028 |
| Traces: requirements | FUX-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/template-library/GenerationRecipeService.yaml, model/template-parameters/connectsoft-base.yaml, model/stores.yaml, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md, docs/solution-packs/software-factory/templates/services/generation-recipe-service/index.md#domain-model, docs/solution-packs/software-factory/templates/services/generation-recipe-service/ddl.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-126 Domain model: GenerationRecipe with ModulePlanEntry, GeneratedOutput |
implementation | The two aggregates and the ModulePlanEntry entity enforce the invariants of the model as it words them; the GenerationRecipe accepts only PlanValidated out of Draft, Changed and Approved out of Validated, RunSubmitted and NewVersion out of Approved, RunCompleted, RunFailed and RunCancelled out of Executing and NewVersion out of Generated, and refuses every change once Approved; the recipe carries draftAllowanceUsed, documentRef and documentHash; the GeneratedOutput refuses a path listed as both generated and preserved; unit tests cover every invariant, each of the nine transitions and the refusal of every other one. | ConnectSoft.AI.SoftwareFactory.GenerationRecipeService |
AIFACTORY-TASK-127 Persistence in generation-recipe-sql: GenerationRecipes, ModulePlanEntries, GeneratedOutputs |
migration | Mappings and migrations for the three tables with the columns the model lists, the columns DraftAllowanceUsed, DocumentRef and DocumentHash of GenerationRecipes among them, the indexes IX_Recipes_Project_State, IX_Outputs_Project_Module and IX_Outputs_Run and the tenant filter in every mapping; the six other tables of the store are migrated by AIFACTORY-TASK-2727 and AIFACTORY-TASK-2746; the retention of GeneratedOutputs is recorded as table metadata; mapping tests run against an isolated test database, never a shared one. | ConnectSoft.AI.SoftwareFactory.GenerationRecipeService |
AIFACTORY-TASK-2722 Verify the scaffold, the aggregates and the store of GenerationRecipeService |
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 two aggregates 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-679 (ADR-0028). |
ConnectSoft.AI.SoftwareFactory.GenerationRecipeService |
AIFACTORY-US-680: GenerationRecipeService host: six REST routes and two gRPC methods behind scope policies, the generation-recipe messaging profile with fifteen subscriptions and the two hosted workers¶
enabling
This PBI makes the scaffold a host on which the behaviour PBIs of the feature land. From the service descriptor the host exposes the six REST operations of the model for its platform gateway and the internal gRPC service Recipes with the methods GetApprovedRecipe and RecordOutput, with their contract documents, an OpenAPI document and a proto. A user token reaches the service forwarded by TemplateCatalogHost: the service validates it again through the resource-server library the profile wires and accepts the audience of its own gateway and no other (ADR-0015 amendments on the one audience of a user token and on the forwarded user token). That gateway is delivered in this increment by feature template-catalog-host and is the one route of a person to these operations (ADR-0028 decision 2, D123); the acceptance suite of this repository calls the host of the service with a token of that audience and the forwarded scope, and the route through the gateway is proven by the gateway feature. Each route requires its scope: factory.recipes.read for ListRecipes, GetRecipe and ListGeneratedOutputs, factory.recipes.write for DraftRecipe and ValidateRecipe, factory.recipes.approve for ApproveRecipe. A gRPC caller needs a workload identity whose token holds a service scope; a workload token carries no tenant claim, and the service reads the tenant and project a workload forwards only under that scope. The model gives each gRPC method its scope (D123): the host requires factory.recipes.read for GetApprovedRecipe and factory.recipes.write for RecordOutput. The project of a project-scoped call is named by the caller (D123): ListRecipes takes the required query parameter projectId and DraftRecipe the required body member projectId; the gateway checks it against the roles of the token, and the service compares it with the project of the trusted scope it receives. One mapping answers every refusal: no token or a token of another audience 401, a call without the required projectId 400, a missing scope or role and a project the token does not grant 403, an unknown resource and a resource of another tenant 404, an idempotency key reused with another body and a state that does not allow the command 409, a blueprint version a recipe may not bind 412, an invalid body 422, a required dependency that fails fast and does not answer 503, each with a problem response; over gRPC Unauthenticated, PermissionDenied, NOT_FOUND, InvalidArgument, FailedPrecondition and Unavailable. The filter of the Idempotency-Key header guards DraftRecipe: the same key with the same input returns the stored result, and the same key with another input is a conflict by ADR-0014 decision 3, which the filter answers with 409. Messaging runs on the Orleans messaging profile with the service name of OrleansMessaging:ServiceName, default generation-recipe, whose inbox and outbox belong to this service alone (ADR-0028). The outbox writer enlists in the transaction of the command, and the dispatcher publishes the four modelled events on their topics under the run event envelope of the pinned contracts package. The inbox registers the fifteen consumed rows of the model, idempotently on the event id: from BlueprintService the submitted and the published blueprint, the validated blueprint with its two handlers, the derived context map and the derived domain model; from ArtifactService the stored artifact; from TemplateRegistryService the discovered and the published template version, the discovered library version and the checked compatibility; from RunControlService the completed, the failed and the cancelled run; from PipelineExecutionService the merged change proposal. The PlanProposer is hosted with its event trigger, two attempts 60 s apart, the key of blueprint id and blueprint version and at most two parallel executions; the RecipeValidator is hosted to be run by ValidateRecipe, with two attempts 30 s apart, the key of recipe id, version and content hash and at most four parallel executions; both are partitioned by project. What each route, handler and worker does is delivered by the behaviour PBIs. The three options of the model are bound and validated at start, and readiness names what is missing.
Acceptance criteria
| AC1 | Given the host built from the service descriptor, when the contract tests of the repository run, then the OpenAPI document lists the six REST operations of model/services/template-library/GenerationRecipeService.yaml with their paths, scopes and response codes, the required query parameter projectId of ListRecipes and the required body member projectId of DraftRecipe among them, and the proto lists the service Recipes with GetApprovedRecipe and RecordOutput, each with the scope the model gives it. |
| AC2 | Given each REST route and each gRPC method, when it is called without a token, with a user token whose audience is not the gateway of the service, with a user token that lacks the scope of the route, without a workload identity, or with a workload token that lacks the service scope of the method, then the answer is 401, 401, 403, Unauthenticated or PermissionDenied respectively, with a problem response on REST, and no handler runs; and a call of ListRecipes or DraftRecipe without projectId is answered 400 with a problem response (ADR-0015, model/services/template-library/GenerationRecipeService.yaml). |
| AC3 | Given the messaging profile generation-recipe, when a command commits, rolls back, or commits while the transport is down, then the committed event is published once on its topic under run-event-envelope-v1, the rolled back one never, and the one written during the outage after the outbox retried with backoff, neither lost nor duplicated under its event id; and each of the fifteen consumed rows delivered twice under one event id reaches its handler once (ADR-0012, ADR-0014). |
| AC4 | Given the hosted PlanProposer and RecipeValidator, when the trigger of the first is delivered twice for one blueprint id and blueprint version, or the second is run twice for one recipe id, version and content hash, then one execution has an effect; the first runs at most two executions in parallel and makes at most two attempts 60 s apart, the second at most four in parallel with at most two attempts 30 s apart, both partitioned by project; and the service is ready only after generation-recipe-sql is migrated and the messaging profile has started, and it names what is missing while it is unready (model/services/template-library/GenerationRecipeService.yaml). |
| Traces: services | GenerationRecipeService |
| Traces: descriptors | run-event-envelope-v1 |
| Traces: adrs | ADR-0012, ADR-0014, ADR-0015, ADR-0028 |
| Depends on | AIFACTORY-US-679, feature:component-base-template-factory-profile, feature:contracts-package |
| Sources | model/services/template-library/GenerationRecipeService.yaml, model/descriptors.yaml, docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md, docs/solution-packs/software-factory/templates/services/generation-recipe-service/index.md#apis |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-128 API hosting skeleton: REST and gRPC hosts, scope policies, problem responses and contract documents for the 6 REST operations and 2 gRPC methods |
implementation | The six REST routes and the two gRPC methods are hosted with token validation that accepts the audience of TemplateCatalogHost, scope enforcement per route, the workload identity and service scope check per gRPC method, problem responses for every modelled refusal code, the Idempotency-Key filter of DraftRecipe, and the OpenAPI and proto documents; the behaviour of each operation is delivered by AIFACTORY-US-683 to AIFACTORY-US-687, not here. | ConnectSoft.AI.SoftwareFactory.GenerationRecipeService |
AIFACTORY-TASK-129 Messaging skeleton: outbox and inbox wiring of the generation-recipe profile for 4 published events and 15 consumed rows |
implementation | The outbox writer enlists in the transaction of the command and the dispatcher of the generation-recipe messaging profile publishes RecipeValidated, RecipeApproved, GenerationCompleted and GeneratedOutputRecorded on their topics under the run event envelope of the pinned contracts package; the inbox registers the fifteen consumed rows of the model with idempotency on the event id, BlueprintValidated with its two handlers, BlueprintSubmitted, TemplateVersionDiscovered and RunCancelled among them; what each handler does is delivered by AIFACTORY-US-682, AIFACTORY-US-683, AIFACTORY-US-687 and AIFACTORY-US-688. | ConnectSoft.AI.SoftwareFactory.GenerationRecipeService |
AIFACTORY-TASK-130 Worker hosting skeleton: triggers, partitioning and retry policies of PlanProposer and RecipeValidator |
implementation | The PlanProposer is hosted with its event trigger, two attempts with 60 s backoff, the key of blueprint id and blueprint version and at most two parallel executions; the RecipeValidator is hosted to be run by ValidateRecipe with two attempts with 30 s backoff, the key of recipe id, version and content hash and at most four parallel executions; both are partitioned by project and a duplicate trigger has no second effect; what each worker does is delivered by AIFACTORY-US-683 and AIFACTORY-US-685. | ConnectSoft.AI.SoftwareFactory.GenerationRecipeService |
AIFACTORY-TASK-2723 Verify the hosted surface of GenerationRecipeService |
verification | Run the contract, authorization, messaging and readiness tests of the repository pipeline; they prove AC1 to AC4 of AIFACTORY-US-680: the OpenAPI document and the proto match model/services/template-library/GenerationRecipeService.yaml, every route and method refuses a caller without token, audience, scope or workload identity, an event is published once per committed command and never for a rolled back one, and a duplicate trigger of either worker has one effect. | ConnectSoft.AI.SoftwareFactory.GenerationRecipeService |
AIFACTORY-US-681: GenerationRecipeService filters every query by tenant, answers a foreign recipe as not found, starts only with its transport secret reference and keeps generated content out of telemetry¶
enabling
Tenancy is enforced in the service and not only at the gateway. Every query of every table of generation-recipe-sql runs under the tenant row filter of the Factory profile: the nine tables of the model, that is the three tables of the recipes and outputs, the five projection tables that AIFACTORY-US-682 fills and the table PlanProposals that AIFACTORY-US-683 fills. Through I4 the catalog rows belong to the platform tenant only (D123): the envelope of every catalog event names the platform tenant, the three catalog projections, template versions, library versions and compatibility cells, keep each row under the tenant of the envelope of its event, and their filter admits the rows of the platform tenant for reading by every tenant, as the catalog of TemplateRegistryService does. A recipe binds catalog rows of the platform tenant and no other, so a row kept under any other tenant is invisible to the other tenants and bound by no recipe; templates owned by a tenant are a later feature. The tenant and project of a user call come from the trusted scope of the forwarded token; those of a workload call are the ones the workload forwards and are read only when its token holds the service scope of the method (ADR-0015 amendment D114). A recipe or a generated output of another tenant is invisible under the filter: every operation that addresses it answers 404, or the gRPC status NOT_FOUND, the same answer as for an id that does not exist (ADR-0015 amendment D113); a missing scope or role inside the tenant of the caller stays 403 or PERMISSION_DENIED. The project of a project-scoped call is named by the caller, in the query parameter projectId of ListRecipes and in the body member projectId of DraftRecipe (D123): a call without it is answered 400, the gateway checks it against the roles of the token and answers 403 for a project the token does not grant, and the service compares it with the project of the trusted scope it receives and answers 403 when the two differ, so a recipe is never written or listed for another project than the one the gateway admitted. The service holds no project registry and the model lists no dependency on ProjectService, so the one operation that takes a project in its path, ListGeneratedOutputs, compares the path projectId with the project of the trusted scope of the forwarded token: an equal id is answered 200, with an empty list when nothing is recorded, and every other id is answered 404, because the service cannot tell a project of another tenant from a project of the same tenant outside the scope of the caller. Whether a project of the same tenant should be answered 403 instead, which the amendment D113 would suggest for a missing right inside the tenant, is reported to the owner. The only secret of the service is the transport credential messaging-transport, read from its key vault reference with the rotation the model states; the service does not start without the reference and never logs the value. The data class of the service is confidential, so generated content stays out of telemetry: no log record, activity, metric or event carries a recipe document, the parameters of a module, a file of a generated output or a list of paths; events and logs carry ids, versions, hashes, states, counts and reasons (ADR-0019). Telemetry follows the Factory conventions of feature component-observability-factory-conventions, consumed by a version pin: tenant and project are on metrics by default, and run, step and attempt are on activities and log records only. The four metrics of the model are recorded with their modelled dimensions: connectsoft.factory.recipes by tenant and state on every state change, connectsoft.factory.recipes.generated_modules by tenant, module kind and template id, connectsoft.factory.recipes.validation_failures by reason, and connectsoft.factory.recipes.inbox_lag as the age of the oldest unprocessed inbox message. Health checks cover the store and the messaging profile. A runbook records the two failure modes of the model: a template version that is deprecated after a recipe that pins it was approved, in which case the recipe stays valid for its pinned version, a newer version is offered and a run that executes the recipe is not interrupted, and the loss of the store, detected by readiness and recovered by a restore within the recovery point of 15 minutes that model/stores.yaml states.
Acceptance criteria
| AC1 | Given the fixture of two tenants with one recipe and one generated output each, when a caller of the first tenant addresses the recipe of the second through every REST route and every gRPC method that takes a recipe, or calls ListGeneratedOutputs with the project id of the second, then each answer is 404 or the gRPC status NOT_FOUND, the same answer as for an id that does not exist: the recipe because the row filter hides it, the project because the path projectId is compared with the project of the trusted scope and every other id is answered 404; no list contains a row of the other tenant, a catalog row announced under the second tenant is invisible to the first while a row of the platform tenant is visible to both, and a caller of the right tenant without the scope is answered 403 or PERMISSION_DENIED (ADR-0015). |
| AC2 | Given a draft or a list without projectId, a draft or a list whose projectId differs from the project of the trusted scope, a draft whose body names a blueprint version of another project or tenant, a draft whose body names a recipe id that the project of the trusted scope does not hold, or a workload call whose token lacks the service scope under which a forwarded tenant and project are read, when it arrives, then it is refused with 400, 403, 412, 422 or PermissionDenied respectively and nothing is written; the 412 is the same answer as for a blueprint version that is unknown or that a recipe may not bind and never says which (ADR-0015, model/services/template-library/GenerationRecipeService.yaml). |
| AC3 | Given deployment values without the key vault reference of the secret messaging-transport that model/services/template-library/GenerationRecipeService.yaml names, when the service starts, then the start fails and names the missing reference; with the reference the service starts, and no log record, activity or metric carries the value. |
| AC4 | Given drafts, validations, approvals and recorded outputs of the fixture, when telemetry is collected, then connectsoft.factory.recipes, connectsoft.factory.recipes.generated_modules, connectsoft.factory.recipes.validation_failures and connectsoft.factory.recipes.inbox_lag are recorded with the dimensions of model/services/template-library/GenerationRecipeService.yaml, run, step and attempt appear on activities and log records only, and no log record, activity, metric or event holds a recipe document, module parameters, a generated file or a list of paths (ADR-0019). |
| Traces: services | GenerationRecipeService |
| Traces: aggregates | GenerationRecipeService/GenerationRecipe, GenerationRecipeService/GeneratedOutput |
| Traces: adrs | ADR-0015, ADR-0019 |
| Traces: requirements | FUX-01 |
| Depends on | AIFACTORY-US-680, feature:component-observability-factory-conventions, feature:local-development-environment |
| Sources | model/services/template-library/GenerationRecipeService.yaml, model/stores.yaml, docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md, docs/architecture/adr/0019-data-governance.md, docs/solution-packs/software-factory/templates/services/generation-recipe-service/index.md#failure-and-recovery |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-131 Security, tenancy and telemetry of GenerationRecipeService |
implementation | The tenant row filter is on every query of every table of generation-recipe-sql, the five projection tables and PlanProposals among them, and admits the platform tenant for reading on the three catalog projections; an architecture test fails on a mapping without the filter; the tenant and project of a user call come from the trusted scope, the projectId a caller names in ListRecipes or DraftRecipe is compared with that project and answered 403 when it differs, the tenant and project of a workload call are read only under the service scope, a resource of another tenant is answered 404 or NOT_FOUND and a missing scope or role 403 or PERMISSION_DENIED, ListGeneratedOutputs answers 404 for every path projectId that is not the project of the trusted scope, the transport credential comes from its key vault reference, the four metrics carry the dimensions of the model, activities and log records carry run, step and attempt, and no telemetry holds generated content. | ConnectSoft.AI.SoftwareFactory.GenerationRecipeService |
AIFACTORY-TASK-2724 Acceptance fixture of two tenants with their projects, members and workload identities |
fixture | A fixture of the acceptance suite seeds two tenants, each with a project, a member per scope of the model, a member with the Reviewer role and a workload identity with the service scopes, one recipe and one generated output per tenant, and catalog rows of the three catalog projections under the platform tenant and under each of the two tenants, so that every scenario of the feature can be run once inside a tenant and once across tenants; the fixture uses an isolated test database and the test authority of the local environment. | ConnectSoft.AI.SoftwareFactory.GenerationRecipeService |
AIFACTORY-TASK-2725 Runbook of the two failure modes of GenerationRecipeService |
documentation | The repository documentation holds a runbook for a template version deprecated after approval (the recipe stays valid for its pinned version, the newer version is shown as available, the executing run is not interrupted) and for the loss of the store (detection by readiness, restore within the recovery point of model/stores.yaml, recipe documents still held by ArtifactService). | ConnectSoft.AI.SoftwareFactory.GenerationRecipeService |
AIFACTORY-TASK-2726 Verify tenancy, the failing start without the secret reference and the telemetry content guard |
verification | Run the two-tenant tests, the start test and the telemetry guard of the repository pipeline; they prove AC1 to AC4 of AIFACTORY-US-681: a foreign recipe or output is answered 404 or NOT_FOUND on every operation, a path projectId other than the project of the trusted scope is answered 404, a catalog row of another tenant is invisible while one of the platform tenant is visible, a call without projectId is answered 400 and a projectId other than the project of the trusted scope 403, a blueprint version of another project is answered 412 and a recipe id of another project 422, the service does not start without the reference of messaging-transport, and a scan of the collected logs, activities, metrics and events finds the content of no fixture recipe or generated file (ADR-0015, ADR-0019). | ConnectSoft.AI.SoftwareFactory.GenerationRecipeService |
AIFACTORY-US-682: Keep the blueprint versions, design inputs, template versions, library versions and compatibility evidence a recipe may bind, and return a Validated recipe to Draft when a pinned blueprint changes¶
behavior
A recipe may bind only what the service has heard is available, and it hears it through its inbox, because the model gives it no read of the state of a blueprint or of the catalog besides the manifest and the derived models. Eight handlers keep that knowledge in the five projection tables of the model, each idempotent on the event id (D123). TrackBindableBlueprints records in BindableBlueprintVersions the blueprint version that BlueprintSubmitted of BlueprintService announces, with the state Submitted, and OfferRecipe records the version that BlueprintPublished announces, with the state Published, as one a recipe can be drafted from; the row keeps the last state announced, and a Submitted announcement that arrives after the Published one does not lower it. TrackDesignInputs records in ValidatedDesignInputs the two kinds of design input a module entry may pin (ADR-0027): a Module, Database, Frontend or UX Blueprint version that BlueprintValidated announces with passed true, by blueprint id, version and document hash, and an artifact that ArtifactStored of ArtifactService announces with the descriptor application-design-v1, by artifact id, version in its chain and content hash. TrackTemplates records in TemplateVersionProjections each template version that TemplateVersionDiscovered of TemplateRegistryService announces, with the state Discovered, and OfferUpgrade records each version that TemplateVersionPublished announces, with the state Published, as one a module may reference; a Discovered announcement that arrives after the Published one does not lower the state. TrackLibraries records in LibraryVersionProjections each library version with its catalog state from LibraryVersionDiscovered, and RefreshEvidence records in CompatibilityCellProjections each compatibility cell with its result and its entry id from CompatibilityChecked. Until the evaluation gate of AgentRegistryService is delivered in I4 the Draft allowance applies (D123): a recipe may bind a blueprint version in the state Submitted and a template version in the state Discovered beside Published ones, and the recipe records in draftAllowanceUsed that the allowance was used. One read port of the projection applies that rule for DraftRecipe, the PlanProposer, GetRecipe and the RecipeValidator. Arriving in I4 a recipe binds only rows in the state Published, which is a change of that one rule and of no handler. The offer of an upgrade is a read: a recipe that pins an earlier version of that template shows the newer Published version as available through the reads of the service, and nothing is drafted automatically. The purpose of OfferUpgrade in the model is that a newer template version offers a recipe version; that the offer is a read and the handler drafts nothing is a reading of this PBI, and this reading is reported to the owner. A recipe that is already Approved stays valid for the version it pins, also when that version is deprecated later, and a run that executes it is not interrupted, as the failure mode of the model states. InvalidateDrafts handles BlueprintValidated for a blueprint that a recipe is built on or pins: when the event announces another document hash than the recipe pins for that blueprint version, or passed false for it, a recipe in state Validated returns to Draft through Changed and must be validated again; a Draft stays Draft; an Approved, Executing, Generated or Superseded recipe is never touched, because an approved recipe is immutable. The purpose of InvalidateDrafts in the model is that a changed blueprint invalidates Draft recipes built on it, while the state table gives a Draft no transition and gives Changed to a Validated recipe alone; that the handler returns Validated recipes to Draft and leaves a Draft untouched is a reading of this PBI, and this reading is reported to the owner. Every row of the projection is kept under a tenant. Blueprint versions and design inputs are kept under the tenant and project of their event. Through I4 the catalog rows belong to the platform tenant only (D123): the payloads of the four catalog events name no tenant, run-event-envelope-v1 requires the tenant id (ADR-0014 decision 1), and the envelope of every catalog event names the platform tenant. The three catalog projections, template versions, library versions and compatibility cells, keep each row under the tenant of the envelope of its event; every tenant reads the rows of the platform tenant, and a recipe binds catalog rows of the platform tenant and no other. Templates owned by a tenant are a later feature. The five tables are those the model lists on generation-recipe-sql, and this PBI migrates them. The projection holds ids, versions, hashes, states and results and no document content. Two facts reach the projection through no modelled event, and both are reported to the owner: no event announces that a library version became Published after it was discovered, since LibraryVersionDiscovered carries the catalog state at discovery and is the only library event, and no event announces that a template version was deprecated, since TemplateVersionDiscovered and TemplateVersionPublished are the only template events this service consumes, although the failure mode of the model names a deprecation heard through the catalog. The projection therefore holds the state last announced for a library version and keeps a template version as Published once it was announced; what the validator does with both is stated in AIFACTORY-US-685. BlueprintService publishes BlueprintPublished and TemplateRegistryService publishes TemplateVersionPublished only after AgentRegistryService publishes AssetReleasePublished for the version, which its publication path does from I2 (feature agent-registry-service-publication, D140). On a deployed instance of this increment the projections are therefore filled by the events those services publish today, BlueprintSubmitted after a submission and TemplateVersionDiscovered after a discovery, with rows in the states Submitted and Discovered, and drafting and validation work on them under the allowance. The two handlers of the Published events are complete here and proven on event fixtures under the run event envelope.
Acceptance criteria
| AC1 | Given BlueprintService/BlueprintSubmitted and later BlueprintService/BlueprintPublished for a blueprint version, and TemplateRegistryService/TemplateVersionDiscovered and later TemplateRegistryService/TemplateVersionPublished for a template version, each under run-event-envelope-v1, when TrackBindableBlueprints, OfferRecipe, TrackTemplates and OfferUpgrade handle them, then BindableBlueprintVersions holds the blueprint version for its tenant and project with the state Submitted and then Published, TemplateVersionProjections holds the template version under the tenant of its envelope, the platform tenant, with the state Discovered and then Published, a second delivery of the same event id adds nothing, a Submitted or Discovered announcement that arrives after the Published one does not lower the state, and no recipe is drafted or changed by any of the four handlers, the offer of an upgrade being a read by the reading of OfferUpgrade that this PBI reports to the owner (ADR-0015, model/services/template-library/GenerationRecipeService.yaml). |
| AC2 | Given BlueprintService/BlueprintValidated with passed true for a Module, Database, Frontend or UX Blueprint version and ArtifactService/ArtifactStored with the descriptor application-design-v1, when TrackDesignInputs handles them, then each is recorded as a design input that may be pinned, by id, version and hash, and an event with passed false, of another kind or with another descriptor records none (ADR-0027). |
| AC3 | Given TemplateRegistryService/LibraryVersionDiscovered and TemplateRegistryService/CompatibilityChecked, when TrackLibraries and RefreshEvidence handle them, then LibraryVersionProjections holds the library version with its catalog state and CompatibilityCellProjections the compatibility cell with its result and entry id, each under the tenant of the envelope of its event, the platform tenant, a later event for the same library version or cell replaces the earlier value, and the projection holds no document content (ADR-0015, model/services/template-library/TemplateRegistryService.yaml). |
| AC4 | Given a GenerationRecipeService/GenerationRecipe in state Validated that pins a blueprint version by document hash, when BlueprintService/BlueprintValidated announces another hash or passed false for that blueprint version and InvalidateDrafts handles it, then the recipe returns to Draft through Changed; a Draft recipe stays Draft, and an Approved, Executing, Generated or Superseded recipe is not changed; that the handler acts on Validated recipes, while its purpose in the model names Draft recipes, is the reading this PBI reports to the owner (model/services/template-library/GenerationRecipeService.yaml). |
| AC5 | Given the rows of AC1 and AC3 before the evaluation gate of I4, when DraftRecipe, the PlanProposer, GetRecipe and the RecipeValidator read the projection through its one read port, then a blueprint version in the state Submitted and a template version in the state Discovered are offered as ones a recipe may bind, beside Published ones, as the Draft allowance of model/services/template-library/GenerationRecipeService.yaml states; a catalog row of the platform tenant is offered to every tenant, and a template version, a library version or a compatibility cell kept under another tenant than the platform tenant is offered to no caller and bound by no recipe (ADR-0015). |
| Traces: services | GenerationRecipeService, BlueprintService, TemplateRegistryService, ArtifactService |
| Traces: aggregates | GenerationRecipeService/GenerationRecipe |
| Traces: events | BlueprintService/BlueprintSubmitted, BlueprintService/BlueprintPublished, BlueprintService/BlueprintValidated, ArtifactService/ArtifactStored, TemplateRegistryService/TemplateVersionDiscovered, TemplateRegistryService/TemplateVersionPublished, TemplateRegistryService/LibraryVersionDiscovered, TemplateRegistryService/CompatibilityChecked |
| Traces: descriptors | application-design-v1, run-event-envelope-v1 |
| Traces: adrs | ADR-0014, ADR-0015, ADR-0027 |
| Depends on | AIFACTORY-US-680, feature:blueprint-service, feature:template-registry-service, feature:artifact-service |
| Sources | model/services/template-library/GenerationRecipeService.yaml, model/services/template-library/BlueprintService.yaml, model/services/template-library/TemplateRegistryService.yaml, model/services/knowledge/ArtifactService.yaml, docs/architecture/adr/0027-generation-input-contract.md, docs/solution-packs/software-factory/templates/services/generation-recipe-service/index.md#messages |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-2727 Projection tables of the pinnable inputs in generation-recipe-sql |
migration | Migrations and mappings create the five projection tables of model/services/template-library/GenerationRecipeService.yaml with the keys, columns and indexes it lists: BindableBlueprintVersions with the state Submitted or Published, ValidatedDesignInputs, TemplateVersionProjections with the state Discovered or Published, LibraryVersionProjections with the catalog state last announced, and CompatibilityCellProjections with the result and the entry id. Each holds ids, versions, hashes, states and results only, leads its key with the tenant and has the tenant row filter in its mapping: blueprint versions and design inputs under the tenant and project of their event, the three catalog tables under the tenant of the envelope of their event, the platform tenant through I4, with a filter that admits the platform tenant for reading. Mapping tests run against an isolated test database. | ConnectSoft.AI.SoftwareFactory.GenerationRecipeService |
AIFACTORY-TASK-2728 Inbox handlers TrackBindableBlueprints, OfferRecipe, TrackDesignInputs, TrackTemplates, OfferUpgrade, TrackLibraries, RefreshEvidence and InvalidateDrafts |
implementation | The eight handlers keep the projection from BlueprintSubmitted, BlueprintPublished, BlueprintValidated, ArtifactStored, TemplateVersionDiscovered, TemplateVersionPublished, LibraryVersionDiscovered and CompatibilityChecked, idempotently on the event id, and write every row under the tenant of the envelope of its event, the catalog rows included; a blueprint version keeps the state Submitted or Published and a template version the state Discovered or Published, and a later Submitted or Discovered announcement never lowers a Published row; one read port of the projection serves the later PBIs, returns the blueprint versions and design inputs of the tenant and project of the caller and, for the three catalog tables, the rows of the platform tenant, and applies the Draft allowance in one place: until I4 it offers Submitted blueprint versions and Discovered template versions beside Published ones as rows a recipe may bind; InvalidateDrafts returns a Validated recipe to Draft through Changed when BlueprintValidated announces another document hash or a failed verdict for a blueprint version the recipe pins, and never touches a recipe that is Approved or later. | ConnectSoft.AI.SoftwareFactory.GenerationRecipeService |
AIFACTORY-TASK-2729 Event fixtures of the catalog, blueprint and artifact events the projection is built from |
fixture | The acceptance suite builds the eight consumed events from the payloads of model/services/template-library/BlueprintService.yaml, model/services/template-library/TemplateRegistryService.yaml and model/services/knowledge/ArtifactService.yaml under the run event envelope of the pinned contracts package and delivers them once and twice under one event id and in both orders of the Submitted and Published, and of the Discovered and Published, announcement; BlueprintSubmitted, TemplateVersionDiscovered, LibraryVersionDiscovered and CompatibilityChecked are built as BlueprintService and TemplateRegistryService publish them in this increment, with the platform tenant in the envelope of the catalog events, and BlueprintPublished and TemplateVersionPublished are fixtures of events that no service publishes before the publication path of AgentRegistryService arrives in I2 (D140); a two-tenant catalog case delivers one template version, one library version and one compatibility cell under the platform tenant and one of each under the envelope of the second tenant, so that the visibility of catalog rows can be proven for a recipe of the first tenant. | ConnectSoft.AI.SoftwareFactory.GenerationRecipeService |
AIFACTORY-TASK-2730 Verify track-pinnable-generation-inputs through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&Feature=track-pinnable-generation-inputs"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-682 on the events of AIFACTORY-TASK-2729: every handler records its input once per event id, an event that does not qualify records nothing, a blueprint version goes from Submitted to Published and a template version from Discovered to Published and neither state is lowered by a late announcement, and a Validated recipe returns to Draft on a changed blueprint while an Approved one does not; the read port of the projection, the one port through which DraftRecipe, the PlanProposer, GetRecipe and the RecipeValidator see what a recipe may bind, offers a Submitted blueprint version and a Discovered template version under the Draft allowance, and on the two-tenant catalog case it returns to the first tenant the rows of the platform tenant and none of the rows delivered under the second tenant; the suites of AIFACTORY-US-683 to AIFACTORY-US-685 repeat the case through each of those callers. |
ConnectSoft.AI.SoftwareFactory.GenerationRecipeService |
AIFACTORY-US-683: Propose a module plan from the derived context map and domain model, and draft a recipe from a blueprint version a recipe may bind¶
behavior · persona requester
As a requester, I want a module plan proposed from the derived models of my blueprint and a Draft recipe I can adjust, so that I start from one module per bounded context with a template version and do not assemble the plan by hand.
When BlueprintService announces ContextMapDerived, the inbox handler ProposeModulePlan triggers the PlanProposer, once per blueprint id and blueprint version. The worker reads the context map and the domain models of that version through Blueprints.GetDerivedModel of BlueprintService with its workload token and proposes a module plan: one microservice per bounded context, a gateway, a shell and microfrontends per UI blueprint and a library per shared kernel, each entry with a module kind, the context it serves, a template version a recipe may bind from TemplateVersionProjections (AIFACTORY-US-682), the default switches, the path and the pins of the design inputs its kind needs where a validated version is known. DomainModelDerived adds the parameters of the module of its context to the proposal. The template versions the worker may use are those of the platform tenant, which every tenant reads: Published versions and, until the evaluation gate of AgentRegistryService is delivered in I4, versions the catalog has discovered that are not yet Published (D123). For a context for whose module kind no such template version is known, the worker invents no template: the proposal keeps the entry with its kind, context, parameters and path and without a template, marked as unresolved, and a draft taken from such a proposal is refused until the caller sends a plan whose entries name a template. On a deployed instance of this increment TemplateRegistryService announces the versions it discovers, so the proposal names them under the Draft allowance and does not wait for the gate. The proposal is not a recipe. It is kept per blueprint version in the table PlanProposals of the model (D123), with tenant, blueprint id, blueprint version, project and the entries, so that DraftRecipe on any replica of the service takes it; this PBI migrates the table in generation-recipe-sql under the tenant row filter. The model has the proposer name modules through the model profile of Templates:Recipes:ProposerProfile and lists ModelRouterService as an optional dependency that degrades. A model invocation of ModelRouterService needs the route plan of a run, and a proposal runs outside a run, so in this delivery the worker derives every name from the context ids by a fixed rule and calls no model, which is the degraded mode; the option is bound and validated, and how a call outside a run is routed is reported to the owner. BlueprintService is a required dependency that fails fast: when it does not answer, the execution fails, is tried once more after 60 s and is then left to the failed work of the inbox, and no partial proposal is kept. A Requester or an Asset maintainer whose forwarded user token carries factory.recipes.write drafts a recipe through DraftRecipe with an Idempotency-Key. The scope summary of the model also names agents under a run, but no tool is modelled for this operation, so only a user token calls it in this delivery. The body names the project in the required member projectId, the blueprint id and version, and may carry the module plan, the library versions and the repository layout as the caller adjusted them; without a plan in the body the proposal is taken. A call without projectId is answered 400; the gateway checks the named project against the roles of the token and answers 403 for a project the token does not grant, and the service compares the member with the project of the trusted scope it receives and answers 403 when the two differ (D123). The service knows a blueprint only through its projection, so one rule answers the precondition: a blueprint id and version that BindableBlueprintVersions does not hold for the trusted tenant and project is answered 412, whether it is unknown, belongs to another project or tenant or was not yet submitted, and the answer never says which (ADR-0015 amendment D113). Until the evaluation gate of I4 a version in the state Submitted is bound under the Draft allowance beside a Published one; from I4 the 412 answers every version that is not Published (D123). The recipe records in draftAllowanceUsed whether the allowance was used: the member is true when the bound blueprint version is Submitted or a module entry names a template version in the state Discovered, and false when every bound version is Published. The service writes the GenerationRecipe in state Draft with its module entries, and a body that names an existing recipe id of the project drafts the next version of that recipe. The model gives no operation that edits a Draft or Validated recipe, although the summary of the endpoint says that people or agents adjust the plan and the state table returns a Validated recipe to Draft on Changed. In this delivery an adjustment is therefore a new POST that drafts the next version, and Changed is raised by no REST operation, only by the handler InvalidateDrafts of AIFACTORY-US-682; both are readings reported to the owner. The answer is 201 with the recipe id and version. The model names no result event for the command, so no integration event of the service is published; connectsoft.factory.recipes counts the Draft. The command still leaves evidence, because every command of the first outcome belongs in the audit trail: the Factory sink of the audit library, consumed by a version pin from feature component-audit-factory-evidence, writes one audit-evidence-v1 record with the actor, the recipe id and the version to the outbox in the transaction of the command, on the topic audit.evidence.v1.evidence-submitted under the run event envelope; a rolled back command leaves none and an idempotent repeat writes no second one. A repeated call with the same key and the same body returns the same recipe. The same key with another body is a conflict by ADR-0014 decision 3 and is answered 409 (D123). 422 is kept for the body: a module entry with an unknown module kind or without a template, an entry that a proposal left without a template, a recipe id that the project of the trusted scope does not hold, and a call without a plan in the body when no proposal exists for the blueprint version, because the PlanProposer failed twice or ContextMapDerived has not arrived, which is refused with 422 that names the missing plan. Nothing is written in any of these cases. A missing scope is 403. The project of the recipe is the project the caller names in projectId, which is the project of the trusted scope. The service decides no approval and repeats no write on its own.
Acceptance criteria
| AC1 | Given BlueprintService/ContextMapDerived and BlueprintService/DomainModelDerived for a blueprint version with two bounded contexts, when the PlanProposer runs, then it reads the derived models through BlueprintService/Blueprints.GetDerivedModel and keeps one proposal for that blueprint version in the table PlanProposals, under the tenant and project of the event, with one microservice entry per context, each with a template version of the platform tenant that a recipe may bind, Published or, under the Draft allowance until I4, Discovered, its switches, parameters and path; a context for whose module kind no such template version is known yields an entry without a template, marked as unresolved, and never an invented one, and a draft taken from that proposal is refused as AC3 states; a second trigger for the same blueprint id and blueprint version has no second effect, and no model is called (model/services/template-library/GenerationRecipeService.yaml). |
| AC2 | Given a caller with factory.recipes.write and a blueprint version of the project of the trusted scope that BindableBlueprintVersions holds as Submitted or as Published, when GenerationRecipeService/DraftRecipe is called with the projectId of that project and an Idempotency-Key, then a GenerationRecipeService/GenerationRecipe is written in state Draft with the module entries of the proposal or of the body, draftAllowanceUsed is true when the blueprint version is Submitted or a module entry names a Discovered template version and false when every bound version is Published, the response is 201 with recipe id and version, no integration event of the service is published, and one audit-evidence-v1 record with the actor, the recipe id and the version is in the outbox, written in the transaction of the command on the topic audit.evidence.v1.evidence-submitted under run-event-envelope-v1; a command that is rolled back leaves no record (SCN-GenerationRecipeService-003). |
| AC3 | Given the same call repeated with the same key, the same key with another body, a body without projectId, a projectId that differs from the project of the trusted scope, a blueprint id and version that BindableBlueprintVersions does not hold for the trusted tenant and project, a module entry with an unknown kind or without a template, a proposal whose entry was left without a template, no plan in the body while no proposal exists for the blueprint version, or a caller without factory.recipes.write, when it arrives at GenerationRecipeService/DraftRecipe, then the repeat returns the same recipe, creates none and writes no second evidence record; the reused key, a conflict by ADR-0014 decision 3, is answered 409; the missing projectId is answered 400 and the differing one 403; the blueprint version is answered 412 whether it is unknown, belongs to another project or tenant or was not yet submitted, and the answer never says which; the entries are refused with 422 that names the module, and the missing plan with 422 that names it; the missing scope is answered 403; each refusal carries a problem response and writes no recipe and no evidence record (SCN-GenerationRecipeService-003, ADR-0015). |
| AC4 | Given a body that names an existing recipe id of the project, when GenerationRecipeService/DraftRecipe is called, then the next version of that recipe is written in state Draft and the earlier versions are unchanged, which is how a plan is adjusted in this delivery, because the model gives no operation that edits a Draft or Validated recipe, a reading reported to the owner; a recipe id that the project of the trusted scope does not hold is refused with 422; and given BlueprintService does not answer the PlanProposer, then the execution is tried twice 60 s apart, keeps no partial proposal and leaves GenerationRecipeService/DraftRecipe working with a plan in the body (SCN-GenerationRecipeService-003). |
| Traces: services | GenerationRecipeService, BlueprintService |
| Traces: aggregates | GenerationRecipeService/GenerationRecipe |
| Traces: apis | GenerationRecipeService/DraftRecipe, BlueprintService/Blueprints.GetDerivedModel |
| Traces: events | BlueprintService/ContextMapDerived, BlueprintService/DomainModelDerived |
| Traces: descriptors | audit-evidence-v1, run-event-envelope-v1 |
| Traces: adrs | ADR-0014, ADR-0015, ADR-0027 |
| Traces: requirements | FR-03 |
| Traces: scenarios | SCN-GenerationRecipeService-003 |
| Depends on | AIFACTORY-US-681, AIFACTORY-US-682, feature:blueprint-service, feature:component-audit-factory-evidence |
| Sources | model/services/template-library/GenerationRecipeService.yaml, model/services/template-library/BlueprintService.yaml, model/model-profiles.yaml, docs/reference/schemas/audit-evidence.schema.json, docs/architecture/adr/0014-run-and-lifecycle-envelopes.md, docs/solution-packs/software-factory/templates/services/generation-recipe-service/index.md#workers-and-jobs |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-215 Module plan proposal and pinned design inputs |
implementation | The ProposeModulePlan handler triggers the PlanProposer once per blueprint id and blueprint version; the worker reads the derived models through Blueprints.GetDerivedModel and writes one row of the table PlanProposals of AIFACTORY-TASK-2746 per blueprint version, whose module entries carry kind, context, a template version of the platform tenant that a recipe may bind, Published or until I4 Discovered, switches, parameters, path and the pins of their design inputs by id, version and hash where a validated version is known; an entry for whose module kind no such template version is known is kept without a template and marked unresolved, never with an invented one; names come from the context ids by a fixed rule and no model is called; a failed read is tried twice 60 s apart and keeps no partial proposal. | ConnectSoft.AI.SoftwareFactory.GenerationRecipeService |
AIFACTORY-TASK-2746 Table PlanProposals of the module plan in generation-recipe-sql |
migration | A migration and a mapping create the table PlanProposals of model/services/template-library/GenerationRecipeService.yaml in generation-recipe-sql: the key of tenant, blueprint id and blueprint version, the project, the proposed entries and the time of the proposal, with the tenant row filter in the mapping, so that DraftRecipe on any replica reads the proposal the PlanProposer wrote; mapping tests run against an isolated test database. | ConnectSoft.AI.SoftwareFactory.GenerationRecipeService |
AIFACTORY-TASK-2731 DraftRecipe with idempotency, the bindable blueprint precondition, the Draft allowance and versioned drafts |
implementation | DraftRecipe requires the body member projectId, answers 400 without it and 403 when it differs from the project of the trusted scope, requires the blueprint id and version to be held by BindableBlueprintVersions for the trusted tenant and project, as Submitted under the Draft allowance until I4 or as Published, and answers 412 otherwise, the same answer for an unknown, a foreign and a not yet submitted blueprint version, writes the Draft GenerationRecipe with the module entries of the proposal or of the body, sets draftAllowanceUsed when the blueprint version is Submitted or a module entry names a Discovered template version, writes the next version when the body names an existing recipe of the project, and answers 201; in the transaction of the command it writes one audit-evidence-v1 record with the actor, the recipe id and the version through the Factory sink of the pinned audit library to the outbox, on the topic audit.evidence.v1.evidence-submitted; it refuses with 422 an unknown module kind, an entry without a template, a recipe id the project does not hold and a missing plan when no proposal exists, and with 409 the reused key with another body; the idempotent repeat and the 400, 403, 409, 412 and 422 refusals are covered by acceptance tests. | ConnectSoft.AI.SoftwareFactory.GenerationRecipeService |
AIFACTORY-TASK-2732 Contract of the draft body and of the recipe view |
contract | The OpenAPI document of the service defines the body of DraftRecipe (the required projectId, blueprint id and version, optional recipe id, module entries with kind, context, template id and version, switches, parameters, path and design input pins, library versions, repository layout) and the recipe view that GetRecipe returns, with the fields of the GenerationRecipe aggregate and the ModulePlanEntry entity of model/services/template-library/GenerationRecipeService.yaml. | ConnectSoft.AI.SoftwareFactory.GenerationRecipeService |
AIFACTORY-TASK-2733 Verify propose-a-module-plan-and-draft-a-recipe through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&Scenario=SCN-GenerationRecipeService-003"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-683 with a fake of Blueprints.GetDerivedModel: the proposal per blueprint version read from PlanProposals by a second instance of the service, the proposal and the draft on a Submitted blueprint version and a Discovered template version with draftAllowanceUsed true, the same on Published versions with draftAllowanceUsed false, the entry left without a template when no template version a recipe may bind is known, the draft from the proposal and from an adjusted body, the next version of an existing recipe, the idempotent repeat, the 400 without projectId and the 403 for a projectId other than the project of the trusted scope, the 412 that is the same for an unknown, a foreign and a not yet submitted blueprint version, the 422 for the missing plan and for the entry without a template, the 409 for the reused key, and the 403 for the missing scope; they read the outbox and find one audit-evidence-v1 record with the actor, the recipe id and the version per drafted recipe and none after a repeat, a refusal or a rolled back command; and on the two-tenant catalog case of AIFACTORY-TASK-2729 the proposal and the draft of the first tenant use no template version delivered under the second tenant. |
ConnectSoft.AI.SoftwareFactory.GenerationRecipeService |
AIFACTORY-US-684: Read the recipes of a project with their versions and states, and one recipe with its module plan, pins, layout and compatibility evidence¶
behavior · persona asset-maintainer
As an asset maintainer, I want to read a recipe with every module, every pinned version and the evidence it was validated against, so that I approve exactly what I have seen.
A caller whose forwarded user token carries factory.recipes.read reads the recipes of a project. ListRecipes takes the required query parameter projectId (D123) and returns the recipes of that project with their versions and states. A call without the parameter is answered 400; the gateway checks the named project against the roles of the token and answers 403 for a project the token does not grant, and the service compares the parameter with the project of the trusted scope it receives and answers 403 when the two differ. GetRecipe returns one version addressed by recipe id and version: the blueprint version it is built on, the module plan with the kind, context, template id and version, switches, parameters and path of each module, the design inputs each module pins by id, version and hash, the library versions, the repository layout, the compatibility evidence the recipe was validated against, the state, the approver and draftAllowanceUsed, so that the approver sees whether the recipe binds a Submitted blueprint version or a discovered template version under the Draft allowance. For a module that pins a template version for which a newer Published version is known among the catalog rows of the platform tenant, the answer names that newer version as available, which is how an upgrade is offered (AIFACTORY-US-682); a version kept under another tenant than the platform tenant is never named. Both reads run under the tenant row filter. A caller without the scope is refused with 403; a recipe id or version that does not exist and a recipe of another tenant are both answered 404 by GetRecipe, which never confirms that a foreign recipe exists (ADR-0015 amendment D113); ListRecipes has no not-found answer and never contains a row of another tenant or of a project outside the trusted scope. Nothing is written and nothing is published by a read. The views of the Studio are built by StudioBff in its own increment on these operations, and the command-line client prints a recipe from GetRecipe (AIFACTORY-US-013); a person reaches the reads through the gateway TemplateCatalogHost, which is delivered in this increment, and the client through the typed client of that gateway (D123).
Acceptance criteria
| AC1 | Given a caller with factory.recipes.read and recipes of several states in the project of the trusted scope, when GenerationRecipeService/ListRecipes is called with the projectId of that project, then the response is 200 with the recipes of that project, each with its versions and their states, and nothing of another project or tenant (SCN-GenerationRecipeService-001). |
| AC2 | Given a GenerationRecipeService/GenerationRecipe of the tenant and project of the caller, when GenerationRecipeService/GetRecipe is called, then the response is 200 with the blueprint version, the module plan with kind, context, template id and version, switches, parameters and path of each module, the design inputs each module pins by id, version and hash, the library versions, the repository layout, the compatibility evidence, the state, the approver and draftAllowanceUsed, and a module that pins a template version for which a newer Published version is known in the catalog rows of the platform tenant names that version as available (SCN-GenerationRecipeService-002, ADR-0027). |
| AC3 | Given a caller without factory.recipes.read, a call of GenerationRecipeService/ListRecipes without projectId or with a projectId that differs from the project of the trusted scope, a recipe id or version that does not exist, or a recipe of another tenant, when either read is called, then the response is 403 for the missing scope, 400 for the missing projectId, 403 for the differing one and, on GenerationRecipeService/GetRecipe, 404 for the unknown and for the foreign recipe alike, each with a problem response, and nothing is written by any read (SCN-GenerationRecipeService-001, SCN-GenerationRecipeService-002, ADR-0015). |
| Traces: services | GenerationRecipeService |
| Traces: aggregates | GenerationRecipeService/GenerationRecipe |
| Traces: apis | GenerationRecipeService/ListRecipes, GenerationRecipeService/GetRecipe |
| Traces: adrs | ADR-0015, ADR-0027 |
| Traces: requirements | FUX-01 |
| Traces: scenarios | SCN-GenerationRecipeService-001, SCN-GenerationRecipeService-002 |
| Depends on | AIFACTORY-US-681, AIFACTORY-US-683 |
| Sources | model/services/template-library/GenerationRecipeService.yaml, docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md, docs/solution-packs/software-factory/templates/services/generation-recipe-service/index.md#apis |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-2734 ListRecipes and GetRecipe over the recipes of the trusted project under the tenant filter |
implementation | ListRecipes requires the query parameter projectId, answers 400 without it and 403 when it differs from the project of the trusted scope, and returns the recipes of that project with versions and states, and GetRecipe returns one version with its module plan, pins, libraries, layout, compatibility evidence, state, approver and draftAllowanceUsed and names a newer Published template version as available where the projection knows one; both apply the tenant row filter, a recipe of another tenant is answered 404 like an unknown one and a missing scope 403 (ADR-0015). | ConnectSoft.AI.SoftwareFactory.GenerationRecipeService |
AIFACTORY-TASK-2735 Verify read-recipes through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-GenerationRecipeService-001\|Scenario=SCN-GenerationRecipeService-002)"; a zero-match filter counts as a failure; the tests prove AC1 to AC3 of AIFACTORY-US-684 on the two-tenant fixture, the 400 for a list without projectId, the 403 for a projectId other than the project of the trusted scope, the 404 for a foreign recipe, draftAllowanceUsed in the recipe view and the newer template version shown as available among them. |
ConnectSoft.AI.SoftwareFactory.GenerationRecipeService |
AIFACTORY-US-685: Validate a recipe against template manifests, switches, the compatibility matrix and its pinned design inputs, and announce the verdict¶
behavior · persona asset-maintainer
As an asset maintainer, I want a recipe to be Validated only when every template, library and pinned design input holds, so that a generation run never starts on a plan that cannot be scaffolded or on a design nobody validated.
A Requester or an Asset maintainer whose forwarded user token carries factory.recipes.write validates a recipe version of the tenant and project of the caller through ValidateRecipe. The scope summary of the model also names agents under a run, but no tool is modelled for this operation, so only a user token calls it in this delivery. The call runs the RecipeValidator for that version and answers 200 with the result when it ends. Every catalog row the validator reads is a row of the platform tenant (AIFACTORY-US-682, D123). The validator first checks the blueprint version the recipe is built on against BindableBlueprintVersions: a Published version passes, and until the evaluation gate of AgentRegistryService is delivered in I4 a Submitted version passes under the Draft allowance; a version the projection does not hold fails with a reason of its own. It then checks every module entry: the template version must be one a recipe may bind in TemplateVersionProjections, Published or until I4 Discovered under the same allowance, its pinned manifest is read through Catalog.ResolveManifest of TemplateRegistryService, which until I4 serves the manifest of a version the catalog has discovered that is not yet Published, the switches the module sets must be declared by that manifest and must accept the parameters of the module, and the path must not collide with another module. From I4 only Published versions pass both checks. In the transaction of the result the recipe keeps in draftAllowanceUsed whether the allowance was used: true when the blueprint version is Submitted, a module names a template version that is not yet Published or, until I4, a library passed with a cell that is Unknown, false when every bound version is Published and every library cell is Compatible or CompatibleWithWarnings. No modelled event tells this service that a template version was deprecated, so the projection keeps a version as Published once it was announced. The reply of Catalog.ResolveManifest, as feature template-registry-service delivers it, names the state of the version: when it names the state Deprecated or Retired, and from I4 every state other than Published, the template rule fails with a reason of its own. That the reply carries the state is an open point of that feature, and the missing event is reported to the owner. The validator checks every pinned library against the invariant that a library is Published and Compatible with every template that consumes it, with evidence. The state of a library version is the one last announced by LibraryVersionDiscovered, because no modelled event announces that a library version became Published later; a library whose last announced state is not Published, and a library the projection does not hold, each fail with a reason of their own, and the gap is reported to the owner. The compatibility of a library with a template is the result of the cell of the projection, one of the four values of Compatibility: Compatible passes and the entry id of the cell becomes compatibility evidence of the recipe; Incompatible fails; a missing cell fails as missing evidence; each failure has a reason of its own. Unknown is decided by the Draft allowance, which decision D125 extends to libraries: until I4 a cell that is Unknown passes with a finding of severity warning that names the library and the template, and the recipe keeps in draftAllowanceUsed that the allowance was used; from I4 a library must be Compatible, and a cell that is Unknown fails with a reason of its own. CompatibleWithWarnings passes in this delivery: the entry id is kept as evidence together with its result, and the result of the validation lists the library as a warning that the approver reads with the recipe. The invariant names Compatible alone, so this outcome is a reading reported to the owner. It checks every design input (ADR-0027, D67): a backend module pins a Module Blueprint and an application design; a module with persistence also pins a Database Blueprint and the domain model; a shell or microfrontend pins a Frontend Blueprint and a UX Blueprint; each pin names id, version and hash and must resolve to a validated version in the projection of AIFACTORY-US-682 with that hash. A domain model pin is resolved through Blueprints.GetDerivedModel of BlueprintService. The result lists one failure per broken rule with its reason and names the module and the pin or library; connectsoft.factory.recipes.validation_failures counts each by reason. In the transaction of the result a recipe that holds every rule moves from Draft to Validated through PlanValidated and keeps its evidence, and a recipe that breaks one stays Draft; RecipeValidated with passed true or false and the number of modules is written to the outbox in that transaction and published under the run event envelope. That event is also the audit evidence of the validation: it is the event AuditService consumes, and no separate evidence record is written. Validation is idempotent on recipe id, version and the hash of the recipe content: a repeated call for an unchanged recipe returns the same result and publishes nothing again. A caller without the scope is refused with 403; an unknown recipe and a recipe of another tenant are answered 404 alike; a recipe that is Approved, Executing, Generated or Superseded is refused with 422, because it is immutable. TemplateRegistryService and BlueprintService are required dependencies that fail fast: when one does not answer, the validator makes its second attempt after 30 s and the call then ends with 503 and a problem response, the recipe stays Draft and nothing is published (D123). The service repeats no write of a caller. On a deployed instance of this increment no blueprint or template version is Published before the gate of I4: a validation there passes on a Submitted blueprint version and on discovered template versions under the Draft allowance, the recipe records that the allowance was used, and the chain reaches an approved recipe without the gate.
Acceptance criteria
| AC1 | Given a caller with factory.recipes.write and a Draft GenerationRecipeService/GenerationRecipe of the tenant and project of the caller whose blueprint version is Published or, under the Draft allowance until I4, Submitted, and in which every module names a template version that is Published or, under the same allowance, Discovered, whose manifest, read through TemplateRegistryService/Catalog.ResolveManifest, declares its switches and accepts its parameters, every library is Published by the state last announced for it and has, with every template that consumes it, a compatibility cell whose result is Compatible or CompatibleWithWarnings, and every design input its kind needs is pinned by id, version and hash and resolves to a validated version, when GenerationRecipeService/ValidateRecipe is called, then the recipe moves from Draft to Validated through PlanValidated, draftAllowanceUsed is true exactly when a Submitted blueprint version or a template version that is not yet Published is bound or a library cell is Unknown, which passes until I4 with a finding of severity warning (D125), the entry id of every such cell is kept as compatibility evidence with its result, a cell with CompatibleWithWarnings is listed in the result as a warning and does not fail the validation, an outcome this PBI delivers as a reading reported to the owner, GenerationRecipeService/RecipeValidated with passed true is written in the same transaction, and the response is 200 with the result (SCN-GenerationRecipeService-004, ADR-0027). |
| AC2 | Given a recipe with a blueprint version that BindableBlueprintVersions does not hold, a template version that TemplateVersionProjections does not hold or whose manifest reply names the state Deprecated or Retired, a switch the manifest does not declare, a library whose last announced state is not Published or that the projection does not hold, a library whose cell with a template that consumes it is Incompatible or is missing, from I4 also one whose cell is Unknown, a catalog row that only another tenant than the platform tenant holds, a missing pin for a design input the module kind needs, or a pin whose id, version or hash resolves to no validated version, when it is validated, then the result lists one failure per broken rule with a reason of its own, Incompatible, Unknown and missing evidence being three different reasons, with the module and the pin or library, the recipe stays Draft, GenerationRecipeService/RecipeValidated with passed false is written in the same transaction and connectsoft.factory.recipes.validation_failures is incremented by reason (SCN-GenerationRecipeService-004, ADR-0027). |
| AC3 | Given the verdict was committed, when the outbox dispatcher of the profile generation-recipe publishes GenerationRecipeService/RecipeValidated on generation.recipes.v1.recipe-validated, then the event is sent under the run event envelope with recipeId, version, tenantId, projectId, passed and the number of modules and without recipe content, and a transport outage is retried with backoff so the event is neither lost nor duplicated under its event id (SCN-GenerationRecipeService-009, ADR-0012). |
| AC4 | Given a caller without factory.recipes.write, a recipe that does not exist or belongs to another tenant, a recipe that is Approved, Executing, Generated or Superseded, or TemplateRegistryService or BlueprintService not answering, when GenerationRecipeService/ValidateRecipe is called, then the response is 403, 404, 422, and after the second attempt of the RecipeValidator 30 s later 503 with a problem response respectively, the recipe keeps its state and nothing is published; a repeated call for an unchanged recipe returns the same result and publishes nothing again; and a domain model pin is resolved through BlueprintService/Blueprints.GetDerivedModel (SCN-GenerationRecipeService-004, ADR-0015). |
| Traces: services | GenerationRecipeService, TemplateRegistryService, BlueprintService |
| Traces: aggregates | GenerationRecipeService/GenerationRecipe |
| Traces: apis | GenerationRecipeService/ValidateRecipe, TemplateRegistryService/Catalog.ResolveManifest, BlueprintService/Blueprints.GetDerivedModel |
| Traces: events | GenerationRecipeService/RecipeValidated |
| Traces: adrs | ADR-0012, ADR-0015, ADR-0027 |
| Traces: requirements | NFR-13 |
| Traces: scenarios | SCN-GenerationRecipeService-004, SCN-GenerationRecipeService-009 |
| Relates: nfrs | NFR-05 |
| Depends on | AIFACTORY-US-682, AIFACTORY-US-683, feature:template-registry-service, feature:blueprint-service |
| Sources | model/services/template-library/GenerationRecipeService.yaml, model/services/template-library/TemplateRegistryService.yaml, docs/architecture/adr/0027-generation-input-contract.md, docs/solution-packs/software-factory/templates/services/generation-recipe-service/index.md#workers-and-jobs |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-216 Validation and approval rules |
implementation | The RecipeValidator checks the blueprint version of the recipe against BindableBlueprintVersions, where Published passes and until I4 Submitted passes under the Draft allowance; it checks every module against the manifest read through Catalog.ResolveManifest and its switches and fails the template rule when TemplateVersionProjections does not hold the version as Published or, until I4, as Discovered, or when the reply names the state Deprecated or Retired; in the transaction of the result it sets draftAllowanceUsed to true when a Submitted blueprint version or a template version that is not yet Published is bound or, until I4, a library passed with an Unknown cell, and to false otherwise; it checks every library against the state last announced by LibraryVersionDiscovered and against the compatibility cells of the projection, where Compatible passes with the entry id as evidence, CompatibleWithWarnings passes with the entry id and a warning in the result, Unknown passes until I4 with a finding of severity warning under the Draft allowance and fails from I4 (D125), and Incompatible and a missing cell each fail with a reason of their own; it reads only catalog rows of the platform tenant; it checks every design input pin of the module kind against a validated version by id, version and hash; in one transaction it applies PlanValidated with the compatibility evidence or leaves the recipe Draft and writes RecipeValidated; ValidateRecipe runs it under the key of recipe id, version and content hash, refuses a recipe that is Approved or later with 422 and answers 503 when TemplateRegistryService or BlueprintService does not answer the second attempt; the rule that approval makes a recipe immutable is delivered by AIFACTORY-TASK-2738. | ConnectSoft.AI.SoftwareFactory.GenerationRecipeService |
AIFACTORY-TASK-2736 Acceptance doubles of the template catalog and of the derived model read, with one recipe per broken rule |
fixture | A test double answers Catalog.ResolveManifest with fixture manifests and their switches, a second answers Blueprints.GetDerivedModel, and both can be switched to not answering; the suite holds one recipe that holds every rule on a Submitted blueprint version and a Discovered template version, the same recipe on Published versions, one recipe whose library cell is CompatibleWithWarnings and that passes with a warning, and one recipe per broken rule of AC2 of AIFACTORY-US-685, so that every failure reason is proven to be reported: a blueprint version the projection does not hold, a template version the projection does not hold, a manifest reply that names the state Deprecated, an undeclared switch, a library whose last announced state is not Published, a library the projection does not hold, an Incompatible cell, an Unknown cell, which passes with a warning and sets draftAllowanceUsed before I4 and fails from I4, a missing cell, a catalog row held only by the second tenant of the two-tenant catalog case of AIFACTORY-TASK-2729, a missing pin and a pin that resolves to no validated version. | ConnectSoft.AI.SoftwareFactory.GenerationRecipeService |
AIFACTORY-TASK-2737 Verify validate-a-recipe through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-GenerationRecipeService-004\|Scenario=SCN-GenerationRecipeService-009)"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-685: the passed and the failed verdict with the state each leaves, the passed verdict under the Draft allowance with draftAllowanceUsed true and on Published versions with draftAllowanceUsed false, the outcome of each of the four values of Compatibility and of a missing cell, every failure reason of the fixture, the catalog row of another tenant that the validator does not see, the idempotent repeat, the refusals, the outage of a required dependency answered 503 and the publication and payload of RecipeValidated; consumer handling is proven by the suites of the consumers. |
ConnectSoft.AI.SoftwareFactory.GenerationRecipeService |
AIFACTORY-US-686: Approve a Validated recipe, make it immutable, supersede its earlier versions and announce it as the single gate of generation¶
behavior · persona asset-maintainer
As an asset maintainer, I want my approval to bind one validated recipe version and to make that version immutable, so that the generation run executes exactly the version I approved and a change needs a new approval.
A caller whose forwarded user token carries factory.recipes.approve approves a Validated recipe version of the tenant and project of the caller through ApproveRecipe. The model grants the scope to the Requester or the Asset maintainer; when Templates:Recipes:RequireReviewerApproval is true the caller must hold the Reviewer role, otherwise the call is refused with 403. The model says that policy may enforce the reviewer per project and lists no dependency on a policy service, so this delivery reads the option alone and reports the gap. This approval is the command of this service and is not an approval of RunControlService: it has no request, no expiry and no run. In one transaction the recipe moves from Validated to Approved through Approved, approvedBy is set, the recipe document, that is the module plan with every pin, the libraries, the layout and the evidence, is stored in ArtifactService through Artifacts.Store and its reference and content hash are kept with the recipe, every earlier version of the same recipe that is Approved or Generated moves to Superseded through NewVersion, and RecipeApproved with recipeId, version and approvedBy is written to the outbox. From that moment the recipe is immutable: no operation changes it, and a change is a new version that needs its own approval. The Approved recipe is the single gate of the generation run (ADR-0027, D67): the readiness correlation of WorkflowEngineService submits generate-product on the event, and RunControlService marks a pending approval that was bound to an earlier version of the recipe stale, each in its own PBI. The answer is 200. A repeated call for a version already Approved returns 200 and writes nothing. A caller without the scope or without the required role is refused with 403; an unknown recipe and a recipe of another tenant are answered 404 alike; a recipe that is Draft, Executing, Generated or Superseded is refused with 409, and so is a Validated recipe whose pins no longer resolve at approval, with the unresolved pin named. ArtifactService fails fast: when it does not answer, the call ends with 503 and a problem response and the recipe stays Validated (D123). A recipe whose draftAllowanceUsed is true is approved like any other until I4, and the approver reads the member with the recipe. RecipeApproved is also the audit evidence of the approval: it names the approver and is the event AuditService consumes, so no separate evidence record is written. The service repeats no write on its own. The recipe keeps the reference and the hash of its document in documentRef and documentHash of the model (D123). The model names no operation as the one that stores the document and no rule for when NewVersion is raised or for what supersedes a version that is Executing; this PBI stores the document at approval, raises NewVersion at the approval of a later version and leaves an Executing version to the end of its run, and reports the three readings to the owner.
Acceptance criteria
| AC1 | Given a caller with factory.recipes.approve and a Validated GenerationRecipeService/GenerationRecipe of the tenant and project of the caller, when GenerationRecipeService/ApproveRecipe is called, then in one transaction the recipe moves to Approved through Approved, approvedBy names the caller, the recipe document is stored through ArtifactService/Artifacts.Store and its reference and content hash are kept in documentRef and documentHash, and GenerationRecipeService/RecipeApproved is written; the response is 200, and a repeated call for the version already Approved returns 200 and writes nothing (SCN-GenerationRecipeService-005, FR-06). |
| AC2 | Given a caller without factory.recipes.approve, a caller without the Reviewer role while Templates:Recipes:RequireReviewerApproval is true, a recipe that does not exist or belongs to another tenant, a recipe that is Draft, Executing, Generated or Superseded, or a Validated recipe with a pin that no longer resolves, when GenerationRecipeService/ApproveRecipe is called, then the response is 403, 403, 404, 409 and 409 respectively with a problem response, the last one naming the unresolved pin, the state does not change and nothing is published; and given ArtifactService does not answer, then the call ends with 503 and a problem response and the recipe stays Validated (SCN-GenerationRecipeService-005, ADR-0015). |
| AC3 | Given an Approved recipe, when any operation tries to change its modules, libraries, layout or evidence, then nothing changes, because a change is a new version; and given a later version of the same recipe is approved, then every earlier version that is Approved or Generated moves to Superseded through NewVersion in the transaction of that approval, while a version that is Executing is left to the end of its run (model/services/template-library/GenerationRecipeService.yaml, ADR-0027). |
| AC4 | Given the approval was committed, when the outbox dispatcher publishes GenerationRecipeService/RecipeApproved on generation.recipes.v1.recipe-approved, then the event is sent under the run event envelope with recipeId, version, tenantId, projectId and approvedBy, and a transport outage is retried with backoff so the event is neither lost nor duplicated under its event id (SCN-GenerationRecipeService-010, ADR-0012). |
| Traces: services | GenerationRecipeService, ArtifactService, WorkflowEngineService, RunControlService |
| Traces: aggregates | GenerationRecipeService/GenerationRecipe |
| Traces: apis | GenerationRecipeService/ApproveRecipe, ArtifactService/Artifacts.Store |
| Traces: events | GenerationRecipeService/RecipeApproved |
| Traces: adrs | ADR-0012, ADR-0015, ADR-0027 |
| Traces: requirements | FR-06 |
| Traces: scenarios | SCN-GenerationRecipeService-005, SCN-GenerationRecipeService-010 |
| Relates: nfrs | NFR-05 |
| Depends on | AIFACTORY-US-685, feature:artifact-service |
| Sources | model/services/template-library/GenerationRecipeService.yaml, model/services/knowledge/ArtifactService.yaml, model/workflows/generate-product.yaml, docs/architecture/adr/0027-generation-input-contract.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-2738 ApproveRecipe with the role check, the stored recipe document, the superseded versions and the RecipeApproved outbox record |
implementation | ApproveRecipe checks the scope and, when Templates:Recipes:RequireReviewerApproval is true, the Reviewer role, checks that every pin still resolves, and in one transaction applies Approved, sets approvedBy, stores the recipe document through Artifacts.Store and keeps its reference and content hash in documentRef and documentHash of the recipe, the columns DocumentRef and DocumentHash that AIFACTORY-TASK-127 migrates, applies NewVersion to the earlier Approved or Generated versions of the recipe and writes RecipeApproved; an Approved recipe refuses every change; an outage of ArtifactService is answered 503 and leaves the recipe Validated; the repeat and the 403, 404 and 409 refusals are covered by acceptance tests. | ConnectSoft.AI.SoftwareFactory.GenerationRecipeService |
AIFACTORY-TASK-2739 Verify approve-a-validated-recipe through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-GenerationRecipeService-005\|Scenario=SCN-GenerationRecipeService-010)"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-686: the approval with its stored document, the role rule under the option, the refusals, the immutability, the superseded earlier versions, the outage of ArtifactService answered 503 and the publication and payload of RecipeApproved; consumer handling is proven by the suites of WorkflowEngineService and RunControlService. |
ConnectSoft.AI.SoftwareFactory.GenerationRecipeService |
AIFACTORY-US-687: Serve the approved recipe with every pin resolved to a generation run, record the provenance of each generated module and list it by project¶
behavior
A generation run executes the approved recipe and leaves its provenance here. In the first step of generate-product, ToolAdapterService executes the read-class tool get-approved-recipe and calls Recipes.GetApprovedRecipe with a workload token that holds factory.recipes.read and the scope of the run. The reply is artifact-v1: the reference and the content hash of the recipe document of the approved version, which holds the module plan, the counts by module kind and, per module, every pinned design input resolved to its reference: Module Blueprint, application design, domain model, Database, Frontend and UX Blueprint. The run reads its inputs through these pins and never waits for a blueprint on its own (ADR-0027, D67). The read writes nothing; a recipe that is not Approved or Executing is answered FailedPrecondition, an unknown recipe and a recipe of another tenant NOT_FOUND alike. A generation attempt records the provenance of one generated module through Recipes.RecordOutput (decision D133): in the step record-outputs of generate-product, a step of the class shared-write, ToolAdapterService executes the tool record-generated-output, bound to the skill microservice-generator-record-outputs, and calls the method with its own workload identity, whose token holds factory.recipes.write. The call carries recipe id and version, module name, run and attempt, agent release, template id and version, manifest hash, the generated files with their hashes and the preserved paths. The service writes one GeneratedOutput and GeneratedOutputRecorded in one transaction and answers ack-v1; connectsoft.factory.recipes.generated_modules counts it by module kind and template. The call is idempotent on the run, the recipe and the hash of the change set, as the catalogue entry of the tool declares: a repeated call with the same three returns the same acknowledgement and records nothing. Because this caller exists in I1, the first recorded output of a run moves the recipe to Executing and the end of the run moves it to Generated with GenerationCompleted in this increment, as AIFACTORY-US-688 delivers. A module that is not in the plan of the recipe, a template version other than the one the module pins, and a path listed as both generated and preserved are refused with InvalidArgument; a recipe that is neither Approved nor Executing is refused with FailedPrecondition. A call without a workload identity is refused with Unauthenticated, a token without factory.recipes.write with PermissionDenied, and a recipe that does not exist or belongs to another tenant with NOT_FOUND; every refusal writes no output and no event. GeneratedOutputRecorded is also the audit evidence of a recorded output, since AuditService consumes it. The service never writes code and repeats no write on its own; a lost reply leaves the step Uncertain for the Operator decision in RunControlService. A caller with factory.recipes.read lists the provenance of the generated modules of a project through ListGeneratedOutputs, by commit, with the generated and the preserved files. The service holds no project registry and the model lists no dependency on ProjectService, so the rule it can evaluate is this: the path projectId is compared with the project of the trusted scope of the forwarded token; an equal id is answered 200, with an empty list when nothing is recorded for the project, and every other id is answered 404, because the service cannot tell a project of another tenant from a project of the same tenant outside the scope of the caller. Whether a project of the same tenant should be answered 403 instead, as a missing right inside the tenant under the amendment D113 of ADR-0015, is reported to the owner. The handler LinkCommit sets the proposal id and the commit on the outputs of the run that a merged change proposal of PipelineExecutionService names, idempotently on the event id; that event is first published in I2, so the handler is proven on a fixture and the event is not traced here. Two gaps of the model are reported and not decided. The request schema of RecordOutput, change-set-v1, has no field for recipe, module, template, manifest hash or preserved paths, so the proto of this PBI carries them beside the change set. The request schema of GetApprovedRecipe, execution-scope-v1, names no recipe, while the tool takes artifact-v1, so the proto takes the recipe id and version with the scope.
Acceptance criteria
| AC1 | Given ToolAdapterService executing the tool get-approved-recipe in the step generate-product/resolve-recipe with a workload token that holds factory.recipes.read and the scope of the run, when it calls GenerationRecipeService/Recipes.GetApprovedRecipe for an Approved or Executing recipe version of that scope, then the reply is artifact-v1 with the reference and content hash of the recipe document, which holds the module plan with its counts by module kind and every pinned design input of every module resolved to its reference, and nothing is written (SCN-GenerationRecipeService-007, ADR-0027). |
| AC2 | Given a call of GenerationRecipeService/Recipes.GetApprovedRecipe or of GenerationRecipeService/Recipes.RecordOutput without a workload identity, without the service scope of the method, factory.recipes.read for the read and factory.recipes.write for the write, or for a recipe that does not exist or belongs to another tenant, when it arrives, then it is refused with Unauthenticated, PermissionDenied and NOT_FOUND respectively, no output is written, no event is written and no state changes; and given an invalid request or a recipe that is Draft, Validated, Generated or Superseded at GenerationRecipeService/Recipes.GetApprovedRecipe, then the answer is InvalidArgument or FailedPrecondition (SCN-GenerationRecipeService-007, SCN-GenerationRecipeService-008, ADR-0015). |
| AC3 | Given ToolAdapterService executing the tool record-generated-output in the step generate-product/record-outputs with its workload identity, whose token holds factory.recipes.write, and an Approved or Executing recipe, when GenerationRecipeService/Recipes.RecordOutput is called with recipe id and version, module name, run, attempt, agent release, template id and version, manifest hash, the generated files with their hashes and the preserved paths, then one GenerationRecipeService/GeneratedOutput and GenerationRecipeService/GeneratedOutputRecorded are written in one transaction and the reply is ack-v1; a repeated call for the same run, recipe and change set hash returns the same acknowledgement and records nothing; a module outside the plan, a template version other than the pinned one or a path listed as both generated and preserved is refused with InvalidArgument, and a recipe in any other state with FailedPrecondition (SCN-GenerationRecipeService-008). |
| AC4 | Given the output was committed, when the outbox dispatcher publishes GenerationRecipeService/GeneratedOutputRecorded on generation.outputs.v1.generated-output-recorded, then the event is sent under the run event envelope with outputId, tenantId, projectId, moduleName, templateId, templateVersion, runId and, once known, proposalId, without file content, and a transport outage is retried with backoff so the event is neither lost nor duplicated under its event id (SCN-GenerationRecipeService-012, ADR-0012). |
| AC5 | Given a caller with factory.recipes.read whose trusted scope names a project, when GenerationRecipeService/ListGeneratedOutputs is called with that project id in the path, then the response is 200 with the provenance of its generated modules by commit, each with recipe version, run, attempt, agent release, template version, manifest hash, generated files with hashes and preserved paths, and with an empty list when nothing is recorded for the project; a missing scope is 403; a path projectId that is not the project of the trusted scope is answered 404, the one code this PBI names for every other id, because the service holds no project registry, while the choice of 403 for a project of the same tenant is reported to the owner; and after the fixture event of a merged change proposal for the run, handled by LinkCommit, the outputs of that run show the proposal id and the commit (SCN-GenerationRecipeService-006, ADR-0015, XL-10). |
| Traces: services | GenerationRecipeService, ToolAdapterService, PipelineExecutionService |
| Traces: aggregates | GenerationRecipeService/GenerationRecipe, GenerationRecipeService/GeneratedOutput |
| Traces: apis | GenerationRecipeService/Recipes.GetApprovedRecipe, GenerationRecipeService/Recipes.RecordOutput, GenerationRecipeService/ListGeneratedOutputs |
| Traces: events | GenerationRecipeService/GeneratedOutputRecorded |
| Traces: steps | generate-product/resolve-recipe, generate-product/record-outputs |
| Traces: tools | get-approved-recipe, record-generated-output |
| Traces: descriptors | artifact-v1, ack-v1, change-set-v1, execution-scope-v1 |
| Traces: adrs | ADR-0012, ADR-0015, ADR-0027 |
| Traces: requirements | FR-07, XL-10 |
| Traces: scenarios | SCN-GenerationRecipeService-006, SCN-GenerationRecipeService-007, SCN-GenerationRecipeService-008, SCN-GenerationRecipeService-012 |
| Relates: nfrs | NFR-05 |
| Depends on | AIFACTORY-US-686, feature:tool-adapter-service |
| Sources | model/services/template-library/GenerationRecipeService.yaml, model/tools/get-approved-recipe.yaml, model/tools/record-generated-output.yaml, model/workflows/generate-product.yaml, model/services/devops-gitops/PipelineExecutionService.yaml, docs/reference/schemas/change-set.schema.json, docs/reference/schemas/execution-scope.schema.json, docs/architecture/adr/0027-generation-input-contract.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-2740 Proto of the Recipes service with the recipe reference and the provenance fields |
contract | The proto of the service defines Recipes.GetApprovedRecipe, which takes the forwarded scope with a recipe id and version and answers with a message that maps onto docs/reference/schemas/artifact.schema.json, and Recipes.RecordOutput, which takes the change set of docs/reference/schemas/change-set.schema.json together with recipe id and version, module name, run, attempt, agent release, template id and version, manifest hash and the preserved paths and answers with the acknowledgement; the fields the modelled request schemas lack are listed in the repository documentation. | ConnectSoft.AI.SoftwareFactory.GenerationRecipeService |
AIFACTORY-TASK-2741 Recipes.GetApprovedRecipe over the stored recipe document |
implementation | Recipes.GetApprovedRecipe returns artifact-v1 with the reference and content hash of the recipe document of an Approved or Executing version under the tenant filter and the service scope factory.recipes.read; a recipe in another state is FailedPrecondition, an unknown recipe and a recipe of another tenant NotFound, the gRPC status NOT_FOUND (ADR-0015), and the read writes nothing. | ConnectSoft.AI.SoftwareFactory.GenerationRecipeService |
AIFACTORY-TASK-2742 Recipes.RecordOutput, ListGeneratedOutputs and the LinkCommit inbox handler |
implementation | Recipes.RecordOutput admits ToolAdapterService, the executor of the tool record-generated-output, as its caller under its workload identity with factory.recipes.write (D133), writes one GeneratedOutput and GeneratedOutputRecorded in one transaction for a module of the plan of an Approved or Executing recipe, idempotently on run, recipe and change set hash, and refuses a module outside the plan, another template version than the pinned one and a path listed as both generated and preserved with InvalidArgument, a recipe in any other state with FailedPrecondition, a caller without a workload identity with Unauthenticated, a token without factory.recipes.write with PermissionDenied and a recipe that does not exist or belongs to another tenant with NOT_FOUND, each with no output and no event written; ListGeneratedOutputs compares the path projectId with the project of the trusted scope, returns for an equal id the provenance of the generated modules by commit, an empty list when nothing is recorded, and answers 404 for every other id; LinkCommit sets proposal id and commit on the outputs of the run a merged change proposal names, idempotently on the event id. | ConnectSoft.AI.SoftwareFactory.GenerationRecipeService |
AIFACTORY-TASK-2743 Verify serve-the-approved-recipe-and-record-generated-outputs through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-GenerationRecipeService-006\|Scenario=SCN-GenerationRecipeService-007\|Scenario=SCN-GenerationRecipeService-008\|Scenario=SCN-GenerationRecipeService-012)"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-687: the read of the approved recipe with its refusals, the recorded output under the workload token of a ToolAdapterService fixture for the tool record-generated-output with its repeat on the same run, recipe and change set hash and its refusals, among them Unauthenticated without a workload identity, PermissionDenied without factory.recipes.write and NOT_FOUND for an unknown recipe and for a recipe of another tenant, each leaving no output and no event, the list by project with the empty list of a project without outputs and the 404 for every path projectId other than the project of the trusted scope, the commit linked from a fixture event of a merged change proposal and the publication and payload of GeneratedOutputRecorded; consumer handling is proven by the suites of the consumers. |
ConnectSoft.AI.SoftwareFactory.GenerationRecipeService |
AIFACTORY-US-688: Move a recipe to Executing on the first recorded output of its run, to Generated when the run completes and back to Approved when it fails or is cancelled¶
behavior
The end of the generation run settles the recipe. The trigger RunSubmitted of the transition from Approved to Executing is the first Recipes.RecordOutput of a run for the recipe (D123): the accepted run is not consumed and carries no recipe, and Recipes.RecordOutput is the one call that names both a run and a recipe. The first recorded output of a run for an Approved recipe applies RunSubmitted in the transaction of that output, and the recipe is Executing from then on. The service makes no call to RunControlService, although the model lists it as a required dependency for generation runs: the run is submitted by the readiness correlation of WorkflowEngineService and its end is heard through the inbox. When RunControlService announces RunCompleted, the handler CompleteGeneration finds the recipe that is Executing for that run by the run id of its generated outputs, moves it to Generated through RunCompleted and writes GenerationCompleted in the same transaction, with recipe id, version, tenant, project, run id, the number of modules whose provenance is recorded and the proposal ids known for those outputs, an empty list when none is known yet. In practice the list is empty at completion: the only modelled input that gives this service a proposal id is the handler LinkCommit, which hears a merged change proposal, and a merge follows the end of the run. No modelled input names a proposal before the run completes, so proposalIds of the event cannot be filled as its name promises; this is reported to the owner. GenerationCompleted is also the audit evidence of the completion, since AuditService consumes it. When RunControlService announces RunFailed, the handler RevertToApproved moves the recipe that is Executing for that run back to Approved through RunFailed; the recorded outputs of the failed run stay as provenance, nothing is published, and the recipe can be executed by a new run. When RunControlService announces RunCancelled, the same handler RevertToApproved returns the recipe that is Executing for that run to Approved through RunCancelled, as it does for a failed run (D123): the recorded outputs of the cancelled run stay as provenance, nothing is published, and the recipe can be executed by a new run. A run that ends before it recorded an output never moved the recipe, which is therefore still Approved, the result the model states for a failed and for a cancelled run. Both handlers are idempotent on the event id and act only inside the tenant of the envelope; an event for a run that no recipe of the tenant is Executing for is acknowledged without an effect, because most runs are not generation runs. The outbox publishes GenerationCompleted under the run event envelope; WorkflowEngineService, AuditService, StudioBff, DashboardService, FleetRolloutService and RepositoryIntelligenceService consume it in their own PBIs and increments. The service decides no approval and repeats no write on its own.
Acceptance criteria
| AC1 | Given an Approved GenerationRecipeService/GenerationRecipe and the first recorded GenerationRecipeService/GeneratedOutput of a run for it, when the output is committed, then the recipe is Executing through RunSubmitted in the same transaction, because the first Recipes.RecordOutput of a run for the recipe is that trigger, and a later output of the same run changes no state (model/services/template-library/GenerationRecipeService.yaml). |
| AC2 | Given a recipe that is Executing for a run and RunControlService/RunCompleted for that run, when CompleteGeneration handles it, then the recipe moves to Generated and GenerationRecipeService/GenerationCompleted is written in the same transaction with recipeId, version, tenantId, projectId, runId, the number of modules recorded and the known proposalIds, an empty list when no merged change proposal was heard before the completion, which is the usual case; a second delivery of the same event id and an event for a run no recipe is Executing for change nothing (SCN-GenerationRecipeService-011). |
| AC3 | Given a recipe that is Executing for a run and RunControlService/RunFailed or RunControlService/RunCancelled for that run, when RevertToApproved handles it, then the recipe returns to Approved through RunFailed or through RunCancelled respectively, the outputs of the run stay recorded, nothing is published, a second delivery of the same event id changes nothing, and a recipe whose run failed or was cancelled before its first output is still Approved (model/services/template-library/GenerationRecipeService.yaml). |
| AC4 | Given the completion was committed, when the outbox dispatcher publishes GenerationRecipeService/GenerationCompleted on generation.recipes.v1.generation-completed, then the event is sent under the run event envelope with the payload of AC2, and a transport outage is retried with backoff so the event is neither lost nor duplicated under its event id (SCN-GenerationRecipeService-011, ADR-0012). |
| Traces: services | GenerationRecipeService, RunControlService, WorkflowEngineService |
| Traces: aggregates | GenerationRecipeService/GenerationRecipe, GenerationRecipeService/GeneratedOutput |
| Traces: events | GenerationRecipeService/GenerationCompleted, RunControlService/RunCompleted, RunControlService/RunFailed, RunControlService/RunCancelled |
| Traces: adrs | ADR-0012, ADR-0014, ADR-0027 |
| Traces: requirements | FR-03 |
| Traces: scenarios | SCN-GenerationRecipeService-011 |
| Relates: nfrs | NFR-05 |
| Depends on | AIFACTORY-US-687, feature:run-control-service |
| Sources | model/services/template-library/GenerationRecipeService.yaml, model/services/control-plane/RunControlService.yaml, docs/solution-packs/software-factory/templates/services/generation-recipe-service/index.md#sagas-and-long-running-flows |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-2744 RunSubmitted on the first recorded output, and the CompleteGeneration and RevertToApproved inbox handlers |
implementation | The first GeneratedOutput of a run for an Approved recipe applies RunSubmitted in its transaction; CompleteGeneration finds the Executing recipe of a completed run by the run id of its outputs, applies RunCompleted and writes GenerationCompleted with the module count and the known proposal ids in the same transaction; RevertToApproved applies RunFailed to the Executing recipe of a failed run and RunCancelled to the Executing recipe of a cancelled run and keeps its outputs in both cases; both handlers are idempotent on the event id and ignore a run that no recipe of the tenant is Executing for. | ConnectSoft.AI.SoftwareFactory.GenerationRecipeService |
AIFACTORY-TASK-2745 Verify complete-or-revert-a-generation through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&Scenario=SCN-GenerationRecipeService-011"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-688 with the completed, the failed and the cancelled run delivered as events under the run event envelope: the Executing state on the first output, the Generated state with the publication and payload of GenerationCompleted, the return to Approved with the outputs kept after RunFailed and after RunCancelled, and the duplicate and the unrelated run that change nothing; consumer handling is proven by the suites of the consumers. |
ConnectSoft.AI.SoftwareFactory.GenerationRecipeService |