Skip to content

AIFACTORY-FEAT-082: BlueprintService: 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 80 of 185 (Factory code)

BlueprintService is the service of bounded context BC-02 (Blueprint). Blueprint versions as typed descriptor documents validated against their JSON Schemas and rule sets, with derived context maps and domain models, validation reports with rule ids, and submission of a validated blueprint to Asset Publication (BC-02; parser, validator, context-map and domain-model rows merged). Its own repository is ConnectSoft.AI.SoftwareFactory.BlueprintService.

Delivers BlueprintService (complete)
Stubs —
Realizes adrs: ADR-0021
Requirements FR-02, FR-03, FUX-01, FUX-03, NFR-11, XL-07
Depends on —
Sources model/services/template-library/BlueprintService.yaml

Scenarios to trace (13, catalog): SCN-BlueprintService-001 ✓, SCN-BlueprintService-002 ✓, SCN-BlueprintService-003 ✓, SCN-BlueprintService-004 ✓, SCN-BlueprintService-005 ✓, SCN-BlueprintService-006 ✓, SCN-BlueprintService-007 ✓, SCN-BlueprintService-008 ✓, SCN-BlueprintService-009 ✓, SCN-BlueprintService-010 ✓, SCN-BlueprintService-011 ✓, SCN-BlueprintService-012 ✓, SCN-BlueprintService-013 ✓

AIFACTORY-US-008: A blueprint draft is submitted and validated with a receipt

behavior · persona requester As a requester, I want every blueprint the Factory drafts to be stored as a version and validated against its schema and rules, so that later steps only ever build on a blueprint that passed validation.

This is the integration PBI of the feature: it proves that the behaviour PBIs of BlueprintService compose into the chain the first outcome needs, on one deployed instance of the service. A run of vision-to-blueprint drafts a Vision Blueprint. Its step submit-version calls the tool blueprint-submit-version, which ToolAdapterService executes after the policy decision of the project: allow runs the call, allow-with-approval waits for an approval that RunControlService opens and decides, and a Draft version is autonomous by default (D64). The call reaches Blueprints.SubmitDraftVersion with a workload token and the scope of the run. The service stores the document in ArtifactService by reference and hash and keeps a Draft BlueprintVersion for the project, once per document hash (AIFACTORY-US-674). The step validate calls blueprint-validate, which reaches Blueprints.Validate: the service validates the version against the JSON Schema and the rule set of its kind, stores the report as an artifact, returns a blueprint-validation-receipt-v1 and writes BlueprintValidated with passed true or false in the transaction of the verdict; it moves the version from Draft to Validated itself and only for the exact document hash that passed (AIFACTORY-US-676). For a Module Blueprint the rule MOD-002 is evaluated against the manifest of the pinned template version, which the service reads from TemplateRegistryService (D123). A failed receipt leaves the version Draft; the workflow returns the findings to the drafting step at most twice, and the redrafted document replaces the Draft document of the same blueprint id and version. For a Service or Module Blueprint that passed, the context map and the domain models are derived in the same transaction and announced by ContextMapDerived and DomainModelDerived (AIFACTORY-US-677). The step store-artifacts of the workflow that follows records lineage in ArtifactService and calls no operation of this service, so it is traced by the PBIs of the workflow and not here. A person reads the versions of the project and one version with its references (AIFACTORY-US-675), and an Asset maintainer submits a Validated version to Asset Publication (AIFACTORY-US-678). The service is scaffolded from the base template with the Factory profile (AIFACTORY-US-671), hosts its routes, its messaging profile and its worker (AIFACTORY-US-672) and enforces tenancy and the telemetry conventions (AIFACTORY-US-673). It never decides an approval, never retries a write on its own and never marks a version Published by itself. One limit of this increment is stated here and not hidden. The publication path of AgentRegistryService arrives in I2 with feature agent-registry-service-publication (D140), but its handler OpenReleaseCandidate, which opens the candidate of a blueprint from BlueprintSubmitted, arrives with feature agent-registry-service-complete in I4, so on a deployed instance a Submitted version stays Submitted and no BlueprintPublished is published before I4; the two handlers of the release events are built and proven on event fixtures. Until that gate the Draft allowance applies (D123): a generation recipe may bind the Submitted version, which GenerationRecipeService hears through BlueprintSubmitted. A person reaches the REST operations through the gateway TemplateCatalogHost, which feature template-catalog-host delivers in this increment; that feature depends on this one, so this feature states the route in words and does not depend on it. Repository: ConnectSoft.AI.SoftwareFactory.BlueprintService.

Acceptance criteria

AC1 Given a Vision Blueprint document, a document of the kind blueprint-vision-v1, produced in a run and the allow decision of the project policy, when the tool blueprint-submit-version reaches BlueprintService/Blueprints.SubmitDraftVersion in the step vision-to-blueprint/submit-version, then a Draft BlueprintService/BlueprintVersion exists for the project of the run with documentRef and documentHash, the reply is blueprint-version-ref-v1, and submitting the same document again returns the same version and creates none (ADR-0026).
AC2 Given that version, when the tool blueprint-validate reaches BlueprintService/Blueprints.Validate in the step vision-to-blueprint/validate, then the reply is a blueprint-validation-receipt-v1 that records the document hash, the rule set version and the findings with their rule ids, the report is stored as an artifact, and BlueprintService/BlueprintValidated is written in the same transaction with passed true or false and the document hash (ADR-0026).
AC3 Given a receipt with passed false, when the workflow returns the findings to the drafting step, at most twice by the condition check-valid of model/workflows/vision-to-blueprint.yaml, and the redrafted document is submitted for the same blueprint id and version, then the version is still Draft and holds the new documentHash, a second call of BlueprintService/Blueprints.Validate returns a new receipt for that hash, and the service itself retries nothing.
AC4 Given a Service Blueprint version whose validation passed, when the transaction of the verdict commits, then the version is Validated, one BlueprintService/ContextMap and one BlueprintService/DomainModel per bounded context exist with their artifact references, BlueprintService/ContextMapDerived and BlueprintService/DomainModelDerived are in the outbox of that transaction, and BlueprintService/GetBlueprintVersion shows the report, the context map and the domain model references.
AC5 Given a Validated version and an Asset maintainer, when the version is submitted to Asset Publication, then it is Submitted and stays Submitted on a deployed instance of this increment, because no service publishes the release event of a blueprint before the handler OpenReleaseCandidate of AgentRegistryService opens its candidate in I4, although the publication path of AgentRegistryService arrives in I2 (D140), and the version becomes Published only through the handler of that event, as the state diagram of docs/solution-packs/software-factory/templates/services/blueprint-service/index.md shows.
Traces: services BlueprintService, ArtifactService, ToolAdapterService
Traces: aggregates BlueprintService/BlueprintVersion, BlueprintService/ContextMap, BlueprintService/DomainModel
Traces: apis BlueprintService/Blueprints.SubmitDraftVersion, BlueprintService/Blueprints.Validate, BlueprintService/GetBlueprintVersion
Traces: events BlueprintService/BlueprintValidated, BlueprintService/ContextMapDerived, BlueprintService/DomainModelDerived
Traces: steps vision-to-blueprint/submit-version, vision-to-blueprint/validate
Traces: tools blueprint-submit-version, blueprint-validate
Traces: descriptors blueprint-vision-v1, blueprint-version-ref-v1, blueprint-validation-receipt-v1
Traces: adrs ADR-0021, ADR-0026
Depends on AIFACTORY-US-671, AIFACTORY-US-672, AIFACTORY-US-673, AIFACTORY-US-674, AIFACTORY-US-675, AIFACTORY-US-676, AIFACTORY-US-677, AIFACTORY-US-678, feature:artifact-service, feature:tool-adapter-service, feature:template-registry-service, feature:local-development-environment
Sources model/services/template-library/BlueprintService.yaml, model/workflows/vision-to-blueprint.yaml, model/tools/blueprint-submit-version.yaml, model/tools/blueprint-validate.yaml, docs/architecture/adr/0026-requirements-to-ux-handoff.md, docs/solution-packs/software-factory/templates/services/blueprint-service/index.md#sagas-and-long-running-flows

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-2701 Deployment values of BlueprintService: replica range, secret reference, dependency addresses and the schema registry path 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 ArtifactService and of TemplateRegistryService, the messaging service name blueprint and the value of Templates:Blueprints:SchemaRegistryPath with the registered blueprint schemas mounted read-only; the acceptance environment of feature local-development-environment starts the service with these values and its readiness answers ready. ConnectSoft.AI.SoftwareFactory.BlueprintService
AIFACTORY-TASK-786 Verify blueprint-validated by running the chain test of the acceptance suite verification Run dotnet test -c Release --filter "Category=Acceptance&Chain=blueprint-validated"; a zero-match filter counts as a failure; one test drives a Vision document and a Service Blueprint document through submission, a failed and a passed validation, the derivation, the reads and the submission to Asset Publication against fakes of ArtifactService and of the transport, and proves AC1 to AC5 of AIFACTORY-US-008. ConnectSoft.AI.SoftwareFactory.BlueprintService

AIFACTORY-US-671: BlueprintService repository: scaffolded from the base template with the Factory profile, with its three aggregates and the store blueprint-sql

enabling The repository ConnectSoft.AI.SoftwareFactory.BlueprintService is created and scaffolded in I0 by AIFACTORY-TASK-118 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.BlueprintService --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 descriptors blueprint-common-v1, blueprint-version-ref-v1 and blueprint-validation-receipt-v1 come from the contracts package by a version pin. On that scaffold this PBI adds the domain and the store. The BlueprintVersion is one version of one blueprint document of one of the 22 kinds of BlueprintKind for a project, identified by blueprint id and version: schema version, the reference and the hash of the document, state, the reference of the validation report with its ValidationFinding entities (rule id, severity, path, message), the references of the derived context map and domain model, the release id and the author, a user or a run. It has exactly five transitions: Draft to Validated (ValidationPassed), Validated to Draft (DocumentChanged), Validated to Submitted (SubmitForPublication), Submitted to Published (AssetReleasePublished) and Published to Deprecated (AssetReleaseDeprecated). It is Validated only for the document hash that passed the schema and every rule of its kind, and no command of the service moves it to Published. The ContextMap holds the bounded contexts, their relationships and the published-language events derived from one blueprint version; it is derived and never edited. The DomainModel holds the aggregates and events of one bounded context; every aggregate has a root entity, an identity and at least one invariant, and every event names its aggregate. The store blueprint-sql is owned by this service alone (ADR-0028 decision 5). This PBI migrates its four tables, BlueprintVersions, ValidationFindings, ContextMaps and DomainModels, with the columns and indexes of the model and the tenant row filter of the Factory profile in every mapping. The keys lead with the tenant, as the model lists them (D123): the primary keys of BlueprintVersions and ValidationFindings and the unique indexes UX_ContextMaps_Blueprint and UX_DomainModels_Blueprint_Context start with TenantId, because the blueprint id comes from the metadata of a document that a tenant writes. A blueprint id and version are therefore unique inside a tenant and never across tenants: a document of one tenant never collides with a version of another tenant that the row filter hides, and no refusal confirms that a foreign version exists (ADR-0015 amendment D113). The document, the report and the derived models as documents live in ArtifactService; the tables keep references and hashes. 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-118 of feature repository-and-pipeline-conventions with dotnet new connectsoft-base -n ConnectSoft.AI.SoftwareFactory.BlueprintService --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 BlueprintService/BlueprintVersion, BlueprintService/ContextMap and BlueprintService/DomainModel aggregates, when their unit tests run, then the version accepts exactly the five transitions of model/services/template-library/BlueprintService.yaml and refuses every other one, a move to Published or Deprecated by a command of the service among them; ValidationPassed is accepted only for the document hash the version holds; DocumentChanged returns a Validated version to Draft and clears the report and the derived references; a context map cannot be edited after it was derived; and a domain model whose aggregate lacks a root entity, an identity or an invariant, or whose event names no aggregate, is refused.
AC3 Given blueprint-sql created by the migrations of the repository on an isolated test database, when the mapping tests run, then the four tables exist with their keys, the index IX_Blueprints_Project_Kind and the unique indexes UX_ContextMaps_Blueprint and UX_DomainModels_Blueprint_Context, a second context map for one blueprint version and a second domain model for one version and context of one tenant each violate their unique index, one blueprint id and version can be stored for two tenants because the tenant leads the two keys and the two unique indexes, as model/services/template-library/BlueprintService.yaml lists them, a query made for one tenant never returns a row of another, and BlueprintVersions holds the reference and the hash of a document and has no column for its content (ADR-0015, model/stores.yaml).
Traces: services BlueprintService
Traces: aggregates BlueprintService/BlueprintVersion, BlueprintService/ContextMap, BlueprintService/DomainModel
Traces: descriptors blueprint-common-v1, blueprint-version-ref-v1, blueprint-validation-receipt-v1
Traces: adrs ADR-0015, 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/BlueprintService.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/blueprint-service/index.md#domain-model, docs/solution-packs/software-factory/templates/services/blueprint-service/ddl.md

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-119 Domain model: BlueprintVersion with ValidationFinding, ContextMap, DomainModel implementation The three aggregates and the ValidationFinding entity enforce the invariants of the model as it words them; the BlueprintVersion accepts only ValidationPassed out of Draft, DocumentChanged and SubmitForPublication out of Validated, AssetReleasePublished out of Submitted and AssetReleaseDeprecated out of Published, and accepts ValidationPassed only for the document hash it holds; the ContextMap is immutable after derivation; unit tests cover every invariant, each of the five transitions and the refusal of every other one. ConnectSoft.AI.SoftwareFactory.BlueprintService
AIFACTORY-TASK-120 Persistence in blueprint-sql: BlueprintVersions, ValidationFindings, ContextMaps, DomainModels migration Mappings and migrations for the four tables with the columns the model lists, the index IX_Blueprints_Project_Kind, the unique indexes UX_ContextMaps_Blueprint and UX_DomainModels_Blueprint_Context and the tenant filter in every mapping; the tenant is the leading column of the keys of BlueprintVersions and ValidationFindings and of the two unique indexes, as the model lists them; mapping tests run against an isolated test database, never a shared one. ConnectSoft.AI.SoftwareFactory.BlueprintService
AIFACTORY-TASK-2702 Verify the scaffold, the aggregates and the store of BlueprintService 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 three 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-671 (ADR-0028). ConnectSoft.AI.SoftwareFactory.BlueprintService

AIFACTORY-US-672: BlueprintService host: five REST routes and three gRPC methods behind scope policies, the blueprint messaging profile with three subscriptions and the hosted Validator

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 five REST operations of the model for its platform gateway and the internal gRPC service Blueprints with the methods SubmitDraftVersion, Validate and GetDerivedModel, 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.blueprints.read for ListBlueprints and GetBlueprintVersion, factory.blueprints.write for CreateBlueprintVersion and ValidateBlueprint, factory.blueprints.publish for SubmitBlueprint. 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.blueprints.write for SubmitDraftVersion and Validate and factory.blueprints.read for GetDerivedModel. The project of a project-scoped call is named by the caller (D123): ListBlueprints takes the required query parameter projectId and CreateBlueprintVersion 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 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, 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 CreateBlueprintVersion: 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 blueprint, 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 five modelled events on their topics under the run event envelope of the pinned contracts package. The inbox registers the three consumed events of the model, the published and the deprecated asset release of AgentRegistryService and ArtifactValidated of ArtifactService, idempotently on the event id. The Validator is hosted with its modelled trigger, its retry of three attempts 30 s apart, its idempotency key of blueprint id, version and document hash and at most four parallel executions 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 five REST operations of model/services/template-library/BlueprintService.yaml with their paths, scopes and response codes, the required query parameter projectId of ListBlueprints and the required body member projectId of CreateBlueprintVersion among them, the proto lists the service Blueprints with SubmitDraftVersion, Validate and GetDerivedModel, each with the scope the model gives it, and the reply messages map onto docs/reference/schemas/blueprint-version-ref.schema.json and docs/reference/schemas/blueprint-validation-receipt.schema.json.
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 ListBlueprints or CreateBlueprintVersion without projectId is answered 400 with a problem response (ADR-0015, model/services/template-library/BlueprintService.yaml).
AC3 Given the messaging profile blueprint, 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 a consumed event delivered twice under one event id reaches its handler once (ADR-0012, ADR-0014).
AC4 Given the hosted Validator, when its trigger is delivered twice for one blueprint id, version and document hash, then one execution has an effect, the worker runs at most four executions in parallel partitioned by project and makes at most three attempts 30 s apart; and the service is ready only after blueprint-sql is migrated, the messaging profile has started and the path of Templates:Blueprints:SchemaRegistryPath is readable, and it names what is missing while it is unready (model/services/template-library/BlueprintService.yaml).
Traces: services BlueprintService
Traces: descriptors run-event-envelope-v1, blueprint-version-ref-v1, blueprint-validation-receipt-v1
Traces: adrs ADR-0012, ADR-0014, ADR-0015, ADR-0028
Depends on AIFACTORY-US-671, feature:component-base-template-factory-profile, feature:contracts-package
Sources model/services/template-library/BlueprintService.yaml, model/descriptors.yaml, docs/reference/schemas/blueprint-version-ref.schema.json, docs/reference/schemas/blueprint-validation-receipt.schema.json, docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md, docs/solution-packs/software-factory/templates/services/blueprint-service/index.md#apis

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-121 API hosting skeleton: REST and gRPC hosts, scope policies, problem responses and contract documents for the 5 REST operations and 3 gRPC methods implementation The five REST routes and the three 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 CreateBlueprintVersion, and the OpenAPI and proto documents; the behaviour of each operation is delivered by AIFACTORY-US-674 to AIFACTORY-US-678, not here. ConnectSoft.AI.SoftwareFactory.BlueprintService
AIFACTORY-TASK-122 Messaging skeleton: outbox and inbox wiring of the blueprint profile for 5 published and 3 consumed events implementation The outbox writer enlists in the transaction of the command and the dispatcher of the blueprint messaging profile publishes BlueprintValidated, BlueprintSubmitted, BlueprintPublished, ContextMapDerived and DomainModelDerived on their topics under the run event envelope of the pinned contracts package; the inbox registers AssetReleasePublished, AssetReleaseDeprecated and ArtifactValidated with idempotency on the event id; what each handler does is delivered by AIFACTORY-US-676 and AIFACTORY-US-678. ConnectSoft.AI.SoftwareFactory.BlueprintService
AIFACTORY-TASK-123 Worker hosting skeleton: trigger, partitioning and retry policy of the Validator implementation The Validator is hosted with its event trigger, the fixed retry of three attempts with 30 s backoff, the idempotency key of blueprint id, version and document hash and at most four parallel executions partitioned by project; a duplicate trigger has no second effect; what the worker validates and derives is delivered by AIFACTORY-US-676 and AIFACTORY-US-677. ConnectSoft.AI.SoftwareFactory.BlueprintService
AIFACTORY-TASK-2703 Verify the hosted surface of BlueprintService verification Run the contract, authorization, messaging and readiness tests of the repository pipeline; they prove AC1 to AC4 of AIFACTORY-US-672: the OpenAPI document and the proto match model/services/template-library/BlueprintService.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 the Validator has one effect. ConnectSoft.AI.SoftwareFactory.BlueprintService

AIFACTORY-US-673: BlueprintService filters every query by tenant, answers a foreign version as not found, starts only with its transport secret reference and keeps blueprint content out of telemetry

enabling Tenancy is enforced in the service and not only at the gateway. Every query of the four tables of blueprint-sql runs under the tenant row filter of the Factory profile. The tenant and project of a user call come from the trusted scope of the forwarded token; the tenant and project 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 version, a context map or a domain model 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, and never confirms that it exists (ADR-0015 amendment D113); a missing scope 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 ListBlueprints and in the body member projectId of CreateBlueprintVersion (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 version is never written or listed for another project than the one the gateway admitted. A document whose metadata names another project than that scope is refused. The blueprint id of a version comes from the metadata of its document, so two tenants can choose the same id. The keys of the store lead with the tenant (AIFACTORY-US-671), so a blueprint id and version that another tenant already holds are free for the caller: the document is stored as a Draft version of the tenant of the caller with the ordinary answer, and the version of the other tenant is neither changed nor revealed by any answer. 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 blueprint content stays out of telemetry: no log record, activity, metric or event carries a document, a finding message or the content of a derived model; events and logs carry ids, references, hashes, kinds, states and rule ids (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 three metrics of the model are recorded with their modelled dimensions: connectsoft.factory.blueprints.versions by tenant, kind and state on every state change, connectsoft.factory.blueprints.validation_failures by kind and rule id, and connectsoft.factory.blueprints.inbox_lag as the age of the oldest unprocessed inbox message. Health checks cover the store, the messaging profile and the schema registry path. A runbook records the two failure modes of the model: a schema of a kind that is missing or stale, which fails validation with the schema id until the descriptor registry is corrected, 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 blueprint version each, when a caller of the first tenant addresses the version of the second through every REST route and every gRPC method that takes a version, then each answer is 404 or the gRPC status NOT_FOUND, the same answer as for an id that does not exist, no list contains a row of the other tenant, and a caller of the right tenant without the scope is answered 403 or PERMISSION_DENIED (ADR-0015).
AC2 Given a call of ListBlueprints or CreateBlueprintVersion without projectId, a call whose projectId differs from the project of the trusted scope, or a write through either store operation whose document names another project than the project of the trusted scope, when it arrives, then the first is answered 400, the second 403 and the third 422 or InvalidArgument, each REST refusal with a problem response, and nothing is stored or listed for a project the gateway did not admit (ADR-0015, model/services/template-library/BlueprintService.yaml).
AC3 Given deployment values without the key vault reference of the secret messaging-transport that model/services/template-library/BlueprintService.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 stores, validations and reads of the fixture, when telemetry is collected, then connectsoft.factory.blueprints.versions, connectsoft.factory.blueprints.validation_failures and connectsoft.factory.blueprints.inbox_lag are recorded with the dimensions of model/services/template-library/BlueprintService.yaml, run, step and attempt appear on activities and log records only, and no log record, activity, metric or event holds document content, a finding message or the content of a derived model (ADR-0019).
AC5 Given the fixture in which the second tenant holds a BlueprintService/BlueprintVersion with a blueprint id and version that the first tenant does not hold, when a caller of the first tenant stores a document with that same blueprint id and version through either store operation and then reads, validates and submits it, then the document is stored as a Draft version of the first tenant with the ordinary answer of the operation, every later answer concerns the version of the first tenant alone, the version of the second tenant keeps its document, state and findings, and no answer, problem response, log record or event of the first tenant reveals that the second version exists (ADR-0015).
Traces: services BlueprintService
Traces: aggregates BlueprintService/BlueprintVersion
Traces: adrs ADR-0015, ADR-0019
Traces: requirements FUX-01
Depends on AIFACTORY-US-672, feature:component-observability-factory-conventions, feature:local-development-environment
Sources model/services/template-library/BlueprintService.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/blueprint-service/index.md#failure-and-recovery

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-124 Security, tenancy and telemetry of BlueprintService implementation The tenant row filter is on every query of the four tables, the tenant and project of a user call come from the trusted scope, the projectId a caller names in ListBlueprints or CreateBlueprintVersion 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 403 or PERMISSION_DENIED, the transport credential comes from its key vault reference, the three metrics carry the dimensions of the model, activities and log records carry run, step and attempt, and no telemetry holds blueprint content. ConnectSoft.AI.SoftwareFactory.BlueprintService
AIFACTORY-TASK-2704 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 and a workload identity with the service scopes, and one blueprint version per tenant, so that every scenario of the feature can be run once inside a tenant and once across tenants; it also holds a document for the first tenant whose blueprint id and version equal those of the version of the second tenant, for the collision case of AC5 of AIFACTORY-US-673; the fixture uses an isolated test database and the test authority of the local environment. ConnectSoft.AI.SoftwareFactory.BlueprintService
AIFACTORY-TASK-2705 Runbook of the two failure modes of BlueprintService documentation The repository documentation holds a runbook for the schema of a kind that is missing or stale (detection by the finding that names the schema id, correction of the descriptor registry, validation run again) and for the loss of the store (detection by readiness, restore within the recovery point of model/stores.yaml, documents and reports still held by ArtifactService). ConnectSoft.AI.SoftwareFactory.BlueprintService
AIFACTORY-TASK-2706 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 AC5 of AIFACTORY-US-673: a foreign version is answered 404 or NOT_FOUND on every operation, a call without projectId is answered 400 and a projectId other than the project of the trusted scope 403, a document of another project is refused, a document whose blueprint id and version another tenant already holds is stored for the tenant of the caller without touching or revealing the foreign version, 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 document (ADR-0015, ADR-0019). ConnectSoft.AI.SoftwareFactory.BlueprintService

AIFACTORY-US-674: Store a blueprint document as a Draft version, by a person through CreateBlueprintVersion and by a run through Blueprints.SubmitDraftVersion, once per document hash

behavior · persona requester As a requester, I want a blueprint document that I or a run of my project wrote to be kept as a Draft version of its kind, so that the project has one addressable version of every blueprint that validation and generation can refer to.

A blueprint enters the service as a document of one of the 22 kinds and becomes a Draft BlueprintVersion. Two callers store one. A person, Requester or Asset maintainer, calls CreateBlueprintVersion with a user token that carries factory.blueprints.write, forwarded by the gateway, the required body member projectId and an Idempotency-Key. A call without projectId is answered 400; the gateway answers 403 for a project the roles of the token do not grant, and the service compares the member with the project of the trusted scope and answers 403 when the two differ (D123). A run calls Blueprints.SubmitDraftVersion through ToolAdapterService, which executes the tool blueprint-submit-version for a step with a workload token that holds the service scope and with the scope of the run. The tool is a shared write under the policy of the project (D64): whether the call needs an approval is decided by the policy decision that ToolAdapterService obtains before it calls; allow runs the call, allow-with-approval waits for an approval that RunControlService opens and decides, and by default a Draft version is autonomous. BlueprintService evaluates no policy, opens and decides no approval and never repeats a write on its own. Both operations do the same thing. The service checks the common metadata of the document against blueprint-common-v1: blueprint id, kind, version, schema version, project, title, status and author. The kind must be a value of BlueprintKind and the project must be the project of the trusted scope. It stores the document through Artifacts.Store of ArtifactService, which is idempotent on tenant and hash, and writes the version in state Draft with documentRef, documentHash and authoredBy: the user of the token, or the run, flagged with its run and attempt. The REST answer is 201 with the version reference; the gRPC reply is blueprint-version-ref-v1. The model names no result event for the command, so no integration event of the service is published; connectsoft.factory.blueprints.versions counts the new 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 to the outbox in the transaction of the command, on the topic audit.evidence.v1.evidence-submitted under the run event envelope, with the actor, that is the user or the run and its attempt, the blueprint id, the version, the kind and the document hash. The record is written when a version is created and also when a document replaces the document of an existing version; a rolled back command leaves none, and an idempotent repeat, which changes nothing, writes no second one. A repeated REST call with the same key returns the same result, and the same document for the same blueprint id and version returns the existing version under any key, because submission is naturally idempotent on the document hash. A document that fails the metadata check is refused with 422; over gRPC an invalid body is InvalidArgument. The same key with another document is a conflict by ADR-0014 decision 3 and is answered 409 (D123). When a document with another hash arrives for a blueprint id and version that already exist in the tenant, which is the redraft after a failed validation, a Draft version takes the new document, a Validated version takes it and returns to Draft through DocumentChanged with its report and derived references cleared, and a Submitted, Published or Deprecated version keeps its document, because a submitted document no longer changes. That last refusal is a state conflict; it is answered 409 on REST and FailedPrecondition over gRPC (D123). The model names the transition DocumentChanged and not the operation that raises it; that the two store operations raise it is a reading reported to the owner. A blueprint id and version that only another tenant holds are no conflict: the keys lead with the tenant, the document becomes a Draft version of the tenant of the caller and the foreign version is never revealed (AIFACTORY-US-671, AIFACTORY-US-673). The summary of CreateBlueprintVersion in the model also names agents, through the write-file and propose-change-set tools under their run. Since ADR-0026 and D64 a run stores a document only through blueprint-submit-version and Blueprints.SubmitDraftVersion; the two older tools belong to ToolAdapterService and have no modelled route to this service, so that agent path is not built here and is reported as a stale summary. ArtifactService is a required dependency that fails fast: when it does not answer, the call ends with 503 and a problem response, or with the gRPC status Unavailable, and nothing is written (D123). When the reply to a tool call is lost, the outcome of the step is Uncertain and goes to the Operator decision of RunControlService; a repeat with the same document returns the same version, so the effect can be observed.

Acceptance criteria

AC1 Given a caller whose forwarded user token carries factory.blueprints.write for the project of the trusted scope and a document whose metadata is valid against blueprint-common-v1, names one of the 22 kinds and names that project, when BlueprintService/CreateBlueprintVersion is called with the body member projectId of that project and an Idempotency-Key, then the document is stored through ArtifactService/Artifacts.Store, a BlueprintService/BlueprintVersion is written in state Draft with documentRef, documentHash and the caller as authoredBy, the response is 201 with the version reference, no integration event of the service is published, because the model names none for this command, and one audit-evidence-v1 record with the caller as actor, the blueprint id, the version, the kind and the document hash 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-BlueprintService-003).
AC2 Given the same request repeated with the same Idempotency-Key, the same document posted under another key, the same key with another document, a body without projectId, a projectId that differs from the project of the trusted scope, a document with invalid metadata, an unknown kind or the project of another scope, or a caller without factory.blueprints.write, when it arrives at BlueprintService/CreateBlueprintVersion, then the first two return the existing version, create none and write no second evidence record, the reused key with another document, a conflict by ADR-0014 decision 3, is answered 409, the missing projectId 400, the differing projectId 403, the invalid document 422 and the missing scope 403, each refusal with a problem response, no state change and no evidence record (SCN-BlueprintService-003, ADR-0015).
AC3 Given ToolAdapterService executing the tool blueprint-submit-version for a step of a run, after the policy decision of the project allowed the call or its approval was decided in RunControlService, when it calls BlueprintService/Blueprints.SubmitDraftVersion with a workload token that holds factory.blueprints.write and the scope of the run, then the document is stored once, the version is Draft with the run as authoredBy and its run and attempt recorded, the reply is blueprint-version-ref-v1 with blueprint id, version, kind, document hash, state, tenant and project, one audit-evidence-v1 record with the run and its attempt as actor, the blueprint id, the version, the kind and the document hash is written to the outbox in the same transaction, and a second call with the same document hash returns the same version, creates none and writes no second record (SCN-BlueprintService-006, ADR-0026).
AC4 Given a call of BlueprintService/Blueprints.SubmitDraftVersion without a workload identity, without the service scope, or with a body that is no document of a blueprint kind or names another project than the forwarded scope, when it arrives, then it is refused with Unauthenticated, PermissionDenied or InvalidArgument respectively and nothing is stored; and given ArtifactService does not answer either store operation, then the REST call ends with 503 and a problem response and the gRPC call with Unavailable, nothing is written, no evidence record exists and the service retries nothing (SCN-BlueprintService-003, SCN-BlueprintService-006).
AC5 Given a document with another hash for a blueprint id and version that already exist in the tenant of the caller, when it is stored through either operation, then a Draft version takes the new documentRef and documentHash, a Validated version does the same and returns to Draft through DocumentChanged with its report and derived references cleared, each replacement writes one audit-evidence-v1 record with the new document hash in its transaction, and a Submitted, Published or Deprecated version keeps its document: that state conflict is answered 409 on REST and FailedPrecondition over gRPC (the transition is listed in model/services/template-library/BlueprintService.yaml and names no operation, so the operation that raises it is a reading reported to the owner).
Traces: services BlueprintService, ArtifactService, ToolAdapterService, RunControlService
Traces: aggregates BlueprintService/BlueprintVersion
Traces: apis BlueprintService/CreateBlueprintVersion, BlueprintService/Blueprints.SubmitDraftVersion, ArtifactService/Artifacts.Store
Traces: steps vision-to-blueprint/submit-version
Traces: tools blueprint-submit-version
Traces: descriptors blueprint-common-v1, blueprint-version-ref-v1, artifact-v1, audit-evidence-v1, run-event-envelope-v1
Traces: adrs ADR-0014, ADR-0015, ADR-0026
Traces: requirements FR-03, FUX-01
Traces: scenarios SCN-BlueprintService-003, SCN-BlueprintService-006
Depends on AIFACTORY-US-672, AIFACTORY-US-673, feature:artifact-service, feature:tool-adapter-service, feature:component-audit-factory-evidence
Sources model/services/template-library/BlueprintService.yaml, model/services/knowledge/ArtifactService.yaml, model/tools/blueprint-submit-version.yaml, model/blueprints.yaml, docs/reference/schemas/blueprint-common.schema.json, docs/reference/schemas/blueprint-version-ref.schema.json, docs/reference/schemas/audit-evidence.schema.json, docs/architecture/adr/0014-run-and-lifecycle-envelopes.md, docs/architecture/adr/0026-requirements-to-ux-handoff.md

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-203 Versions, document hash and idempotent submission implementation CreateBlueprintVersion and Blueprints.SubmitDraftVersion check the common metadata, the kind and the project of the trusted scope, store the document through Artifacts.Store and write the Draft BlueprintVersion with documentRef, documentHash and authoredBy; the same document for the same blueprint id and version returns the existing version, a document with another hash replaces the document of a Draft or Validated version and returns a Validated version to Draft through DocumentChanged, and a Submitted, Published or Deprecated version is refused; every created version and every replaced document writes one audit-evidence-v1 record with the actor (user, or run and attempt), blueprint id, version, kind and document hash through the Factory sink of the pinned audit library to the outbox in the transaction of the command, on the topic audit.evidence.v1.evidence-submitted, and a repeat or a rolled back command writes none; CreateBlueprintVersion answers a body without projectId with 400 and a projectId that differs from the project of the trusted scope with 403; the reused key with another document and the state conflict are answered 409; the 400, 403, 409, 422 and 503 answers and the gRPC statuses Unauthenticated, PermissionDenied, InvalidArgument, FailedPrecondition and Unavailable are covered by acceptance tests. ConnectSoft.AI.SoftwareFactory.BlueprintService
AIFACTORY-TASK-2707 Contract of the stored document, the version reference and the two store operations contract The OpenAPI document of CreateBlueprintVersion and the proto of Blueprints.SubmitDraftVersion take a document of any blueprint kind of model/blueprints.yaml and refuse any other body, the body of CreateBlueprintVersion requires the member projectId beside the document, and their answers map onto docs/reference/schemas/blueprint-version-ref.schema.json with blueprint id, version, kind, document hash, state, tenant and project. ConnectSoft.AI.SoftwareFactory.BlueprintService
AIFACTORY-TASK-2708 Acceptance double of ArtifactService for store, fetch and outage fixture A test double answers Artifacts.Store idempotently on tenant and hash and Artifacts.Fetch by reference, records every call and can be switched to not answering, so the scenarios of AIFACTORY-US-674, AIFACTORY-US-676 and AIFACTORY-US-677 run without ArtifactService and prove the fail-fast branch of SCN-BlueprintService-003. ConnectSoft.AI.SoftwareFactory.BlueprintService
AIFACTORY-TASK-2709 Verify store-a-blueprint-draft-version through the acceptance suite verification Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-BlueprintService-003\|Scenario=SCN-BlueprintService-006)"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-674: the two store operations, the idempotent repeats by key and by document hash, the refusals, among them 400 without projectId, 403 for a projectId other than the project of the trusted scope and 409 for the reused key and for the state conflict, the replaced document with the DocumentChanged transition and the outage of ArtifactService answered 503 or Unavailable; they read the outbox and find one audit-evidence-v1 record per created version and per replaced document with its actor, blueprint id, version, kind and document hash, and none after a repeat, a refusal or a rolled back command; and on the two-tenant fixture of AIFACTORY-TASK-2704 a document whose blueprint id and version the other tenant holds becomes a Draft version of the tenant of the caller while the foreign version stays unchanged and unrevealed. ConnectSoft.AI.SoftwareFactory.BlueprintService

AIFACTORY-US-675: Read the blueprints of a project by kind and state, and one version with its document, report and derived model references

behavior · persona requester As a requester, I want to list the blueprints of my project and read one version with its state, its validation report and its derived models, so that I know which version of a blueprint the Factory holds and whether later steps may build on it.

A caller whose forwarded user token carries factory.blueprints.read reads the blueprints of a project. ListBlueprints takes the required query parameter projectId (D123) and returns the blueprints of that project, filtered by kind and by state, each with its versions, their kind, state, schema version, document hash and author. 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. GetBlueprintVersion returns one version addressed by blueprint id and version: state, kind, schema version, the reference and hash of the document, the reference of the validation report with its findings by rule id, severity, path and message, the references of the derived context map and domain model, the release id once the version is Published, the author and, for a version authored by a run, its run and attempt. A Draft version authored by a run is project scope like any other Draft: it is visible to the readers of the project and flagged by its authoring run (D64). The reads return references and hashes; the content of a document, a report or a derived model is fetched from ArtifactService by its reference under the scope of the reader and is never copied into an answer of this service. Both reads run under the tenant row filter. A caller without the scope is refused with 403. A blueprint id or version that does not exist and a version of another tenant are both answered 404 by GetBlueprintVersion, which never confirms that a foreign version exists (ADR-0015 amendment D113); ListBlueprints 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 that show blueprints are built by StudioBff in its own increment on these two operations; a person reaches both reads through the gateway TemplateCatalogHost, which is delivered in this increment (D123).

Acceptance criteria

AC1 Given a caller with factory.blueprints.read and versions of several kinds and states in the project of the trusted scope, some authored by a person and some by a run, when BlueprintService/ListBlueprints is called with the projectId of that project and a kind or a state filter, then the response is 200 with the blueprints of that project that match, each with its versions, kind, state and author, a Draft version authored by a run among them and flagged with its run, and nothing of another project or tenant (SCN-BlueprintService-001, ADR-0026).
AC2 Given a BlueprintService/BlueprintVersion of the tenant and project of the caller, when BlueprintService/GetBlueprintVersion is called, then the response is 200 with the state, the kind, the schema version, the reference and hash of the document, the validation report reference with its findings, the context map and domain model references, the release id once Published and the author, and the content of the document is not part of the answer (SCN-BlueprintService-002).
AC3 Given a caller without factory.blueprints.read, a call of BlueprintService/ListBlueprints without projectId or with a projectId that differs from the project of the trusted scope, a blueprint id or version that does not exist, or a version 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 BlueprintService/GetBlueprintVersion, 404 for the unknown and for the foreign version alike, each with a problem response, and nothing is written by any read (SCN-BlueprintService-001, SCN-BlueprintService-002, ADR-0015).
Traces: services BlueprintService
Traces: aggregates BlueprintService/BlueprintVersion
Traces: apis BlueprintService/ListBlueprints, BlueprintService/GetBlueprintVersion
Traces: adrs ADR-0015, ADR-0026
Traces: requirements FUX-01
Traces: scenarios SCN-BlueprintService-001, SCN-BlueprintService-002
Depends on AIFACTORY-US-672, AIFACTORY-US-673, AIFACTORY-US-674
Sources model/services/template-library/BlueprintService.yaml, docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md, docs/solution-packs/software-factory/templates/services/blueprint-service/index.md#apis

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-2710 ListBlueprints and GetBlueprintVersion over the versions of the trusted project under the tenant filter implementation ListBlueprints requires the query parameter projectId, answers 400 without it and 403 when it differs from the project of the trusted scope, and returns the blueprints of that project filtered by kind and state with their versions, and GetBlueprintVersion returns one version with the document reference and hash, the report reference with its findings, the derived references, the release id and the author with the run and attempt of a run-authored version; both apply the tenant row filter, a version of another tenant is answered 404 like an unknown one and a missing scope 403 (ADR-0015). ConnectSoft.AI.SoftwareFactory.BlueprintService
AIFACTORY-TASK-2711 Verify read-blueprints-and-versions through the acceptance suite verification Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-BlueprintService-001\|Scenario=SCN-BlueprintService-002)"; a zero-match filter counts as a failure; the tests prove AC1 to AC3 of AIFACTORY-US-675 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 version and the absence of document content in the answers among them. ConnectSoft.AI.SoftwareFactory.BlueprintService

AIFACTORY-US-676: Validate a blueprint version against the schema and the rule set of its kind, return a receipt and announce the verdict

behavior · persona requester As a requester, I want every blueprint version to be validated against the schema and the rules of its kind with a receipt that names each finding, so that a version is Validated only for the exact document that passed and a failed one tells its author what to fix.

Validation is an operation with a receipt (ADR-0026 decision 5). A person with factory.blueprints.write calls ValidateBlueprint for a version of the tenant and project of the caller; a run calls Blueprints.Validate through ToolAdapterService, which executes the sandbox-class tool blueprint-validate with a blueprint-version-ref-v1, a workload token that holds the service scope and the scope of the run. Both run the same routine, the Validator. It reads the document through Artifacts.Fetch of ArtifactService and checks that its hash is the documentHash of the version. It validates the common metadata, then the JSON Schema of the kind at the schema version the document names, resolved under Templates:Blueprints:SchemaRegistryPath, then every rule of the rule set of the kind in model/blueprints.yaml. Each violation is a ValidationFinding with rule id, severity error, warning or info, path and message; warnings fail the validation only when Templates:Blueprints:FailOnWarnings is true. A schema version the registry cannot resolve fails the validation with a finding that names the schema id, the failure mode the model states. One rule needs another service. MOD-002, template switches used are declared by the pinned template version, needs the manifest of that template version, which TemplateRegistryService holds. BlueprintService depends on that service as a required dependency that fails fast (D123): for a Module Blueprint the validator reads the manifest of the pinned template version through Catalog.ResolveManifest with the workload identity of the service and evaluates the rule itself, with one finding of rule id MOD-002 and severity error for every switch the document uses and the manifest does not declare. Until the evaluation gate of AgentRegistryService is delivered in I4 the registry serves the manifest of a version the catalog has discovered that is not yet Published, so the rule is evaluated on a deployed instance of this increment. A pinned template version that the registry answers as not found fails the rule with a finding that names the template id and version, a reading of this PBI reported to the owner. While the registry does not answer, ValidateBlueprint answers 503 for a Module Blueprint and the version stays as it was; a version of any other kind is validated without a call to the registry. The invariant of the model therefore holds for every kind: a blueprint is Validated only when its document passes every rule of the rule set of its kind. Every other rule is evaluated from the document, from the versions and derived models this service holds and from artifacts of ArtifactService; where the wording of a rule names another platform, as AGM-003 does for registered MCP servers and DB-003 for the store catalog, the validator checks what the document declares and calls no other service, a reading that is reported as well. UX-006 is marked by model/blueprints.yaml itself as a workflow gate and not a rule of BlueprintService, so the validator does not evaluate it and writes no finding for it. The report is stored as an artifact through Artifacts.Store, the findings are kept with the version, and the receipt blueprint-validation-receipt-v1 carries receipt id, blueprint id, version, kind, document hash, schema version, rule set version, verdict, finding counts, report reference, the derived references, the idempotency key of blueprint id, version and document hash, and the receipt hash. The schema of the receipt requires ruleSetVersion and model/blueprints.yaml gives a rule set no version: in this delivery the value is the version of the rule classes the service ships, one value for all kinds that changes with every release of the service that changes a rule, and the missing version of the model is reported to the owner. The Validate call itself writes only the receipt, which is why its class is sandbox. The service moves the state: in the transaction of the verdict a passed version goes from Draft to Validated through ValidationPassed, for exactly the document hash that was validated, and a failed version stays Draft; BlueprintValidated with passed true or false, the report reference and the document hash 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, since AuditService consumes it; no separate evidence record is written. The derivation that follows a passed Service or Module Blueprint is delivered by AIFACTORY-US-677. Validation is naturally idempotent on blueprint id, version and document hash: a repeated call returns the same receipt and publishes nothing again. The inbox handler AttachValidation receives ArtifactValidated of ArtifactService; when the artifact is the document of a Draft version it hands that version to the Validator under the same key, and any other artifact is acknowledged without an effect. The handler hands the version over whatever passed of the event says: the artifact verdict concerns the artifact, the version has no field that could hold it, and only the receipt of this service moves a version, so a failed artifact verdict is not attached and does not fail the version by itself. The model names the handler AttachValidation and nothing it attaches to; this reading is reported to the owner. A caller without the scope is refused with 403 or PermissionDenied and a caller without a workload identity with Unauthenticated; an unknown version and a version of another tenant are answered 404 or NOT_FOUND alike; a version that is Submitted, Published or Deprecated is refused with 409 or FailedPrecondition, because its document no longer changes and a validation for it is a state conflict (D123). ArtifactService fails fast, and so does TemplateRegistryService for a Module Blueprint: the call ends with 503 and a problem response, or with Unavailable, no receipt is written and nothing changes; the event-triggered execution is tried three times 30 s apart and then left to the failed work of the inbox. The service never retries the call of a caller; whether a failed tool call is repeated is decided by RunControlService under the retry rule of a sandbox step.

Acceptance criteria

AC1 Given a caller with factory.blueprints.write and a Draft BlueprintService/BlueprintVersion of the tenant and project of the caller whose document satisfies the schema and every rule of its kind, when BlueprintService/ValidateBlueprint is called, then the document is read through ArtifactService/Artifacts.Fetch, the report is stored through ArtifactService/Artifacts.Store, the version moves from Draft to Validated through ValidationPassed for exactly that document hash, validationReportRef is set, BlueprintService/BlueprintValidated with passed true is written in the same transaction, and the response is 200 with the receipt; and given a Module Blueprint, then the validator reads the manifest of its pinned template version through TemplateRegistryService/Catalog.ResolveManifest and evaluates the rule MOD-002 of model/blueprints.yaml against it: the version becomes Validated when every switch the document uses is declared by that manifest and its schema and every other rule hold, and a switch the manifest does not declare is a finding with rule id MOD-002 and severity error that fails the validation (SCN-BlueprintService-004).
AC2 Given a document that violates the common metadata, the JSON Schema of its kind or a rule of its rule set, a warning while Templates:Blueprints:FailOnWarnings is true, or a kind whose schema version the registry cannot resolve, when the version is validated, then the receipt has passed false with one finding per violation carrying rule id, severity, path and message, the unresolved schema is named by its schema id, the findings are kept in ValidationFindings, the version stays Draft, BlueprintService/BlueprintValidated with passed false is written in the same transaction and connectsoft.factory.blueprints.validation_failures is incremented by kind and rule id (SCN-BlueprintService-004, model/blueprints.yaml).
AC3 Given ToolAdapterService executing the tool blueprint-validate with a blueprint-version-ref-v1, a workload token that holds factory.blueprints.write and the scope of the run, when it calls BlueprintService/Blueprints.Validate, then the reply is blueprint-validation-receipt-v1 with receipt id, document hash, schema version, rule set version, which is the version of the rule classes the service ships, verdict, finding counts, report reference, derived references, idempotencyKey of blueprint id, version and document hash, and receipt hash, as docs/reference/schemas/blueprint-validation-receipt.schema.json requires, the call itself writes only the receipt while the service moves the state as in AC1 and AC2, and a repeated call for the same version and document hash returns the same receipt and publishes nothing again (SCN-BlueprintService-007, ADR-0026).
AC4 Given the verdict was committed, when the outbox dispatcher of the profile blueprint publishes BlueprintService/BlueprintValidated on blueprints.versions.v1.blueprint-validated, then the event is sent under the run event envelope with blueprintId, version, tenantId, projectId, kind, passed, validationReportRef and documentHash and without document content, and a transport outage is retried with backoff so the event is neither lost nor duplicated under its event id (SCN-BlueprintService-009, ADR-0012).
AC5 Given a caller without the scope, a caller without a workload identity, a version that does not exist or belongs to another tenant, a version that is Submitted, Published or Deprecated, or a required dependency not answering, that is ArtifactService for every kind and TemplateRegistryService for a Module Blueprint, when a validation is requested, then the answer is 403 or PermissionDenied, Unauthenticated, 404 or NOT_FOUND, 409 or FailedPrecondition, and 503 with a problem response or Unavailable respectively, with no receipt, no state change and no event; and given ArtifactService/ArtifactValidated names the document artifact of a Draft version, with passed true or false, then the Validator validates that version once per blueprint id, version and document hash, with at most three attempts 30 s apart, and the verdict of the version is the receipt of this service alone (SCN-BlueprintService-004, SCN-BlueprintService-007, ADR-0015).
Traces: services BlueprintService, ArtifactService, ToolAdapterService, TemplateRegistryService
Traces: aggregates BlueprintService/BlueprintVersion
Traces: apis BlueprintService/ValidateBlueprint, BlueprintService/Blueprints.Validate, ArtifactService/Artifacts.Fetch, ArtifactService/Artifacts.Store, TemplateRegistryService/Catalog.ResolveManifest
Traces: events BlueprintService/BlueprintValidated, ArtifactService/ArtifactValidated
Traces: steps vision-to-blueprint/validate
Traces: tools blueprint-validate
Traces: descriptors blueprint-validation-receipt-v1, blueprint-version-ref-v1, blueprint-common-v1
Traces: adrs ADR-0012, ADR-0015, ADR-0026
Traces: requirements FR-03
Traces: scenarios SCN-BlueprintService-004, SCN-BlueprintService-007, SCN-BlueprintService-009
Relates: nfrs NFR-05
Depends on AIFACTORY-US-674, feature:artifact-service, feature:tool-adapter-service, feature:template-registry-service
Sources model/services/template-library/BlueprintService.yaml, model/services/template-library/TemplateRegistryService.yaml, model/blueprints.yaml, model/tools/blueprint-validate.yaml, docs/reference/schemas/blueprint-validation-receipt.schema.json, docs/architecture/adr/0026-requirements-to-ux-handoff.md, docs/solution-packs/software-factory/templates/services/blueprint-service/index.md#workers-and-jobs

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-204 Validation against the kind schema and rule set with a receipt implementation The Validator reads the document through Artifacts.Fetch, validates the common metadata, the JSON Schema of the kind resolved under Templates:Blueprints:SchemaRegistryPath and the rules of the 22 kinds of model/blueprints.yaml as rule classes with their rule ids, honours Templates:Blueprints:FailOnWarnings, stores the report through Artifacts.Store, keeps the findings, returns the receipt and, in one transaction, applies ValidationPassed for the validated document hash or leaves the version Draft and writes BlueprintValidated; ValidateBlueprint, Blueprints.Validate and the AttachValidation handler all run it under the key of blueprint id, version and document hash, the handler whatever passed of ArtifactValidated says; for a Module Blueprint it reads the manifest of the pinned template version through Catalog.ResolveManifest of TemplateRegistryService with the workload identity of the service and evaluates the rule MOD-002 against it, with one error finding per switch the manifest does not declare and one for a template version the registry answers as not found, and for no other kind does it call the registry; UX-006, a workflow gate by model/blueprints.yaml, is not evaluated and writes no finding; the receipt carries the idempotency key and, as ruleSetVersion, the version of the rule classes the service ships, because the model gives a rule set no version; a version that is Submitted, Published or Deprecated is answered 409 or FailedPrecondition; an outage of ArtifactService, and for a Module Blueprint of TemplateRegistryService, is answered 503 or Unavailable and leaves the version as it was. ConnectSoft.AI.SoftwareFactory.BlueprintService
AIFACTORY-TASK-2712 Contract of the validation receipt and of the two validation operations contract The OpenAPI document of ValidateBlueprint and the proto of Blueprints.Validate take a version reference and answer with a message that maps onto docs/reference/schemas/blueprint-validation-receipt.schema.json field by field, the finding counts and the derived references among them, and the payload of BlueprintValidated matches model/services/template-library/BlueprintService.yaml. ConnectSoft.AI.SoftwareFactory.BlueprintService
AIFACTORY-TASK-2713 Schema registry fixture with a passing and a failing document for every blueprint kind fixture The acceptance suite holds the registered schemas of the 22 kinds under a fixture registry path and, for every kind of model/blueprints.yaml, one document that passes and one document per rule that breaks exactly that rule, plus a document whose schema version the registry does not hold, so that every evaluated rule id is proven to produce its finding; the failing document of MOD-002 uses a switch that the fixture manifest of its pinned template version does not declare, and the passing Module document uses only switches that manifest declares; exactly one rule id has no failing document: UX-006, which model/blueprints.yaml marks as a workflow gate and for which no finding is expected. ConnectSoft.AI.SoftwareFactory.BlueprintService
AIFACTORY-TASK-3431 Acceptance double of TemplateRegistryService for the manifest read of the rule MOD-002 and its outage fixture A test double answers Catalog.ResolveManifest by template id and version with fixture manifests that declare their switches, answers a template version it does not hold as not found, records every call and can be switched to not answering, so that the suite of AIFACTORY-US-676 evaluates MOD-002 without TemplateRegistryService, proves the 503 and the Unavailable answer of the validation of a Module Blueprint while the registry does not answer, and proves that a version of any other kind is validated without a call to the double. ConnectSoft.AI.SoftwareFactory.BlueprintService
AIFACTORY-TASK-2714 Verify validate-a-blueprint-version-with-a-receipt through the acceptance suite verification Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-BlueprintService-004\|Scenario=SCN-BlueprintService-007\|Scenario=SCN-BlueprintService-009)"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-676: the passed and the failed verdict with the state each leaves, every evaluated rule id of the fixture, the rule MOD-002 evaluated against the manifest that the double of AIFACTORY-TASK-3431 answers, with a Module document that becomes Validated and one whose undeclared switch fails the validation, the receipt fields with the idempotency key and the rule set version, the idempotent repeat, the refusals, among them 409 or FailedPrecondition for a Submitted, Published or Deprecated version, the artifact verdict with passed false that still leads to a validation, the outage of ArtifactService, and of TemplateRegistryService for a Module Blueprint, answered 503 or Unavailable with the version left as it was, and the publication and payload of BlueprintValidated; consumer handling is proven by the suites of the consumers. ConnectSoft.AI.SoftwareFactory.BlueprintService

AIFACTORY-US-677: Derive the context map and the domain models of a passed Service or Module Blueprint, announce them and serve them to recipes and agents

behavior A passed Service or Module Blueprint yields the typed inputs of generation. In the transaction in which the Validator records ValidationPassed, it derives one ContextMap for the blueprint version, with the bounded contexts, their relationships (upstream, downstream, shared kernel, anti-corruption layer) and the published-language events, and one DomainModel per bounded context, with aggregates, entities, value objects, invariants and events. Each derived model is stored as a document in ArtifactService through Artifacts.Store; the version keeps contextMapRef and domainModelRef, the rows of ContextMaps and DomainModels keep the derived structure the model lists, and the receipt names both references. The aggregate and the receipt hold one domainModelRef, while a Service Blueprint can name several bounded contexts: in this delivery the reference names one index artifact that lists, per context id, the reference and the content hash of the domain model document of that context, with one entry for a blueprint of one context; the single field of the model is reported to the owner. ContextMapDerived, with the number of contexts, and one DomainModelDerived per context, with the number of aggregates, are written to the outbox in that same transaction and published under the run event envelope without model content. WorkflowEngineService, GenerationRecipeService and StudioBff consume them in their own PBIs. A version of any other kind derives nothing, and a failed validation derives nothing. A domain model that would break its invariant, an aggregate without a root entity, an identity or an invariant, or an event that names no aggregate, fails the validation with a finding of the matching rule instead of being stored. Derived models are never edited: a changed document returns the version to Draft and clears both references, and the next passed validation replaces the derived rows of that version, which the unique indexes over tenant, blueprint id and version, and over tenant, blueprint id, version and context, keep single. The summary of the ContextMap aggregate also names a Vision Blueprint as a source while the worker derives for the Service and Module kinds only; this PBI follows the worker and reports the difference. The optional dependency EnvelopeRegistryService, which would check the published-language events against the topic registry, is delivered in I4: until then the event names are checked by the naming rule of the kind alone and no call is made, which is the degraded mode the model allows. The result is read through Blueprints.GetDerivedModel, the read by which a recipe resolves the domain model pin of a module (ADR-0027). The caller of this increment is GenerationRecipeService; AgentRuntimeWorker is the second modelled caller and arrives with its own feature, and no tool is modelled for this method, so ToolAdapterService does not call it. A caller with a workload identity whose token holds factory.blueprints.read, with the forwarded tenant and project, addresses a blueprint version and receives artifact-v1 with the references and content hashes of its context map and domain models. The read writes nothing. A version of the tenant without derived models is answered FailedPrecondition; an unknown version and a version of another tenant are answered NOT_FOUND alike.

Acceptance criteria

AC1 Given a Service Blueprint version, a document of blueprint-service-v1, or a Module Blueprint version, a document of blueprint-module-v1, whose validation passes, when the transaction of the verdict commits, then one BlueprintService/ContextMap exists for the blueprint version with its contexts, relationships and published-language events, one BlueprintService/DomainModel exists per bounded context with its aggregates and events, each is stored as a document through ArtifactService/Artifacts.Store, contextMapRef of the BlueprintService/BlueprintVersion names the context map document and its one domainModelRef names an index artifact that lists the reference and content hash of the domain model document of every context, the single reference of the model being reported to the owner, and BlueprintService/ContextMapDerived and one BlueprintService/DomainModelDerived per context are written in that same transaction (SCN-BlueprintService-012, SCN-BlueprintService-013).
AC2 Given a version of any other kind that passes, a version that fails, or a derived domain model whose aggregate lacks a root entity, an identity or an invariant or whose event names no aggregate, when validation ends, then nothing is derived and no derivation event is written, the last case failing the validation with a finding that carries the rule id; and given a changed document, then the version returns to Draft with both references cleared and the next passed validation replaces the derived rows of that version, as the invariants of model/services/template-library/BlueprintService.yaml require.
AC3 Given the derivation was committed, when the outbox dispatcher publishes BlueprintService/ContextMapDerived on blueprints.models.v1.context-map-derived and BlueprintService/DomainModelDerived on blueprints.models.v1.domain-model-derived, then the first carries contextMapId, tenantId, projectId, blueprintId, blueprintVersion and the number of contexts, the second domainModelId, tenantId, projectId, blueprintId, contextId and the number of aggregates, both under the run event envelope and without model content, and a transport outage is retried with backoff so neither is lost or duplicated under its event id (SCN-BlueprintService-012, SCN-BlueprintService-013, ADR-0012).
AC4 Given GenerationRecipeService as the caller of this increment, with a workload identity whose token holds factory.blueprints.read and the forwarded tenant and project, when BlueprintService/Blueprints.GetDerivedModel is called for a blueprint version, the read by which a recipe resolves a domain model pin (ADR-0027), then the reply is artifact-v1 with the references and content hashes of the context map and of the domain models of that version and nothing is written; a version of the tenant without derived models is answered FailedPrecondition, an unknown version and a version of another tenant NOT_FOUND alike, a missing identity Unauthenticated, a missing scope PermissionDenied and an invalid request InvalidArgument (SCN-BlueprintService-008, ADR-0015).
Traces: services BlueprintService, ArtifactService
Traces: aggregates BlueprintService/BlueprintVersion, BlueprintService/ContextMap, BlueprintService/DomainModel
Traces: apis BlueprintService/Blueprints.GetDerivedModel, ArtifactService/Artifacts.Store
Traces: events BlueprintService/ContextMapDerived, BlueprintService/DomainModelDerived
Traces: descriptors artifact-v1, blueprint-service-v1, blueprint-module-v1
Traces: adrs ADR-0012, ADR-0015, ADR-0027
Traces: scenarios SCN-BlueprintService-008, SCN-BlueprintService-012, SCN-BlueprintService-013
Relates: nfrs NFR-05
Depends on AIFACTORY-US-676, feature:artifact-service
Sources model/services/template-library/BlueprintService.yaml, model/blueprints.yaml, docs/reference/schemas/blueprint-service.schema.json, docs/reference/schemas/blueprint-module.schema.json, docs/solution-packs/software-factory/templates/services/blueprint-service/index.md#domain-model

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-205 Derivation of the context map and the domain model implementation In the transaction of ValidationPassed the Validator derives one ContextMap per blueprint version and one DomainModel per bounded context from a Service or Module Blueprint, stores each as a document through Artifacts.Store, stores one index artifact that lists the domain model document of every context by reference and content hash, sets contextMapRef and sets domainModelRef to that index, replaces the derived rows of a version that is validated again and writes ContextMapDerived and one DomainModelDerived per context to the outbox; another kind and a failed validation derive nothing, and a model that breaks the domain model invariant fails the validation with its rule finding. ConnectSoft.AI.SoftwareFactory.BlueprintService
AIFACTORY-TASK-2715 Blueprints.GetDerivedModel over the derived references of a version implementation Blueprints.GetDerivedModel returns artifact-v1 with the references and content hashes of the context map and of the domain models of the addressed version under the tenant filter and the service scope factory.blueprints.read; a version without derived models is FailedPrecondition, an unknown version and a version of another tenant NotFound, the gRPC status NOT_FOUND (ADR-0015), and the read writes nothing. ConnectSoft.AI.SoftwareFactory.BlueprintService
AIFACTORY-TASK-2716 Verify derive-context-map-and-domain-model through the acceptance suite verification Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-BlueprintService-008\|Scenario=SCN-BlueprintService-012\|Scenario=SCN-BlueprintService-013)"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-677 on the Service and Module fixture documents: the derived rows and references, the kinds that derive nothing, the replacement after a changed document, the read with its refusals and the publication and payload of both derivation events; consumer handling is proven by the suites of the consumers. ConnectSoft.AI.SoftwareFactory.BlueprintService

AIFACTORY-US-678: Submit a Validated blueprint version to Asset Publication and follow the release it becomes to Published and Deprecated

behavior · persona asset-maintainer As an asset maintainer, I want to submit a validated blueprint version to Asset Publication and see when it is Published or Deprecated, so that recipes build on the submitted version until the evaluation gate of I4 exists and only on Published versions from then on.

An Asset maintainer whose forwarded user token carries factory.blueprints.publish submits a Validated version to Asset Publication through SubmitBlueprint. The version moves from Validated to Submitted through SubmitForPublication and BlueprintSubmitted is written to the outbox in the same transaction; the answer is 202, because publication is decided elsewhere. BlueprintSubmitted is also the audit evidence of the submission, and BlueprintPublished that of the publication, since AuditService consumes both; no separate evidence record is written. A Service or Module version must hold its derived context map and domain model references, as its invariant requires. A repeated call for a version already Submitted returns 202 and writes nothing. A caller without the scope is refused with 403; an unknown version and a version of another tenant are answered 404 alike; a version that is Draft, Published or Deprecated, and a Service or Module version without derived references, are refused with 409. Publication goes through Asset Publication and its evaluation gate (ADR-0021); this service never marks a version Published on its own, decides no approval and repeats no write. The model lists AgentRegistryService as a required outbound dependency for submitting release candidates and names no operation of that service for it, while AgentRegistryService names the handler OpenReleaseCandidate for BlueprintSubmitted; this PBI therefore makes no synchronous call and the event is the submission, which is reported to the owner. The inbox handler MarkPublished handles the published asset release event of AgentRegistryService: when its asset id and version name a Submitted version of the tenant of the envelope, the version moves to Published through AssetReleasePublished, releaseId is set and BlueprintPublished is written in the same transaction. The enum AssetKind of AgentRegistryService has no value for a blueprint, so the handler matches by asset id and version and ignores every release that matches no Submitted version; which asset kind a blueprint release carries is reported to the owner. The handler MarkDeprecated handles the deprecated asset release event: the Published version whose releaseId it names moves to Deprecated through AssetReleaseDeprecated. The model names no event of this service for a deprecation, so the state is read through the reads of the service. Both handlers are idempotent on the event id. In this increment AgentRegistryService is delivered thin and publishes neither event; its publication path arrives in I2 with feature agent-registry-service-publication (D140), and its handler OpenReleaseCandidate, which opens the candidate of a blueprint from BlueprintSubmitted, with feature agent-registry-service-complete in I4. On a deployed instance a Submitted version therefore stays Submitted and BlueprintPublished is not published before I4. Until that gate the Draft allowance applies (D123): GenerationRecipeService consumes BlueprintSubmitted and keeps the Submitted version as one a recipe may bind, so the chain to an approved recipe does not wait for the gate, and from I4 a recipe binds only a Published version. The two handlers are built here and proven on event fixtures that carry the payloads of model/services/control-plane/AgentRegistryService.yaml under the run event envelope; neither release event is traced by this PBI, because no feature of this increment publishes it.

Acceptance criteria

AC1 Given a caller with factory.blueprints.publish and a Validated BlueprintService/BlueprintVersion of the tenant and project of the caller, of a Service or Module kind with its derived references or of any other kind, when BlueprintService/SubmitBlueprint is called, then the version moves to Submitted through SubmitForPublication, BlueprintService/BlueprintSubmitted is written in the same transaction, the response is 202, and a repeated call for the version already Submitted returns 202 and writes nothing (SCN-BlueprintService-005).
AC2 Given a caller without factory.blueprints.publish, a version that does not exist or belongs to another tenant, a version that is Draft, Published or Deprecated, or a Validated Service or Module version without its derived context map and domain model, when BlueprintService/SubmitBlueprint is called, then the response is 403, 404, 409 and 409 respectively with a problem response, the state does not change and nothing is published (SCN-BlueprintService-005, ADR-0015).
AC3 Given the submission was committed, when the outbox dispatcher publishes BlueprintService/BlueprintSubmitted on blueprints.versions.v1.blueprint-submitted, then the event is sent under the run event envelope with blueprintId, version, tenantId and projectId, a transport outage is retried with backoff so the event is neither lost nor duplicated under its event id, and the service calls no operation of Asset Publication itself (SCN-BlueprintService-010, ADR-0012).
AC4 Given a Submitted version and the event fixture of a published asset release that names its blueprint id and version in its tenant, when the inbox handler MarkPublished runs, then the version moves to Published through AssetReleasePublished, releaseId is set and BlueprintService/BlueprintPublished is written in the same transaction and published on blueprints.versions.v1.blueprint-published with blueprintId, version, tenantId, projectId and releaseId; a second delivery of the same event id, a release that matches no Submitted version and a release of another tenant change nothing (SCN-BlueprintService-011, ADR-0021).
AC5 Given a Published version and the event fixture of a deprecated asset release that names its releaseId, when the inbox handler MarkDeprecated runs, then the version moves to Deprecated through AssetReleaseDeprecated, idempotently on the event id, the state is readable through the reads of the service, and no command of the service ever moves a version to Published or Deprecated (model/services/template-library/BlueprintService.yaml, NFR-11).
Traces: services BlueprintService, AgentRegistryService
Traces: aggregates BlueprintService/BlueprintVersion
Traces: apis BlueprintService/SubmitBlueprint
Traces: events BlueprintService/BlueprintSubmitted, BlueprintService/BlueprintPublished
Traces: adrs ADR-0012, ADR-0015, ADR-0021
Traces: requirements FR-02, NFR-11
Traces: scenarios SCN-BlueprintService-005, SCN-BlueprintService-010, SCN-BlueprintService-011
Depends on AIFACTORY-US-676, AIFACTORY-US-677
Sources model/services/template-library/BlueprintService.yaml, model/services/control-plane/AgentRegistryService.yaml, docs/architecture/adr/0021-quality-gates.md, docs/solution-packs/software-factory/templates/services/blueprint-service/index.md#sagas-and-long-running-flows

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-2717 SubmitBlueprint with the Validated to Submitted transition and the BlueprintSubmitted outbox record implementation SubmitBlueprint applies SubmitForPublication to a Validated version of the trusted tenant and project, requires the derived references of a Service or Module version, writes BlueprintSubmitted in the same transaction and answers 202; a repeat for a Submitted version returns 202 and writes nothing; 403, 404 and 409 are covered by acceptance tests and the service calls no operation of AgentRegistryService. ConnectSoft.AI.SoftwareFactory.BlueprintService
AIFACTORY-TASK-2718 MarkPublished and MarkDeprecated inbox handlers implementation MarkPublished moves the Submitted version that a published asset release names by asset id and version, inside the tenant of the envelope, to Published with its releaseId and writes BlueprintPublished in the same transaction; MarkDeprecated moves the Published version that a deprecated asset release names by releaseId to Deprecated; both are idempotent on the event id and ignore a release that matches no version. ConnectSoft.AI.SoftwareFactory.BlueprintService
AIFACTORY-TASK-2719 Event fixtures of a published and a deprecated asset release fixture The acceptance suite builds the published and the deprecated asset release events from the payloads of model/services/control-plane/AgentRegistryService.yaml under the run event envelope of the pinned contracts package and delivers them to the inbox, once, twice under one event id, for an unknown asset and for another tenant, because no service of this increment publishes them. ConnectSoft.AI.SoftwareFactory.BlueprintService
AIFACTORY-TASK-2720 Verify submit-and-publish-a-blueprint-version through the acceptance suite verification Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-BlueprintService-005\|Scenario=SCN-BlueprintService-010\|Scenario=SCN-BlueprintService-011)"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-678: the submission with its refusals and its repeat, the publication and payload of BlueprintSubmitted, and on the event fixtures the Published and Deprecated transitions with the publication and payload of BlueprintPublished; consumer handling is proven by the suites of the consumers. ConnectSoft.AI.SoftwareFactory.BlueprintService