AIFACTORY-FEAT-157: Base template: the Factory service profile¶
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 Ecosystem component extensions · Increment I0 Readiness · State elaborated · Route backend-developer · Phase before development · Build order 9 of 185 (Templates and libraries)
Before development
Template or library work: every task of this feature changes a template or a shared library the Factory builds on, and it lands before the Factory's own repositories of I0 are developed. The mark travels with every task (tag phase:before-development).
Forty-six Factory services are scaffolded from the base template (D94) and deploy alone (ADR-0028), so the work a host did once is done per service by the scaffold. The profile a Factory service is generated with: the Orleans messaging adapter for the outbox and inbox with the accepted envelope, the tenant and project scope read from the token and propagated to every call and message, token validation against the authorization server with the Factory roles as claims, a REST and gRPC surface described by descriptors, health and readiness endpoints, and telemetry that carries run and attempt correlation. A service scaffolded with the profile builds and passes unchanged, which is the acceptance of the readiness checklist. Component: BaseTemplate (extend).
| Delivers | — |
| Stubs | — |
| Realizes | components: cmp-base-template adrs: ADR-0014, ADR-0024, ADR-0028 |
| Requirements | — |
| Depends on | — |
| Sources | model/components.yaml, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md, docs/templates-docs/base-template.md |
AIFACTORY-US-226: Base template: MessagingModelType accepts Orleans and the generated service commits the accepted envelope to the Orleans outbox with its state change¶
enabling · persona asset-maintainer
As an asset maintainer, I want the base template to offer the Orleans outbox and inbox as a messaging choice that writes the accepted envelope, so that every Factory service scaffolded from it has a durable outbox and inbox of its own without a broker and without copied messaging code.
The template configuration of the base template offers three values of MessagingModelType today: None, NServiceBus and MassTransit (model/template-parameters/connectsoft-base.yaml). ADR-0012 makes ConnectSoft.Extensions.MessagingModel the only messaging contract of application code and the transport a profile, and ADR-0028 decision 7 gives every service that publishes or consumes messages its own messaging service name, its own transport credential and the Orleans messaging profile library, because its inbox and outbox are its own. This PBI adds the value Orleans. The existing library ConnectSoft.Extensions.MessagingModel.Orleans is consumed by a version pin and is not changed here. Its getting started page (Docs/GettingStarted.md of the library) names what it needs: a co-hosted Orleans silo, SQL Server with the messaging tables in the ConnectSoftMessaging schema of the service database, and the NHibernate unit of work the outbox writer enlists in. The template therefore refuses a generation that selects the value without ActorModelType Orleans, without PersistenceModelType NHibernate or with an NHibernateDialectType other than SqlServer, and the message names both symbols. The adapter also requires declared routing, so the generated service carries an OrleansMessaging configuration section with ServiceName, the Outbox connection, Subscribers, Subscriptions and PublishedEvents: every published event has a subscription or an UnroutedReason, startup fails otherwise, an undeclared publish throws, and a publish outside a transaction is refused. The adapter has one wire type, MessageEnvelope, and the accepted envelope of the Factory does not replace it. A Factory service writes the run event envelope of the contracts package for its integration events (ADR-0014 amendment of D114), so the envelope type is read from the Factory contracts package by a version pin, is never copied into the template, and its fields are mapped onto the publish options of the adapter: eventId is the caller message id, correlationId and causationId are the options of the same name, orderingKey is OrderingKey, the aggregate version is AggregateRevision, and schemaVersion is the version a handler registration declares. The inbox deduplicates by (DeduplicationScope, MessageId); a failing handler is retried with back-off and poisoned per subscriber at MaxAttempts, a contract failure at once, and a poisoned delivery is recovered through IOutboxRecovery. MassTransit and NServiceBus stay selectable as transports for generated products and their generated output does not change.
Acceptance criteria
| AC1 | Given the template configuration with the value Orleans of MessagingModelType, when a service is generated with it together with ActorModelType Orleans, PersistenceModelType NHibernate and NHibernateDialectType SqlServer, then the service registers the outbox dispatcher and the inbox grains of the Orleans messaging adapter library with its own messaging service name and holds no MassTransit or NServiceBus registration; a generation that combines the value with another actor model, another persistence model or another dialect is refused with a message naming both symbols (ADR-0012 decision 2, ADR-0028 decision 7, model/template-parameters/connectsoft-base.yaml). |
| AC2 | Given a generated service that changes state and publishes an event in one handler, when the unit of work commits, then one outbox record is committed in the same transaction and carries the accepted envelope with event id, event type, schema version, occurred-at, producer, tenant id, correlation id and payload, and with project id, causation id and ordering key where the event has them; eventId is passed as the caller message id, correlationId and causationId as the options of the same name, orderingKey as OrderingKey and the aggregate version as AggregateRevision, so that two publications of one event id carry one message id; when the unit of work rolls back neither the state change nor the record exists (ADR-0012 decision 4, ADR-0014 decisions 1 and 4, descriptor run-event-envelope-v1). |
| AC3 | Given the same message id delivered twice inside one deduplication scope, when the inbox of a generated service dispatches it, then the handler runs once and the second delivery has no effect; a handler that keeps failing is retried with back-off and poisoned at MaxAttempts, is visible in the poison metric of the adapter and is recoverable through IOutboxRecovery; a message whose schemaVersion no handler registration declares is refused as IncompatibleSchemaVersion (ADR-0014 decision 3, ADR-0012). |
| AC4 | Given the generated OrleansMessaging section with the service name, the outbox connection and the sample event declared in PublishedEvents with a route or an UnroutedReason, when the generated tests run, then a publish of an event that is not declared throws, a declared event without a route and without a reason fails startup with its key named, and a publish outside the unit of work is refused (ADR-0012 decision 4, ADR-0028 decision 7). |
| AC5 | Given a generation with MassTransit or NServiceBus, when the cases of the template pipeline run, then those cases generate and pass as before, the Compatibility cases hold an Orleans case while the gating case of the value is the Factory preset case of AIFACTORY-US-230, and model/template-parameters/connectsoft-base.yaml lists the value Orleans after the next template inventory, so that MassTransit stays a selectable transport for products (ADR-0012 decision 3). |
| Traces: descriptors | run-event-envelope-v1 |
| Traces: adrs | ADR-0012, ADR-0014, ADR-0028 |
| Depends on | feature:contracts-package |
| Sources | model/components.yaml, docs/architecture/adr/0012-messaging-port-and-transport-profiles.md, docs/architecture/adr/0014-run-and-lifecycle-envelopes.md, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md, model/template-parameters/connectsoft-base.yaml, docs/reference/schemas/run-event-envelope.schema.json |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-1071 Orleans value of MessagingModelType with its computed symbol and the silo, NHibernate and SQL Server constraints |
contract | The template configuration lists the value Orleans of MessagingModelType with a computed symbol that source conditions use; a generation that selects it without ActorModelType Orleans, without PersistenceModelType NHibernate or with an NHibernateDialectType other than SqlServer fails with a message naming both symbols; the parameters page of the template documents the value and its three prerequisites. |
ConnectSoft.BaseTemplate |
AIFACTORY-TASK-580 Messaging profile Orleans with the accepted envelope |
implementation | MessagingModelType accepts Orleans; the generated service registers the outbox dispatcher and the inbox grains of ConnectSoft.Extensions.MessagingModel.Orleans, writes the outbox record in the NHibernate unit of work of the state change and publishes the ADR-0014 envelope, read from the pinned contracts package, with eventId as the caller message id, correlationId and causationId as the options of the same name, orderingKey as OrderingKey, the aggregate version as AggregateRevision and schemaVersion as the version the handler registration declares; the Compatibility cases of the template pipeline have an Orleans case and the Factory preset case of AIFACTORY-US-230 gates the value. |
ConnectSoft.BaseTemplate |
AIFACTORY-TASK-1166 Generated OrleansMessaging section with declared routing of the sample event |
implementation | The generated configuration of the Orleans case holds the OrleansMessaging section with ServiceName set to the messaging service name of the service, the Outbox connection of the service database, and the sample event declared in PublishedEvents with a subscription or an UnroutedReason; the options are validated at startup and a generated test fails when the section is absent. |
ConnectSoft.BaseTemplate |
AIFACTORY-TASK-1072 Outbox transaction, deduplication, poison and declared routing tests of the generated Orleans case |
fixture | The generated solution of the Orleans case holds tests for commit and rollback of the outbox record with the state change, for one message id of two publications of one event id, for a second delivery of a message id inside the deduplication scope that has no effect, for a failing handler that is retried with back-off, poisoned at MaxAttempts, counted in the poison metric and recovered through IOutboxRecovery, for an unknown schema version that is refused, for an undeclared publish that throws, for a declared event without route or reason that fails startup, and for a publish outside the unit of work that is refused. |
ConnectSoft.BaseTemplate |
AIFACTORY-TASK-1073 Verify the Orleans messaging profile on a generated service |
verification | Generate the Orleans case and the MassTransit case from the packed template, build both in Release and run their tests; the Orleans case passes the outbox, deduplication, poison and declared routing tests, a generation with another dialect is refused, and the MassTransit case is unchanged, which proves AC1 to AC5 of AIFACTORY-US-226 (ADR-0012, ADR-0014). | ConnectSoft.BaseTemplate |
AIFACTORY-US-227: Base template: a Factory service takes the tenant from the token, admits a project only when the token grants it, carries the scope on every call and message, and answers 404 for a foreign tenant¶
enabling · persona asset-maintainer
As an asset maintainer, I want a generated Factory service to establish the trusted scope once per request or message and to carry it everywhere, so that no Factory service acts on a tenant or project a caller merely claims and no service reveals that a resource of another tenant exists.
ADR-0015 decision 2 requires every Factory contract to carry the trusted tenant id and project id derived from the authenticated context, never from caller-controlled headers, and decision 3 requires every backend to enforce authorization for every read and write. ADR-0028 notes that what a host did once is now done per service by the scaffold. This PBI adds the Factory profile switch to the base template and, under it, the scope chain of a service. The switch is the one the amendment of ADR-0028 (D114) decides: the boolean UseFactoryProfile, off by default so that other generations do not change, named the same in every template that has a Factory shape, and passed by the Factory scaffold command, dotnet new connectsoft-base -n ConnectSoft.AI.SoftwareFactory.<ServiceId> --UseFactoryProfile true. The template defines no scope type of its own. The scope accessor and the middleware that fills it are AIFACTORY-TASK-186 and AIFACTORY-TASK-142 of AIFACTORY-US-220 in feature component-extensions-ai; they live in ConnectSoft.Extensions.AI.Factory.Abstractions, which that feature publishes, and the template pins that package and registers them. The tenant resolution, the tenant filters and the tenant propagation live in the ConnectSoft.Extensions.Saas libraries. UseFactoryProfile requires the existing switch UseIdentityPlatform, and a generation without it is refused. On an inbound REST or gRPC call the tenant comes from the tid claim of the validated token and overwrites any tenant header the caller sent. The token holds no single project claim: it holds one role claim per project assignment. The project of a request is the one the route addresses or the gateway forwarded, and it is admitted into the scope only when the validated token holds a role claim for that project or the tenant-wide Platform admin role; otherwise the answer is 403, and a project value the token does not grant is never read into the scope. A workload token carries service scopes, no audience of a user API and no tenant claim; the tenant and project it forwards are read only when the token holds the svc. scope that names the service (ADR-0015 amendment of D114). Outbound HTTP and gRPC calls carry the tenant in X-Tenant-Id and tenant-id and the project in the header the abstractions package names, published messages take tenant and project from the accessor into the envelope, and a message handler or a grain call sees the scope of the message or of the caller. The persistence filter makes rows of another tenant invisible, so a request for an identifier of another tenant is answered 404, over gRPC the status NOT_FOUND, exactly as an unknown identifier is; a caller without the scope or the project right an endpoint requires inside its own tenant is answered 403; a call without a token or without a trusted source of the tenant is answered 401 before any handler runs. The envelope a Factory service writes for its integration events is the run event envelope of the contracts package (ADR-0014 amendment of D114); it requires the tenant and leaves the project optional. The generic SaaS templates keep their own envelope base, so under the profile an inbound message in that base, such as a tenant event of the Tenants service, is mapped onto the run event envelope before the scope is read: tenantId, schemaVersion, correlationId and causationId map by name, occurredOn is occurredAt, the message id is eventId, the topic name is eventType, the messaging service name of the publisher is producer and the event body is payload. A message without the tenant, in either envelope, is therefore not handled and goes to the poison handling of the Orleans messaging profile with the reason, through the tenant propagation of the SaaS libraries (AIFACTORY-US-204). A message without a project, such as a tenant suspension, a tenant-scope role assignment or a retention event, is handled under a tenant-only scope, and only a handler that declares itself project-scoped refuses it. Every refusal is logged with the correlation id and without token content.
Acceptance criteria
| AC1 | Given a service generated with UseFactoryProfile and a call with a valid user token, when a REST endpoint or a gRPC method handles it, then the tenant of the scope is the tid claim and a tenant header sent by the caller with another value is overwritten and never read; the project of the scope is the one the route addresses or the gateway forwarded and is admitted only when the token holds a role claim for that project or the tenant-wide Platform admin role, otherwise the answer is 403 and the project value is never read into the scope (ADR-0015 decision 2, FR-01, descriptor execution-scope-v1). |
| AC2 | Given a handler that calls another service over HTTP and over gRPC, calls a grain and publishes an event, when it runs under a scope, then the outbound calls carry the tenant in X-Tenant-Id and tenant-id and the project in the header the abstractions package names, the grain call carries the same scope, the envelope of the event carries tenant and project, and the consuming handler reads the same scope from its accessor (ADR-0014 decision 1, ADR-0015 decisions 1 and 2). |
| AC3 | Given two tenants with one resource each, when a caller of the first tenant requests the identifier of the resource of the second, then the answer is 404 with the same body as for an identifier that does not exist, and over gRPC the status NOT_FOUND; when the caller lacks the scope or the project right the endpoint requires inside its own tenant, then the answer is 403; when the call has no token, a user token has no tid claim or a workload token forwards no tenant, then the answer is 401 and no handler runs; a workload token has its forwarded tenant and project read only when it holds the svc. scope that names the service (ADR-0015 amendment on a resource of another tenant, D113; docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md). |
| AC4 | Given a message whose envelope carries no tenant, when the inbox of a generated service receives it, then it is not handled and goes to the poison handling of the Orleans messaging profile with the reason, through the tenant propagation of the ConnectSoft.Extensions.Saas libraries, and the refusal is logged with the correlation id; given a tenant-level event without a project, when it is received, then it is handled under a tenant-only scope, and only a handler that declares itself project-scoped refuses it; given a tenant event in the envelope base of a generic SaaS template, when it is received, then the profile maps it onto the run event envelope with a source for every required field and the handler reads the tenant of the event from the scope accessor (ADR-0014 decision 1 and its amendment on envelopes per event family, ADR-0015 decision 3, docs/reference/schemas/run-event-envelope.schema.json). |
| Traces: descriptors | execution-scope-v1 |
| Traces: adrs | ADR-0014, ADR-0015, ADR-0028 |
| Traces: requirements | FR-01 |
| Depends on | AIFACTORY-US-226, feature:component-extensions-ai, feature:component-saas-extensions |
| Sources | model/components.yaml, docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md, docs/architecture/adr/0014-run-and-lifecycle-envelopes.md, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md, docs/reference/schemas/execution-scope.schema.json, docs/reference/schemas/run-event-envelope.schema.json, model/template-parameters/connectsoft-base.yaml |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-1074 UseFactoryProfile symbol with the pins of the Factory abstractions and the SaaS tenancy libraries |
contract | The template configuration holds the boolean UseFactoryProfile of the ADR-0028 amendment, off by default so that other generations do not change and named as in the worker, gateway and library templates; a generation with it and without UseIdentityPlatform is refused with both symbols named; with it the generated solution pins ConnectSoft.Extensions.AI.Factory.Abstractions and the ConnectSoft.Extensions.Saas packages in central package management, registers the scope accessor and middleware of AIFACTORY-TASK-186 and AIFACTORY-TASK-142 and holds no copy of a scope type or of a header name; the parameters page of the template documents the symbol and the scaffold command that passes it. |
ConnectSoft.BaseTemplate |
AIFACTORY-TASK-581 Factory scope from the token to every call and message |
implementation | The generated service takes the tenant from the tid claim of the validated token, admits the project the route addresses or the gateway forwarded only when the token holds a role claim for it or the tenant-wide Platform admin role, exposes both through the scope accessor, forwards them on outbound HTTP and gRPC calls and grain calls and stamps them on messages; an identifier of another tenant is answered 404, a project the token does not grant or a missing scope inside the own tenant 403, a missing token or tenant source 401; a message without the tenant goes to the poison handling of the Orleans messaging profile and a message without a project is handled under a tenant-only scope unless its handler is declared project-scoped. |
ConnectSoft.BaseTemplate |
AIFACTORY-TASK-1465 Mapping of the envelope base of the generic SaaS templates onto the run event envelope |
implementation | Under UseFactoryProfile the inbox of the generated service maps a message in the envelope base of a generic SaaS template onto the run event envelope of the pinned contracts package before the scope is read, tenantId, schemaVersion, correlationId and causationId by name, occurredOn as occurredAt, the message id as eventId, the topic name as eventType, the messaging service name of the publisher as producer and the event body as payload; a message of that base without a tenant goes to the poison handling with the reason; the mapping reads the fields of the base by name and the generated solution references no package of a SaaS template. |
ConnectSoft.BaseTemplate |
AIFACTORY-TASK-1075 Two-tenant and two-project acceptance fixture of the generated Factory service |
fixture | The generated acceptance suite of the Factory preset holds a fixture with two tenants and two projects on one disposable database and scenarios for the carried scope, the overwritten tenant header, a project the token does not grant, the 404, 403 and 401 answers, a workload token with and without its svc. scope, a message without the tenant that is poisoned with the reason, a tenant-level event without a project that is handled under a tenant-only scope, the same event refused by a handler declared project-scoped, and a tenant event in the envelope base of a generic SaaS template that is mapped onto the run event envelope; the assertions are not weakened when one fails. |
ConnectSoft.BaseTemplate |
AIFACTORY-TASK-1076 Verify the scope chain and the refusal codes on a generated Factory service |
verification | Generate the Factory preset from the packed template, build it in Release and run its acceptance suite; the scope scenarios, the 404, 403 and 401 scenarios, the tenant-level event scenario and the envelope mapping scenario pass, which proves AC1 to AC4 of AIFACTORY-US-227 (ADR-0015, FR-01). | ConnectSoft.BaseTemplate |
AIFACTORY-US-228: Base template: a Factory service validates tokens through the resource-server library and maps the seven Factory roles to endpoint policies¶
enabling · persona asset-maintainer
As an asset maintainer, I want a generated Factory service to validate the tokens of the authorization server and to enforce the seven Factory roles per request, so that every backend enforces the roles the authorization server issued and menu visibility in the Studio grants nothing.
ADR-0015 decisions 5 and 6 define seven roles, assigned per project except Platform admin, issued as claims by the authorization server and enforced by every backend per request, and ADR-0008 fixes the authorization server as the OpenIddict issuer. The identity platform page of the base template (Docs/Identity-Platform-Foundation.md of the template) states that the template is neither an authorization server nor an identity service and that derived templates implement resource-server behaviour. ADR-0028 decision 7 names the resource-server library for that, and ADR-0008 records ConnectSoft.Extensions.ResourceServer as existing. The template already has the switch UseIdentityPlatform (model/template-parameters/connectsoft-base.yaml); UseFactoryProfile requires it, and a generation without it is refused. Under both switches the validation of issuer, signature, lifetime and audience, the refusal of an identity token used as an API credential and the loading of the signing keys are the registration of the pinned ConnectSoft.Extensions.ResourceServer, and the template writes none of that. What this PBI adds is the policies: one named policy per role (Requester, Reviewer, Asset maintainer, Operator, Workspace admin, Platform admin, Observer) and scope policies for workloads. The claim type names, the role names and the parser of the scoped role value come from the pinned ConnectSoft.Extensions.AI.Factory.Abstractions package (AIFACTORY-TASK-1173 of AIFACTORY-US-220 in feature component-extensions-ai), which the authorization server, identity and gateway templates pin as well, so no template types them again and the profile does not wait for the authorization server template. A project role counts only when its claim names the project the scope chain admitted for the request. Workspace admin of a project satisfies the Requester, Reviewer, Asset maintainer and Operator policies of that project and of no other. Platform admin counts for the whole tenant, and an admission through it is marked on the authorization result, so that a service that decides approvals can demand the audited reason decision 5 requires. Observer counts for a project or for the tenant and never satisfies a command policy. Audience validation applies to user tokens: a user token has one audience, the resource of the gateway that fronts its granted scopes (ADR-0015 amendment of D114), which for a service is the gateway that fronts it. A workload token carries service scopes, no audience of a user API and no tenant claim: it is admitted by issuer, signature, lifetime and the svc. scope that names the service, and it never satisfies a role policy or a user-audience policy. An invalid or expired token, a user token for another audience and an identity token are answered 401; a valid token without the required role in the project or without the required scope is answered 403; when the signing keys of the authority cannot be loaded the service refuses requests and reports the authority in its readiness. A refusal is logged with policy, tenant, project and correlation id and never with the token.
Acceptance criteria
| AC1 | Given a service generated with UseFactoryProfile and UseIdentityPlatform and configured with the issuer and the audience of the gateway that fronts it, when it receives a user access token of the authorization server, then issuer, signature, lifetime and audience are validated by the registration of the pinned ConnectSoft.Extensions.ResourceServer, and an expired token, a user token issued for another audience and an identity token are each answered 401; a generation with UseFactoryProfile and without UseIdentityPlatform is refused (ADR-0008, ADR-0015 decision 6, ADR-0028 decision 7). |
| AC2 | Given endpoints that require each of the seven roles, when the acceptance matrix calls them with a token holding the role in the project of the request, the same role in another project of the same tenant, Workspace admin of the project, Workspace admin of another project, Platform admin of the tenant and Observer, then the role in the project and Platform admin are admitted, Workspace admin of the project satisfies the Requester, Reviewer, Asset maintainer and Operator policies of that project and of no other project, the role of another project is answered 403, an admission through Platform admin is marked on the authorization result, and Observer is admitted to read endpoints and answered 403 on every command (ADR-0015 decision 5). |
| AC3 | Given a workload token of a service client, which carries no audience of a user API, when it calls an endpoint, then it is admitted by issuer, signature, lifetime and the svc. scope that names the service, is answered 403 without that scope, and never satisfies a role policy or a user-audience policy (ADR-0015 decision 6, FR-01). |
| AC4 | Given the signing keys of the authority cannot be loaded and none are cached, when a request arrives, then it is refused, readiness reports the identity authority as unreachable, and the refusal is logged with policy, tenant, project and correlation id without token content (ADR-0028 decision 7 names this failure mode for gateways; docs/architecture/adr/0028-one-repository-and-deployable-per-service.md). |
| Traces: adrs | ADR-0008, ADR-0015, ADR-0028 |
| Traces: requirements | FR-01 |
| Depends on | AIFACTORY-US-227, feature:component-extensions-ai |
| Sources | model/components.yaml, docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md, docs/architecture/adr/0008-openiddict-identity.md, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md, model/template-parameters/connectsoft-base.yaml |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-1077 Resource-server pin, role policy names and the issuer and audience options of the Factory profile |
contract | Under UseFactoryProfile with UseIdentityPlatform the generated solution pins ConnectSoft.Extensions.ResourceServer and registers it with the issuer and audience options, validated at startup; one policy name per Factory role and per svc. scope kind exists as a constant that endpoints reference, built on the role names and claim type names of the pinned Factory abstractions package; the security page of the template documents them and the relation of the two switches. |
ConnectSoft.BaseTemplate |
AIFACTORY-TASK-582 Token validation with the Factory roles |
implementation | The identity platform switch validates tokens of the authorization server through the pinned ConnectSoft.Extensions.ResourceServer and maps the seven Factory roles to policies with the parser of the pinned Factory abstractions package; a generated service refuses a token without the role its endpoint requires in the project of the request, lets Workspace admin stand for the four project roles of its own project only, marks an admission through Platform admin and admits a workload token by its svc. scope alone; the acceptance suite covers the matrix. |
ConnectSoft.BaseTemplate |
AIFACTORY-TASK-1078 Test token issuer and role matrix of the generated acceptance suite |
fixture | The generated acceptance suite holds a test issuer that signs tokens with the claim type names and the scoped role value of the pinned Factory abstractions package, never with names typed in the test, and a role matrix feature with one scenario per role, per foreign project, for Workspace admin in its own and in another project, for Platform admin, for Observer, for a workload token with and without its svc. scope and for the 401 cases. |
ConnectSoft.BaseTemplate |
AIFACTORY-TASK-1079 Verify token validation and the role matrix on a generated Factory service |
verification | Generate the Factory preset, build it in Release and run the role matrix; every admitted and refused case answers as the matrix states, which proves AC1 to AC4 of AIFACTORY-US-228 (ADR-0015, ADR-0008). | ConnectSoft.BaseTemplate |
AIFACTORY-US-229: Base template: a Factory service exposes REST and gRPC from a service descriptor, serves health and readiness, and emits scope and run correlation through the single enrichment registration¶
enabling · persona asset-maintainer
As an asset maintainer, I want a generated Factory service to expose exactly the operations its descriptor names, to report its readiness and to wire its telemetry through the shared registration, so that a platform gateway can route to it, an operator can see whether it is ready, every activity and log record carries the tenant, project, run, step and attempt it belongs to, every metric carries the tenant and project, and no service writes a telemetry convention of its own.
ADR-0028 decision 2 routes public REST and internal gRPC calls through the platform gateway to the services, and its consequences list health and readiness and telemetry wiring among the work the base template provides per service. The template offers one service model per generation today: ServiceModelType is a single choice with Grpc as default, and UseRestApi and UseGrpc are computed from it (model/template-parameters/connectsoft-base.yaml). Under UseFactoryProfile this PBI generates both the REST and the gRPC service model over one set of use cases and adds a service descriptor file to the generated repository. The file lists each operation as the apis section of a service file of the model does (for example model/services/control-plane/ProjectService.yaml): name, method and path or gRPC method, scope, side-effect class, idempotency and response codes. It is a separate file and not a part of the descriptor family the SaaS templates carry (Microservice.schema.json with a context descriptor, the import format of ADR-0025): that family describes the entity model a service is generated from, while this file is no generation input and only records the surface the code is checked against. A contract test compares the mapped endpoints with the file in both directions and fails on an endpoint the file does not name or an operation without an endpoint. The service serves a liveness endpoint and a readiness endpoint; readiness is unready until the store is migrated and the silo has started, while the outbox readiness check of the Orleans messaging adapter (AddConnectSoftOrleansMessagingOutboxHealthCheck, on backlog age and depth) is unhealthy, and while the identity authority is unreachable. The template registers that check of the adapter and writes no outbox check of its own. Telemetry is wiring only, and it carries the correlation the feature promises. The feature component-observability-factory-conventions is in the same increment (D114) and delivers one enrichment registration in the observability libraries (AIFACTORY-TASK-632): it reads the scope accessor and the run event envelope and puts tenant, project, run, step and attempt on every activity and log record, and its instrument helper tags a metric with tenant and project by default; run, step and attempt reach a metric only through the allowlist of the instrument helper (D115, AIFACTORY-US-257). The generated service pins the library version that carries that registration, calls it once and creates its instruments through the instrument helper, so a request handled under a scope emits activities and log records with tenant and project, a message handled under the envelope of a run emits them with run, step and attempt as well, under the attribute names of the library, and a measurement of the service carries the tags tenant and project. The Factory preset leaves the allowlist at its default and does not put run, step and attempt on every metric; a service that needs one of them on a series names it in its own options. The generated solution defines no enricher and no tag name for tenant, project, run, step or attempt of its own and creates no instrument outside the helper, and an architecture test fails when one appears, so that no service writes a telemetry convention.
Acceptance criteria
| AC1 | Given a service generated with UseFactoryProfile and a service descriptor file that lists REST operations and gRPC methods, when the solution builds and its contract test runs, then both the REST and the gRPC host expose exactly the operations of the file with the scope each names, and the test fails when an endpoint is absent from the file or the file names an operation without an endpoint (ADR-0028 decision 2, model/services/control-plane/ProjectService.yaml as the shape of the operations). |
| AC2 | Given a generated Factory service that starts, when its store is not migrated, its silo has not started or the outbox readiness check of the Orleans messaging adapter (AddConnectSoftOrleansMessagingOutboxHealthCheck) is unhealthy, then the readiness endpoint answers unready and names the dependency while the liveness endpoint answers alive; when all three are healthy and the identity authority is reachable, then readiness answers ready (ADR-0028 consequences on health and readiness per service). |
| AC3 | Given a service generated with UseFactoryProfile that pins the single enrichment registration of the observability libraries, when a request is handled under a scope and a message is handled whose envelope carries run, step and attempt, then the exported activity and log record of each carry tenant and project, and those of the message also run, step and attempt, under the attribute names of the library, while a measurement recorded through the instrument helper carries the tags tenant and project and no run, step or attempt tag, because the preset leaves the allowlist of the helper at its default; when its architecture tests run, then telemetry is registered by one call of that registration, every instrument of the solution is created through the instrument helper, the generated solution defines no enricher and no tag name for tenant, project, run, step or attempt of its own, a planted enricher fails the test, and no generated code writes a request or message payload to a span or metric attribute (ADR-0014 decision 1 names the identifiers, ADR-0028 consequences on telemetry wiring per service). |
| AC4 | Given the architecture and correlation tests of the generated Factory preset, when they run, then they assert the three: descriptor conformity of both hosts, mapped liveness and readiness endpoints, and the single enrichment registration with tenant, project, run, step and attempt read from an activity and a log record exported to the in-memory exporter of the tests, and a planted endpoint outside the descriptor fails the suite (ADR-0028, ADR-0014 decision 1, docs/templates-docs/base-template.md). |
| Traces: adrs | ADR-0014, ADR-0028 |
| Depends on | AIFACTORY-US-226, AIFACTORY-US-227, AIFACTORY-US-228, feature:component-observability-factory-conventions |
| Sources | model/components.yaml, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md, docs/architecture/adr/0014-run-and-lifecycle-envelopes.md, docs/templates-docs/base-template.md, model/template-parameters/connectsoft-base.yaml, model/services/control-plane/ProjectService.yaml |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-583 Descriptor-described REST and gRPC surface with health and telemetry |
contract | A generated service exposes its REST and gRPC endpoints from a service descriptor file whose schema is part of the template, serves health and readiness, and wires its telemetry through the single enrichment registration of the pinned observability libraries, so that its activities and log records carry tenant, project, run, step and attempt and its metrics carry tenant and project; the architecture tests assert the three. | ConnectSoft.BaseTemplate |
AIFACTORY-TASK-1080 Both service models, the readiness endpoint and the telemetry wiring under the Factory profile |
implementation | Under UseFactoryProfile the template generates the REST and the gRPC service model over one set of use cases, maps a liveness and a readiness endpoint with checks for the store, the silo and the identity authority and with the outbox readiness check the adapter ships (AddConnectSoftOrleansMessagingOutboxHealthCheck), pins the observability libraries at the version that carries the single enrichment registration of AIFACTORY-TASK-632, calls it once and creates its instruments through the instrument helper with the allowlist at its default, so that every activity and log record carries tenant, project, run, step and attempt and every measurement carries tenant and project; the generated solution holds no enricher, no tag name for a scope or run identifier, no instrument created outside the helper and no outbox check of its own. |
ConnectSoft.BaseTemplate |
AIFACTORY-TASK-1081 Descriptor conformity, readiness, telemetry wiring and correlation tests of the generated Factory preset |
fixture | The generated solution holds a contract test that compares mapped endpoints with the descriptor file in both directions, readiness tests with each dependency down, an architecture test that finds exactly one call of the enrichment registration and fails on an enricher or a scope tag name defined in the solution and on an instrument created outside the instrument helper, and a correlation test that exports the activities and log records of a scoped request and of a message of a run to the in-memory exporter and reads tenant, project, run, step and attempt from them, and that reads the tags tenant and project and no run, step or attempt tag from a measurement of the service; a planted endpoint outside the descriptor fails the contract test and a planted enricher fails the architecture test. |
ConnectSoft.BaseTemplate |
AIFACTORY-TASK-1082 Verify the surface, readiness, telemetry wiring and correlation on a generated Factory service |
verification | Generate the Factory preset, build it in Release and run its contract, readiness, architecture and correlation tests; all pass, the exported activities and log records carry tenant, project, run, step and attempt, the measurements carry tenant and project only, and the planted endpoint and the planted enricher are refused, which proves AC1 to AC4 of AIFACTORY-US-229 (ADR-0028, ADR-0014). | ConnectSoft.BaseTemplate |
AIFACTORY-US-230: Base template: the Factory preset is the additional gating case of the shared template pipeline and is packed, installed, generated, built and tested before the package publishes¶
evidence · persona asset-maintainer
As an asset maintainer, I want the Factory preset to be a gated case of the template pipeline, so that no package that would scaffold a Factory service that does not build or pass reaches the feed.
The estate has one gate mechanism for templates, the shared template pipeline of ConnectSoft.AzurePipelines (template-ci/v1): one packed candidate, scaffold cases, result validation with discovery and completion checks, dependency audit, package protection and publication evidence bound to the candidate hash, all driven by the build/template-ci.json manifest of the consumer. The findings feature of the base template moves the template onto it, and the preset matrix of build/Test-BaseTemplateRegressions.ps1 becomes the cases of that manifest. This PBI adds the Factory preset as a gating case and is the proof of the feature. The Domain profile of the shared tooling declares one case per artifact kind, and the amendment of ADR-0028 (D114) admits one additional gating case per declared profile while the default generations stay gated as today. The Factory preset is that additional case of the declared Factory profile. The admission is a change of the shared tooling, made once by a task of this PBI in ConnectSoft.AzurePipelines, which is a before-development repository, and the gate PBIs of the gateway and Tenants templates build on it. The candidate is installed, a solution is generated by the Factory scaffold command with UseFactoryProfile under the name of a Factory service repository, restored and built in Release, and its tests run with the discovery and completion checks, so that a truncated run fails. The manifest names the services the case needs: SQL Server for the outbox and the two-tenant fixture, and a co-hosted silo. The dependency audit of the generated solution runs through the shared tooling. A case that fails any stage fails the run with the case and the stage named, and publication is not reached. Publication requires the complete reports of every case bound to the candidate and pushes a version that is not yet on the ConnectSoft feed. The PBI proves the amendment of ADR-0028 that scaffolds the Factory services from connectsoft-base and the release gate of FR-11: a service scaffolded with the profile builds and passes unchanged, which is the acceptance of the readiness checklist of the increment.
Acceptance criteria
| AC1 | Given a change of the base template, when the template pipeline runs the shared installer jobs with build/template-ci.json, then the candidate is packed once and installed, the default cases run as today, the Factory preset case, the one additional gating case of the declared Factory profile, is generated with UseFactoryProfile under the name of a Factory service repository, restored and built in Release, its tests run with the discovery and completion checks against the services the manifest declares for the case, SQL Server for the outbox and the two-tenant fixture and a co-hosted silo, and the dependency audit of the generated solution runs (ADR-0028 amendments on scaffolding Factory services from the base template and on the Factory profile switch, FR-11). |
| AC2 | Given the Factory preset case fails any stage, when the pipeline evaluates the run, then the run fails with the case and the stage named, the logs are kept in the diagnostics artifact and publication is not reached; a planted failing case proves the refusal (FR-11, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md). |
| AC3 | Given complete reports of every case bound to the candidate hash, when the publication job runs, then the package is pushed with a version that is not on the feed, a fresh install of that version generates the Factory preset that builds unchanged, and model/template-parameters/connectsoft-base.yaml lists UseFactoryProfile and the Orleans value after the next template inventory (ADR-0028, FR-11). |
| Traces: adrs | ADR-0028 |
| Traces: requirements | FR-11 |
| Depends on | AIFACTORY-US-226, AIFACTORY-US-227, AIFACTORY-US-228, AIFACTORY-US-229, feature:component-base-template-findings |
| Sources | model/components.yaml, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md, model/template-parameters/connectsoft-base.yaml, docs/architecture/catalogs/templates.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-1464 Admission of one additional gating case per declared profile in the shared template pipeline |
implementation | The manifest schema and Read-TemplateManifest.ps1 of template-ci/v1 accept a declared profile with one additional gating case beside the one Domain case per artifact kind and refuse a second additional case of the same profile with the case named; the installer jobs run that case on every change and the publication evidence requires its complete report; Test-InstallerTooling.SelfTest.ps1 covers an admitted and a refused manifest, the readme of template-ci/v1 states the rule, and a manifest without a declared profile is gated as before. |
ConnectSoft.AzurePipelines |
AIFACTORY-TASK-1083 Factory preset case as the additional gating case of the template pipeline manifest |
operations | build/template-ci.json declares the Factory profile and holds, beside the default Domain cases, the Factory preset case as its one additional gating case, generated with UseFactoryProfile, the Orleans messaging value and a Factory service name, with its test filter and the required services SQL Server and a silo; build/local-scaffold-presets.ps1 offers the same preset for local runs; the shared installer jobs run the case on every change. |
ConnectSoft.BaseTemplate |
AIFACTORY-TASK-1084 Planted failing Factory case for the gate |
fixture | A pipeline fixture generates the Factory preset case with a planted failing test and asserts that the run fails at the test stage with the case named, that the diagnostics artifact holds its logs and that publication is not reached. | ConnectSoft.BaseTemplate |
AIFACTORY-TASK-1085 Publication on the complete report of the Factory preset case |
operations | The publication job of the template pipeline requires the complete report of the Factory preset case beside the reports of the other cases, each bound to the candidate hash, the selected profile and the test filter; a missing or failed stage, an incomplete report or a version that is already on the feed refuses publication with the reason. | ConnectSoft.BaseTemplate |
AIFACTORY-TASK-1086 Verify the gate on a green run and on the planted run |
verification | One pipeline run with every case green reaches publication and a fresh install of the published version generates the Factory preset that builds unchanged; the planted run fails before publication; both prove AC1 to AC3 of AIFACTORY-US-230 (ADR-0028, FR-11). | ConnectSoft.BaseTemplate |
AIFACTORY-US-103: Base template: the Factory service profile is delivered and proven on a generated solution¶
enabling · persona asset-maintainer
As an asset maintainer, I want BaseTemplate to carry the Factory service profile, so that it serves every Factory service that is not a gateway or an agent host, and every generated product module (D94, D95) without later rework.
This is the integration PBI of the feature. Forty-six Factory services are scaffolded from the base template and deploy alone, so the profile carries per service what a host did once. With the Orleans messaging choice and the accepted envelope, the scope chain with its 404, 403 and 401 answers, token validation through the resource-server library with the seven Factory roles, the descriptor-described REST and gRPC surface with health, readiness and the telemetry wiring, and the Factory preset case in the shared template pipeline, the asset maintainer runs the pipeline end to end: pack, install, generate the Factory preset, build, test and audit, then publish. A case that fails any stage blocks publication. The migrated implementation tasks sit under the PBIs that deliver them, and the verification task of this PBI is the proof on the published package. The feature is done when a service generated from the published package with the Factory profile builds and passes unchanged, which is what the readiness checklist of the increment accepts, and when the template inventory of this repository lists the new symbols. The activities and log records of a generated service carry tenant, project, run, step and attempt correlation and its metrics carry tenant and project, because the profile pins the single enrichment registration of the feature component-observability-factory-conventions, which is in the same increment (D114).
Acceptance criteria
| AC1 | Given the template repository ConnectSoft.BaseTemplate with the work of this feature, when the template is packed, installed and instantiated with the Factory preset in its pipeline, then the generated solution builds and its tests pass before the package publishes with a verified version (ADR-0028, model/components.yaml). |
| AC2 | Given the work of AIFACTORY-TASK-580 (messaging profile Orleans with the accepted envelope) is done, then MessagingModelType accepts Orleans, the generated service registers the outbox dispatcher and the inbox grains of the Orleans messaging adapter library and writes the ADR-0014 envelope on every published message in the transaction of the state change, and the Compatibility cases of the template pipeline have an Orleans case (ADR-0012). |
| AC3 | Given the work of AIFACTORY-TASK-581 (Factory scope from the token to every call and message) is done, then the generated service takes the tenant from the tid claim, admits a project only when the token grants it, forwards the scope on outbound calls and stamps it on messages, answers 404 for an identifier of another tenant, 403 for a project or a scope the token does not grant inside the own tenant and 401 without a token, sends a message without the tenant to the poison handling of the Orleans messaging profile, and handles a tenant-level event without a project under a tenant-only scope (ADR-0015, ADR-0014 decision 1). |
| AC4 | Given the work of AIFACTORY-TASK-582 (token validation with the Factory roles) is done, then the generated service validates tokens of the authorization server through the resource-server library, maps the seven Factory roles to policies and refuses a token without the role its endpoint requires in the project of the request, and the acceptance suite covers the matrix (ADR-0015 decision 5). |
| AC5 | Given the work of AIFACTORY-TASK-583 (descriptor-described REST and gRPC surface with health and telemetry) is done, then a generated service exposes its REST and gRPC endpoints from a service descriptor file, serves health and readiness, and wires its telemetry through the single enrichment registration of the pinned observability libraries, so that its activities and log records carry tenant, project, run, step and attempt correlation and its metrics carry tenant and project, with no enricher of its own, and the architecture tests assert the three (ADR-0014, ADR-0028). |
| Traces: adrs | ADR-0012, ADR-0014, ADR-0015, ADR-0024, ADR-0028 |
| Depends on | AIFACTORY-US-226, AIFACTORY-US-227, AIFACTORY-US-228, AIFACTORY-US-229, AIFACTORY-US-230 |
| Sources | model/components.yaml, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md, docs/templates-docs/base-template.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-672 Verify base-template-factory-profile-delivered by running the declared command |
verification | Run dotnet build -c Release and dotnet test -c Release --no-build on the solution generated from the published package with the Factory preset; they pass and prove AC1 to AC5 of AIFACTORY-US-103. |
ConnectSoft.BaseTemplate |
AIFACTORY-TASK-1087 Template inventory of this repository records the Factory profile symbols |
documentation | After python -I tools/docs_model inventory-templates, model/template-parameters/connectsoft-base.yaml lists UseFactoryProfile and the value Orleans of MessagingModelType; the authored note of MessagingModelType no longer says that the template offers only NServiceBus and MassTransit and its factory_default names the Orleans value, and the authored note of ServiceModelType says that the Factory profile generates both service models and no longer that the recipe adds the gRPC project; the generated row of docs/architecture/catalogs/templates.md still renders. |
ConnectSoft.AI.SoftwareFactory.Documentation |