AIFACTORY-FEAT-062: GovernanceHost: gateway delivery¶
Generated from the architecture model
This page is rendered from model/**/*.yaml by tools/docs_model during mkdocs build. Edit the YAML, not this page; hand-written design lives on the linked service, platform and plane pages.
A design artefact, not a tracker
This backlog is generated from model/backlog/ and validated against the architecture model. No work item exists in any tracker, and no item carries a date, an estimate or an assignee (ADR-0029).
Epic Governance (PF-12) · Increment I1 Generate a microservice · State elaborated · Route backend-developer · Build order 78 of 185 (Factory code)
GovernanceHost is the platform API gateway of bounded context BC-18 (Policy). The API gateway of the Governance platform (ADR-0028): routes public REST and internal gRPC calls to the 4 services it fronts, validates tokens and scopes, and owns no business state. Its own repository is ConnectSoft.AI.SoftwareFactory.GovernanceHost.
| Delivers | GovernanceHost (complete) |
| Stubs | — |
| Realizes | adrs: ADR-0012, ADR-0015, ADR-0016, ADR-0017, ADR-0019 |
| Requirements | FR-06, FUX-05, NFR-01, NFR-04, NFR-10, XL-05, XL-13 |
| Depends on | — |
| Sources | model/services/governance/GovernanceHost.yaml |
Scenarios to trace (7, catalog): SCN-GovernanceHost-001 ✓, SCN-GovernanceHost-002 ✓, SCN-GovernanceHost-003 ✓, SCN-GovernanceHost-004 ✓, SCN-GovernanceHost-005 ✓, SCN-GovernanceHost-006 ✓, SCN-GovernanceHost-007 ✓
AIFACTORY-US-083: GovernanceHost routes the calls of its platform under a trusted scope¶
enabling · persona platform-admin
As a platform admin, I want one gateway in front of the four services of the Governance platform that validates tokens and scopes, so that no service of the platform is reachable from outside the cluster except through its gateway and every call arrives with a scope the service can trust.
This is the integration PBI of the gateway of the Governance platform. ADR-0028 re-scopes the former composition host as the API gateway of its platform: GovernanceHost routes public REST and internal gRPC calls to the four services the model lists under deployment.fronts, ApprovalPolicyService, AuditService, PolicyEngineService and SecretBrokerService, validates tokens and scopes and owns no business state, no relational store and no secret (gateway role GW-03). It stands in front of the decision point of the Factory: decisions are made by PolicyEngineService, approval routing and decision validation by ApprovalPolicyService, evidence, classification and redaction by AuditService and credential issuance by SecretBrokerService, and the gateway decides none of it. The repository ConnectSoft.AI.SoftwareFactory.GovernanceHost is created and scaffolded in I0 by AIFACTORY-TASK-454 of feature repository-and-pipeline-conventions (D140), and this feature starts from that scaffold: it is scaffolded once from the pinned API gateway template package with UseFactoryProfile and the gateway role Platform (feature component-api-gateway-template), which fixes persistence, messaging and the actor model to none. The gateway therefore has no outbox and no inbox, consumes no event (ADR-0028 amendment on gateways and events) and its only store is the shared cache. The scope of a call is established once from the validated token with the scope accessor of the pinned ConnectSoft.Extensions.AI.Factory.Abstractions package (feature component-extensions-ai); the gateway copies neither the accessor nor the token contract. A user token has one audience, this gateway, and the gateway forwards it to the fronted service unchanged and exchanges no token, because the fronted service accepts the audience of its own gateway (ADR-0015 amendment D117). A workload token carries service scopes and no tenant claim and is admitted only on an internal gRPC route whose operation names a service scope the token holds (ADR-0015 amendment D114). The feature is delivered by five further PBIs: the fronts file and the routes generated from it (AIFACTORY-US-928), token, tenant, project and scope on every read and sandbox route (AIFACTORY-US-929), the pass-through of a shared-write call (AIFACTORY-US-930), the production and external routes whose gate stays in the fronted service (AIFACTORY-US-931), and health, revisions, limits and telemetry with the four failure modes of the model (AIFACTORY-US-932). A call without a token, with an expired token or with a user token issued for another gateway is answered 401 and a missing scope 403, and no fronted service is called. A project-scoped route names its project in the path, in a query parameter or in a body member and never in a header the caller types. Three operations of the platform name the project in their path, ValidateProjectPolicy of PolicyEngineService, ValidateProjectApprovalRules of ApprovalPolicyService and ExportAudit of AuditService: the gateway admits the named project only for a token that holds a role claim for it or the tenant-wide Platform admin role, answers 403 itself for a project the token does not grant and calls no service, and sets the project header of the abstractions package itself from the admitted project; a project header a caller sends is dropped on every route. Every other route addresses a resource by its identifier or reads under the tenant of the token: a gateway without business state cannot know the project or the tenant of a revision, a run, a finding or a secret reference, so it forwards under the tenant of the token and the scope of the operation, the fronted service answers 403 for a missing right and 404 for a resource of another tenant (ADR-0015 amendment D113), and the gateway returns that answer unchanged. The feature is of increment I1, like the other gateways (D127), so the public routes of the platform are reached through this gateway from the first delivery: a tenant administrator who reads or validates a policy bundle, registers a secret reference or reads audit evidence calls a route of this gateway, and the fronted services build no direct public route. PolicyEngineService, AuditService and SecretBrokerService are delivered complete in I1, and ApprovalPolicyService arrives in I4: until then a route of ApprovalPolicyService answers 503 with a problem response that names the service, and the refusals and the failure branches of every route class are proven against fakes generated from the fronts file. This feature delivers the routes and moves no internal caller onto them. The services of I1 that ask the platform, among them RunControlService, ToolAdapterService, ModelRouterService and ArtifactService, keep the in-cluster address of PolicyEngineService, AuditService and SecretBrokerService they were delivered with, and no PBI of the backlog switches them to this gateway. That switch would be a deployment value of each caller; it is out of scope of this feature, and which feature makes it is reported to the owner. The internal gRPC routes are therefore proven against the fakes of the fronted services, and their first caller on a deployed installation is RunControlService of I4, which asks ApprovalPolicy.Route and ApprovalPolicy.ValidateDecision through this gateway in the feature of ApprovalPolicyService. When this gateway is unavailable every caller fails closed by design, no run is accepted, no tool executes and no credential is issued, which is why the model sets at least three replicas. The gateway invents no response.
Acceptance criteria
| AC1 | Given the repository ConnectSoft.AI.SoftwareFactory.GovernanceHost created and scaffolded in I0 by AIFACTORY-TASK-454 of feature repository-and-pipeline-conventions, whose first commit is the unchanged output of dotnet new connectsoft-apigateway -n ConnectSoft.AI.SoftwareFactory.GovernanceHost --UseFactoryProfile true --GatewayRole Platform from the pinned template package, when its pipeline runs with the work of this feature, then no second scaffold was run, the solution builds, the tests pass with complete reports and a container image is published (ADR-0028, model/services/governance/GovernanceHost.yaml). |
| AC2 | Given a valid token for a route of each fronted service deployed in the increment, when the call passes the gateway, then the scope is established once from the token through the scope accessor of the pinned abstractions package, the call is forwarded with the token unchanged, the tenant, the project the gateway admitted where the route names one, the correlation id and the trace context, the fronted service answers and the response returns unchanged, as AIFACTORY-US-929 to AIFACTORY-US-931 prove per route class (ADR-0015, FR-06). |
| AC3 | Given the generated gateway, when its architecture test runs, then the test fails on a persistence model, an aggregate, a migration or a message consumer, the gateway binds no relational store, no outbox and no inbox, its configuration holds no secret, and no event of the model lists GovernanceHost as a consumer (ADR-0012, ADR-0028, model/services/governance/GovernanceHost.yaml). |
| AC4 | Given the gateway deployed with three replicas, when GovernanceHost/GovernanceHealth is probed and one replica is stopped, then health reports the identity platform and the four fronted services, a replica stays in rotation while it can validate tokens, the other replicas keep serving and nothing is replayed, because the gateway holds no state (ADR-0017, NFR-01, model/services/governance/GovernanceHost.yaml). |
| Traces: services | GovernanceHost, ApprovalPolicyService, AuditService, PolicyEngineService, SecretBrokerService |
| Traces: apis | GovernanceHost/GovernanceHealth |
| Traces: adrs | ADR-0012, ADR-0015, ADR-0016, ADR-0017, ADR-0028 |
| Traces: requirements | FR-06, NFR-01 |
| Depends on | AIFACTORY-US-928, AIFACTORY-US-929, AIFACTORY-US-930, AIFACTORY-US-931, AIFACTORY-US-932, feature:repository-and-pipeline-conventions, feature:component-api-gateway-template, feature:component-extensions-ai, feature:policy-engine-service, feature:audit-service-complete, feature:secret-broker-service |
| Sources | model/services/governance/GovernanceHost.yaml, model/gateways.yaml, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md, docs/planes/trust-operations/governance/services/governance-host/index.md#purpose-and-responsibilities |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-3728 Deployment values of the gateway: replica range, ports, probes and the address of each fronted service |
operations | The deployment manifest of the gateway states the replica range 3 to 10, the ports https 8000 and grpc 8002, the liveness and readiness probes on the health operation and one base address per fronted service from configuration, as model/services/governance/GovernanceHost.yaml records them; it leaves Governance:Host:FrontedServices at its default, the four service identifiers of deployment.fronts, sets ConnectSoftIdentityPlatform:Authority to the authority of the profile, holds no secret and binds the shared cache as its only store; the same image runs in the saas-default, hybrid, on-prem and hybrid-compute topologies (ADR-0017). | ConnectSoft.AI.SoftwareFactory.GovernanceHost |
AIFACTORY-TASK-754 Verify governance-host-routes-its-platform by running the declared command |
verification | Run dotnet build -c Release and dotnet test -c Release --no-build in the pipeline of the repository; a run that discovers no test counts as a failure; the runs pass and prove AC1 to AC4 of AIFACTORY-US-083, that is the repository with its scaffold of the Platform role, the scope established once and forwarded, the architecture test of the Platform role and, for AC4, the acceptance test of feature ThreeReplicas (dotnet test -c Release --filter "Category=Acceptance&Feature=ThreeReplicas"), which hosts three instances of the gateway behind one test balancer with the fakes of the fronted services, probes GovernanceHost/GovernanceHealth on each, stops one instance and asserts that the others keep serving and that no call is replayed. |
ConnectSoft.AI.SoftwareFactory.GovernanceHost |
AIFACTORY-US-928: Governance fronts file: named clients and REST and gRPC routes of the four fronted services, generated at build¶
enabling · persona platform-admin
As a platform admin, I want the route table of the governance gateway generated from the list of services it fronts, so that every operation of the platform has exactly one route with its scope and class and no forwarding code is written by hand.
The API gateway template is a custom gateway with controllers, use cases and named clients and is no reverse proxy, so a route exists only when it is declared. Under UseFactoryProfile the generated solution holds a build-time source generator that reads a fronts file on every build and emits one named HTTP client and one gRPC client per fronted service, the REST and gRPC routes that forward to them and the route table (feature component-api-gateway-template). This PBI writes the fronts file of the Governance platform. It lists the four services of deployment.fronts in model/services/governance/GovernanceHost.yaml, each with its base addresses from configuration and its operations in the shape of the apis section of its service file: name, method and path or gRPC method with its streaming mode, scope, side-effect class and idempotency. For PolicyEngineService these are the five REST operations ListPolicyBundles, GetPolicyBundle, ValidateProjectPolicy, SimulatePolicy and ListRunDecisions and the three gRPC methods Policy.Decide, Policy.GetActiveRevision and Policy.ValidateTightening. For ApprovalPolicyService these are ListApprovalRules, ValidateProjectApprovalRules and GetApprovalRouting and the gRPC methods ApprovalPolicy.Route and ApprovalPolicy.ValidateDecision. For AuditService these are the six REST operations SearchAudit, ExportAudit, ListClassifications, SetClassification, ListFindings and ResolveFinding and the gRPC methods Audit.Record, Audit.Classify and Audit.Redact. For SecretBrokerService these are the five REST operations ListSecretReferences, RegisterSecretReference, RotateSecret, RevokeSecretReference and ListRunIssuances and the gRPC methods SecretBroker.Issue, SecretBroker.Revoke and SecretBroker.Verify. That is nineteen REST routes and eleven gRPC routes, all eleven unary. The file holds the whole surface of the model, also for ApprovalPolicyService, which arrives in I4: the route exists, and what it answers until then is 503 with the service named (AIFACTORY-US-083). The REST operations are the public surface that StudioBff and a typed client call; the gRPC methods are the internal surface over which the gateways of the other platforms ask for decisions, approval routing, evidence, classification and credentials. Each route carries the scope and the side-effect class of its operation, which is what the route class PBIs of this feature enforce; an internal gRPC route names the service scope a workload token must hold. Each REST entry also states how its operation addresses a project. A project-scoped route names its project in the path, in a query parameter or in a body member and never in a header the caller types, and the gateway checks it against the roles of the token. ValidateProjectPolicy, ValidateProjectApprovalRules and ExportAudit name it in the path parameter projectId. Eight operations name a revision, a run, an approval, a resource type, a finding or a secret reference in their path and are marked as addressed by a resource identifier only: GetPolicyBundle, ListRunDecisions, GetApprovalRouting, SetClassification, ResolveFinding, RotateSecret, RevokeSecretReference and ListRunIssuances. ListPolicyBundles, SimulatePolicy, ListApprovalRules, SearchAudit and ListFindings read under the scope of the caller, and their service files name no path parameter, query parameter or body member for a project; until the model names one they are marked as scoped by the tenant of the token, and the gap is reported as a correction of the service files. ListClassifications, ListSecretReferences and RegisterSecretReference act on the classification registry and the secret references of the tenant, which a Platform admin owns tenant-wide, so they are marked as tenant-wide by design, a fourth marking that is no gap of the model. The four markings cover all nineteen REST operations: three by the path parameter projectId, eight by a resource identifier only, five by the tenant of the token until their service files name a project parameter, and three tenant-wide by design. A test lists the emitted route table against the file and against the four service files of the model, so an operation of the model without a route, a route without an operation, a service named twice or a route named twice fails the build with the entry named. A path that no route matches is answered 404. The gateway adds no operation of its own beyond GovernanceHealth and GovernanceRevisions, transforms no payload and composes no response from two services. The option Governance:Host:FrontedServices is bound at startup and compared with the service names of the fronts file: a value that names no service of the file, or a service of the file that the value omits, fails startup with the name, so the option can neither add nor remove a route; it is not reloadable. The fronts file names its services by their identifiers, as deployment.fronts lists them, and the default of a fronted-services option equals that set by decision. model/services/governance/GovernanceHost.yaml shows that default as the four service identifiers, and the deployment manifest does not set the option. The pipeline of this repository publishes the OpenAPI document of the nineteen public REST operations as a build output, checked against the fronts file and the four service files. This feature builds and publishes no client package: the typed client of a gateway is published by feature typed-gateway-clients, and the package version in which it adds the governance gateway is reported to the owner.
Acceptance criteria
| AC1 | Given the fronts file of the Governance platform, when the gateway builds, then one named HTTP client and one gRPC client exist per service of deployment.fronts and one route per REST operation and gRPC method of those services, nineteen REST routes and eleven unary gRPC routes, each with the scope, side-effect class and idempotency of the operation, and the route table test passes against model/services/governance/GovernanceHost.yaml and the four service files under model/services/governance (ADR-0028). |
| AC2 | Given an operation removed from the file, a route named twice or a service named twice, when the gateway builds, then the build fails with the entry named; given Governance:Host:FrontedServices at its default, the four service identifiers of deployment.fronts in model/services/governance/GovernanceHost.yaml, when the gateway starts, then startup succeeds; given a value of the option that names no service of the fronts file or omits one, when the gateway starts, then startup fails with the differing name; given a path no route matches, when it is called, then the answer is 404 and no fronted service is called (ADR-0028, docs/architecture/catalogs/gateways.md). |
| AC3 | Given a fake of each fronted service, when one REST route and one gRPC route per service are called with a valid token, then each call reaches the fake of its service with the authorization header, which carries the token of the caller unchanged because the gateway exchanges no token, the tenant, the correlation id and the trace context, a project header sent by the caller has been dropped, and the response of the fake returns unchanged (ADR-0015, FR-06). |
| AC4 | Given the built gateway, when its pipeline publishes the OpenAPI document of the public REST routes, then the document holds exactly the nineteen REST operations of the fronts file with their methods, paths, scopes and response codes and no internal gRPC method, and a contract check fails the build when it differs from the four service files under model/services/governance (docs/architecture/api-governance.md). |
| Traces: services | GovernanceHost, ApprovalPolicyService, AuditService, PolicyEngineService, SecretBrokerService |
| Traces: adrs | ADR-0015, ADR-0028 |
| Traces: requirements | FR-06 |
| Depends on | feature:component-api-gateway-template, feature:policy-engine-service, feature:audit-service-complete, feature:secret-broker-service |
| Sources | model/services/governance/GovernanceHost.yaml, model/services/governance/PolicyEngineService.yaml, model/services/governance/ApprovalPolicyService.yaml, model/services/governance/AuditService.yaml, model/services/governance/SecretBrokerService.yaml, model/gateways.yaml, docs/architecture/catalogs/gateways.md, docs/architecture/api-governance.md, docs/planes/trust-operations/governance/services/governance-host/index.md#context-and-boundaries |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-455 Fronts file with the REST and gRPC operations of ApprovalPolicyService, AuditService, PolicyEngineService and SecretBrokerService |
implementation | The fronts file lists the four services of deployment.fronts with their base addresses from configuration and every REST operation and gRPC method of their service files with name, path or method, streaming mode, scope, side-effect class and idempotency, and for each REST operation how it addresses a project, one of four markings that together cover all nineteen operations: by the path parameter projectId for ValidateProjectPolicy, ValidateProjectApprovalRules and ExportAudit; by a resource identifier only for GetPolicyBundle, ListRunDecisions, GetApprovalRouting, SetClassification, ResolveFinding, RotateSecret, RevokeSecretReference and ListRunIssuances; by the tenant of the token for ListPolicyBundles, SimulatePolicy, ListApprovalRules, SearchAudit and ListFindings, whose service files name no project parameter, which is reported as a correction of those files; and tenant-wide by design for ListClassifications, ListSecretReferences and RegisterSecretReference; a test fails when a REST operation carries none or more than one of the four markings; the build emits the named clients, the nineteen REST routes, the eleven gRPC routes and the route table; at startup the option Governance:Host:FrontedServices, whose default is the four service identifiers of deployment.fronts, is compared with the service names of the fronts file, the gateway starts with the option at its default, and a difference in either direction fails startup with the name; a project header of a caller is dropped on every route; a call without a valid token or scope is refused at the gateway by the generated policies. | ConnectSoft.AI.SoftwareFactory.GovernanceHost |
AIFACTORY-TASK-3729 Fakes of the four fronted services and the token matrix of the acceptance suite |
fixture | The acceptance suite of the gateway holds one fake per fronted service, generated from its fronts entry, that records the headers and metadata it received and answers a configured status and body, a switch that makes a fake stop answering, a configuration in which ApprovalPolicyService has no instance behind its base address, and tokens for the matrix of role, tenant and project, including an expired token, an identity token, a user token of another audience, a token with a role in one project and none in another, a token with the tenant-wide Platform admin role, and a workload token with and without the service scope of a gRPC route. | ConnectSoft.AI.SoftwareFactory.GovernanceHost |
AIFACTORY-TASK-3730 OpenAPI document of the public REST routes of the gateway as a published build output |
contract | The pipeline publishes one OpenAPI document with the nineteen public REST operations of the fronts file, their methods, paths, scopes, idempotency headers and response codes, and no internal gRPC method; a contract check compares the document with the four service files under model/services/governance and fails the build on a missing operation, an operation of another service or a differing method, path, scope or response code, so the document can be the input from which feature typed-gateway-clients generates the client of this gateway; no client package is built here. | ConnectSoft.AI.SoftwareFactory.GovernanceHost |
AIFACTORY-TASK-3731 Verify the route table against the fronts file and the model |
verification | Run dotnet test -c Release --filter "Category=Acceptance&Feature=RouteTable"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-928: one route per operation of the four service files under model/services/governance, the failing builds, the start with the option at its default, the failing startup on a value that names no service of the fronts file or omits one, the 404 of an unknown path, one forwarded call per service and protocol with the dropped project header of the caller, and the contract check of the published OpenAPI document. |
ConnectSoft.AI.SoftwareFactory.GovernanceHost |
AIFACTORY-US-929: A read or sandbox route of the governance gateway forwards a call only under a validated token, the tenant of the token and the scope of its operation¶
behavior · persona observer
As an observer, I want my read calls to reach the policy, approval policy, audit and secret broker services only with the tenant and the scope my token grants, so that I see the bundles, rules, decisions, evidence and references I am entitled to and nobody reads across a tenant through the gateway.
A caller reaches a read or a sandbox operation of the Governance platform through the gateway. A person reads the policy bundles in force and the rules of a revision, the policy decisions and the credential issuances of a run, the approval rules and the routing of an approval, audit evidence, classifications, findings and secret references; a Workspace admin validates a project policy or project approval rules and simulates a candidate bundle; and the gateways of the other platforms ask for decisions over gRPC. A user presents an access token of the authorization server whose one audience is this gateway (ADR-0015 amendment D114); a client that also calls the Control Plane gateway requests a second token for it. The gateway validates issuer, signature, lifetime and audience through the pinned resource-server library and requires the scope the operation names: factory.policies.read for ListPolicyBundles, GetPolicyBundle and ListApprovalRules, factory.runs.read for ListRunDecisions and ListRunIssuances, factory.approvals.read for GetApprovalRouting, factory.audit.read for SearchAudit, ListClassifications and ListFindings, factory.secrets.admin for ListSecretReferences, and factory.policies.write for the three sandbox operations ValidateProjectPolicy, SimulatePolicy and ValidateProjectApprovalRules. It takes the tenant from the tid claim and overwrites any tenant header of the caller. Of these thirteen operations two name their project in the path, ValidateProjectPolicy and ValidateProjectApprovalRules: the gateway admits the project only for a token that holds a role claim for it or the tenant-wide Platform admin role, sets the project header from it and answers 403 itself for a project the token does not grant, calling no service. Four name a resource by identifier, a revision, a run or an approval, and a gateway without business state cannot know the tenant or the project of such a resource: it forwards the call under the tenant of the token and the scope of the operation, the fronted service answers 403 for a missing role and 404 for a resource of another tenant (ADR-0015 amendment D113), and the gateway returns that answer unchanged. ListPolicyBundles, SimulatePolicy, ListApprovalRules, SearchAudit and ListFindings read under the scope of the caller and name no resource; until their service files name the parameter that carries a project (AIFACTORY-US-928), the gateway forwards them under the tenant of the token, and the fronted service, which validates the forwarded token again, applies its own project rule from the role claims of that token. ListClassifications and ListSecretReferences are tenant-wide by design. A project header a caller sends is dropped and establishes nothing. A sandbox route of this platform belongs to no run and to no workspace: the fronted service validates or simulates a candidate, stores nothing, activates nothing and publishes nothing, and its result, valid or not valid, returns unchanged with its status; the gateway reads no candidate and keeps none. Every public REST operation names a factory. scope and none names a service scope, so no REST route admits a workload token; a workload token on such a route is answered 403. The scope is established once with the scope accessor of the pinned abstractions package and forwarded: the authorization header with the user token itself, the tenant in X-Tenant-Id, the correlation id and the trace context. The gateway exchanges no token; the fronted service accepts the audience of its own gateway, which is this one, and applies its own tenant filter and role policies (ADR-0015 amendment D117). The internal gRPC surface has six methods of class read: Policy.Decide, Policy.GetActiveRevision, Policy.ValidateTightening, ApprovalPolicy.Route, ApprovalPolicy.ValidateDecision and Audit.Classify. They are the decision path of the Factory: run control asks through them whether a run may be accepted and who may approve, and the runtime, the model gateway and the tool executor ask before every gated call. A workload presents a token that carries service scopes, no audience of a user API and no tenant claim, and each gRPC route names the service scope the token must hold. For a workload token that holds it, the gateway forwards the tenant-id and the project metadata of the caller unchanged, because the fronted service reads a forwarded tenant and project only under that scope; for a workload token without it, and for a user token, which holds no service scope, the answer is PERMISSION_DENIED and no fronted service is called. The gateway decides nothing on this path and remembers nothing of it: it caches no decision, no revision and no routing, because the decision cache per revision belongs to PolicyEngineService, and that Policy.Decide, ApprovalPolicy.Route and ApprovalPolicy.ValidateDecision record a decision or an evaluation in their own store is the matter of those services. For every route of this PBI the response is served by the fronted service and returns unchanged with the correlation id; the gateway keeps nothing of the call and records connectsoft.factory.governance.host.requests and connectsoft.factory.governance.host.request_duration for the route. A call without a token, with an expired token, with an identity token or with a user token issued for another gateway is answered 401 and a token without the scope of the operation 403; in each case no fronted service is called and the refusal is counted for the route and logged with the correlation id and without the token. When the fronted service does not answer, or is not deployed yet as ApprovalPolicyService is until I4, the route answers 503, over gRPC UNAVAILABLE, with a retry hint that names the service and never its address, and the routes of the other services keep serving. The gateway never answers a decision in place of the policy engine: a caller that receives UNAVAILABLE fails closed.
Acceptance criteria
| AC1 | Given a user token whose audience is this gateway, with factory.policies.read, when the read route of GetPolicyBundle is called, then the gateway forwards the call with the user token unchanged in the authorization header, without a token exchange, the tenant of the tid claim, the correlation id and the trace context, PolicyEngineService answers, the response returns unchanged with the correlation id and nothing is written by the gateway (SCN-GovernanceHost-005, ADR-0015, FUX-05). |
| AC2 | Given the token matrix of the acceptance suite, when the read and the sandbox routes of the four fronted services are called, then a call without a token, with an expired token, with an identity token or with a user token issued for another gateway is answered 401, a token without the scope of the operation and a workload token on a REST route are answered 403, and in none of these cases a fronted service is called; each refusal is counted for its route and logged with the correlation id and without the token (SCN-GovernanceHost-005, SCN-GovernanceHost-006, ADR-0015). |
| AC3 | Given a token with factory.policies.write, when the sandbox route of ValidateProjectPolicy is called with a projectId in its path, then a token that holds a role claim for that project or the tenant-wide Platform admin role is forwarded with the project in the project header the gateway sets and the body unchanged, the result of the fake of PolicyEngineService, valid or not valid, returns unchanged with its status, and a token that grants no role in that project is answered 403 by the gateway itself without a call; the gateway stored no candidate, and the route of SimulatePolicy is forwarded under the tenant of the token, as model/services/governance/GovernanceHost.yaml and the service files name no project parameter for it (SCN-GovernanceHost-006). |
| AC4 | Given a valid user token, a tenant header of the caller that names another tenant and a project header of the caller, when a read route addressed by a revision, a runId or an approvalId is called, then the tenant header is overwritten with the tid claim, the project header of the caller is dropped, the call is forwarded under the tenant of the token and the scope of the operation, and the 403 of the fronted service for a missing role and its 404 for a resource of another tenant return unchanged; given a workload token that holds the service scope the route names, when the gRPC routes of Policy.Decide and Audit.Classify are called with tenant-id and project metadata, then the gateway forwards each call with that metadata unchanged and returns the reply unchanged, and a workload token without the scope and a user token are answered PERMISSION_DENIED without a call (SCN-GovernanceHost-005, NFR-01). |
| AC5 | Given a fronted service that does not answer and the routes of ApprovalPolicyService while that service is not deployed, when their read and sandbox routes are called, then the gateway answers 503, over gRPC UNAVAILABLE, with a problem response that carries a retry hint and names the service and never its address, no response and no decision is invented, the shared cache holds no decision, revision or routing, and the routes of the other services keep serving (SCN-GovernanceHost-005, SCN-GovernanceHost-006, model/services/governance/GovernanceHost.yaml). |
| Traces: services | GovernanceHost, ApprovalPolicyService, AuditService, PolicyEngineService, SecretBrokerService |
| Traces: adrs | ADR-0015, ADR-0028 |
| Traces: requirements | FR-06, FUX-05, NFR-01, NFR-04 |
| Traces: scenarios | SCN-GovernanceHost-005, SCN-GovernanceHost-006 |
| Relates: screens | policies, approval-policy, audit, findings, secrets-references, run-detail |
| Depends on | AIFACTORY-US-928, feature:component-api-gateway-template, feature:component-extensions-ai, feature:policy-engine-service, feature:audit-service-complete, feature:secret-broker-service |
| Sources | model/services/governance/GovernanceHost.yaml, model/services/governance/PolicyEngineService.yaml, model/services/governance/ApprovalPolicyService.yaml, model/services/governance/AuditService.yaml, docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md, docs/planes/trust-operations/governance/services/governance-host/index.md#purpose-and-responsibilities |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-3732 Issuer, audience, scope, tenant and project configuration of the read and sandbox routes |
implementation | The gateway is configured with the authority of ConnectSoftIdentityPlatform:Authority and its own resource as the one audience of a user token; each read and sandbox route requires the scope of its operation; the tenant header is overwritten with the tid claim; a project header of a caller is dropped on every route and the project header is set only from a project the gateway admitted from a path parameter, a query parameter or a body member; the routes of ValidateProjectPolicy and ValidateProjectApprovalRules admit the projectId of their path only for a token with a role claim for it or the tenant-wide Platform admin role and answer 403 themselves otherwise; a route addressed by a resource identifier is marked as such, so the gateway checks token and scope and leaves the role and the tenant of the resource to the fronted service; ListPolicyBundles, SimulatePolicy, ListApprovalRules, SearchAudit and ListFindings are forwarded under the tenant of the token until their service files name a project parameter; a workload token is refused with 403 on a REST route; a gRPC route names the service scope a workload token must hold and forwards the tenant-id and project metadata unchanged with it (ADR-0015 amendment D114); the user token is forwarded unchanged and no token is exchanged (ADR-0015 amendment D117); no decision, revision or routing is cached; refusals are counted per route and logged with the correlation id and without the token. | ConnectSoft.AI.SoftwareFactory.GovernanceHost |
AIFACTORY-TASK-3733 Verify the read and sandbox routes through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-GovernanceHost-005\|Scenario=SCN-GovernanceHost-006)"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-929 over the token matrix of AIFACTORY-TASK-3729: the token received by the fake equal to the user token of the caller, the overwritten tenant header and the dropped project header, a route addressed by a resource id whose 403 and 404 come from the fake and return unchanged, the routes forwarded under the tenant of the token, the sandbox route of ValidateProjectPolicy with a granted and a refused project and with both results of the fake, a workload token refused on a REST route, the gRPC routes of Policy.Decide and Audit.Classify with and without the service scope, a fake that stops answering, the routes of the service that is not deployed and an inspection of the shared cache. |
ConnectSoft.AI.SoftwareFactory.GovernanceHost |
AIFACTORY-US-930: A shared-write route of the governance gateway passes the call through and the gateway keeps nothing between calls, a credential least of all¶
behavior · persona platform-admin
As a platform admin, I want a write that is repeated after a failure to be applied once by the service that owns it, and a credential that passes the gateway to stay nowhere in it, so that a lost answer or a restarted gateway never appends evidence twice, and no secret can be read from the gateway.
A shared-write operation changes state that others read. The Governance platform has one on its public surface, ResolveFinding of AuditService, by which a holder of factory.audit.admin resolves a finding or accepts its risk with a reason, and four on its internal gRPC surface: Audit.Record, which appends evidence for a command that is not an event, Audit.Redact, which applies the redaction rules of a class to a content reference and returns the reference of the redacted artifact, SecretBroker.Issue, which issues a short-lived scoped credential for a subject and a purpose after a policy decision, and SecretBroker.Revoke, which revokes an issuance. The caller sends each through the gateway under the token, tenant and scope rules of AIFACTORY-US-929: factory.audit.admin for ResolveFinding, and on a gRPC route a workload token that holds the service scope the route names. ResolveFinding names a finding by identifier, so the gateway forwards it under the tenant of the token and the scope of the operation, and the 403 of the fronted service for a missing role and its 404 for a finding of another tenant (ADR-0015 amendment D113) return unchanged. None of the five declares the idempotency key-header: ResolveFinding is naturally idempotent, Audit.Record appends once per evidence id, and what SecretBroker.Issue and SecretBroker.Revoke do with a repeated request is the rule of SecretBrokerService. The gateway is no party to idempotency. It forwards the request with its body, its headers and its metadata unchanged, stores neither a request nor a result, keeps no session and no pending call, has no outbox and writes no event and no audit evidence of its own. A gateway replica that crashes during a call therefore loses nothing it owned: the replica restarts, nothing is replayed, and the caller repeats the call and receives from the service the answer of its own rule (failure mode Gateway replica crash of the model). The reply of SecretBroker.Issue carries a credential, delivered once over the authenticated channel. The gateway passes it through as it arrives. It writes the credential to no log record, no activity, no metric and no cache entry, and neither the request nor the reply of the four gRPC routes is logged with its body; a conformance test scans the captured telemetry and the shared cache for the marker credential of the suite. Raw secrets never reach the gateway at rest: it has no secret of its own and no store that could hold one. When the fronted service does not answer, the route answers 503, over gRPC UNAVAILABLE, with a problem response that names the service and carries a retry hint, the other routes keep serving and the caller fails closed: no credential is issued and no evidence is assumed recorded. A refusal by the gateway, 401, 403 or PERMISSION_DENIED, reaches no fronted service, so it applies nothing. An invalid body and every domain refusal are answers of the fronted service and return unchanged with the correlation id. AuditService and SecretBrokerService were delivered complete in I1 and answer these routes on a deployed instance; the pass-through, the refusals and the failure branches are proven against the fakes generated from the fronts entries. The gateway records request count and latency for the route with the status that was returned.
Acceptance criteria
| AC1 | Given a valid token with factory.audit.admin, when the shared-write route of ResolveFinding is called, then the gateway forwards the request with the body unchanged under the tenant of the token, the fake of AuditService applies it and the response returns unchanged with the correlation id; the 403 of the fake for a missing role and its 404 for a finding of another tenant return unchanged (SCN-GovernanceHost-007, ADR-0015). |
| AC2 | Given a workload token that holds the service scope the route names, when the gRPC routes of Audit.Record, Audit.Redact, SecretBroker.Issue and SecretBroker.Revoke are called with tenant-id and project metadata, then each call reaches its fake with that metadata and the message unchanged and the reply returns unchanged; a workload token without the scope and a user token are answered PERMISSION_DENIED and no fronted service is called (SCN-GovernanceHost-007, ADR-0028). |
| AC3 | Given the reply of SecretBroker.Issue that carries the marker credential of the suite, when it passes the gateway, then the caller receives it unchanged and a scan of the captured log records, activities and metrics and of the shared cache finds the marker nowhere; the gateway holds no secret and binds no store that could hold one, as model/services/governance/GovernanceHost.yaml states (SCN-GovernanceHost-007, ADR-0019). |
| AC4 | Given a gateway replica stopped while a shared-write call is in flight, when the caller repeats the call through another replica, then the second replica forwards it as a new call, the fake received two calls, the gateway replayed nothing and stored neither a request nor a result; given a fronted service that does not answer, then the route answers 503, over gRPC UNAVAILABLE, with a retry hint that names the service while the other routes keep serving (SCN-GovernanceHost-007, NFR-01). |
| Traces: services | GovernanceHost, AuditService, SecretBrokerService |
| Traces: adrs | ADR-0015, ADR-0019, ADR-0028 |
| Traces: requirements | NFR-01, NFR-04 |
| Traces: scenarios | SCN-GovernanceHost-007 |
| Relates: screens | findings |
| Depends on | AIFACTORY-US-928, AIFACTORY-US-929, feature:component-api-gateway-template, feature:audit-service-complete, feature:secret-broker-service |
| Sources | model/services/governance/GovernanceHost.yaml, model/services/governance/AuditService.yaml, model/services/governance/SecretBrokerService.yaml, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md, docs/planes/trust-operations/governance/services/governance-host/index.md#failure-and-recovery |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-3734 Forwarded headers and metadata of a write route and a call path that keeps no body and no credential |
implementation | A shared-write route forwards the body, the headers and the metadata of the call and the established scope unchanged and returns the status and the body of the fronted service unchanged; the four gRPC routes Audit.Record, Audit.Redact, SecretBroker.Issue and SecretBroker.Revoke are excluded from body logging in both directions; no request, result or credential is written to the shared cache, to a log record, to an activity or to a metric; the gateway writes no event and no audit evidence of its own; request count and latency are recorded for the route with the returned status. | ConnectSoft.AI.SoftwareFactory.GovernanceHost |
AIFACTORY-TASK-3735 Verify the shared-write routes through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&Scenario=SCN-GovernanceHost-007"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-930 with the fakes of AIFACTORY-TASK-3729: the route of ResolveFinding with the 403 and the 404 of the fake returned unchanged, the four gRPC routes with and without the service scope, the marker credential in the reply of SecretBroker.Issue with the scan of the captured telemetry and of the shared cache, a replica stopped during a call with the repeated call forwarded as a new one, and a fake that stops answering. |
ConnectSoft.AI.SoftwareFactory.GovernanceHost |
AIFACTORY-US-931: A production or external route of the governance gateway is forwarded under its scope and the gate of the action stays in the fronted service¶
behavior · persona platform-admin
As a platform admin, I want a classification change, a secret reference change or an audit export to be decided by the service that owns its state, with the gateway only checking who I am and what I may call, so that a gate is never decided twice or by a component that holds no state.
Two side-effect classes of the Governance platform carry a gate beyond the scope. The production routes are SetClassification of AuditService, by which a Platform admin sets the data class, the retention, the redaction rules and the residency of a resource type or instance, and three operations of SecretBrokerService on secret references: RegisterSecretReference, which registers a reference to a vault secret or an exchangeable identity, RotateSecret, which records a rotation and revokes the live issuances of the old version, and RevokeSecretReference, which revokes a reference and every live issuance. The external routes are ExportAudit of AuditService, the export of the evidence of a project in open formats with chain proofs (D31, XL-14), and the internal gRPC method SecretBroker.Verify, a probe that a reference resolves and its credential works without issuing it to the caller. ADR-0028 leaves a platform gateway routing and the validation of tokens and scopes and no business state, and names a gateway that accumulates logic beyond routing and validation as a reason to revisit the decision. The gateway therefore treats these routes as it treats every route: it validates the token, takes the tenant from it, requires the scope the operation names, factory.audit.admin for SetClassification, factory.secrets.admin for the three operations on secret references and factory.audit.export for ExportAudit, and forwards the call with the established scope; on the gRPC route of SecretBroker.Verify it requires a workload token that holds the service scope the route names. ExportAudit names its project in the path parameter projectId: the gateway admits it only for a token that holds a role claim for that project or the tenant-wide Platform admin role, sets the project header from it and answers 403 itself for a project the token does not grant. SetClassification, RotateSecret and RevokeSecretReference name a resource type or a secret reference by identifier, and RegisterSecretReference acts on the secret references of the tenant of the token, so the gateway forwards them under the tenant of the token and the scope of the operation, and the 403 of the fronted service for a missing role and its 404 for a resource of another tenant (ADR-0015 amendment D113) return unchanged. ExportAudit, RegisterSecretReference and RotateSecret declare the idempotency key-header: the gateway forwards the Idempotency-Key unchanged, the fronted service applies the request once under its own rule, and its answer for a reused key returns unchanged, whatever its status. The gate itself is decided where the state is. AuditService decides a classification change and answers 409 where it conflicts, accepts an export with 202 and has its own worker produce the package. SecretBrokerService decides the registration, the rotation and the revocation of a reference, answers 409 where a command conflicts with the state of a reference, and talks to the vault itself. Whatever gate one of these commands has is decided by the fronted service that owns it. The gateway evaluates no policy and no approval, holds no approval reference, no classification and no secret reference, calls no vault and no connector, and writes no receipt and no audit evidence. Where a command leaves audit evidence, the service that owns the command writes it to its own outbox in the transaction of the command, as the event AuditEvidenceSubmitted on the topic audit.evidence.v1.evidence-submitted; the gateway has no outbox. The answer of the fronted service, including 201, 202 and 409, returns unchanged with the correlation id. A call without a token is answered 401 and a token without the scope 403, and no fronted service is called. The body of a request to register or rotate a reference names a vault location and never a secret value, and the gateway logs no body of these routes all the same. In this increment AuditService and SecretBrokerService are deployed, delivered complete in I1; the refusals and the failure branches are proven against fakes generated from the fronts entries. When the fronted service does not answer, the route answers 503, over gRPC UNAVAILABLE, with a problem response that names the service and a retry hint, and the caller retries with its key.
Acceptance criteria
| AC1 | Given a token with factory.audit.export and a role claim for the project of the path, when the external route of ExportAudit is called with an Idempotency-Key, then the gateway forwards the call with the key unchanged and the project in the project header it sets, the fake of AuditService accepts the export and answers 202, and that answer returns unchanged with the correlation id; the gateway called no connector and wrote no receipt and no evidence; given a token without a role in that project, then the gateway answers 403 itself and AuditService is not called (SCN-GovernanceHost-003, ADR-0028, XL-14). |
| AC2 | Given a token with factory.secrets.admin, when the production routes of RegisterSecretReference and RotateSecret are called with an Idempotency-Key against the fake of SecretBrokerService that answers 201, 200, 404 or 409, then the gateway forwards each call with the key and the body unchanged under the tenant of the token and returns each answer unchanged; given a token with factory.audit.admin, when the production route of SetClassification is called against the fake of AuditService that answers 200, 403 or 409, then each answer returns unchanged; the gateway evaluated no approval and no policy and holds no classification and no secret reference (SCN-GovernanceHost-004, ADR-0028). |
| AC3 | Given a workload token that holds the service scope the route names, when the external gRPC route of SecretBroker.Verify is called, then the call reaches the fake with its metadata unchanged and the reply returns unchanged; a workload token without the scope and a user token are answered PERMISSION_DENIED and no fronted service is called (SCN-GovernanceHost-003, ADR-0015). |
| AC4 | Given a call without a token or with an expired token, or a token that lacks the scope of the operation, when a production or external route is called, then the gateway answers 401 or 403 and no fronted service is called; given a route that names only a resource id, such as the referenceId of a rotation or a revocation, when the fronted service answers 403 for a missing role or 404 for a resource of another tenant, then the gateway returns that answer unchanged (SCN-GovernanceHost-003, SCN-GovernanceHost-004, ADR-0015). |
| AC5 | Given a fronted service that does not answer, when a production or external route of it is called, then the gateway answers 503, over gRPC UNAVAILABLE, with a problem response that names the service and carries a retry hint, invents no response, and the routes of the other services keep serving; and the register of gated routes fails the build when a route of class production or external has no scope or when the gateway holds a handler, a cache entry or a store for an approval, a classification, a secret reference, an export or a receipt (SCN-GovernanceHost-003, SCN-GovernanceHost-004, model/services/governance/GovernanceHost.yaml). |
| Traces: services | GovernanceHost, AuditService, SecretBrokerService |
| Traces: adrs | ADR-0015, ADR-0019, ADR-0028 |
| Traces: requirements | NFR-04, XL-14 |
| Traces: scenarios | SCN-GovernanceHost-003, SCN-GovernanceHost-004 |
| Relates: screens | audit, findings, secrets-references |
| Depends on | AIFACTORY-US-928, AIFACTORY-US-929, feature:component-api-gateway-template, feature:audit-service-complete, feature:secret-broker-service |
| Sources | model/services/governance/GovernanceHost.yaml, model/services/governance/AuditService.yaml, model/services/governance/SecretBrokerService.yaml, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md, docs/architecture/adr/0019-data-governance.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-3736 Project check of the audit export route and the route class register of the gateway |
implementation | The route of ExportAudit admits the projectId of its path only for a token with a role claim for it or the tenant-wide Platform admin role, sets the project header from it, forwards the Idempotency-Key unchanged and answers 403 itself otherwise; the routes of RegisterSecretReference and RotateSecret forward their Idempotency-Key unchanged; no body of a production or external route is logged; a register test lists every route of class production and external from the route table and fails when such a route has no scope or when the gateway holds a handler, a cache entry or a store for an approval, a classification, a secret reference, an export or a receipt. | ConnectSoft.AI.SoftwareFactory.GovernanceHost |
AIFACTORY-TASK-3737 Fakes of the production and external routes for the acceptance suite |
fixture | The acceptance suite holds a fake of ExportAudit of AuditService that answers 202, 403 and 404, a fake of SetClassification that answers 200, 403 and 409, fakes of RegisterSecretReference, RotateSecret and RevokeSecretReference of SecretBrokerService that answer 201, 200, 403, 404 and 409 and apply an Idempotency-Key once, and a fake of SecretBroker.Verify, each generated from its fronts entry and each recording the headers, the metadata and the body it received. | ConnectSoft.AI.SoftwareFactory.GovernanceHost |
AIFACTORY-TASK-3738 Verify the production and external routes through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-GovernanceHost-003\|Scenario=SCN-GovernanceHost-004)"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-931: the export forwarded with its key and its admitted project and refused for a project without a role, the answers 200, 201, 202, 403, 404 and 409 of the fakes returned unchanged, the gRPC route of SecretBroker.Verify with and without the service scope, the refusals of the gateway without a call to a fronted service, a fake that stops answering and the register of gated routes. |
ConnectSoft.AI.SoftwareFactory.GovernanceHost |
AIFACTORY-US-932: Health, revisions, limits and telemetry of the governance gateway while the identity platform, a fronted service or a replica fails¶
behavior · persona operator
As an operator, I want to see whether the governance gateway, the identity platform and each fronted service answer, and which policy and approval rule revisions are in force, so that I can tell a failing service from a failing gateway and act on the right one before callers fail closed.
An operator and the probes of the cluster read the state of the gateway through its two own operations. GovernanceHost/GovernanceHealth reports liveness and readiness of the gateway with the aggregated health of the four services it fronts and of the identity platform. Liveness needs no token; the detail is served to a caller whose scope carries factory.health.read. The identity platform is the one required dependency of the gateway, and the health check is the detection signal the model names for its failure. What the gateway does when it is unreachable is decided (ADR-0015 amendment D117). While a cached signing key still validates tokens, the gateway stays in rotation: readiness stays ready, tokens that were already issued keep passing, and from the first failed probe GovernanceHealth answers 200 with the health degraded and a detail that names the identity platform as unreachable, so the operator sees the failure in health while calls still pass. The gateway leaves rotation only when no valid key remains, because none was cached or the cached keys expired: readiness turns unready, GovernanceHealth answers 503 with a problem response that names the identity platform, and calls are refused, so the gateway fails closed. Liveness keeps answering 200 without a token in both phases. A fronted service is an optional dependency: when it does not answer, or is not deployed yet as ApprovalPolicyService is until I4, health reports it as unavailable in the detail and the answer stays 200, its routes answer 503 with a retry hint, and the routes of the other services keep serving. GovernanceHost/GovernanceRevisions returns to a caller whose scope carries factory.meta.read, an operator or the Studio about page, three members the model names: the active policy revisions per scope, the approval rule revisions per scope and the head of the audit hash chain. The gateway holds no state and reads no store. The three values belong to PolicyEngineService, ApprovalPolicyService and AuditService. Policy.GetActiveRevision answers for one scope a caller names, and the model gives no operation that lists the active revisions per scope, none that returns the approval rule revisions and none that returns the chain head, so the source of the three members is an open point reported to the owner. Until it is decided the members are part of the reply and are read through one metadata port of the gateway that has no production binding: a deployed instance answers 200 and states each member as not reported, and invents no value; the reply with the members filled is proven against a fake metadata source of the acceptance suite only. The model lists the code 200 alone for this operation; a call without a token is answered 401 and a token without the scope 403 all the same. A call that exceeds the rate limit configured for its route is refused with 429, over gRPC RESOURCE_EXHAUSTED, through the pinned rate-limiting library, from the configuration of the gateway, and calls no fronted service; the limit values are configuration of the deployment and none is fixed here. The gateway emits connectsoft.factory.governance.host.requests with the dimensions service, method and status and connectsoft.factory.governance.host.request_duration with service and route, the latency including the fronted service, each recorded through the helper of the pinned observability library, which puts the tenant, and the project where the route names one, on the instrument by default (ADR-0019); the gateway carries the trace context to the service. The gateway belongs to the class pilot-interactive of model/nfr-targets.yaml with an availability of 99.9 percent as its override; the duration series is what the class is measured against once the system is deployed, and no value is claimed here. Logs, activities and metrics never contain a token, a credential, a rule, evidence or any other payload. The model names four failure modes, and the runbook of the repository holds one entry for each. The identity platform is unreachable, in its two phases. A fronted service is unavailable. A replica crashes: the readiness probe detects it, the replica restarts and, because the gateway holds no state, nothing is replayed and callers retry. The gateway as a whole is unavailable: decision calls fail and every caller fails closed, no run is accepted, no tool executes and no credential is issued, which three replicas and regional placement are there to prevent. The roles of the gateway are Observer, Operator and Platform admin.
Acceptance criteria
| AC1 | Given the gateway with the identity platform and the fronted services reachable, when GovernanceHost/GovernanceHealth is called, then liveness answers 200 without a token and a caller with factory.health.read receives 200 with the state of each of the four fronted services and of the identity platform; a call for the detail without a token is answered 401 and a token without the scope 403 (SCN-GovernanceHost-001, NFR-18). |
| AC2 | Given the identity platform is unreachable and a cached signing key still validates tokens, when calls arrive and GovernanceHost/GovernanceHealth is probed, then tokens that were already issued are validated with the cached key, readiness stays ready so the replica stays in rotation, and from the first failed probe health answers 200 with the health degraded and a detail that names the identity platform as unreachable, while liveness keeps answering 200; given no valid key remains, because none was cached or the cached keys expired, when calls arrive, then they are refused, readiness is unready so the replica leaves rotation, GovernanceHost/GovernanceHealth answers 503 with a problem response that names the identity platform and no state changes (SCN-GovernanceHost-001, model/services/governance/GovernanceHost.yaml). |
| AC3 | Given one fronted service does not answer and ApprovalPolicyService is not deployed, when GovernanceHost/GovernanceHealth and the routes are called, then health answers 200 and reports both services as unavailable in its detail, their routes answer 503 with a retry hint that names the service, over gRPC UNAVAILABLE, the routes of the other services keep serving and the gateway invents no response (SCN-GovernanceHost-001, ADR-0028). |
| AC4 | Given a caller with factory.meta.read, when GovernanceHost/GovernanceRevisions is called on an instance whose metadata port has no source, then the response is 200 with the active policy revisions, the approval rule revisions and the head of the audit hash chain each stated as not reported; given the fake metadata source of the acceptance suite bound to the port, then the reply names the revisions per scope and the chain head the source reported; a call without a token is answered 401 and a token without the scope 403, no operation of a fronted service was called and nothing is written (SCN-GovernanceHost-002, NFR-04). |
| AC5 | Given routed calls and a call above the rate limit of its route, when the metrics and logs are read, then connectsoft.factory.governance.host.requests counts every call by service, method and status, the call above the limit was refused with 429 and called no fronted service, connectsoft.factory.governance.host.request_duration holds the latency by service and route, both series carry the tenant of the call, and the project where the route names one, as the helper of the pinned observability library adds them, and no log record, activity or metric holds a token, a credential or a payload (ADR-0019, NFR-10, model/services/governance/GovernanceHost.yaml). |
| Traces: services | GovernanceHost, PolicyEngineService, ApprovalPolicyService, AuditService |
| Traces: apis | GovernanceHost/GovernanceHealth, GovernanceHost/GovernanceRevisions |
| Traces: adrs | ADR-0015, ADR-0017, ADR-0019, ADR-0028 |
| Traces: requirements | NFR-04, NFR-10, NFR-18 |
| Traces: scenarios | SCN-GovernanceHost-001, SCN-GovernanceHost-002 |
| Depends on | AIFACTORY-US-928, feature:component-api-gateway-template, feature:component-observability-factory-conventions |
| Sources | model/services/governance/GovernanceHost.yaml, model/nfr-targets.yaml, docs/architecture/adr/0017-deployment-profiles.md, docs/planes/trust-operations/governance/services/governance-host/index.md#metrics-and-observability, docs/planes/trust-operations/governance/services/governance-host/index.md#failure-and-recovery |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-456 Health, revisions and telemetry of the gateway |
implementation | The health operation serves liveness without a token and the detail under factory.health.read with the aggregated state of the four fronted services and of the identity platform; while the identity platform is unreachable and a cached signing key still validates tokens, readiness stays ready and the operation answers 200 with the health degraded and the identity platform named in the detail from the first failed probe; when no valid key remains, readiness turns unready and the operation answers 503 with a problem response that names the identity platform (D117); liveness stays at 200 in both phases; the revisions operation serves, under factory.meta.read, the active policy revisions, the approval rule revisions and the head of the audit hash chain its metadata port returns, states each as not reported when the port has no source, and calls no operation of a fronted service; the port has no production binding; every routed call records connectsoft.factory.governance.host.requests and connectsoft.factory.governance.host.request_duration with their modelled dimensions and, through the helper of the pinned observability library, with the tenant of the call and the project where the route names one (ADR-0019), and carries the trace context to the service. | ConnectSoft.AI.SoftwareFactory.GovernanceHost |
AIFACTORY-TASK-3739 Rate limits per route from the configuration of the gateway |
implementation | Each route takes its rate limit from the configuration of the gateway through the pinned rate-limiting library and answers 429 above it, over gRPC RESOURCE_EXHAUSTED; a refusal by the limit calls no fronted service and is counted under its status in connectsoft.factory.governance.host.requests; the limit values are configuration of the deployment and none is fixed in code. | ConnectSoft.AI.SoftwareFactory.GovernanceHost |
AIFACTORY-TASK-3740 Runbook of the four failure modes of the gateway |
documentation | The repository documentation holds one runbook entry per failure mode of model/services/governance/GovernanceHost.yaml (identity platform unreachable, fronted service unavailable, gateway replica crash, gateway unavailable) with its detection signal, the expected answers of the gateway and the recovery step; the entry of the identity platform states its two phases, degraded and in rotation while a cached signing key validates tokens, and out of rotation and failing closed when no valid key remains (D117); the entry of the fronted service names ApprovalPolicyService as not deployed before I4; the entry of the replica crash states that nothing is replayed and that callers retry; the entry of the unavailable gateway states that every caller fails closed, so that no run is accepted, no tool executes and no credential is issued, and names the three replicas and the regional placement as the protection (NFR-18). | ConnectSoft.AI.SoftwareFactory.GovernanceHost |
AIFACTORY-TASK-3741 Verify health, revisions, limits and telemetry through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-GovernanceHost-001\|Scenario=SCN-GovernanceHost-002)"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-932 with the identity platform stopped while a cached key validates tokens (readiness ready, health 200 and degraded), without a cached key and after the cached key expired (readiness unready, health 503), one fake stopped and one service without an instance, the revisions operation without a metadata source, with the fake metadata source and without its scope, a call above its limit, the two series connectsoft.factory.governance.host.requests and connectsoft.factory.governance.host.request_duration with their dimensions, the tenant of the call and the project of a project-scoped route, and a scan of the captured logs and activities for token, credential and payload content. |
ConnectSoft.AI.SoftwareFactory.GovernanceHost |