AIFACTORY-FEAT-163: SaaS Tenants template: descriptor, lifecycle, envelope and isolation before the Factory resolves tenants¶
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 15 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).
The Factory resolves its tenants from the SaaS Tenants service from the first increment (FEAT-100) and every generated SaaS product gets its product tenants from the same template (GeneratedSaasFoundations). The template's own gap backlog (saas-EPIC-TEN) is not started: the JSON descriptor and the code disagree, the lifecycle saga covers creation only while the Factory needs Suspended and Decommissioned, integration events carry no common envelope, the Orleans write path is undecided and the architecture tests are placeholders. The two-tenant isolation recipe (OP-020 of the Entitlements template) has no fixture yet. What the Factory needs before FEAT-100 is taken from that backlog; the rest stays with the template. Component: SaaS Tenants service (extend).
| Delivers | — |
| Stubs | — |
| Realizes | components: cmp-saas-tenants adrs: ADR-0014, ADR-0015, ADR-0025 bounded contexts: BC-33 |
| Requirements | — |
| Depends on | — |
| Sources | model/components.yaml, model/services/generated-saas/GeneratedSaasFoundations.yaml, ConnectSoft.Saas.TenantsTemplate/Docs/backlog/tenants-gap-backlog.md, ConnectSoft.Saas.EntitlementsTemplate/Docs/OP-020-SaaS-Two-Tenant-Isolation.md |
AIFACTORY-US-249: SaaS Tenants template: the Tenants descriptor and its entity-model schema describe exactly the aggregate, enumerations and events of the code, and the build validates it¶
enabling · persona asset-maintainer
As an asset maintainer, I want the Tenants descriptor to be a true description of the Tenants service, so that the descriptor import of the Factory and every generated product read what the code really has.
ADR-0025 makes the SaaS descriptor family an import format: the blueprint service maps a context descriptor with its entity-model schema into a Service blueprint and a Module blueprint and records the content hash as provenance. An import of a descriptor that disagrees with the code would produce blueprints of a service that does not exist. Feature saas-TEN-F04 of the gap backlog of the template (Docs/backlog/tenants-gap-backlog.md of the template) lists the disagreement of ConnectSoft.Saas.Tenants.json with the entity ITenant: the descriptor names one guid key where the code has an aggregate identifier and a string partition key, it calls the region RegionCode where the code has ResidencyRegion, it omits TenantKey and AggregateVersion, and its lifecycle vocabulary differs from the event topics. The backlog takes the code as the runtime truth. Its feature saas-TEN-F01 asked whether the tenant stays flat or gains child entities and for program acceptance of the choice, and decision record 0002 of the template (Docs/adr/0002-flat-tenant-vs-rich-aggregate.md of the template) held both options. The owner has accepted the flat tenant (D114). This PBI reconciles the descriptor with the flat tenant the code has, which is all the Factory needs, and records the acceptance in that decision record with the mapping of each deferred blueprint concept. The descriptor then documents both identifiers, the property names of the code, every enumeration value and the five published events. The validation mode of build/regenerate.ps1 runs on every build, and a drift test compares the descriptor with the public surface of ITenant, the enumerations and the event types and fails with the member named. The generated projects are not edited by hand to make the test pass.
Acceptance criteria
| AC1 | Given the reconciled descriptor, when it is compared with the entity of the code, then it documents the aggregate identifier and the string partition key, the property ResidencyRegion, TenantKey and AggregateVersion, every lifecycle value of the enumeration and the five published events, and it validates against its schema and its entity-model schema (ADR-0025 decision 2, saas-TEN-F04 of the gap backlog of the template, model/services/generated-saas/GeneratedSaasFoundations.yaml). |
| AC2 | Given a property, an enumeration value or an event type added to the code without the descriptor, or to the descriptor without the code, when the solution builds and the drift test runs, then the validation mode of the regenerate script or the drift test fails and names the member, and no generated project is edited by hand to pass (ADR-0025 decision 4, FR-11). |
| AC3 | Given decision record 0002 of the template on the flat tenant, which the owner has accepted, when this PBI is done, then the record carries the status accepted for the flat option with the acceptance recorded, lists each blueprint concept that is collapsed into a scalar of the flat tenant with its field, and the descriptor holds no child entity the code lacks, so that the descriptor import of the Factory reads a true descriptor (ADR-0025 decision 2, docs/architecture/adr/0025-saas-descriptor-import.md). |
| Traces: adrs | ADR-0025 |
| Traces: requirements | FR-11 |
| Sources | model/components.yaml, model/services/generated-saas/GeneratedSaasFoundations.yaml, docs/architecture/adr/0025-saas-descriptor-import.md, docs/architecture/ecosystem-composition.md, model/template-parameters/connectsoft-saas-tenants.yaml |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-601 Descriptor reconciled with the code (saas-TEN-F04) |
contract | The Tenants descriptor JSON and its entity-model schema describe exactly the aggregate, enumerations and events the code has; the generator validates the descriptor on every build and the generated projects are not hand edited, so the Factory's descriptor import (ADR-0025) reads a true descriptor. | ConnectSoft.Saas.TenantsTemplate |
AIFACTORY-TASK-1143 Descriptor drift test over the tenant entity, the enumerations and the event types |
fixture | An architecture test reads ConnectSoft.Saas.Tenants.json and compares it with the public surface of ITenant, the lifecycle enumeration and the event types of the messaging model in both directions; a planted extra property fails it with the member named. |
ConnectSoft.Saas.TenantsTemplate |
AIFACTORY-TASK-1144 Acceptance of the flat tenant recorded in decision record 0002 with its mapping table |
documentation | Decision record 0002 of the template on the flat tenant versus the rich aggregate carries the status accepted for the flat option, records the acceptance of the owner and holds a table that maps each deferred blueprint concept to the scalar that stands in for it; the documentation of the template refers to it wherever it names a deferred concept. | ConnectSoft.Saas.TenantsTemplate |
AIFACTORY-TASK-1145 Verify the descriptor against the code and the schema |
verification | Run the validation mode of the regenerate script, build in Release and run the drift test clean and with a planted extra property; the clean run passes and the planted run fails with the member named, which proves AC1 to AC3 of AIFACTORY-US-249 (ADR-0025). | ConnectSoft.Saas.TenantsTemplate |
AIFACTORY-US-250: SaaS Tenants template: activate, suspend, restore and decommission are commands with events, and under the Orleans profile every write passes through the lifecycle grain¶
enabling · persona asset-maintainer
As an asset maintainer, I want the Tenants service to carry a tenant through its whole lifecycle, so that the Factory can suspend, restore and decommission a tenant and every consumer learns of it.
The Factory resolves its tenants from the Tenants service and needs the states Suspended and Decommissioned from the first increment; the product tenants of a generated product move through the same lifecycle with a restore from Suspended to Active (model/services/generated-saas/GeneratedSaasFoundations.yaml). Feature saas-TEN-F03 of the gap backlog of the template (Docs/backlog/tenants-gap-backlog.md of the template) records that the lifecycle saga of the template is a stub for creation only: it correlates on the created event, logs and finishes at once, while the service contract already has operations for draft creation, activation, suspension, decommissioning and a change of residency. The backlog asks for a saga with a durable repository per saas-INTEG-F05 and for states beyond create for the activate, suspend, decommission and residency paths, and saas-TEN-F08 is the grain path. This PBI takes from that what the Factory needs and says what it leaves. The commands activate, suspend and decommission check the current state, refuse a transition the state does not allow with a conflict that names both states, and raise an event. Restore is no new operation: DefaultTenantsProcessor.AllowedTransitions already admits Suspended to Active, so a restore is the activation of a suspended tenant, announced on tenants.domain.v1.tenant-activated with the previous state in the payload, so that a consumer can tell a restore from a first activation. The orchestration differs per messaging profile. Decision record 0003 of the template on the Orleans write path (Docs/adr/0003-orleans-write-path-decision.md of the template) offered two options: route every write through TenantLifecycleGrain, or keep the processor as the write path. The owner has accepted the lifecycle grain under the Orleans messaging profile, with the MassTransit saga only where MassTransit is selected (D114). The Factory generates the service with the Orleans messaging profile, and under it the lifecycle state is held and persisted by TenantLifecycleGrain, every write of the REST and gRPC adapters passes through it, and an architecture rule enforces it; this PBI records the acceptance in that decision record. Under MassTransit the durable saga repository of saas-INTEG-F05 is not delivered here and stays with the template: the saga remains the creation stub, and the MassTransit case is gated on the commands and their events only. The residency path stays with the template as well. Feature saas-TEN-F05 leaves the vocabulary open: the enumeration says Decommissioned and the topic says deleted. This PBI records the mapping in a decision record of the template, with the Factory reading the deleted event as the terminal decommissioned state and not as a removed row, with the draft state as what the Factory calls pending, and with the five values of ProductTenantState of the model (Provisioning, Active, Suspended, Offboarding, Deleted) mapped to the four states of the template.
Acceptance criteria
| AC1 | Given a tenant in each lifecycle state, when activate, suspend or decommission is called, then a transition the state allows changes the state, increases the aggregate version and raises its event, a transition the state does not allow is refused with a conflict that names the current and the requested state and raises nothing, and the activation of a suspended tenant is the restore, announced on tenants.domain.v1.tenant-activated with the previous state Suspended in the payload (saas-TEN-F03 of the gap backlog of the template; model/services/generated-saas/GeneratedSaasFoundations.yaml for the transitions; ADR-0015 decision 4 keeps Factory tenants and product tenants distinct users of the same lifecycle). |
| AC2 | Given a Tenants service generated with the Orleans messaging profile, when create, activate, suspend, restore and decommission run in sequence for one tenant, then every write of the REST and gRPC adapters passes through TenantLifecycleGrain keyed by the tenant, the grain holds and persists the lifecycle state after each event, an architecture rule fails when an adapter calls the processor directly, and the tests cover create to activate and suspend to restore to decommission (ADR-0014 decision 4 on a transition written with its record; saas-TEN-F08 of the gap backlog of the template). |
| AC3 | Given a Tenants service generated with MassTransit, when the same commands run, then the commands and their events behave as under the Orleans profile, the lifecycle saga remains the creation stub, the documentation of the template names the durable saga repository of saas-INTEG-F05 and the residency path as work that stays with the template, and the gate runs the command and event tests of that case and no orchestration test (saas-TEN-F03 of the gap backlog of the template, ADR-0015 decision 4, docs/architecture/ecosystem-composition.md). |
| AC4 | Given the vocabulary question of saas-TEN-F05, when this PBI is done, then a decision record of the template states that the deleted event announces the terminal decommissioned state and not a removed row, that the draft state is what the Factory calls pending, and which state of the template stands for each of the five values of ProductTenantState: Provisioning is Draft, Active is Active, Suspended is Suspended, Deleted is Decommissioned, and Offboarding has no state of the template and is held by the product until it calls decommission; the events page of the template says the same, and decision record 0003 of the template carries the status accepted for the option that routes every write through the grain under the Orleans messaging profile, with the acceptance of the owner recorded (ADR-0015 decision 4, model/services/generated-saas/GeneratedSaasFoundations.yaml). |
| Traces: adrs | ADR-0014, ADR-0015 |
| Depends on | AIFACTORY-US-249 |
| Sources | model/components.yaml, model/services/generated-saas/GeneratedSaasFoundations.yaml, docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md, docs/architecture/adr/0014-run-and-lifecycle-envelopes.md, docs/architecture/ecosystem-composition.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-1146 Previous state on the activation event and the conflict fault of a refused transition |
contract | The service contract of the template keeps its five operations and gains no restore operation; the payload of the activation event carries the previous state, so that the activation of a suspended tenant is readable as a restore on tenants.domain.v1.tenant-activated, as an additive change under the first version of the topic; the conflict fault for a refused transition names the current and the requested state; the published language of the template records both. |
ConnectSoft.Saas.TenantsTemplate |
AIFACTORY-TASK-602 Full tenant lifecycle with Suspended and Decommissioned (saas-TEN-F03) |
implementation | Activate, suspend and decommission are commands of the aggregate with events, and restore is the activation of a suspended tenant; under the Orleans messaging profile the lifecycle grain holds and persists the state for each of them, not creation alone, and every write passes through it; under MassTransit the lifecycle saga stays the creation stub and the durable saga stays with the template; the Factory's Pending and Deleted vocabulary decision of saas-TEN-F05 is recorded in the template's ADR. | ConnectSoft.Saas.TenantsTemplate |
AIFACTORY-TASK-1175 Architecture rule and grain tests of the Orleans write path |
fixture | An architecture test of the Orleans case fails when a REST or gRPC adapter references the processor directly instead of ITenantLifecycleGrain, with a planted direct call as its negative control; grain tests run create, activate, suspend, restore and decommission for one tenant and read the persisted lifecycle state after each event and after a reactivation of the grain. |
ConnectSoft.Saas.TenantsTemplate |
AIFACTORY-TASK-1147 Vocabulary decision record and the recorded acceptance of the Orleans write path |
documentation | The decision records of the template state the mapping of deleted to decommissioned, of draft to pending and of the five values of ProductTenantState to the four states of the template; decision record 0003 of the template carries the status accepted for the option that routes every write through TenantLifecycleGrain under the Orleans messaging profile, with the MassTransit saga only where MassTransit is selected, and records the acceptance of the owner; the documentation names the durable saga of saas-INTEG-F05 and the residency path as work that stays with the template, and the events page uses the same words. |
ConnectSoft.Saas.TenantsTemplate |
AIFACTORY-TASK-1148 Verify the lifecycle transitions and their orchestration |
verification | Run the unit and integration tests of the lifecycle on both cases: every allowed transition raises its event, the activation of a suspended tenant carries the previous state, every refused one answers a conflict, the Orleans case holds the persisted state in the grain after each event and fails the planted direct call, and the MassTransit case passes its command and event tests, which proves AC1 to AC4 of AIFACTORY-US-250 (ADR-0015). | ConnectSoft.Saas.TenantsTemplate |
AIFACTORY-US-251: SaaS Tenants template: every Tenants integration event carries the complete envelope base, which the Factory profile maps, and is published through the outbox of the Orleans messaging profile¶
enabling · persona asset-maintainer
As an asset maintainer, I want the Tenants events to carry the complete envelope base of the template and to leave the service through a transactional outbox, so that a Factory service that consumes a tenant event can attribute and deduplicate it and never sees an event for a change that was rolled back.
ADR-0014 decision 1 fixes the run event envelope of Factory integration events, and its schema (docs/reference/schemas/run-event-envelope.schema.json) names the required fields: eventId, eventType, schemaVersion, occurredAt, producer, tenantId, correlationId and payload. causationId, project, run and attempt are optional. The amendment of that decision (D114) settles who writes it: a Factory service writes the run event envelope of the contracts package for its integration events, while the generic SaaS templates keep their own envelope base and the Factory profile maps it. The Tenants template is generic, it serves the Factory tenants and the product tenants of every generated product, so it pins no Factory package and writes no run event envelope. Its base is the common integration event envelope of the SaaS family (saas-INTEG-F03 of the gap backlog of the template, Docs/backlog/tenants-gap-backlog.md of the template): tenantId, aggregateId, aggregateVersion, schemaVersion, correlationId, an optional causationId and occurredOn. Feature saas-TEN-F05 of the same backlog records that the Tenants events carry it only in part: tenant, aggregate identifier, aggregate version and time, without schema version and correlation id. Decision 4 has the state transition and the outbox record written in one transaction of the selected messaging profile, and the template publishes through MassTransit today. This PBI completes the envelope base on the five event types of the messaging model and records in the published language of the template the mapping that the Factory profile of the base template applies on receipt (AIFACTORY-US-227): tenantId, schemaVersion, correlationId and causationId map by name, occurredOn is occurredAt, the message id of the publication is eventId, the topic name is eventType, the messaging service name of the Tenants service is producer, the event body is payload, and aggregateId with aggregateVersion gives the ordering key and the aggregate revision, so that every required field of the run event envelope has a source. The PBI also lets the template generate with the Orleans messaging profile that the base template gains in its Factory profile feature. That value reaches this template only through its base-template submodule, so the submodule pointer moves to the base template that carries it, the template metadata is reconciled and build/MaterializedDirectory.Packages.props is regenerated. The outbox dispatcher and the inbox grains then come through the submodule, and the template adds no messaging code and no second envelope type. The Orleans messaging adapter needs SQL Server and the NHibernate unit of work, while the template advertises several dialects, so the Orleans case generates with NHibernate on SQL Server and another dialect is refused with the symbols named. The correlation id is taken from the inbound correlation or trace context of the REST or gRPC call. The causation id is the identifier of the command that caused the event and is absent when there is none; the trace id is diagnostics and never stands in for it. The fields of the run event envelope that a tenant event has no value for, such as project, run and attempt, have no source in the base and stay absent after the mapping, as the envelope allows. An event whose base field is missing is refused at publication with the field named. MassTransit stays the selectable transport of generated products and its topology does not change. Golden files fix the serialised form of each event, and a consumer test reads an activation and a suspension from the Orleans inbox with every field of the base filled.
Acceptance criteria
| AC1 | Given the five event types of the Tenants messaging model, when each is serialised, then it carries the envelope base of the template complete, tenantId, aggregateId, aggregateVersion, schemaVersion, correlationId and occurredOn, and the mapping table of the published language names a source for every required field of the run event envelope, eventId, eventType, schemaVersion, occurredAt, producer, tenantId, correlationId and payload; the correlation id is the inbound correlation or trace context of the call, the causation id is the identifier of the command that caused the event and is absent when there is none; its golden file matches, publication of an event with a missing base field is refused with the field named, and the template pins no Factory package (ADR-0014 decision 1 and its amendment on envelopes per event family, saas-TEN-F05 of the gap backlog of the template, docs/reference/schemas/run-event-envelope.schema.json). |
| AC2 | Given the base-template submodule moved to the base template that carries the Orleans value, when a Tenants service is generated with the Orleans messaging profile, then it generates with NHibernate on SQL Server and another dialect is refused with the symbols named; when a command changes the tenant and its unit of work commits, then the outbox record of the event is committed in the same transaction, and when the unit of work rolls back no record exists and no event is delivered (ADR-0014 decision 4, ADR-0012 decision 4, ADR-0024). |
| AC3 | Given a consumer on the Orleans inbox, when a tenant is activated and then suspended, then the consumer reads both events with every field of the envelope base filled and the correlation id of the call that caused them, each field the mapping onto the run event envelope needs has a value, and a second delivery of either message id has no effect (ADR-0014 decision 3, ADR-0012). |
| AC4 | Given a generation of the template with MassTransit, when its tests run, then the events carry the same envelope base and the topology and topic names are unchanged, so that MassTransit stays a selectable transport for products (ADR-0012 decision 3, model/template-parameters/connectsoft-saas-tenants.yaml). |
| Traces: adrs | ADR-0012, ADR-0014, ADR-0024 |
| Depends on | AIFACTORY-US-250, feature:component-base-template-factory-profile |
| Sources | model/components.yaml, docs/architecture/adr/0014-run-and-lifecycle-envelopes.md, docs/architecture/adr/0012-messaging-port-and-transport-profiles.md, docs/architecture/adr/0024-durable-execution-substrate.md, docs/reference/event-envelope.md, docs/reference/schemas/run-event-envelope.schema.json, model/template-parameters/connectsoft-saas-tenants.yaml |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-1176 Base-template submodule moved to the Orleans value with the template metadata and the package snapshot regenerated |
operations | The base-template submodule of the Tenants template points at the base template that carries the value Orleans of MessagingModelType, the template metadata of connectsoft-saas-tenants offers the value with its SQL Server and NHibernate constraint, build/MaterializedDirectory.Packages.props is regenerated and its check passes; no file inside the submodule is edited. |
ConnectSoft.Saas.TenantsTemplate |
AIFACTORY-TASK-1149 Complete envelope base on the five Tenants event types with golden files and the mapping table |
contract | The five event types of the messaging model implement the envelope base of the template with schemaVersion, correlationId and the optional causationId beside the fields they have, with the correlation id from the inbound call and the causation id from the command; the published language page of the template holds the table that maps the base onto the run event envelope; a golden JSON file per event fixes the serialised form, the architecture test for the published language fails on an event type without the base, and the template pins no Factory package. |
ConnectSoft.Saas.TenantsTemplate |
AIFACTORY-TASK-603 Envelope base and the Orleans messaging profile on the Tenants events |
implementation | Every integration event of the template carries the complete envelope base of the template, which the Factory profile maps onto the run event envelope (ADR-0014), and is published through the outbox of the Orleans messaging profile (ADR-0024), which generates with NHibernate on SQL Server; a consumer test reads TenantActivated and TenantSuspended with the envelope fields filled. | ConnectSoft.Saas.TenantsTemplate |
AIFACTORY-TASK-1150 Consumer test on the Orleans inbox and the rollback test of the outbox |
fixture | The acceptance suite of the Orleans case holds a consumer that reads an activation and a suspension with every required field, a duplicate delivery test and a rollback test that finds no outbox record. | ConnectSoft.Saas.TenantsTemplate |
AIFACTORY-TASK-1151 Verify the envelope on both messaging profiles |
verification | Generate the template with the Orleans messaging profile and with MassTransit, build both in Release and run the golden file, consumer and rollback tests; all pass on both and an Orleans generation with another dialect is refused, which proves AC1 to AC4 of AIFACTORY-US-251 (ADR-0014, ADR-0012). | ConnectSoft.Saas.TenantsTemplate |
AIFACTORY-US-252: SaaS Tenants template: a two-tenant fixture proves that a caller reads only its own rows and gets 404 for the other tenant, and real architecture tests replace the placeholders¶
enabling · persona asset-maintainer
As an asset maintainer, I want the isolation of the Tenants service and its layering rules to be proven by tests that can fail, so that the Factory resolves tenants from a service whose tenant filter and structure are verified and not assumed.
The isolation recipe of the SaaS family (Docs/OP-020-SaaS-Two-Tenant-Isolation.md of the entitlements template) is a planning record with no fixture yet. It sets the cases: each of two tenants reads its own data, a caller of one tenant that targets the other gets 404 and no payload of the other, a principal without a resolvable tenant gets 401 before the query runs, overlapping requests keep their own context, and no tenant value survives from one request to the next. It fixes the conditions too: one test server and one disposable shared database with two synthetic tenants, the production tenancy wiring with the tenant claim required and no default tenant, no reuse of the acceptance startup that can drop the configured catalog, and, when the cross-tenant case fails, the evidence is kept and the assertion is not weakened. This PBI builds that fixture for the Tenants service, whose read by identifier is the operation under test. Feature saas-TEN-F06 of the gap backlog of the template (Docs/backlog/tenants-gap-backlog.md of the template) records that two architecture tests of the template are placeholders that always pass. This PBI replaces them with rules that can fail: one aggregate root per repository, the published-language rule with the envelope on every event type, both after the reference implementation in the products catalog template, and it keeps the layering test that is already real. A rule that inspects no type fails instead of passing.
Acceptance criteria
| AC1 | Given two synthetic tenants on one disposable shared database and one test server with the production tenancy wiring, when each tenant reads its own tenant row, then each gets 200 with its own data; when a caller of one tenant reads the identifier of the other, then the answer is 404 with no data of the other tenant (ADR-0015 decision 3 and its amendment on a resource of another tenant, D113; docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md). |
| AC2 | Given an authenticated principal without a tenant claim and no other tenant source, when it calls the read, then the answer is 401 before the query runs; given overlapping and repeated requests of the two tenants on the same host, when they run, then each keeps its own tenant context and no tenant value survives from another request (ADR-0015 decision 1, NFR-01). |
| AC3 | Given the architecture tests of the template, when a second aggregate root, an event type without the envelope or a forbidden reference across the published language is planted, then the matching rule fails with the type named, the existing layering rule still passes on the clean code, and a rule that inspected no type fails (saas-TEN-F06 of the gap backlog of the template, ADR-0014 decision 1, FR-11). |
| Traces: adrs | ADR-0014, ADR-0015 |
| Traces: requirements | FR-11 |
| Relates: nfrs | NFR-01 |
| Depends on | AIFACTORY-US-251 |
| Sources | model/components.yaml, docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md, docs/architecture/adr/0014-run-and-lifecycle-envelopes.md, model/services/generated-saas/GeneratedSaasFoundations.yaml, docs/planes/control/tenancy.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-1152 Disposable shared database with two synthetic tenants on a test server with production tenancy wiring |
fixture | A fixture of the acceptance tests creates a disposable shared database, seeds two synthetic tenants and starts one test server with the tenant claim required, no default tenant and the resolver pipeline of production; it does not use the acceptance startup that can drop the configured catalog and it removes the database when it ends. | ConnectSoft.Saas.TenantsTemplate |
AIFACTORY-TASK-1153 Architecture rules that replace the two placeholder tests |
implementation | The one-aggregate-root rule and the published-language rule with the envelope check are implemented with the architecture test library after the products catalog template, assert that they inspected at least one type, and fail on a planted violation; the layering test is unchanged. | ConnectSoft.Saas.TenantsTemplate |
AIFACTORY-TASK-604 Two-tenant isolation fixture and real architecture tests |
verification | The acceptance run on the two-tenant fixture shows that a caller of one tenant reads only its own rows and gets 404 for the other and 401 without tenant context (the OP-020 cases), and the architecture run shows the placeholder tests of saas-TEN-F06 replaced by rules that fail on a planted violation, which proves AC1 to AC3 of AIFACTORY-US-252. | ConnectSoft.Saas.TenantsTemplate |
AIFACTORY-US-253: SaaS Tenants template: the packed template passes the Orleans and MassTransit cases of the shared template pipeline, descriptor validated and isolation tested, before the package publishes¶
evidence · persona asset-maintainer
As an asset maintainer, I want the Tenants template to be gated by solutions generated from its package, so that the Factory tenants and every product tenant come from a package whose descriptor is true and whose isolation is tested.
The estate gates its templates with the shared template pipeline of ConnectSoft.AzurePipelines (template-ci/v1), whose rollout ledger lists the Tenants template as pending. The Tenants template packs connectsoft-saas-tenants and composes on the base template through its submodule. This PBI is the proof of the feature and adopts that mechanism. A build/template-ci.json manifest declares two cases, one generated with MassTransit and one with the Orleans messaging profile. The MassTransit case is the default generation of the template and stays gated as today. The Orleans case is the one additional gating case that the amendment of ADR-0028 (D114) admits for a declared profile, here the Orleans messaging profile, and the admission in the shared tooling is AIFACTORY-TASK-1464 of the feature component-base-template-factory-profile, on which this PBI depends. Both cases carry the validation mode of the regenerate script as the case validator of the descriptor, the test filter of each case and the services the tests need: SQL Server for the outbox and the two-tenant fixture, and a co-hosted silo for the Orleans case. The template pipeline imports the shared installer jobs: the candidate is packed once and installed, each case is generated, its descriptor is validated, the solution is restored and built in Release, its tests run with the discovery and completion checks, with the lifecycle tests, the envelope golden files, the consumer test and the two-tenant fixture among them, and the dependency audit runs. The MassTransit case runs the command and event tests and no orchestration test, as the lifecycle PBI states. The Scripts check of the shared tooling runs in check mode against the Scripts folder of the base-template submodule. A descriptor that drifts, a failing isolation case or an incomplete run fails the run with the case and the stage named, and the package is not published. Publication requires the complete reports of both cases bound to the candidate and pushes a version that is not yet on the ConnectSoft feed. The PBI proves ADR-0025 for the Tenants descriptor, the isolation rule of ADR-0015 and the release gate of FR-11, before the tenancy integration feature resolves the first Factory tenant.
Acceptance criteria
| AC1 | Given a change of the Tenants template, when its template pipeline runs the shared installer jobs with build/template-ci.json, then the candidate is packed once and installed, the MassTransit case, the default generation gated as today, and the Orleans case, the one additional gating case of the declared Orleans messaging profile, are generated, the descriptor of each is validated by its case validator, each is restored and built in Release, its tests run with the discovery and completion checks against the services the manifest declares, SQL Server for the outbox and the two-tenant fixture and a co-hosted silo for the Orleans case, the dependency audit runs, and the Scripts check passes in check mode (ADR-0025, ADR-0015, ADR-0028 amendment on one additional gating case per declared profile, FR-11). |
| AC2 | Given a planted descriptor drift, a planted failure of the cross-tenant case or an incomplete run, when the pipeline evaluates the run, then it fails with the case and the stage named and the package is not published (FR-11, docs/architecture/adr/0025-saas-descriptor-import.md). |
| AC3 | Given complete reports of both cases bound to the candidate hash, when the publication job runs, then the package is pushed with a version that was not on the feed, and a fresh install of that version generates a Tenants service whose descriptor validates and whose lifecycle, envelope and isolation tests pass unchanged (ADR-0014, ADR-0015, model/template-parameters/connectsoft-saas-tenants.yaml). |
| Traces: adrs | ADR-0014, ADR-0015, ADR-0025, ADR-0028 |
| Traces: requirements | FR-11 |
| Depends on | AIFACTORY-US-249, AIFACTORY-US-250, AIFACTORY-US-251, AIFACTORY-US-252, feature:component-base-template-findings, feature:component-base-template-factory-profile |
| Sources | model/components.yaml, model/services/generated-saas/GeneratedSaasFoundations.yaml, docs/architecture/adr/0025-saas-descriptor-import.md, docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md, model/template-parameters/connectsoft-saas-tenants.yaml, docs/architecture/catalogs/templates.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-1154 Shared template pipeline manifest of the Tenants template with the Orleans and MassTransit cases |
operations | build/template-ci.json of the Tenants template declares the package, the solutions and the tests, the MassTransit case as the default generation and the Orleans case as the one additional gating case of the declared Orleans messaging profile, with the validation mode of build/regenerate.ps1 as the descriptor validator of each, the test filter of each case and the required services SQL Server and, for the Orleans case, a silo; azure-pipelines-template.yml imports template-ci/v1/installer-jobs.yml of the shared tooling and holds no stage of its own for generation, tests or audit; publication requires the complete reports of both cases bound to the candidate. |
ConnectSoft.Saas.TenantsTemplate |
AIFACTORY-TASK-1177 Scripts check of the Tenants template in check mode |
operations | The manifest of the Tenants template holds the entry of the Scripts check, the root Scripts folder is written from the Scripts folder of the base-template submodule, and the pipeline runs the check in check mode beside the package snapshot check and fails with the missing and the changed files named. | ConnectSoft.Saas.TenantsTemplate |
AIFACTORY-TASK-1155 Planted descriptor drift and planted isolation failure for the gate |
fixture | Pipeline fixtures plant an extra descriptor property and a disabled tenant filter, and assert that each run fails at its stage with the case named and that publication is not reached; publication refuses a version that is already on the feed. | ConnectSoft.Saas.TenantsTemplate |
AIFACTORY-TASK-1156 Verify the gate of the Tenants template on a green and on the planted runs |
verification | One green run publishes the package and a fresh install generates a Tenants service whose tests pass; the two planted runs fail before publication; together they prove AC1 to AC3 of AIFACTORY-US-253 (ADR-0025, ADR-0015, FR-11). | ConnectSoft.Saas.TenantsTemplate |
AIFACTORY-US-109: SaaS Tenants template: descriptor, lifecycle, envelope and isolation before the Factory resolves tenants is delivered and proven on a generated solution¶
enabling · persona asset-maintainer
As an asset maintainer, I want SaaS Tenants service to carry descriptor, lifecycle, envelope and isolation before the Factory resolves tenants, so that it serves factory tenants (BC-33) and product tenants (BC-31) without later rework.
This is the integration PBI of the feature. The Factory resolves its tenants from the SaaS Tenants service from the first increment and every generated product gets its product tenants from the same template, whose gap backlog is not started. What the Factory needs first is taken from that backlog and the rest stays with the template: the durable saga of the MassTransit profile, the residency path and the rich tenant aggregate. With the descriptor reconciled with the code, the lifecycle commands with suspension, restore and decommissioning and the lifecycle grain as the write path of the Orleans profile, the complete envelope base on every event, mapped by the Factory profile onto the run event envelope, through the outbox of the Orleans messaging profile, the two-tenant isolation fixture with real architecture tests, and the two cases in the shared template pipeline, the asset maintainer runs the pipeline end to end: pack, install, generate both messaging cases, validate, build, test and audit, then publish. A failing case blocks publication. The migrated 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 Tenants service generated from the published package validates its descriptor and passes its lifecycle, envelope and isolation tests unchanged.
Acceptance criteria
| AC1 | Given the template repository ConnectSoft.Saas.TenantsTemplate with the work of this feature, when the template is packed, installed and instantiated in its pipeline, then the generated solution builds and its tests pass before the package publishes with a verified version (ADR-0015, model/components.yaml). |
| AC2 | Given the work of AIFACTORY-TASK-601 (descriptor reconciled with the code, saas-TEN-F04) is done, then the Tenants descriptor JSON and its entity-model schema describe exactly the aggregate, enumerations and events the code has, the generator validates the descriptor on every build and the generated projects are not hand edited, so that the descriptor import of the Factory reads a true descriptor (ADR-0025). |
| AC3 | Given the work of AIFACTORY-TASK-602 (full tenant lifecycle with Suspended and Decommissioned, saas-TEN-F03) is done, then activate, suspend and decommission are commands of the aggregate with events, restore is the activation of a suspended tenant, the lifecycle grain of the Orleans profile handles each of them and not creation alone, and the vocabulary decision of saas-TEN-F05 is recorded in a decision record of the template (ADR-0015, model/services/generated-saas/GeneratedSaasFoundations.yaml). |
| AC4 | Given the work of AIFACTORY-TASK-603 (envelope base and the Orleans messaging profile on the Tenants events) is done, then every integration event of the template carries the complete envelope base of the template, which the Factory profile maps onto the run event envelope of ADR-0014, and is published through the outbox of the Orleans messaging profile, and a consumer test reads an activation and a suspension with the envelope fields filled. |
| AC5 | Given the work of AIFACTORY-TASK-604 (two-tenant isolation fixture and real architecture tests) is done, then an acceptance fixture with two tenants proves that a caller of one tenant reads only its own rows and gets 404 for the other and 401 without tenant context, and the placeholder architecture tests of saas-TEN-F06 are replaced by the layering rules the template documents (ADR-0015). |
| Traces: adrs | ADR-0014, ADR-0015, ADR-0025 |
| Depends on | AIFACTORY-US-249, AIFACTORY-US-250, AIFACTORY-US-251, AIFACTORY-US-252, AIFACTORY-US-253 |
| Sources | model/components.yaml, model/services/generated-saas/GeneratedSaasFoundations.yaml |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-691 Verify saas-tenants-template-delivered by running the declared command |
verification | Run dotnet build -c Release and dotnet test -c Release --no-build on the Tenants service generated from the published package; they pass and prove AC1 to AC5 of AIFACTORY-US-109. |
ConnectSoft.Saas.TenantsTemplate |