Skip to content

AIFACTORY-FEAT-084: TemplateRegistryService: 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 82 of 185 (Factory code)

TemplateRegistryService is the service of bounded context BC-14 (Template Catalog). One catalog module with pinned manifests: template versions read from the template repositories, library versions read from the feeds, API client catalog, dependency analysis and the compatibility matrix of templates, libraries, runtimes, editions and topologies with evidence (BC-14; eight June-2026 rows merged). Its own repository is ConnectSoft.AI.SoftwareFactory.TemplateRegistryService.

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

Scenarios to trace (11, catalog): SCN-TemplateRegistryService-001 ✓, SCN-TemplateRegistryService-002 ✓, SCN-TemplateRegistryService-003 ✓, SCN-TemplateRegistryService-004 ✓, SCN-TemplateRegistryService-005 ✓, SCN-TemplateRegistryService-006 ✓, SCN-TemplateRegistryService-007 ✓, SCN-TemplateRegistryService-008 ✓, SCN-TemplateRegistryService-009 ✓, SCN-TemplateRegistryService-010 ✓, SCN-TemplateRegistryService-011 ✓

AIFACTORY-US-072: TemplateRegistryService serves its scope end to end: a template repository becomes a pinned manifest, a matrix cell with evidence and a manifest a recipe resolves

behavior · persona asset-maintainer As an asset maintainer, I want one catalog that reads the templates and libraries of the ConnectSoft estate from their repositories and feeds, pins what it read and says with evidence what works together, so that the Template Catalog context has one owner that recipes and agents query at run time through its contract.

This is the integration PBI of the feature: it proves on a deployed instance that the behaviours of TemplateRegistryService work together along one template version, from its repository to a manifest that a generation recipe resolves. TemplateRegistryService is the catalog of bounded context BC-14. It holds the template descriptors and parameter contracts of the ConnectSoft templates as pinned manifests, the library versions of the feeds and the compatibility matrix with evidence, and it is the runtime counterpart of the design-time files model/templates.yaml, model/libraries.yaml and model/template-parameters. A template is consumed by its published package version and never by a path, and the catalog records which version and which commit that is. The chain it proves is this. The Discoverer reads the feeds and the template sources, pins each published version of a template package by manifest hash at the commit that package was built from and each library version with its packages, and announces each new version once (AIFACTORY-US-704). The CompatibilityComputer fills the cells of the new version, Compatible only with evidence and Unknown without, and a succeeded build of the template repository in the platform tenant becomes evidence for the library cells and for the runtime cells of the frameworks it built, whether the run completes before or after the version is discovered (AIFACTORY-US-705). A caller whose scope carries factory.catalog.read lists the template versions, reads one pinned manifest, lists the libraries and queries the matrix (AIFACTORY-US-706). A workload resolves the pinned manifest for a recipe, for the rule MOD-002 that BlueprintService evaluates on a Module Blueprint or for an agent over gRPC (AIFACTORY-US-707). An Asset maintainer of the platform tenant submits a Verified version to Asset Publication, and the catalog mirrors the published and the deprecated release, which it matches by asset kind, asset id and version (AIFACTORY-US-708). The repository, the three aggregates and the store are delivered by AIFACTORY-US-701, the hosted surface by AIFACTORY-US-702 and secrets, tenancy, telemetry and the two failure modes by AIFACTORY-US-703. Through I4 the catalog holds the templates and libraries of the platform tenant only (D123): every tenant reads them, the envelope of every catalog event names the platform tenant, and templates owned by a tenant are a later feature. A resource of another tenant is answered 404, over gRPC NOT_FOUND, and a missing scope or role inside the tenant 403 (ADR-0015 amendment D113). Only an administrator of the platform tenant discovers and publishes: the two commands are admitted only for an Asset maintainer or a Platform admin whose token names the platform tenant, and a caller of another tenant, who can read those rows, is answered 403 by either command. The gateway of this platform, TemplateCatalogHost, is delivered in the same increment (D123): the six REST operations are reached through it with a token whose audience is that gateway, and no service host is reached directly. The delivery states its limits, and each is reported to the owner. The thin AgentRegistryService of this increment has no operation that opens a release candidate and publishes no release event, so the submission is proven against a fake of the release candidate port and the handlers MarkPublished and MarkDeprecated by fixture publishers; on a deployed instance of this increment no template version becomes Published, because the publication path arrives with feature agent-registry-service-publication in I2 (D140). Until the evaluation gate of AgentRegistryService is delivered in I4 the Draft allowance applies (D123): a recipe may bind a version the catalog has discovered that is not yet Published, so Catalog.ResolveManifest serves such a version and TemplateVersionDiscovered, which GenerationRecipeService projects, is published for it; arriving in I4, only a Published version may be selected. The model names the state Verified and no transition that reaches it, and it names no source for the list of template repositories or for the layer of a template; a template version is a published package version pinned at the commit its package states (D123), and the documentation of the templates names no member of a package that states that commit. It names consumers of a template version and defines none, so TemplateRegistryService/ListTemplates returns that field empty. The summary of the service in the model also names an API client catalog and dependency analysis; the model gives neither an aggregate, an operation or an event, so none is built. Build evidence reaches a deployed instance only once a service publishes PipelineRunCompleted, which the complete delivery of PipelineExecutionService brings in I2. The chain therefore runs on a deployed instance whose source port is bound to the connector adapter of AIFACTORY-TASK-2868, with ConnectorRegistryService and the Azure DevOps endpoints answered by the recording stub of the acceptance environment, which serves the recorded template sources and the recorded feed, and with a seeded Verified version and evidence by fixture. This PBI proves the one chain; the tenancy answers are proven by AIFACTORY-US-703, AIFACTORY-US-706 and AIFACTORY-US-707, and every scenario of the service is proven by the suite of the PBI that traces it and is not repeated here.

Acceptance criteria

AC1 Given a deployed instance whose source port is bound to the connector adapter of AIFACTORY-TASK-2868, with ConnectorRegistryService and the Azure DevOps endpoints answered by the recording stub of the acceptance environment that serves the recorded template sources and the recorded feed, when a discovery pass runs, then each recorded version of a template package exists once as a TemplateRegistryService/TemplateVersion in state Discovered with the version of the package, the commit that package was built from and its manifest hash, and each library version once as a TemplateRegistryService/LibraryVersion, TemplateRegistryService/TemplateVersionDiscovered and TemplateRegistryService/LibraryVersionDiscovered are published once per new version, and TemplateRegistryService/ListTemplates returns the versions with layer, state and switches and with the field consumers empty, because the model does not define the consumers of a template version (ADR-0014, model/services/template-library/TemplateRegistryService.yaml).
AC2 Given the versions of AC1 and a fixture publisher of PipelineExecutionService/PipelineRunCompleted with a succeeded run of the platform tenant for the commit of one of them, when the cells are computed and the event is handled, then TemplateRegistryService/QueryCompatibility returns the library cells of that version and the runtime cells of the target frameworks its pinned manifest declares as Compatible with the pipeline run as evidence and every other cell, the runtime cell of a framework the version does not target among them, as Unknown, and TemplateRegistryService/CompatibilityChecked was published once per computed or changed TemplateRegistryService/CompatibilityEntry (NFR-13, model/services/template-library/TemplateRegistryService.yaml).
AC3 Given a workload token that holds the service scope of TemplateRegistryService, when TemplateRegistryService/Catalog.ResolveManifest is called for a version of AC1, which is Discovered and not yet Published and is served under the Draft allowance until I4 (D123), then the reply carries the pinned manifest with the commit and the manifest hash that TemplateRegistryService/GetTemplateVersion returns for the same version, so the gRPC reply and the REST read agree along the chain, and nothing is written; the answers for a version of another tenant, 404 and NOT_FOUND, and for a missing scope or role, 403 and PERMISSION_DENIED, are proven over the tenant matrix by AIFACTORY-US-703, AIFACTORY-US-706 and AIFACTORY-US-707 and are not repeated here (ADR-0015).
AC4 Given a seeded Verified version, the fake of the release candidate port and fixture publishers of AgentRegistryService/AssetReleasePublished and AgentRegistryService/AssetReleaseDeprecated, when TemplateRegistryService/PublishTemplateVersion is called by an Asset maintainer of the platform tenant and the two events are delivered in turn, the published one naming the asset kind TemplateBundle, the template id and the version in the tenant of the version and carrying a release manifest hash that differs from the manifest hash of the catalog, then one candidate is submitted, the version moves to Published with its release id, TemplateRegistryService/TemplateVersionPublished is published once, and the version then moves to Deprecated; the chain test of the acceptance suite runs AC1 to AC4 in one sequence and demands no further scenario of model/scenarios/TemplateRegistryService.yaml (ADR-0021).
Traces: services TemplateRegistryService, AgentRegistryService, PipelineExecutionService, ConnectorRegistryService
Traces: aggregates TemplateRegistryService/TemplateVersion, TemplateRegistryService/LibraryVersion, TemplateRegistryService/CompatibilityEntry
Traces: apis TemplateRegistryService/ListTemplates, TemplateRegistryService/GetTemplateVersion, TemplateRegistryService/QueryCompatibility, TemplateRegistryService/PublishTemplateVersion, TemplateRegistryService/Catalog.ResolveManifest
Traces: events TemplateRegistryService/TemplateVersionDiscovered, TemplateRegistryService/TemplateVersionPublished, TemplateRegistryService/LibraryVersionDiscovered, TemplateRegistryService/CompatibilityChecked, AgentRegistryService/AssetReleasePublished, AgentRegistryService/AssetReleaseDeprecated, PipelineExecutionService/PipelineRunCompleted
Traces: adrs ADR-0014, ADR-0015, ADR-0021, ADR-0028
Traces: requirements FR-06, NFR-13
Relates: screens template-catalog
Depends on AIFACTORY-US-701, AIFACTORY-US-702, AIFACTORY-US-703, AIFACTORY-US-704, AIFACTORY-US-705, AIFACTORY-US-706, AIFACTORY-US-707, AIFACTORY-US-708, feature:agent-registry-service-thin, feature:pipeline-execution-service-thin, feature:connector-registry-service-thin
Sources model/services/template-library/TemplateRegistryService.yaml, model/scenarios/TemplateRegistryService.yaml, model/templates.yaml, model/libraries.yaml, docs/solution-packs/software-factory/templates/workflows.md, docs/solution-packs/software-factory/templates/services/template-registry-service/index.md#purpose-and-responsibilities

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-2831 Deployment values of TemplateRegistryService: replica range, secret references, dependency addresses and the catalog options operations The deployment manifest of the service states the replica range 2 to 4 of model/services/template-library/TemplateRegistryService.yaml, the liveness and readiness probes, the messaging service name template-registry, one base address per dependency (ConnectorRegistryService, AgentRegistryService, RepositoryIntelligenceService) from configuration, the two secret references messaging-transport and package-feed by name and never by value, the binding of the source port to the connector adapter of AIFACTORY-TASK-2868, and the options Templates:Catalog:DiscoverIntervalHours, Templates:Catalog:Runtimes and Templates:Feeds:PackageFeeds with their modelled defaults; the same image runs in the saas-default, hybrid and on-prem topologies. ConnectSoft.AI.SoftwareFactory.TemplateRegistryService
AIFACTORY-TASK-789 Verify template-registry-service-serves-its-scope by running the declared command verification Run dotnet build -c Release and dotnet test -c Release --filter "Category=Acceptance&Feature=CatalogChain" against the deployed instance whose source port is bound to the connector adapter, with the recording stub of the connector and of the Azure DevOps endpoints serving the recorded template sources and the recorded feed, the fake of the release candidate port and the fixture publishers of the release events and of PipelineRunCompleted; a filter that matches no test counts as a failure; the chain of discovery, cells, evidence by fixture, reads, manifest resolution equal to the REST read, submission of a seeded Verified version, publication by a release event whose manifest hash differs from the catalog hash and deprecation by fixture passes in one sequence, which proves AC1 to AC4 of AIFACTORY-US-072. ConnectSoft.AI.SoftwareFactory.TemplateRegistryService

AIFACTORY-US-701: TemplateRegistryService repository: scaffolded from the base template with the Factory profile, with its three aggregates and the store template-registry-sql

enabling The repository ConnectSoft.AI.SoftwareFactory.TemplateRegistryService is created and scaffolded in I0 by AIFACTORY-TASK-132 of feature repository-and-pipeline-conventions (D140), and this feature starts from that scaffold, with the scaffold command of ADR-0028 and its amendment on the Factory profile switch (D114): dotnet new connectsoft-base -n ConnectSoft.AI.SoftwareFactory.TemplateRegistryService --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 comes from the contracts package by a version pin. On that scaffold this PBI adds the domain and the store. A TemplateVersion is the pinned manifest of one template version: the template id, which is the short name of .template.config and the templates catalog id, the version, which is the version of the published template package, the tenant, the layer (L1Foundation, L2Platform or L3Product), the repository and the commit it was read from, the manifest with the projects and their roles, the switches with their allowed values, the generated and preserved paths, the pipelines and the docs, the manifest hash, the state, the release id once an asset release exists, and the time of discovery. The summary of the aggregate also names consumers, while its fields and the table TemplateVersions hold none; no member and no column is added for them here, and the gap is reported to the owner (AIFACTORY-US-706 states what the read returns). Its invariants are those of the model: a manifest is read from the template repository at a commit and pinned by hash and is never edited in the catalog, a template version is a published package version of the template, pinned at the commit its package states, a generation recipe selects a Published version and, until the evaluation gate of AgentRegistryService is delivered in I4, may also select a version the catalog has discovered that is not yet Published, arriving in I4 only a Published version may be selected, and a Deprecated version may be upgraded from and never generated with (D123). The model lists the five values of CatalogState, Discovered, Verified, Published, Deprecated and Retired, and no transition table. The aggregate therefore accepts exactly the transitions the rest of the model implies and refuses every other one: a version is created Discovered, moves from Discovered to Verified, from Verified to Published when its asset release is published, and from Published to Deprecated when that release is deprecated. The model names no trigger for the transition to Verified and no path to Retired; the first exists as a domain operation that no handler of this delivery calls, the second as a value no operation reaches, and both are reported to the owner. A LibraryVersion is one version of one library of the libraries catalog: library id, version, tenant, layer, capability area, the packages with their versions on the feed, the options sections, the templates that consume it, the state and the time of discovery; a library version without a published package is Discovered and not Published. A CompatibilityEntry is one cell of the matrix: subject kind (template or library), subject id and version, the kind it is checked with (library, runtime, edition, topology or template), the id and optional version of that, the result (Compatible, CompatibleWithWarnings, Incompatible or Unknown), the evidence reference and the time of the check; a cell is Compatible only with evidence and Unknown without. The store template-registry-sql is owned by this service alone (ADR-0028 decision 5). The model lists four tables for it; the fourth, PendingBuildEvidence, is migrated by AIFACTORY-US-705 with the handler that writes it (D123). This PBI migrates the other three, TemplateVersions keyed by template id and version, LibraryVersions keyed by library id and version and CompatibilityEntries keyed by entry id, with the columns of the model, the index over state and layer of template versions, the index over area and state of library versions and the unique index over the six columns that identify a cell. Every mapping carries the tenant row filter of the Factory profile. Through I4 the catalog holds the templates and libraries of the platform tenant only (D123): every row is written with the platform tenant, and the read filter admits the rows of the platform tenant beside those of the tenant of the caller. The filter admits the platform tenant for reading only: a command changes rows of the tenant of its caller, so a row of the platform tenant is changed by a caller of the platform tenant, by a worker or by an inbox handler and never by a caller of another tenant (AIFACTORY-US-702). Templates owned by a tenant are a later feature. No deletion job and no deletion-order handler is built here: the model lists no retention event for this service, and those handlers arrive with RetentionResidencyService in I4.

Acceptance criteria

AC1 Given the repository created and scaffolded in I0 by AIFACTORY-TASK-132 of feature repository-and-pipeline-conventions with dotnet new connectsoft-base -n ConnectSoft.AI.SoftwareFactory.TemplateRegistryService --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 with complete reports, a container image is published and the repository records the template version (ADR-0028, model/template-parameters/connectsoft-base.yaml).
AC2 Given the TemplateRegistryService/TemplateVersion, TemplateRegistryService/LibraryVersion and TemplateRegistryService/CompatibilityEntry aggregates, when their unit tests run, then a template version is created Discovered and accepts exactly the transitions Discovered to Verified, Verified to Published and Published to Deprecated and refuses every other one, a transition out of Deprecated or into Retired among them; a change of the manifest of a pinned version is refused; a library version without a published package cannot be Published; and a cell cannot be Compatible without an evidence reference and is Unknown without one (model/services/template-library/TemplateRegistryService.yaml).
AC3 Given template-registry-sql created by the migrations of the repository on an isolated test database, when the mapping tests run, then the three tables exist with their keys and indexes, a second row for one template id and version, for one library id and version or for one cell of the six identifying columns violates its key or its unique index, a query made for one tenant returns the rows of that tenant and of the platform tenant and never a row of another tenant, and a version of another tenant is not found when addressed (ADR-0015, model/stores.yaml).
Traces: services TemplateRegistryService
Traces: aggregates TemplateRegistryService/TemplateVersion, TemplateRegistryService/LibraryVersion, TemplateRegistryService/CompatibilityEntry
Traces: adrs ADR-0015, ADR-0028
Traces: requirements NFR-13
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/TemplateRegistryService.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/template-registry-service/index.md#domain-model

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-133 Domain model: TemplateVersion, LibraryVersion, CompatibilityEntry implementation The three aggregates enforce the invariants of the model as it words them; the TemplateVersion is created Discovered and accepts only the transitions Discovered to Verified, Verified to Published and Published to Deprecated, keeps its manifest and manifest hash unchanged after creation and takes its release id with the transition to Published; the LibraryVersion is Published only with a published package; the CompatibilityEntry is Compatible only with an evidence reference; unit tests cover every invariant, each of the three transitions and the refusal of every other one. ConnectSoft.AI.SoftwareFactory.TemplateRegistryService
AIFACTORY-TASK-134 Persistence in template-registry-sql: TemplateVersions, LibraryVersions, CompatibilityEntries migration Mappings and migrations for the three tables with the columns the model lists, the keys over template id and version and over library id and version, the index IX_Templates_State, the index IX_Libraries_Area, the unique index UX_Compat_Cell and the tenant filter in every mapping, the filter admitting the platform tenant for reading and never for a command of a caller of another tenant; mapping tests run against an isolated test database, never a shared one. ConnectSoft.AI.SoftwareFactory.TemplateRegistryService
AIFACTORY-TASK-2832 Verify the scaffold, the aggregates and the store of TemplateRegistryService 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-701 (ADR-0028). ConnectSoft.AI.SoftwareFactory.TemplateRegistryService

AIFACTORY-US-702: TemplateRegistryService host: six REST routes, one gRPC method, an inbox for four consumed events and the self-subscription that triggers the CompatibilityComputer, and two hosted workers

enabling This PBI turns the scaffold of AIFACTORY-US-701 into a host on which the behaviour PBIs of the feature land. From the service descriptor the host exposes the six REST operations of the model for its platform gateway and the internal gRPC service Catalog with the method ResolveManifest, 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 (ADR-0015 amendment D117). That gateway is delivered in the same increment (D123), and the audience the service accepts is the audience of that gateway from the first deployment on. Each route requires its scope: factory.catalog.read for ListTemplates, GetTemplateVersion, ListLibraries and QueryCompatibility, and factory.catalog.admin for DiscoverTemplates and PublishTemplateVersion. The role policies narrow the admin scope as the model words it: the two commands admit an Asset maintainer and a Platform admin, and a Requester or an Observer issues neither; the four reads admit the four roles of the model, Requester, Asset maintainer, Platform admin and Observer. The policy of the two commands also names the tenant of the caller, as the model states it (D123). Through I4 the catalog holds the rows of the platform tenant only, to which every template version the Discoverer writes belongs, and only an administrator of that tenant discovers and publishes. DiscoverTemplates and PublishTemplateVersion are therefore admitted only for an Asset maintainer or a Platform admin whose token names the platform tenant; an Asset maintainer or a Platform admin of another tenant, who can read those rows, is answered 403 by either command, no pass starts and no candidate is submitted. The tenant of a user call comes from the token. The gRPC method requires a workload identity whose token holds the service scope that names TemplateRegistryService; the model names as its callers GenerationRecipeService, BlueprintService, whose Validator evaluates the rule MOD-002 of a Module Blueprint against the manifest (D123), and AgentRuntimeWorker. A workload token carries no tenant claim, and the service reads the tenant and project a workload forwards only because the token holds that service scope (ADR-0015 amendment D114). A resource of another tenant is invisible under the tenant row filter and is answered 404, over gRPC NOT_FOUND, while a missing scope or role inside the tenant of the caller is answered 403, over gRPC PERMISSION_DENIED (D113); the filter is wired here and the answers are proven by the behaviour PBIs. Every modelled refusal code has a problem response. All six REST operations declare the idempotency natural, so the host carries no Idempotency-Key filter: a repeated command is made harmless by the natural key of what it writes. The messaging profile of the service is named template-registry, the value of OrleansMessaging:ServiceName, and its inbox and outbox belong to this service alone (ADR-0028). The outbox writer enlists in the unit of work of a command, of an inbox handler and of a worker step, and the dispatcher publishes the four events of the model in the run event envelope of the contracts package with their routes declared in the OrleansMessaging section. The inbox holds five registrations with deduplication on the event id: the four consumed events of the model, AssetReleasePublished and AssetReleaseDeprecated of AgentRegistryService, PipelineRunCompleted of PipelineExecutionService and ChunksPublished of KnowledgeIngestionService, and the self-subscription to TemplateVersionDiscovered of the service itself, which is the trigger of the CompatibilityComputer. What the first three handlers do is delivered by AIFACTORY-US-705 and AIFACTORY-US-708. The fourth is delivered here. The model gives RefreshDocs the purpose that template documentation ingested by the Knowledge platform refreshes the docs links of the catalog. The payload of ChunksPublished names a snapshot, a source, a tenant, a chunk count and an embedding profile version and no template, repository or commit; a manifest is never edited in the catalog, and no table of the model has a column for a docs link. The handler is therefore built with the least effect the model words: idempotent on the event id, it logs the snapshot and the source, changes no row and publishes nothing; what it refreshes and where that is kept is reported to the owner. The thin KnowledgeIngestionService of this increment ingests nothing and publishes no ChunksPublished, so the handler is proven with a fixture publisher. The service registers no handler for a retention or deletion-order event: the model lists none for it, and those handlers are built in I4 with RetentionResidencyService. The two workers of the model are hosted with their triggers and limits: the Discoverer on the schedule 0 */6 * * *, which is the default 6 of Templates:Catalog:DiscoverIntervalHours, two attempts 600 seconds apart, four in parallel partitioned by repository, keyed by repository and commit; the CompatibilityComputer on TemplateVersionDiscovered, two attempts 120 seconds apart, four in parallel partitioned by subject id, keyed by cell and evidence. A duplicate trigger has no second effect. The four options of the model are bound and validated at start: Templates:Catalog:DiscoverIntervalHours, Templates:Catalog:Runtimes, Templates:Feeds:PackageFeeds and OrleansMessaging:ServiceName; a value that does not parse stops the start with the option named, and a reloaded value of one of the first three, which are reloadable, applies from the next pass or the next computation and never to one in flight. Readiness reports the store and the messaging profile. What each operation, handler and worker does is delivered by AIFACTORY-US-704 to AIFACTORY-US-708, not here.

Acceptance criteria

AC1 Given the hosted service, when each of the six REST operations of model/services/template-library/TemplateRegistryService.yaml is called without a token and with a token that lacks the scope of the route, then the answers are 401 and 403 with a problem response; when one of the two commands is called by an Observer or a Requester who holds factory.catalog.admin, or by an Asset maintainer or a Platform admin whose token names another tenant than the platform tenant, then the answer is 403; a gRPC call without a workload identity or without the service scope is refused with UNAUTHENTICATED or PERMISSION_DENIED; a user token whose audience is not the gateway of the service is refused with 401; no state changes (ADR-0015).
AC2 Given a handler that changes a TemplateRegistryService/TemplateVersion and publishes one of the four declared events, when its unit of work commits, then one outbox record in run-event-envelope-v1 with event id, tenant id, correlation id and payload is committed in the same transaction; when the unit of work rolls back, neither the change nor the record exists; a publish of an event the OrleansMessaging section does not declare throws (ADR-0012, ADR-0014).
AC3 Given the same event id delivered twice to the inbox of the template-registry messaging profile, or the same trigger of a hosted worker fired twice under one idempotency key, when it is dispatched, then the handler or the worker runs once and the second delivery has no effect; a handler that keeps failing is retried with backoff and never applied twice; given a fixture publisher of KnowledgeIngestionService/ChunksPublished, when the event is delivered, the same event id twice, then the RefreshDocs handler runs once, logs the snapshot and the source, changes no TemplateRegistryService/TemplateVersion and publishes nothing; an event the delivery does not subscribe to, a retention or deletion-order event among them, reaches no handler (ADR-0012).
AC4 Given the service starts, when liveness and readiness are probed, then readiness answers ready only after template-registry-sql is migrated and the messaging profile has started, and it names what is missing while it is unready; the four options of model/services/template-library/TemplateRegistryService.yaml are bound with their modelled defaults; a value that does not parse stops the start with the option named; a reloaded Templates:Catalog:DiscoverIntervalHours, Templates:Catalog:Runtimes or Templates:Feeds:PackageFeeds applies from the next pass or computation; and traces and logs carry the tenant of the call (ADR-0015, ADR-0028).
Traces: services TemplateRegistryService, KnowledgeIngestionService
Traces: aggregates TemplateRegistryService/TemplateVersion
Traces: events KnowledgeIngestionService/ChunksPublished
Traces: descriptors run-event-envelope-v1
Traces: adrs ADR-0012, ADR-0014, ADR-0015, ADR-0028
Traces: requirements NFR-13
Depends on AIFACTORY-US-701, feature:component-base-template-factory-profile, feature:contracts-package, feature:knowledge-ingestion-service-thin
Sources model/services/template-library/TemplateRegistryService.yaml, model/services/knowledge/KnowledgeIngestionService.yaml, model/gateways.yaml, docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md, docs/architecture/adr/0014-run-and-lifecycle-envelopes.md, docs/solution-packs/software-factory/templates/services/template-registry-service/index.md#apis, docs/solution-packs/software-factory/templates/services/template-registry-service/index.md#workers-and-jobs

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-135 API hosting skeleton: REST and gRPC hosts, scope and role policies, problem responses and contract documents for the 6 REST and 1 gRPC operations implementation The six REST routes and the gRPC method Catalog.ResolveManifest are hosted with JWT validation that accepts the audience of the gateway of the service, the scope of each route, the role policy that admits an Asset maintainer and a Platform admin of the platform tenant to DiscoverTemplates and PublishTemplateVersion and answers 403 to a caller of another tenant, the workload identity and service scope check on the gRPC method, problem responses for every modelled refusal code, and the OpenAPI and proto documents; no Idempotency-Key filter is hosted, because every operation declares the idempotency natural; the behaviour of each operation is delivered by AIFACTORY-US-704 to AIFACTORY-US-708, not here. ConnectSoft.AI.SoftwareFactory.TemplateRegistryService
AIFACTORY-TASK-136 Messaging skeleton: outbox and inbox wiring of the template-registry profile for 4 published events, 4 consumed events and the self-subscription that triggers the CompatibilityComputer implementation The outbox writer enlists in the unit of work of a command, a handler and a worker step, and the dispatcher of the template-registry messaging profile publishes TemplateVersionDiscovered, TemplateVersionPublished, LibraryVersionDiscovered and CompatibilityChecked in the run event envelope of the pinned contracts package; the inbox registers the four consumed events AssetReleasePublished, AssetReleaseDeprecated, PipelineRunCompleted and ChunksPublished and, as its fifth registration, the self-subscription to TemplateVersionDiscovered that triggers the CompatibilityComputer, each with deduplication on the event id; the RefreshDocs handler of ChunksPublished logs the snapshot and the source, changes no row and publishes nothing; no handler of a retention or deletion-order event is registered; what the other three handlers do is delivered by AIFACTORY-US-705 and AIFACTORY-US-708. ConnectSoft.AI.SoftwareFactory.TemplateRegistryService
AIFACTORY-TASK-137 Worker hosting skeleton: schedule, partitioning and retry policies of Discoverer and CompatibilityComputer implementation The two workers are hosted with their modelled triggers, retry policies, partitioning and idempotency keys: the Discoverer on the schedule that Templates:Catalog:DiscoverIntervalHours gives, two attempts 600 seconds apart, four in parallel by repository, keyed by repository and commit; the CompatibilityComputer on TemplateVersionDiscovered, two attempts 120 seconds apart, four in parallel by subject id, keyed by cell and evidence; a duplicate trigger has no second effect; what each worker does is delivered by AIFACTORY-US-704 and AIFACTORY-US-705. ConnectSoft.AI.SoftwareFactory.TemplateRegistryService
AIFACTORY-TASK-2833 Verify the hosted surface, the messaging profile and the worker hosts of TemplateRegistryService verification Run dotnet build -c Release and dotnet test -c Release --filter "Category=Acceptance&Feature=HostingSurface"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-702: the 401, 403, UNAUTHENTICATED and PERMISSION_DENIED answers of every route, the outbox record committed and rolled back with its change, the deduplicated inbox with the RefreshDocs handler under a fixture publisher of ChunksPublished, the duplicate worker trigger, readiness and the four bound options of model/services/template-library/TemplateRegistryService.yaml. ConnectSoft.AI.SoftwareFactory.TemplateRegistryService

AIFACTORY-US-703: TemplateRegistryService keeps its secrets as references, filters every row by tenant, reports its three series and recovers from an unreachable feed and a lost store

enabling · persona operator As an operator, I want to see how many versions the catalog holds, how many cells lack evidence and how far its inbox lags, and to know what the service does when a feed or its store is gone, so that I can tell a stale catalog from a broken one and recover it without guessing.

This PBI delivers the rules that every behaviour of the service runs under. Secrets: the model gives the service two, messaging-transport and package-feed, both in the key vault with a rotation of 90 days. Each is bound as a secret reference by name; no value is in configuration, in the image, in a log record or in telemetry, and a rotated value is picked up by reading the reference again and needs no new image. The service holds no credential of a template repository: it reaches repositories through the connectors of the Integration platform. Tenancy: the isolation of the model is the row filter. Every query runs under the tenant of the trusted scope, the rows of the platform tenant are readable by every tenant, and a row of any other tenant is invisible, so it never appears in a list and is answered 404, over gRPC NOT_FOUND, when addressed, the same answer as for an identifier that does not exist (ADR-0015 amendment D113). The filter admits the platform tenant for reading only: a command changes rows of the tenant of its caller, so the two commands of the service, which change rows of the platform tenant, answer 403 to a caller of another tenant (AIFACTORY-US-702). The data class of the catalog is internal. Telemetry: the service emits the three series of the model with their dimensions. connectsoft.factory.templates.versions is an up-down counter by kind, layer and state that moves with every version recorded and every state change, so the sum over the states is the number of versions of the catalog. connectsoft.factory.templates.compatibility_unknown is an up-down counter by subject kind that holds the number of cells without evidence. connectsoft.factory.templates.inbox_lag is a gauge in seconds by service that holds the age of the oldest unprocessed inbox message. Each is recorded through the helper of the pinned observability library (feature component-observability-factory-conventions), which puts the tenant, and the project where a call has one, on the instrument by default (ADR-0019); traces and logs carry the scope of the call, and no log record, activity or metric holds a token or a secret. Health: liveness needs no dependency; readiness reports template-registry-sql and the messaging profile; the health detail names the four outbound dependencies of the model with their state. ConnectorRegistryService and the Azure DevOps system are required and degrade, RepositoryIntelligenceService is optional and degrades, so their outage shows in the detail and leaves the service ready; AgentRegistryService is required and fail-fast, so a publication that needs it fails fast while the reads keep serving. The two failure modes of the model are built and written down. Feed unreachable: discovery errors are the detection signal; the last pinned manifests stay, new versions are not discovered until the feed is back, the cells stay as they were, and the reads serve the stale catalog; the next pass after the feed returns catches up, because a pass is idempotent on repository and commit. Service store lost: readiness is the detection signal; the store is restored from its backup, whose recovery point objective is 15 minutes, and a discovery pass then reads the manifests again from the template repositories and derives the compatibility again, which loses nothing because every row of the catalog is derived from a repository, a feed or an event. The objectives of the model, 360 minutes to recover from a feed outage and 240 minutes from a lost store, are measured once the system is deployed and no value is claimed here.

Acceptance criteria

AC1 Given the deployment manifest and the configuration of the service, when they are scanned together with the image and the captured logs of the acceptance suite, then messaging-transport and package-feed appear as secret references by name only and no secret value, token or feed credential is found; given a rotated value behind a reference, when the service reads the reference again, then it uses the new value without a new image (model/services/template-library/TemplateRegistryService.yaml).
AC2 Given rows of the platform tenant and of two other tenants in the three tables, when every read path of the service is exercised for a caller of one tenant, then only the rows of that tenant and of the platform tenant are returned, a row of the other tenant is answered 404 or NOT_FOUND when addressed, and an architecture test fails on a query that bypasses the tenant filter (ADR-0015).
AC3 Given a discovery pass, a computed cell and a delayed inbox message, when the metrics are read, then connectsoft.factory.templates.versions holds the versions by kind, layer and state, connectsoft.factory.templates.compatibility_unknown the cells without evidence by subject kind and connectsoft.factory.templates.inbox_lag the age of the oldest unprocessed message, each with the tenant the helper adds, and no log record, activity or metric holds a token or a secret (ADR-0019, model/services/template-library/TemplateRegistryService.yaml).
AC4 Given a feed that does not answer, when a discovery pass runs, then the error is logged and shown as degraded in the health detail, readiness stays ready, the pinned manifests and the cells stay as they were and the reads keep answering; given the store is lost and restored, when a discovery pass runs again, then the manifests are read again from the template sources and the cells derived again, and no version and no cell exists twice (NFR-18, docs/solution-packs/software-factory/templates/services/template-registry-service/index.md).
Traces: services TemplateRegistryService
Traces: adrs ADR-0015, ADR-0019, ADR-0028
Traces: requirements NFR-13, NFR-18
Depends on AIFACTORY-US-701, AIFACTORY-US-702, feature:component-observability-factory-conventions
Sources model/services/template-library/TemplateRegistryService.yaml, model/stores.yaml, docs/architecture/adr/0019-data-governance.md, docs/solution-packs/software-factory/templates/services/template-registry-service/index.md#security, docs/solution-packs/software-factory/templates/services/template-registry-service/index.md#metrics-and-observability, docs/solution-packs/software-factory/templates/services/template-registry-service/index.md#failure-and-recovery

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-138 Security, tenancy and telemetry of TemplateRegistryService implementation The two secrets of the model are bound as secret references by name and read again on rotation; every query runs under the tenant filter, which admits the platform tenant for reading; the three series connectsoft.factory.templates.versions, connectsoft.factory.templates.compatibility_unknown and connectsoft.factory.templates.inbox_lag are recorded with their modelled dimensions through the helper of the pinned observability library; the health detail names ConnectorRegistryService, AgentRegistryService, RepositoryIntelligenceService and the Azure DevOps system with their state, and only the store and the messaging profile decide readiness. ConnectSoft.AI.SoftwareFactory.TemplateRegistryService
AIFACTORY-TASK-2834 Runbook of the two failure modes of TemplateRegistryService documentation The repository documentation holds one runbook entry per failure mode of model/services/template-library/TemplateRegistryService.yaml, feed unreachable and service store lost, each with its detection signal, what the service keeps serving, the recovery step and the modelled objective; the entry of the lost store states the restore from backup, the discovery pass that reads the manifests again and the derivation of the cells, and that a pass is idempotent on repository and commit (NFR-18). ConnectSoft.AI.SoftwareFactory.TemplateRegistryService
AIFACTORY-TASK-2835 Verify secrets, tenancy, telemetry and the two failure modes of TemplateRegistryService verification Run dotnet build -c Release and dotnet test -c Release --filter "Category=Acceptance&Feature=SecretsTenancyTelemetry"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-703: the scan for secret values, the three-tenant read matrix with its architecture test, the three series with their dimensions, a feed that stops answering and a store that is emptied and filled again by a discovery pass over the recorded sources. ConnectSoft.AI.SoftwareFactory.TemplateRegistryService

AIFACTORY-US-704: Discover published template package versions and library versions on schedule or on demand, pin each manifest by hash at the commit of its package and announce each new version once

behavior · persona asset-maintainer As an asset maintainer, I want the catalog to read the template repositories and the feeds again on its schedule and whenever I ask, so that a new template or library version is in the catalog with what was really committed and published, and nobody types a manifest in.

The Discoverer is the only writer of new versions of the catalog. It runs on its schedule, at minute 0 of every sixth hour by default, and whenever a caller starts it through TemplateRegistryService/DiscoverTemplates. In one pass it reads every feed of Templates:Feeds:PackageFeeds and every template source through one source port. A template is consumed by its published package version and never by a path, so a TemplateVersion is one published version of the template package. For each version of the package of a template source that a feed lists and the catalog has not pinned, the pass takes the commit that package was built from, reads .template.config, the project files, the pipelines and the docs of the repository at that commit, builds the manifest of the model, that is the short name, the projects and their roles with the target frameworks their project files declare, the switches with their allowed values, the generated and preserved paths, the pipelines and the docs, computes the manifest hash and writes a TemplateVersion with the template id, the version of the package, the layer, the repository, the commit, the manifest, the manifest hash and the state Discovered. A commit of a template repository for which no package version is published on a feed creates no version, the head commit among them, so the catalog never pins what nobody can install, and a recipe that pins a version validates against the manifest of the commit its package was built from. The template id is the short name, which is the templates catalog id of model/templates.yaml. A template version is a published package version of the template, pinned at the commit its package states (D123). The version of a template package is given when the package is packed and .template.config holds none (Docs/Build Process.md of ConnectSoft.BaseTemplate), so the version comes from the feed. That documentation names no member of the package that states the commit it was built from, which is reported to the owner. The source port therefore returns the commit of a package version from the repository metadata of the package where the package carries it; a package version that states no commit is not pinned, creates no version and is logged with its package id and version. The layer of a template has no source in the model or in the documentation of the templates, which is reported to the owner as well: neither .template.config nor the package states it, and model/templates.yaml records it at design time only. The layer therefore comes from the entry of the template source, which names the template id, the repository, the package id and the layer. The switches of a manifest are the parameters the template declares in its own .template.config. The design-time snapshot of the same parameter contracts is model/template-parameters, and the catalog restates none of them: a fixture test compares the switches the Discoverer extracts from a recorded template source with the snapshot file of that template and fails on a parameter the snapshot has and the manifest lacks. A manifest is never edited in the catalog. A changed template becomes visible when a new version of its package is published: a package version that is already pinned and is found again with another commit or another manifest hash writes nothing and is logged with both commits and both hashes. The summary of the aggregate names the consumers of a template version, while its fields and the table TemplateVersions hold none and the model does not say what a consumer of a template version is, a template that extends it or a repository that was generated from it; the pass derives and stores none, and the gap is reported to the owner. For a library the pass reads the packages and their versions from the feed and the layer, the capability area, the options sections and the registration API from the repository, and writes a LibraryVersion with the library id, which is the libraries catalog id of model/libraries.yaml, and the templates that consume it, derived from the package references of the project files the pass has read. Its state follows the invariant of the model: a library version without a published package on the feed is Discovered and not Published, and one whose packages are published is recorded Published. Each new version is written together with its outbox record in one transaction: TemplateVersionDiscovered with templateId, version, layer and commit, and LibraryVersionDiscovered with libraryId, version, area and state. The envelope of each event names the platform tenant (D123). TemplateVersionDiscovered is published for every discovered version, whatever becomes of it later: until the evaluation gate of AgentRegistryService is delivered in I4 a recipe may bind a discovered version that is not yet Published, and GenerationRecipeService hears the version through this event as one a recipe may bind. The pass is idempotent on repository and commit: a package version whose commit is already pinned writes nothing and publishes nothing. Up to four repositories are read in parallel, partitioned by repository; a repository or a feed that cannot be read is tried a second time after 600 seconds and then left for the next pass, while the other repositories proceed. When a feed is unreachable the last pinned manifests stay, no new version is discovered until it is back and the cells stay as they were. A caller whose scope carries factory.catalog.admin, who is Asset maintainer or Platform admin and whose token names the platform tenant starts a pass now through TemplateRegistryService/DiscoverTemplates. The operation is of the shared-write class, has no modelled request body and answers 202: the pass runs after the answer. The command leaves evidence: the Factory sink of the audit library, consumed by a version pin from feature component-audit-factory-evidence, writes an audit-evidence-v1 record that names the actor and the action to the outbox in the transaction of the command, on the topic audit.evidence.v1.evidence-submitted in the run event envelope. Its idempotency is natural: a repeated call starts a pass that finds every published package version pinned and changes nothing. A pass that is lost with a replica is made up by the next scheduled pass. A call without a token is answered 401. A caller without the scope, a Requester or an Observer is answered 403, and so is an Asset maintainer or a Platform admin whose token names another tenant than the platform tenant, because through I4 only an administrator of the platform tenant discovers (D123); no pass starts and no evidence is written. The source port has two bindings. The acceptance suite binds it to recorded sources. A deployed instance binds it to the connector adapter this PBI builds: the adapter resolves the repositories capability of the Azure DevOps connector for the platform tenant through Connectors.ResolveCapability of ConnectorRegistryService. Because a connection is registered and granted to a project of a tenant through IntegrationHost from I1 (D129) and the request execution-scope-v1 of that call requires a projectId, the adapter forwards the template-feed project of the platform tenant, which it takes from configuration, and a deployed instance without that setting discovers nothing and logs that; which project of the platform tenant holds the grant of the template feeds is an owner input, an entry of the I1 precondition register of AIFACTORY-US-1339 that the owner supplies before the I1 run (D140). The adapter then reads the files of a repository at a commit from the Azure DevOps system through the connection that call returns, and lists the versions of a package on a feed of Templates:Feeds:PackageFeeds in Azure Artifacts with the secret reference package-feed. It stores no credential, and a read that fails, an unresolved connector among them, surfaces as the discovery error of the failure mode Feed unreachable. The adapter is contract-tested against a stub of the connector and of the Azure DevOps endpoints. The delivery states its limits, each reported to the owner. The model names the feeds in an option and names no option and no operation that lists the template repositories: the source port returns the template sources it is configured with, and a deployed instance whose port has no template source discovers no template, logs that and invents no list. The model names no operation of ConnectorRegistryService that returns repository content and gives the reply of Connectors.ResolveCapability the descriptor tool-invocation-v1, so the adapter calls the Azure DevOps system itself, and how the resolved connection authorizes that read is reported. The thin ConnectorRegistryService of this increment names the Azure DevOps connector for template feeds in its scope and does not list Connectors.ResolveCapability among the operations it answers, so the adapter is proven against the stub until that method is hosted. The model also names the GitHub connector and lists no GitHub system among the dependencies of the service; the adapter binds Azure DevOps, and a template source on GitHub is not read. RepositoryIntelligenceService is an optional dependency for the dependency graphs of template repositories: this delivery derives the consumers of a library from the package references it reads itself and waits for no graph. The consumers of the two events, StudioBff, AuditService and GenerationRecipeService, handle them in their own PBIs.

Acceptance criteria

AC1 Given a recorded template source whose package has a version on the recorded feed that is not yet pinned and that states the commit it was built from, when the scheduled trigger fires or a caller of the platform tenant with factory.catalog.admin who is Asset maintainer or Platform admin calls TemplateRegistryService/DiscoverTemplates, then the command answers 202 and writes one audit-evidence-v1 record with the actor to the outbox in its transaction, and the pass writes one TemplateRegistryService/TemplateVersion in state Discovered with the template id, the version of the package, the layer of the source entry, the repository, the commit of the package, the manifest read at that commit and the manifest hash, together with the TemplateRegistryService/TemplateVersionDiscovered outbox record in one transaction, whose envelope names the platform tenant; a head commit without a published package version and a package version that states no commit create no version (SCN-TemplateRegistryService-005, SCN-TemplateRegistryService-008, ADR-0014).
AC2 Given a recorded feed with a library whose packages are published and one whose packages are not, when the pass runs, then one TemplateRegistryService/LibraryVersion exists per library version with its packages, layer, area and consuming templates, the first in state Published and the second in state Discovered, each written with its TemplateRegistryService/LibraryVersionDiscovered outbox record, whose payload carries libraryId, version, area and state, in one transaction (SCN-TemplateRegistryService-010).
AC3 Given a pass that has pinned every published package version, when the trigger fires again or TemplateRegistryService/DiscoverTemplates is called again, then no row is written and no event is published; given a package version that is already pinned and is found again with another commit or another manifest hash, when the pass reads it, then the pinned TemplateRegistryService/TemplateVersion is unchanged, nothing is published and both commits and both hashes are logged; given a recorded template source and the snapshot file of that template under model/template-parameters, when the fixture test runs, then every parameter of the snapshot is a switch of the extracted manifest (SCN-TemplateRegistryService-005).
AC4 Given a call to TemplateRegistryService/DiscoverTemplates without a token, with a token that lacks factory.catalog.admin, by a Requester or an Observer, or by an Asset maintainer or a Platform admin whose token names another tenant than the platform tenant, when it arrives, then the answer is 401 for the first and 403 for the others with a problem response, no pass starts, no evidence record is written and no state changes (SCN-TemplateRegistryService-005, ADR-0015).
AC5 Given a feed or a template source that does not answer, when the pass runs, then that source is tried a second time after 600 seconds and then left for the next pass, the versions already pinned stay as they were, the other sources are read, and no event is published for the failed source; given the connector adapter of the source port with a stub of ConnectorRegistryService and of the Azure DevOps endpoints, when its contract tests run, then it resolves the connector through Connectors.ResolveCapability, reads a repository at a commit and lists the versions of a package on a feed with the secret reference package-feed, and a failed read or an unresolved connector surfaces as the same discovery error; given the transport is unavailable when the dispatcher publishes TemplateRegistryService/TemplateVersionDiscovered on template-catalog.templates.v1.template-version-discovered or TemplateRegistryService/LibraryVersionDiscovered on template-catalog.libraries.v1.library-version-discovered, then the committed rows stand and the outbox retries with backoff, so the event is neither lost nor duplicated under its event id (SCN-TemplateRegistryService-008, SCN-TemplateRegistryService-010, ADR-0012).
Traces: services TemplateRegistryService, ConnectorRegistryService
Traces: aggregates TemplateRegistryService/TemplateVersion, TemplateRegistryService/LibraryVersion
Traces: apis TemplateRegistryService/DiscoverTemplates
Traces: events TemplateRegistryService/TemplateVersionDiscovered, TemplateRegistryService/LibraryVersionDiscovered
Traces: descriptors run-event-envelope-v1, audit-evidence-v1
Traces: adrs ADR-0012, ADR-0014, ADR-0015
Traces: requirements NFR-13
Traces: scenarios SCN-TemplateRegistryService-005, SCN-TemplateRegistryService-008, SCN-TemplateRegistryService-010
Relates: screens template-catalog
Depends on AIFACTORY-US-701, AIFACTORY-US-702, feature:connector-registry-service-thin, feature:component-audit-factory-evidence
Sources model/services/template-library/TemplateRegistryService.yaml, model/templates.yaml, model/libraries.yaml, model/template-parameters/connectsoft-base.yaml, model/services/integration/ConnectorRegistryService.yaml, docs/reference/schemas/audit-evidence.schema.json, docs/solution-packs/software-factory/templates/parameters.md, docs/solution-packs/software-factory/templates/services/template-registry-service/index.md#workers-and-jobs

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-2836 Source port of the Discoverer with recorded template sources and a recorded feed for the acceptance suite fixture One source port returns the template sources, each with template id, repository, package id and layer, and the package feeds, lists the published versions of a package with the commit each states, and reads a repository at a commit; the acceptance suite binds it to recorded sources, that is the .template.config, project files, pipelines and docs of two templates at two commits each, a recorded feed with one package version per recorded commit, a head commit without a package version, a package version that states no commit, and a published and an unpublished library version, and can make one source stop answering; a port without a configured template source returns none and the pass logs that. ConnectSoft.AI.SoftwareFactory.TemplateRegistryService
AIFACTORY-TASK-2868 Connector adapter of the source port for a deployed instance, with its contract tests against a stub of the connector implementation The adapter of the source port resolves the repositories capability of the Azure DevOps connector for the platform tenant through Connectors.ResolveCapability of ConnectorRegistryService with the template-feed project of the platform tenant from configuration as the projectId of execution-scope-v1 (D129), discovers nothing and logs that when the setting is absent, reads the files of a repository at a commit from the Azure DevOps system through the resolved connection, lists the versions of a package on a feed of Templates:Feeds:PackageFeeds with the secret reference package-feed and returns the commit a package version states in its repository metadata; it stores no credential; its contract tests run against a stub of the connector and of the Azure DevOps endpoints and prove a resolved read, a package version without a commit, and that a failed read or an unresolved connector surfaces as the discovery error of the failure mode Feed unreachable of model/services/template-library/TemplateRegistryService.yaml; the deployment manifest of AIFACTORY-TASK-2831 binds this adapter, and the acceptance suite binds the recorded sources of AIFACTORY-TASK-2836. ConnectSoft.AI.SoftwareFactory.TemplateRegistryService
AIFACTORY-TASK-2837 Discoverer pass that pins template manifests by hash and records library versions with their events implementation The pass lists the published package versions of each template source, takes the commit of each version that is not pinned, builds the manifest from the files of the repository at that commit, with the target frameworks of the project files, computes the manifest hash and writes the TemplateVersion in state Discovered with the version of the package and the layer of the source entry, with TemplateVersionDiscovered in one transaction; it creates no version for a commit without a published package version or for a package version that states no commit, and derives no consumers of a template version; it writes a LibraryVersion with its packages, area, layer and consumers, Published only when its packages are on the feed, with LibraryVersionDiscovered in one transaction; it is idempotent on repository and commit, writes nothing for a package version that is pinned and found again with another commit or hash and logs both, tries a failed source a second time after 600 seconds and leaves it for the next pass. ConnectSoft.AI.SoftwareFactory.TemplateRegistryService
AIFACTORY-TASK-2838 DiscoverTemplates command with its role policy, its audit evidence and the pass it starts implementation DiscoverTemplates admits a caller of the platform tenant with factory.catalog.admin who is Asset maintainer or Platform admin, writes one audit-evidence-v1 record with the actor through the Factory sink of the pinned audit library to the outbox in its transaction, on the topic audit.evidence.v1.evidence-submitted, answers 202 and starts one pass of the Discoverer out of schedule; a missing token is answered 401, and a missing scope, a Requester, an Observer and a caller of another tenant than the platform tenant 403, each with a problem response and without a pass. ConnectSoft.AI.SoftwareFactory.TemplateRegistryService
AIFACTORY-TASK-2839 Verify discovery through the acceptance suite verification Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-TemplateRegistryService-005\|Scenario=SCN-TemplateRegistryService-008\|Scenario=SCN-TemplateRegistryService-010)"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-704 over the recorded sources: one pinned version per published package version with its commit, its events and payloads, no version for a head commit without a package or for a package without a commit, the evidence record of the command, the idempotent second pass, the package version found again with another commit or hash, the comparison with the snapshot under model/template-parameters, the refusals, a caller of another tenant among them, a source that stops answering and the contract tests of the connector adapter against the stub; consumer handling is proven by the suites of the consumers. ConnectSoft.AI.SoftwareFactory.TemplateRegistryService

AIFACTORY-US-705: Compute the compatibility matrix cell by cell, Compatible only for what a build of the platform tenant proves and Unknown otherwise, and answer queries over it

behavior · persona asset-maintainer As an asset maintainer, I want the catalog to say for each template or library version what it was proven to work with, and to say Unknown where nothing was proven, so that a recipe is validated against evidence and never against an assumption.

The compatibility matrix answers whether a template or library version works with a library version, a runtime, a Factory edition or a topology, and it answers only on evidence. One CompatibilityEntry is one cell: the subject kind, template or library, the subject id and version, the kind it is checked with, the id and optional version of that, the result and the evidence reference. The CompatibilityComputer runs on TemplateVersionDiscovered. For the new version it computes the cells from the pinned manifest and its package references: one cell for each library version the template references and one for each runtime of Templates:Catalog:Runtimes, by default net9.0 and net10.0. The invariant of the model decides the result: a cell is Compatible only with evidence, a build or a conformance run, and without evidence it is Unknown. Each cell that is new or whose result or evidence changed is written with its CompatibilityChecked outbox record in one transaction; the payload carries entryId, subjectKind, subjectId, subjectVersion, withKind, withId and result, and the envelope names the platform tenant (D123). The computer is keyed by cell and evidence: a computation that finds the same cell with the same evidence writes nothing and publishes nothing, and the unique index over the six identifying columns keeps one row per cell. Up to four subjects are computed in parallel, partitioned by subject id, and a failed computation is tried a second time after 120 seconds. Evidence arrives through the inbox handler RecordBuildEvidence of PipelineRunCompleted, because a build of a template repository is compatibility evidence. The event carries pipelineRunId, tenantId, projectId, commit, state and results. Only a succeeded run of the tenant that owns the template version, which is the platform tenant, is evidence: a run of another tenant on the same commit, the build of a fork of a template repository for example, changes no cell and is acknowledged without effect, and so is a run that did not succeed. What a build proves is limited. It proves the library cells of the version, because the run restored and compiled the package references of that commit, and the runtime cells whose runtime is one of the target frameworks the project files of the pinned manifest declare, because those are the frameworks the run built. Every other cell stays Unknown: with the default runtimes and a template whose projects target net10.0, the net10.0 cell becomes Compatible and the net9.0 cell stays Unknown. The model names no rule that maps a pipeline run to runtime cells and leaves the content of results open, so the target frameworks of the pinned manifest are the source this delivery uses, and the rule is reported to the owner. The normal order of events is that the run completes before the version exists: the build of a template repository ends shortly after the commit, while the Discoverer pins the package of that commit on a later pass. A succeeded run of the platform tenant is therefore never dropped. When the commit of the event is the commit of a pinned version, the handler records the pipeline run as the evidence reference of the cells the build proves and moves them from Unknown to Compatible, each with its CompatibilityChecked record in the same transaction; a cell that is already Compatible keeps its evidence reference, so a second succeeded run of the same commit changes nothing. When no version is pinned at that commit yet, the handler writes one row of PendingBuildEvidence with the tenant, the pipeline run id, the commit, the typed results of the run and the time of receipt, and changes no cell. The model makes build evidence an input of the CompatibilityComputer: when the computer runs on TemplateVersionDiscovered for a version of that commit, it reads the pending record, writes the cells the build proves as Compatible with that run as evidence and the others as Unknown, and deletes the pending record in the same transaction. The handler is idempotent on the event id and the pending record is keyed by tenant and pipeline run id, so a redelivered event writes nothing twice. PendingBuildEvidence is the table of template-registry-sql the model gives this evidence (D123): keyed by tenant and pipeline run id, with the commit, the typed results and the time of receipt and an index over tenant and commit. This PBI migrates it under the tenant row filter of every mapping. A pending record whose commit never becomes a template version, the run of a repository that is no template for example, stays; this delivery builds no deletion for it, and its retention is reported to the owner. The thin PipelineExecutionService of this increment publishes no pipeline run event, so the handler is built and proven with a fixture publisher until its complete delivery in I2. A caller whose scope carries factory.catalog.read reads the matrix through TemplateRegistryService/QueryCompatibility: the query names a template or library version and may narrow the kind it is checked with, and the response is 200 with the cells of that subject, each with its result, its evidence reference and the time of the check. The read runs under the tenant row filter, returns the cells of the tenant of the caller and of the platform tenant, writes nothing and calls no other service; the operation lists the code 200 only, so a subject without cells returns an empty list. A call without a token is answered 401 and a token without the scope 403. connectsoft.factory.templates.compatibility_unknown moves with every cell that becomes or stops being Unknown. The delivery states its limits, each reported to the owner. The model names four results and no rule that turns evidence into Incompatible or CompatibleWithWarnings: this delivery writes Compatible for a library cell, or for a runtime cell of a framework the version targets, whose evidence is a succeeded build of the pinned commit in the platform tenant, and Unknown for a cell without evidence, a run that did not succeed changes no cell, and the aggregate, the read and the event carry all four values. The model names the runtimes in an option and no source for the editions and the topologies a cell is computed for, so the computer enumerates library and runtime cells, while a cell of any kind the aggregate allows is stored, read and announced. Conformance runs as scheduled evidence are a later capability of the service page, and no source of them exists in the model. GenerationRecipeService and StudioBff handle CompatibilityChecked in their own PBIs.

Acceptance criteria

AC1 Given a TemplateRegistryService/TemplateVersionDiscovered for a version whose manifest references two library versions, Templates:Catalog:Runtimes at its default and no build evidence for the commit of the version, when the CompatibilityComputer runs, then one TemplateRegistryService/CompatibilityEntry exists for each of the two libraries and for each of the two runtimes, each with the result Unknown and no evidence reference, and each was written together with its TemplateRegistryService/CompatibilityChecked outbox record in one transaction (SCN-TemplateRegistryService-011, ADR-0014).
AC2 Given the cells of AC1 for a version whose pinned manifest declares the target framework net10.0 and a fixture publisher of PipelineExecutionService/PipelineRunCompleted with a succeeded run of the platform tenant for the commit of the version, when RecordBuildEvidence handles the event, then the two library cells and the net10.0 runtime cell move to Compatible with the pipeline run as evidence reference, the net9.0 runtime cell stays Unknown, and one TemplateRegistryService/CompatibilityChecked is recorded per changed cell in the same transaction; the same event id delivered twice changes the cells once; a run that did not succeed, and a succeeded run of another tenant with the same commit, change no cell (SCN-TemplateRegistryService-011).
AC3 Given a succeeded run of the platform tenant for a commit at which no TemplateRegistryService/TemplateVersion is pinned yet, when RecordBuildEvidence handles the event, then one row of PendingBuildEvidence with the tenant, the pipeline run id, the commit and the typed results of the run is written and no cell changes; when the version of that commit is discovered afterwards and the CompatibilityComputer runs on TemplateRegistryService/TemplateVersionDiscovered, then the library cells and the runtime cells of its target frameworks are written Compatible with that run as evidence reference and every other cell Unknown, each with its TemplateRegistryService/CompatibilityChecked record, and the pending record is deleted in the same transaction (SCN-TemplateRegistryService-011, model/services/template-library/TemplateRegistryService.yaml).
AC4 Given a caller with factory.catalog.read and cells of the platform tenant and of two other tenants, when TemplateRegistryService/QueryCompatibility is called for a template version, then the response is 200 with the cells of that version that belong to the platform tenant or to the tenant of the caller, each with result, evidence reference and time of the check, a subject without cells returns an empty list and nothing is written; a call without a token is answered 401 and a token without the scope 403 (SCN-TemplateRegistryService-004, ADR-0015).
AC5 Given a committed cell, when the dispatcher of the template-registry messaging profile publishes TemplateRegistryService/CompatibilityChecked on template-catalog.compatibility.v1.compatibility-checked, then the event is sent in the run event envelope with entryId, subjectKind, subjectId, subjectVersion, withKind, withId and result, and a transport outage is retried with backoff so the event is neither lost nor duplicated under its event id; when the computer is triggered again with the same evidence, or the same trigger fires twice, then no row is written and nothing is published, and no TemplateRegistryService/CompatibilityEntry is Compatible without an evidence reference; connectsoft.factory.templates.compatibility_unknown equals the number of cells without evidence (SCN-TemplateRegistryService-011, ADR-0012, NFR-13).
Traces: services TemplateRegistryService, PipelineExecutionService
Traces: aggregates TemplateRegistryService/CompatibilityEntry, TemplateRegistryService/TemplateVersion
Traces: apis TemplateRegistryService/QueryCompatibility
Traces: events TemplateRegistryService/CompatibilityChecked, TemplateRegistryService/TemplateVersionDiscovered, PipelineExecutionService/PipelineRunCompleted
Traces: descriptors run-event-envelope-v1
Traces: adrs ADR-0012, ADR-0014, ADR-0015
Traces: requirements NFR-13
Traces: scenarios SCN-TemplateRegistryService-004, SCN-TemplateRegistryService-011
Relates: screens template-catalog, recipes
Depends on AIFACTORY-US-701, AIFACTORY-US-702, AIFACTORY-US-704, feature:pipeline-execution-service-thin
Sources model/services/template-library/TemplateRegistryService.yaml, model/services/devops-gitops/PipelineExecutionService.yaml, model/stores.yaml, docs/solution-packs/software-factory/templates/compatibility-model.md, docs/solution-packs/software-factory/templates/services/template-registry-service/index.md#workers-and-jobs

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-2840 CompatibilityComputer that writes library and runtime cells with CompatibilityChecked and applies build evidence that preceded discovery implementation On TemplateVersionDiscovered the computer derives one cell per referenced library version and one per runtime of Templates:Catalog:Runtimes from the pinned manifest and reads the pending build evidence record of the commit of the version; where one exists it writes the cells the build proves, that is the library cells and the runtime cells of the target frameworks of the pinned manifest, as Compatible with that run as evidence reference and deletes the pending record in the same transaction; every other cell is written Unknown; each new or changed CompatibilityEntry is written with its CompatibilityChecked outbox record in one transaction; the computer is keyed by cell and evidence so that a repeated computation writes nothing, and moves connectsoft.factory.templates.compatibility_unknown with every cell that becomes or stops being Unknown. ConnectSoft.AI.SoftwareFactory.TemplateRegistryService
AIFACTORY-TASK-2867 Table PendingBuildEvidence in template-registry-sql for build evidence that precedes discovery migration A migration and a mapping add the table PendingBuildEvidence to template-registry-sql as model/services/template-library/TemplateRegistryService.yaml lists it (D123), keyed by tenant and pipeline run id, with commit, typed results and time of receipt, the index IX_PendingBuildEvidence_Commit over tenant and commit and the tenant row filter; mapping tests on an isolated test database prove that a second row for one tenant and pipeline run id violates the key and that a query made for one tenant returns no row of another; the contract notes of the repository record that no deletion of a pending record whose commit never becomes a template version is built. ConnectSoft.AI.SoftwareFactory.TemplateRegistryService
AIFACTORY-TASK-2841 RecordBuildEvidence inbox handler of PipelineRunCompleted with its fixture publisher implementation The handler takes a succeeded PipelineRunCompleted of the platform tenant as evidence and acknowledges without effect a run that did not succeed and a run of another tenant; when the commit of the event is the commit of a pinned template version it records the run as the evidence reference of the library cells and of the runtime cells of the target frameworks of the pinned manifest, moves them from Unknown to Compatible with CompatibilityChecked in the same transaction and leaves every other cell Unknown; when no version is pinned at that commit it writes one row of PendingBuildEvidence, keyed by tenant and pipeline run id, with the commit and the typed results of the run, and changes no cell; it is idempotent on the event id; the acceptance suite holds a fixture publisher of the event, because the thin PipelineExecutionService publishes none. ConnectSoft.AI.SoftwareFactory.TemplateRegistryService
AIFACTORY-TASK-2842 QueryCompatibility read over the cells of a template or library version implementation QueryCompatibility returns, for the subject the query names and the optional kind it narrows to, the cells of the tenant of the caller and of the platform tenant with result, evidence reference and time of the check, an empty list for a subject without cells, 401 without a token and 403 without factory.catalog.read; it writes nothing and calls no other service. ConnectSoft.AI.SoftwareFactory.TemplateRegistryService
AIFACTORY-TASK-2843 Verify the compatibility matrix through the acceptance suite verification Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-TemplateRegistryService-004\|Scenario=SCN-TemplateRegistryService-011)"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-705: the Unknown cells of a discovered version, the move of the library cells and of the net10.0 runtime cell to Compatible under a fixture publisher of PipelineRunCompleted while the net9.0 cell stays Unknown, a run of another tenant with the same commit that changes no cell, the order run completed and then version discovered, which ends with the same cells Compatible and the pending record deleted, the repeated computation without effect, the three-tenant read with its refusals, and the publication and payload of CompatibilityChecked; consumer handling is proven by the suites of the consumers. ConnectSoft.AI.SoftwareFactory.TemplateRegistryService

AIFACTORY-US-706: Read the catalog: list template versions, read one pinned manifest with its compatibility and list library versions, inside the tenant

behavior · persona requester As a requester, I want to see which template and library versions exist, in which state, and what exactly one template version generates, so that I choose building material for a recipe from what the catalog pinned and never from a name I remember.

A caller whose scope carries factory.catalog.read reads the catalog through three operations. A requester who prepares a recipe, an Asset maintainer, a Platform admin and an Observer are the four roles the model admits, and from I3 the template catalog screen of the Studio reads the same operations through StudioBff and the gateway. TemplateRegistryService/ListTemplates returns the template versions with their layer, state and switches, paged: it is the generated template catalog of this site at run time. It hides no version for its state: a Discovered version, which a recipe may bind until the evaluation gate of AgentRegistryService is delivered in I4 (D123), is listed with that state. The summary of the operation also names consumers. The model does not say what a consumer of a template version is, gives the aggregate no field and the table TemplateVersions no column for it, and the Discoverer derives none (AIFACTORY-US-704). Until the owner decides, the response carries the field consumers as an empty list for every template version, so the contract of the operation keeps its shape and no value is invented; the gap is reported to the owner. TemplateRegistryService/GetTemplateVersion addresses one version by templateId and version and returns the pinned manifest with its projects and their roles, its switches with their allowed values, its generated and preserved paths, its pipelines and its docs, together with the repository and the commit it was read from, the manifest hash, the state, the release id once the version is Published, and the compatibility cells of the version. TemplateRegistryService/ListLibraries returns the library versions by capability area and layer with their packages, their versions on the feed, their state and the templates that consume them, paged. The three reads run under the tenant row filter of the service: a caller reads the rows of its own tenant and those of the platform tenant, which holds the templates and libraries ConnectSoft publishes and is readable by every tenant. Through I4 the catalog holds the rows of the platform tenant only (D123), so on a deployed instance every tenant reads the same catalog, and the filter is proven with seeded rows of other tenants. A row of another tenant never appears in a list, and a version of another tenant that is addressed is answered 404, the same answer as for a templateId and version that do not exist, so the response never confirms that it exists (ADR-0015 amendment D113). A call without a token or with an expired token is answered 401 and a token without factory.catalog.read 403. The reads write nothing, publish nothing and call no other service: they depend on template-registry-sql alone. What they return is what the last discovery pass pinned, so while a feed or a connector is unreachable they keep answering from the stale catalog, which is the data impact the model names for that failure mode; when the store itself is unavailable, readiness is unready and a read fails fast with a problem response. A switch is returned as the manifest holds it, with its name and its allowed values as read from the .template.config of the template at the pinned commit; the reads add no parameter and no default of their own. The reads belong to the interactive class of the model, whose objective is an acknowledgement within 2 seconds at p95; it is measured once the system is deployed and no value is claimed here. The operations are reached through TemplateCatalogHost, the gateway of the platform, which is delivered in the same increment (D123), with a token whose audience is that gateway.

Acceptance criteria

AC1 Given a caller with factory.catalog.read and template versions of the platform tenant and of two other tenants, when TemplateRegistryService/ListTemplates is called with a page cursor, then the response is 200 with the versions of the platform tenant and of the tenant of the caller only, each with template id, version, layer, state and switches and with the field consumers as an empty list, because the model defines no consumer of a template version, paged, and nothing is written (SCN-TemplateRegistryService-001, ADR-0015).
AC2 Given a pinned TemplateRegistryService/TemplateVersion the caller can read, when TemplateRegistryService/GetTemplateVersion is called with its templateId and version, then the response is 200 with the manifest as it was pinned, that is projects and roles, switches with allowed values, generated and preserved paths, pipelines and docs, with repository, commit, manifest hash and state, the release id when the version is Published or Deprecated, and each TemplateRegistryService/CompatibilityEntry of the version with its result and evidence reference (SCN-TemplateRegistryService-002).
AC3 Given a templateId and version that do not exist, or that exist only in another tenant that is not the platform tenant, when TemplateRegistryService/GetTemplateVersion is called, then the response is 404 in both cases with the same problem response; a call without a token is answered 401 and a token without factory.catalog.read 403; no state changes (SCN-TemplateRegistryService-002, ADR-0015).
AC4 Given a caller with factory.catalog.read and library versions of two capability areas, one of them without a published package, when TemplateRegistryService/ListLibraries is called with a filter on area, then the response is 200 with each TemplateRegistryService/LibraryVersion of that area that the caller can read, with layer, packages, state and consuming templates, the version without a published package in state Discovered, and nothing is written (SCN-TemplateRegistryService-003).
AC5 Given the feed and the connectors do not answer, when the three reads are called, then each answers 200 from the rows the last pass pinned; given template-registry-sql is unavailable, when a read is called, then it fails fast with a problem response, readiness is unready and no state changes (SCN-TemplateRegistryService-001, SCN-TemplateRegistryService-003, model/services/template-library/TemplateRegistryService.yaml).
Traces: services TemplateRegistryService
Traces: aggregates TemplateRegistryService/TemplateVersion, TemplateRegistryService/LibraryVersion, TemplateRegistryService/CompatibilityEntry
Traces: apis TemplateRegistryService/ListTemplates, TemplateRegistryService/GetTemplateVersion, TemplateRegistryService/ListLibraries
Traces: adrs ADR-0015
Traces: requirements FUX-03
Traces: scenarios SCN-TemplateRegistryService-001, SCN-TemplateRegistryService-002, SCN-TemplateRegistryService-003
Relates: screens template-catalog
Relates: nfrs NFR-07
Depends on AIFACTORY-US-701, AIFACTORY-US-702
Sources model/services/template-library/TemplateRegistryService.yaml, model/ux/screens.yaml, docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md, docs/solution-packs/software-factory/templates/ui.md, docs/solution-packs/software-factory/templates/services/template-registry-service/index.md#apis

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-2844 ListTemplates, GetTemplateVersion and ListLibraries read models with the tenant row filter and paging implementation ListTemplates returns the template versions with layer, state and switches, paged, and the field consumers as an empty list until the owner decides what a consumer of a template version is; GetTemplateVersion returns the pinned manifest with repository, commit, manifest hash, state, release id and the cells of the version; ListLibraries returns the library versions by area and layer with packages, state and consumers, paged; all three apply the tenant row filter, which admits the platform tenant, so a version of another tenant is answered 404, the same answer as for one that does not exist (ADR-0015), a missing scope is 403 and a missing token 401; the reads write nothing and call no other service. ConnectSoft.AI.SoftwareFactory.TemplateRegistryService
AIFACTORY-TASK-2845 Catalog seed of three tenants for the read tests of the acceptance suite fixture The acceptance suite seeds template versions, library versions and cells of the platform tenant and of two other tenants on an isolated test database, among them a Published version with a release id, a library version without a published package and versions of two capability areas, and issues tokens for the matrix of role and tenant, including a token without factory.catalog.read and an expired token. ConnectSoft.AI.SoftwareFactory.TemplateRegistryService
AIFACTORY-TASK-2846 Verify the catalog reads through the acceptance suite verification Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-TemplateRegistryService-001\|Scenario=SCN-TemplateRegistryService-002\|Scenario=SCN-TemplateRegistryService-003)"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-706 over the three-tenant seed: the two lists with their filters and pages, the manifest of one version with its cells, the 404 that is the same for an unknown version and one of another tenant, the 401 and 403 answers, the reads during a feed outage and the failing read while the store is unavailable. ConnectSoft.AI.SoftwareFactory.TemplateRegistryService

AIFACTORY-US-707: Resolve the pinned manifest of a template version for a recipe or an agent over the internal gRPC method

behavior A workload asks the catalog for the pinned manifest of one template version through the internal gRPC method TemplateRegistryService/Catalog.ResolveManifest. The model names its callers: GenerationRecipeService, which validates the modules of a recipe against manifests and switches and pins what it validated, BlueprintService, whose Validator evaluates the rule MOD-002 of a Module Blueprint against the manifest of the template version the blueprint pins (D123), and AgentRuntimeWorker, through which agents read manifests during a generation run and which arrives in I3. The method is unary and of the read class. The caller presents a workload token that holds the service scope which names TemplateRegistryService; such a token carries no tenant claim, and the service reads the tenant and the project the caller forwards in the call metadata only because the token holds that scope (ADR-0015 amendment D114). The request names a template id and a version. The reply carries the manifest as the Discoverer pinned it, that is the projects and their roles, the switches with their allowed values, the generated and preserved paths, the pipelines and the docs, with the repository, the commit, the manifest hash, the state and, once an asset release exists, the release id. The same template id and version always resolve to the same manifest and the same hash, because a version is one published version of the template package, pinned at the commit that package was built from, and a manifest is never edited in the catalog, so a recipe that pinned a version validates against the manifest of the package it generates from. The method writes nothing and publishes nothing. It resolves every version the forwarded tenant can read, its own and those of the platform tenant, and states the state of the version in the reply. It refuses no version for its state: until the evaluation gate of AgentRegistryService is delivered in I4 the Draft allowance lets a recipe bind a version the catalog has discovered that is not yet Published, so the method serves such a version like a Published one (D123). The rule that arrives in I4, that only a Published version may be selected by a generation recipe, and the rule that a Deprecated version may be upgraded from and never generated with are applied by GenerationRecipeService in its validation with the state this reply carries. A call without a workload identity is refused with UNAUTHENTICATED; a workload token without the service scope, and a user token, which holds no service scope, with PERMISSION_DENIED; a request without a template id or a version with INVALID_ARGUMENT; a version that does not exist, or that belongs to another tenant that is not the platform tenant, with NOT_FOUND, the same status in both cases, and a caller that receives it takes the failure class permanent (ADR-0015 amendment D114). When template-registry-sql is unavailable the call fails fast with UNAVAILABLE; GenerationRecipeService and BlueprintService each declare this dependency fail-fast and decide what their own call does then; BlueprintService answers 503 on the validation of a Module Blueprint (D123). The contract of the method needs a decision of the owner. The model declares release-manifest-v1 as the schema of both messages. That descriptor is the manifest of an asset release of AgentRegistryService: it closes its members, has none for the projects, switches and paths of a template manifest, requires the publication fields of a release and knows the states of a release, not those of the catalog. A version that is Discovered or Verified has no release, so the reply of this method cannot be an instance of it. This delivery therefore declares in the proto a request with template id and version and a reply with the fields of the TemplateVersion, records the difference to the declared descriptor in the contract notes of the repository, and changes nothing in the contracts package; which descriptor the method carries is reported to the owner. The method is also reachable through the gRPC route of TemplateCatalogHost, which is delivered in the same increment (D123), under the same token rule.

Acceptance criteria

AC1 Given a workload token that holds the service scope of TemplateRegistryService and forwarded tenant metadata, when TemplateRegistryService/Catalog.ResolveManifest is called with the template id and the version of a pinned TemplateRegistryService/TemplateVersion, then the reply carries the manifest with its projects, switches, generated and preserved paths, pipelines and docs, the repository, the commit, the manifest hash and the state, equal to what the store holds; a second call returns the same reply, and nothing is written or published (SCN-TemplateRegistryService-007).
AC2 Given a call without a workload identity, a workload token without the service scope, a user token, or a request without a template id or a version, when TemplateRegistryService/Catalog.ResolveManifest is called, then the status is UNAUTHENTICATED for the first, PERMISSION_DENIED for the second and the third and INVALID_ARGUMENT for the fourth, and no state changes (SCN-TemplateRegistryService-007, ADR-0015).
AC3 Given versions of the platform tenant and of two other tenants, when the method is called with the forwarded tenant of one of them, then a version of that tenant and a version of the platform tenant resolve, and a version of the other tenant and a version that does not exist are both answered NOT_FOUND, which never confirms that a foreign version exists (SCN-TemplateRegistryService-007, ADR-0015).
AC4 Given versions in the states Discovered, Verified, Published and Deprecated, when each is resolved, then every one of them resolves, the Discovered and the Verified one under the Draft allowance until I4 (D123), the reply states the state of the version and carries a release id only for the Published and the Deprecated one; given template-registry-sql is unavailable, when the method is called, then the status is UNAVAILABLE and no state changes; the proto of the method and the note on release-manifest-v1 are in the repository as the contract task leaves them (SCN-TemplateRegistryService-007, docs/reference/schemas/release-manifest.schema.json).
Traces: services TemplateRegistryService, GenerationRecipeService, BlueprintService
Traces: aggregates TemplateRegistryService/TemplateVersion
Traces: apis TemplateRegistryService/Catalog.ResolveManifest
Traces: descriptors release-manifest-v1
Traces: adrs ADR-0015
Traces: requirements NFR-13
Traces: scenarios SCN-TemplateRegistryService-007
Relates: screens recipes
Depends on AIFACTORY-US-701, AIFACTORY-US-702
Sources model/services/template-library/TemplateRegistryService.yaml, model/services/template-library/GenerationRecipeService.yaml, model/services/template-library/BlueprintService.yaml, model/descriptors.yaml, docs/reference/schemas/release-manifest.schema.json, docs/solution-packs/software-factory/templates/services/template-registry-service/index.md#apis

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-2847 Proto of Catalog.ResolveManifest and the contract note on the declared descriptor contract The proto of the service declares Catalog.ResolveManifest as a unary method with a request that names template id and version and a reply that carries the manifest, repository, commit, manifest hash, state and release id of the TemplateVersion; the contract notes of the repository record that model/services/template-library/TemplateRegistryService.yaml declares release-manifest-v1 for both messages, that docs/reference/schemas/release-manifest.schema.json has no member for a template manifest and requires the fields of a published release, and that the descriptor of the method waits for the decision of the owner; the contracts package is not changed. ConnectSoft.AI.SoftwareFactory.TemplateRegistryService
AIFACTORY-TASK-2848 Catalog.ResolveManifest with the workload scope check and the forwarded tenant implementation The method requires a workload identity whose token holds the service scope of TemplateRegistryService, reads the forwarded tenant and project only under that scope, resolves a version of that tenant or of the platform tenant to its pinned manifest with its state, whatever that state is, a Discovered version included (D123), and answers UNAUTHENTICATED, PERMISSION_DENIED, INVALID_ARGUMENT, NOT_FOUND for an unknown version and for one of another tenant alike (ADR-0015), and UNAVAILABLE when the store does not answer; it writes nothing. ConnectSoft.AI.SoftwareFactory.TemplateRegistryService
AIFACTORY-TASK-2849 Verify the manifest resolution through the acceptance suite verification Run dotnet test -c Release --filter "Category=Acceptance&Scenario=SCN-TemplateRegistryService-007"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-707 over the three-tenant seed of AIFACTORY-TASK-2845: the reply equal to the stored manifest and repeated unchanged, the four refusal statuses, NOT_FOUND for an unknown and for a foreign version, the state and the release id per catalog state, and UNAVAILABLE while the store is stopped. ConnectSoft.AI.SoftwareFactory.TemplateRegistryService

AIFACTORY-US-708: Submit a Verified template version to Asset Publication and mirror its published and its deprecated release in the catalog

behavior · persona asset-maintainer As an asset maintainer, I want to submit a Verified template version for publication and see the catalog follow what Asset Publication decides, so that a template version becomes Published only through review, and nobody marks a version Published by hand.

A template version becomes Published through Asset Publication like any asset (ADR-0021): the state Published of the catalog mirrors the asset release and is never set by a caller. A caller whose scope carries factory.catalog.admin and who is Asset maintainer or Platform admin calls TemplateRegistryService/PublishTemplateVersion for a templateId and a version. Through I4 only an administrator of the platform tenant publishes (D123): the command is admitted only for an Asset maintainer or a Platform admin whose token names the platform tenant, to which every version of the catalog belongs. The version must be Verified. The service submits it to AgentRegistryService, the release authority, as a release candidate through one release candidate port: the asset kind of a template release, which the model of AgentRegistryService names TemplateBundle and release-manifest-v1 names template-bundle, the template id as asset id and the version, which together are the identity of the candidate, and as its content the repository and the commit the manifest was read from and the manifest hash of the catalog, with the caller as the submitting subject. The answer is 202, because publication is observed and not assumed. The review, the evaluation where a suite exists and the approval by someone other than the subject that submitted the candidate belong to Asset Publication and are decided there and never here. The operation is of the publication class, and the model gives the command no result event: it changes no state of the version, which stays Verified until the release is published. The command leaves evidence: the Factory sink of the pinned audit library writes an audit-evidence-v1 record that names the actor, the template id, the version and the manifest hash to the outbox in the transaction of the command, on the topic audit.evidence.v1.evidence-submitted in the run event envelope. Its idempotency is natural, and the service states what it guarantees itself. It keeps no record of a submission, because the model gives the command no result event and no state change. A repeated call therefore sends the release candidate port the same identity, that is asset kind, asset id and version, with the same content, answers 202 again and writes its own audit-evidence-v1 record, because each admitted call is an act of its caller. That one candidate exists per asset kind, asset id and version is the rule of the release authority, whose releases are unique over tenant, asset kind, asset id and version (model/services/control-plane/AgentRegistryService.yaml), and no guarantee of this service. A caller without the scope, a Requester or an Observer is refused with 403. An Asset maintainer or a Platform admin of another tenant who addresses a version of the platform tenant is refused with 403 as well: the caller can read that version, so the answer hides nothing, and may not change it. A version that does not exist, or that belongs to a tenant that is neither the tenant of the caller nor the platform tenant, is answered 404, the same answer in both cases. A version that is not Verified, that is one that is Discovered, Published, Deprecated or Retired, is refused with 409. AgentRegistryService is a required fail-fast dependency: when it does not answer, the call fails fast with 503 and a problem response that names AgentRegistryService, and nothing is written; the operation lists the code 503 for it (D123). The catalog follows the release through two inbox handlers. MarkPublished handles AssetReleasePublished and matches a published release on the asset kind, the asset id and the version inside the tenant, as the model states it (D123): when the assetKind of the event is TemplateBundle and its assetId and version name a Verified version inside the tenant of the envelope, it moves the version to Published, records the releaseId and writes TemplateVersionPublished with templateId, version, layer and releaseId in the same transaction, in an envelope that names the platform tenant; the handler is idempotent on the event id, and a release of another asset kind, a release in another tenant and a release that names no Verified version are acknowledged without effect. The manifestHash of the event is the hash over the release manifest of AgentRegistryService and not the manifest hash of the catalog, which pins the template manifest, so the handler compares neither with the other: a release whose manifest hash differs from the catalog hash, which is every real release, publishes the version. The event carries no source commit, so the handler cannot tell a release that was cut from another commit than the pinned one; such a guard needs the commit in the event or a read of the release and is reported to the owner. MarkDeprecated handles AssetReleaseDeprecated: the version whose release id the event names, inside the tenant of the envelope, moves from Published to Deprecated, so it may still be upgraded from and is never generated with; the model names no event of the catalog for this transition, so nothing is published and connectsoft.factory.templates.versions moves. The delivery states its limits, each reported to the owner. The thin AgentRegistryService of this increment answers resolution and loading of seeded releases only: the one operation of the model that creates a candidate, SubmitRelease, is a public REST operation with a key header that arrives with feature agent-registry-service-publication in I2 (D140), while the model names the dependency of this service as gRPC. The port is therefore proven against a fake, the two handlers by fixture publishers, and on a deployed instance of this increment no version becomes Published. Until then the Draft allowance applies: a recipe may bind a discovered version that is not yet Published (D123), and arriving in I4 only a Published version may be selected. The model names no trigger that moves a version to Verified, so the acceptance suite seeds a Verified version. The model gives this service no handler for AssetReleaseRevoked, so a revoked template release is not mirrored here. GenerationRecipeService, FleetRolloutService, StudioBff and AuditService handle TemplateVersionPublished in their own PBIs.

Acceptance criteria

AC1 Given a Verified TemplateRegistryService/TemplateVersion of the platform tenant and a caller of that tenant with factory.catalog.admin who is Asset maintainer or Platform admin, when TemplateRegistryService/PublishTemplateVersion is called, then the response is 202, one candidate with the asset kind of templates, the template id and the version as its identity, the repository, the commit and the manifest hash of the catalog as its content and the caller as submitting subject reached the release candidate port, the version is still Verified, and one audit-evidence-v1 record with the actor is in the outbox, written in the transaction of the command (SCN-TemplateRegistryService-006, ADR-0021, FR-06).
AC2 Given a caller without factory.catalog.admin, a Requester or an Observer, an Asset maintainer whose token names another tenant than the platform tenant and who addresses a version of the platform tenant, a version that does not exist or belongs to a third tenant, a version that is Discovered, Published, Deprecated or Retired, or an AgentRegistryService that does not answer, when TemplateRegistryService/PublishTemplateVersion is called, then the response is 403, 403, 403, 404, 409 or 503 with a problem response that names AgentRegistryService respectively, the 404 being the same for the unknown and the foreign version; no candidate is submitted in the first five cases, no evidence record is written and no state changes (SCN-TemplateRegistryService-006, ADR-0015).
AC3 Given a call that was answered 202, when TemplateRegistryService/PublishTemplateVersion is called again for the same version, then the service sends the release candidate port a second submission with the same asset kind, asset id and version as the identity of the candidate and the same content, answers 202, writes a second audit-evidence-v1 record for the second call and leaves the version Verified; the test asserts the two submissions the port received and not a count kept by the fake, because that one candidate exists per asset kind, asset id and version is the rule of the release authority (SCN-TemplateRegistryService-006, model/services/control-plane/AgentRegistryService.yaml).
AC4 Given a Verified version and a fixture publisher of AgentRegistryService/AssetReleasePublished with the asset kind TemplateBundle, the template id as asset id and the version, in the tenant of the version, and with a release manifest hash that differs from the manifest hash of the catalog, when MarkPublished handles the event, then the version is Published with the releaseId of the event and the TemplateRegistryService/TemplateVersionPublished outbox record was written in the same transaction; the same event id delivered twice publishes once; a release of another asset kind, a release in another tenant and a release that names no Verified version change no version (SCN-TemplateRegistryService-009, ADR-0014).
AC5 Given the published version, when the dispatcher publishes TemplateRegistryService/TemplateVersionPublished on template-catalog.templates.v1.template-version-published, then the event is sent in the run event envelope with templateId, version, layer and releaseId, and a transport outage is retried with backoff so the event is neither lost nor duplicated under its event id; given a fixture publisher of AgentRegistryService/AssetReleaseDeprecated that names the release id of the version in its tenant, when MarkDeprecated handles it, then the version moves from Published to Deprecated and nothing is published (SCN-TemplateRegistryService-009, ADR-0012).
Traces: services TemplateRegistryService, AgentRegistryService
Traces: aggregates TemplateRegistryService/TemplateVersion
Traces: apis TemplateRegistryService/PublishTemplateVersion
Traces: events TemplateRegistryService/TemplateVersionPublished, AgentRegistryService/AssetReleasePublished, AgentRegistryService/AssetReleaseDeprecated
Traces: descriptors release-manifest-v1, audit-evidence-v1, run-event-envelope-v1
Traces: adrs ADR-0012, ADR-0014, ADR-0015, ADR-0021
Traces: requirements FR-06
Traces: scenarios SCN-TemplateRegistryService-006, SCN-TemplateRegistryService-009
Relates: screens template-catalog
Depends on AIFACTORY-US-701, AIFACTORY-US-702, feature:agent-registry-service-thin, feature:component-audit-factory-evidence
Sources model/services/template-library/TemplateRegistryService.yaml, model/services/control-plane/AgentRegistryService.yaml, docs/architecture/adr/0021-quality-gates.md, docs/reference/schemas/release-manifest.schema.json, docs/reference/schemas/audit-evidence.schema.json, docs/solution-packs/software-factory/templates/services/template-registry-service/index.md#messages

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-2850 Fake of the release candidate port, fixture publishers of the two release events and a seeded Verified version fixture The acceptance suite holds a fake of the release candidate port that records each submission with asset kind, template id, version, repository, commit, catalog manifest hash and submitting subject, answers a repeated asset kind, asset id and version with the candidate that exists, as the release authority does, and can stop answering; fixture publishers of AssetReleasePublished and AssetReleaseDeprecated in the run event envelope of the pinned contracts package, the first with the asset kind TemplateBundle, a tenant and a release manifest hash that differs from the manifest hash of the catalog; tokens of an Asset maintainer of the platform tenant and of another tenant; and a seed that places a template version in state Verified, because no operation of model/services/template-library/TemplateRegistryService.yaml moves a version there. ConnectSoft.AI.SoftwareFactory.TemplateRegistryService
AIFACTORY-TASK-2851 PublishTemplateVersion command with the release candidate port and its audit evidence implementation PublishTemplateVersion admits a caller with factory.catalog.admin who is Asset maintainer or Platform admin of the platform tenant, answers 403 to a caller of another tenant, 404 for an unknown version and for one of a third tenant alike and 409 for a version that is not Verified, submits the candidate through the release candidate port with the caller as submitting subject, asset kind, template id and version as its identity and repository, commit and catalog manifest hash as its content, writes one audit-evidence-v1 record with the actor to the outbox in its transaction, leaves the state of the version unchanged and answers 202; a repeated call sends the same identity again and writes its own evidence record; when the port does not answer, the call fails fast with 503 and a problem response that names AgentRegistryService and nothing is written. ConnectSoft.AI.SoftwareFactory.TemplateRegistryService
AIFACTORY-TASK-2852 MarkPublished and MarkDeprecated inbox handlers that mirror the asset release implementation MarkPublished moves a Verified version to Published for an AssetReleasePublished whose assetKind is TemplateBundle and whose assetId and version name that version inside the tenant of the envelope, records the releaseId and writes TemplateVersionPublished with templateId, version, layer and releaseId in the same transaction; it does not compare the manifestHash of the event, which is the hash over the release manifest, with the manifest hash of the catalog; MarkDeprecated moves the version whose release id AssetReleaseDeprecated names, inside the tenant of the envelope, from Published to Deprecated and publishes nothing; both are idempotent on the event id, acknowledge an event that matches no version without effect and move connectsoft.factory.templates.versions with the state change; no handler of AssetReleaseRevoked is registered. ConnectSoft.AI.SoftwareFactory.TemplateRegistryService
AIFACTORY-TASK-2853 Verify the submission and the mirrored release through the acceptance suite verification Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-TemplateRegistryService-006\|Scenario=SCN-TemplateRegistryService-009)"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-708 with the fake of the release candidate port and the fixture publishers: the 202 with its candidate and its evidence record, the 403, 404 and 409 refusals, the 403 of a caller of another tenant for a version of the platform tenant among them, the 503 that names AgentRegistryService, the repeated call with the same identity sent again and a second evidence record, the publication under a release event whose manifest hash differs from the catalog hash, a release of another asset kind or tenant that changes nothing, the payload of TemplateVersionPublished and the move to Deprecated; consumer handling is proven by the suites of the consumers. ConnectSoft.AI.SoftwareFactory.TemplateRegistryService