Skip to content

AIFACTORY-FEAT-100: Tenancy integration: tenant resolution for the Factory

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 16 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, editions and feature entitlements from the SaaS Tenants service instead of owning them. The first outcome needs tenant resolution only; editions and entitlements follow with commercialisation. Component: SaaS Tenants service (extend).

Delivers —
Stubs —
Realizes components: cmp-saas-tenants
bounded contexts: BC-33
Requirements —
Depends on AIFACTORY-FEAT-163 SaaS Tenants template: descriptor, lifecycle, envelope and isolation before the Factory resolves tenants
Sources model/components.yaml, docs/architecture/ecosystem-composition.md

AIFACTORY-US-254: Tenancy integration: the Tenants service answers a resolution query with the tenant, its residency region and lifecycle state, and answers not found for an unknown tenant

enabling · persona asset-maintainer As an asset maintainer, I want the Tenants service to answer who a tenant is, where its data resides and whether it is active, so that the Factory resolves the tenant of a token from the service that holds tenants and keeps no tenant table of its own.

The Factory resolves its tenants from the SaaS Tenants service instead of holding them (BC-33), and ADR-0015 decision 4 keeps a Factory tenant and a product tenant as distinct identities and stores, so the Factory reads its own instance of the service. The first outcome needs resolution only: for the tenant a token names, the control plane needs to know that the tenant exists, the region its data resides in, which a project inherits and records, and its lifecycle state. The service contract of the template has five operations and all of them write; its REST page lists the read by identifier as a placeholder (Docs/rest-api.md of the template). This PBI adds the resolution query to the service contract, so that REST and the code-first gRPC adapter expose it from one interface as the template prescribes. The answer carries the tenant identifier, the tenant key, the residency region, the lifecycle state and the aggregate version; a suspended or decommissioned tenant is returned with its state to a workload caller that holds the resolution scope and is never hidden from it, so that the caller decides. An identifier that names no tenant is answered 404 over REST and with the not-found fault over gRPC. A workload caller needs the resolution scope and is answered 403 without it; a caller with a user token resolves only the tenant of its own token and gets 404 for any other. The resolution scope is an svc. scope of the workload registration file of AIFACTORY-US-245, and a workload token carries no tenant claim. The service this feature builds on is proven with the tenant claim required and no default tenant, where a principal without a tenant claim is answered 401 before the query runs, so the resolution operation is stated as what it is: the one named exemption from the tenant-claim requirement. It is open only to a workload token with the resolution scope, it sets the tenant context from the requested identifier for the single load and never from a default, and every other operation of the service still answers 401 for a principal without a tenant claim. A test plants a second exempt operation and fails, so that the exemption cannot spread. The read always binds the tenant predicate to the requested identifier and never runs without one. The query is added to the descriptor, so the drift test of the template feature stays green.

Acceptance criteria

AC1 Given an active tenant with a residency region, when a workload caller with the resolution scope resolves its identifier over REST and over gRPC, then both answers carry the tenant identifier, the tenant key, the residency region, the lifecycle state and the aggregate version (ADR-0015 decisions 1 and 4, FR-01, model/components.yaml).
AC2 Given an identifier that names no tenant, when it is resolved, then the answer is 404 over REST and the not-found fault over gRPC; given a suspended and a decommissioned tenant, when a workload caller that holds the resolution scope resolves each, then the answer carries the tenant with its state and is not a not-found answer (ADR-0015 decision 1, docs/architecture/ecosystem-composition.md).
AC3 Given a workload caller without the resolution scope, when it resolves a tenant, then the answer is 403; given a caller with a user token of one tenant, when it resolves another tenant, then the answer is 404 with the same body as for an unknown identifier, and when it resolves its own tenant, then it gets the answer (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).
AC4 Given the descriptor of the Tenants service, when the query is added to the contract, then the descriptor lists it and the drift test of the template passes, and the read is shown by a test to run with the tenant predicate bound to the requested identifier (ADR-0015 decision 1, ADR-0028).
AC5 Given the production tenancy wiring with the tenant claim required and no default tenant, when a workload token with the svc. resolution scope and no tenant claim calls the resolution operation, then the operation is the one named exemption from the tenant-claim requirement: it sets the tenant context from the requested identifier for the single load and never from a default; every other operation of the service answers 401 for a principal without a tenant claim, and a test that plants a second exempt operation fails (ADR-0015 decisions 1 and 3, FR-01, docs/planes/control/tenancy.md).
Traces: adrs ADR-0015, ADR-0028
Traces: requirements FR-01
Depends on feature:component-saas-tenants-template, feature:component-auth-server-template-factory-tokens
Sources model/components.yaml, docs/architecture/ecosystem-composition.md, docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md, docs/planes/control/tenancy.md, model/template-parameters/connectsoft-saas-tenants.yaml

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-1157 Resolution request, answer and fault on the service contract and in the descriptor contract The service contract of the template holds the resolution operation with its request message, its answer with tenant identifier, tenant key, residency region, lifecycle state and aggregate version, and the not-found fault; the operation requires the svc. resolution scope of the workload registration file and is marked as the one named exemption from the tenant-claim requirement; ConnectSoft.Saas.Tenants.json lists the query; the REST and gRPC pages of the template document it and the exemption. ConnectSoft.Saas.TenantsTemplate
AIFACTORY-TASK-165 Tenant resolution from the SaaS Tenants service implementation The Tenants service answers the resolution query over REST and gRPC with the tenant, its residency region and its lifecycle state, so that the control plane resolves a tenant and its region for a token; an unknown tenant is refused with a not-found answer; for a workload token with the resolution scope the tenant context of the single load is set from the requested identifier and never from a default, and no other operation is exempt from the tenant-claim requirement. ConnectSoft.Saas.TenantsTemplate
AIFACTORY-TASK-1158 Verify the resolution query on the generated Tenants service verification Run the acceptance scenarios for an active, a suspended, a decommissioned and an unknown tenant, for a workload caller with and without the scope and for a user token of another tenant, over REST and gRPC, and the exemption cases, a workload token without a tenant claim that is admitted on the resolution operation only, the same token answered 401 on every other operation, and a planted second exempt operation that fails its test; the answers are as stated, which proves AC1 to AC5 of AIFACTORY-US-254 (ADR-0015). ConnectSoft.Saas.TenantsTemplate

AIFACTORY-US-255: Tenancy integration: the ServiceModel package of the Tenants service offers a typed resolution client that never answers with a default tenant

enabling · persona asset-maintainer As an asset maintainer, I want a typed client for the resolution query in the package the Tenants service already publishes its contracts in, so that a Factory gateway resolves a tenant by a version pin and no Factory repository writes its own client or copies a contract.

The REST page of the template states that the contracts and the typed client facades of the service live in the package ConnectSoft.Saas.Tenants.ServiceModel. A consumer of the resolution query therefore takes the package by a version pin and does not copy a type. This PBI adds the resolution facade to that package for REST and for gRPC. The facade takes the transport the consumer configured, with the workload token of the consumer and the propagation of correlation and trace context, and adds no authentication of its own. It returns one of three typed outcomes: the tenant with its region and state, an unknown tenant, or a failure to reach the service. It never returns a default tenant and never turns a failure into an unknown tenant, because the canonical tenancy rules the Factory inherits fail closed on missing evidence and the isolation recipe of the SaaS family runs without a default tenant. It keeps no cache: a platform gateway has the shared cache as its only store (ADR-0028 decision 7), and how long an answer may be reused is the decision of the consumer. Contract tests in the template run the facade against the generated service over both transports, so that the client and the service cannot drift apart inside one package version.

Acceptance criteria

AC1 Given the resolution facade of the ServiceModel package and a generated Tenants service, when the facade resolves an active tenant over REST and over gRPC, then both return the tenant with its residency region and lifecycle state as a typed outcome (ADR-0015 decision 1, FR-01, model/components.yaml).
AC2 Given an identifier that names no tenant, when the facade resolves it, then the outcome is the typed unknown tenant; given a service that cannot be reached or answers an error, when the facade resolves, then the outcome is the typed failure and never an unknown tenant or a default tenant (ADR-0015 decision 1 on the inherited fail-closed rule, docs/planes/control/tenancy.md).
AC3 Given the facade, when a consumer configures its transport with a workload token and trace context, then the call carries both unchanged, the facade holds no cache and no credential, and the contract tests of the template fail when the facade and the service contract differ (ADR-0028 decision 7, ADR-0015).
Traces: adrs ADR-0015, ADR-0028
Traces: requirements FR-01
Depends on AIFACTORY-US-254
Sources model/components.yaml, docs/architecture/ecosystem-composition.md, docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md, docs/planes/control/tenancy.md

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-1159 Typed resolution facade over REST and gRPC in the ServiceModel package implementation The package ConnectSoft.Saas.Tenants.ServiceModel holds a resolution facade for REST and for the code-first gRPC client with three typed outcomes (tenant, unknown tenant, failure); it takes the configured transport of the consumer and holds no cache, credential or default tenant. ConnectSoft.Saas.TenantsTemplate
AIFACTORY-TASK-1160 Contract tests of the facade against the generated service fixture Tests of the template run the facade against the generated Tenants service over both transports for an active, a suspended and an unknown tenant and against a stopped service, and assert the typed outcome of each. ConnectSoft.Saas.TenantsTemplate
AIFACTORY-TASK-1161 Verify the typed outcomes of the resolution facade verification Run the contract tests of the facade; the four cases return the tenant, the tenant with its state, the unknown tenant and the failure, which proves AC1 to AC3 of AIFACTORY-US-255 (ADR-0015). ConnectSoft.Saas.TenantsTemplate

AIFACTORY-US-256: Tenancy integration: the ServiceModel package with the resolution contract is built, tested and published to the ConnectSoft feed with a version the consumers pin

evidence · persona asset-maintainer As an asset maintainer, I want the resolution contract and its client on the ConnectSoft feed in a package whose version consumers pin, so that the control plane of the next increment resolves tenants from a published package that was proven against a generated Tenants service.

The template has a pipeline for its service model package (azure-pipelines-service-model.yml of the template) beside its template pipeline. This PBI is the proof of the feature: the package ConnectSoft.Saas.Tenants.ServiceModel with the resolution contract and its typed facade is built and tested in that pipeline, the contract tests of the facade run against a Tenants service generated from the packed template, and the package is published to the ConnectSoft feed, the Azure Artifacts feed the ConnectSoft libraries already publish to, which the amendment of ADR-0028 (D114) names as the feed of the Factory. Publication is reached only when the build, the tests and the contract tests are green and refuses a version that is already on the feed. A probe then proves what a consumer will do: a small project that pins the published version, and holds no project reference into the template, resolves an active tenant with its region from the generated service, receives the unknown-tenant outcome for an identifier that names no tenant, and sees the state of a suspended tenant. The published version is recorded on the documentation of the template, because the model of this repository holds no package versions. The PBI proves that the Factory can resolve tenants from the Tenants service as the ecosystem composition page states (docs/architecture/ecosystem-composition.md) and the release gate of FR-11 for the package.

Acceptance criteria

AC1 Given the service model pipeline of the Tenants template, when it runs on the work of this feature, then the ServiceModel package builds, its tests and the contract tests of the facade against a generated Tenants service pass, and only then is the package published to the ConnectSoft feed (FR-11, ADR-0028, model/components.yaml).
AC2 Given a version that is already on the feed or a failing contract test, when the pipeline reaches publication, then publication is refused with the reason and the run fails (FR-11, docs/architecture/ecosystem-composition.md).
AC3 Given the published package, when a probe project that pins that version and references nothing else of the template calls a Tenants service generated from the published template, then it resolves an active tenant with its residency region, receives the unknown-tenant outcome for an unknown identifier and reads the state of a suspended tenant (ADR-0015 decision 1, FR-01).
Traces: adrs ADR-0015, ADR-0028
Traces: requirements FR-01, FR-11
Depends on AIFACTORY-US-254, AIFACTORY-US-255
Sources model/components.yaml, docs/architecture/ecosystem-composition.md, docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-1162 Service model pipeline runs the contract tests before publication operations The service model pipeline of the template builds the package, runs its tests and the contract tests of the facade against a service generated from the packed template, and publishes to the ConnectSoft feed only when all are green; a version that is already on the feed is refused with the reason. ConnectSoft.Saas.TenantsTemplate
AIFACTORY-TASK-1163 Probe project that pins the published package fixture A probe under the build folder of the template restores the published version from the feed with no project reference into the template and runs the three resolution cases against a generated Tenants service; the pipeline runs it after publication. ConnectSoft.Saas.TenantsTemplate
AIFACTORY-TASK-1164 Published version recorded on the documentation of the template documentation The REST and gRPC pages of the template name the resolution query, the facade and the version of the ServiceModel package that first carries them, so that a consumer knows which version to pin. ConnectSoft.Saas.TenantsTemplate
AIFACTORY-TASK-1165 Verify the published package with the probe verification Run the service model pipeline to publication and the probe against the published version; the three cases pass and a repeated version is refused, which proves AC1 to AC3 of AIFACTORY-US-256 (ADR-0015, FR-11). ConnectSoft.Saas.TenantsTemplate

AIFACTORY-US-110: Tenancy integration: tenant resolution for the Factory is delivered and proven on a generated solution

enabling · persona asset-maintainer As an asset maintainer, I want SaaS Tenants service to carry tenant resolution for the Factory, 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, and later its editions and entitlements, from the SaaS Tenants service instead of holding them; the first outcome needs tenant resolution only. The feature builds on the template feature that reconciles the descriptor, completes the lifecycle and proves the isolation of the service. With the resolution query on the service contract, the typed resolution client in the ServiceModel package and the package published to the ConnectSoft feed with a pinned version, the asset maintainer runs the template pipeline and the service model pipeline end to end and proves the result with the probe. A failing contract test or a repeated version blocks publication. The migrated implementation task sits under the PBI that delivers the query, and the verification task of this PBI is the proof on the generated solution. The feature is done when a Tenants service generated from the published template answers the resolution query for an active, a suspended and an unknown tenant, and a consumer that pins the published package reads those answers, so that the control plane of the next increment can resolve a tenant and its region for a token and refuse an unknown tenant.

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-0028, model/components.yaml).
AC2 Given the work of AIFACTORY-TASK-165 (tenant resolution from the SaaS Tenants service) is done, then the generated Tenants service answers the resolution query with the tenant, its residency region and its lifecycle state, so that the control plane resolves a tenant and its region for a token, and an unknown tenant is refused with a not-found answer (ADR-0015 decision 1, docs/architecture/ecosystem-composition.md).
AC3 Given the published ServiceModel package, when a consumer pins its version, then the typed resolution client returns the tenant, the unknown tenant or the failure and never a default tenant, which the probe of the package proves against a generated service (ADR-0015, ADR-0028).
Traces: adrs ADR-0015, ADR-0028
Depends on AIFACTORY-US-254, AIFACTORY-US-255, AIFACTORY-US-256, feature:component-saas-tenants-template
Sources model/components.yaml, docs/architecture/ecosystem-composition.md

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-692 Verify saas-tenants-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 template, with the resolution scenarios in its acceptance suite; they pass and prove AC1 to AC3 of AIFACTORY-US-110. ConnectSoft.Saas.TenantsTemplate