AIFACTORY-FEAT-022: KnowledgeHost: 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 Knowledge Platform (PF-04) · Increment I1 Generate a microservice · State elaborated · Route backend-developer · Build order 66 of 185 (Factory code)
KnowledgeHost is the platform API gateway of bounded context BC-11 (Retrieval & Indexes). The API gateway of the Knowledge platform (ADR-0028): routes public REST and internal gRPC calls to the 6 services it fronts, validates tokens and scopes, and owns no business state. Its own repository is ConnectSoft.AI.SoftwareFactory.KnowledgeHost.
| Delivers | KnowledgeHost (complete) |
| Stubs | — |
| Realizes | adrs: ADR-0005, ADR-0013, ADR-0016, ADR-0017, ADR-0019 |
| Requirements | FR-07, FR-08, FUX-06, FUX-09, NFR-03, NFR-10, NFR-16, XL-07, XL-14 |
| Depends on | — |
| Sources | model/services/knowledge/KnowledgeHost.yaml |
Scenarios to trace (7, catalog): SCN-KnowledgeHost-001 ✓, SCN-KnowledgeHost-002 ✓, SCN-KnowledgeHost-003 ✓, SCN-KnowledgeHost-004 ✓, SCN-KnowledgeHost-005 ✓, SCN-KnowledgeHost-006 ✓, SCN-KnowledgeHost-007 ✓
AIFACTORY-US-081: KnowledgeHost 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 six services of the Knowledge 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 Knowledge platform. ADR-0028 re-scopes the former composition host as the API gateway of its platform: KnowledgeHost routes public REST and internal gRPC calls to the six services the model lists under deployment.fronts, ArtifactService, ContextBuilderService, KnowledgeIngestionService, MemoryPromotionService, RepositoryIntelligenceService and VectorMemoryService, validates tokens and scopes and owns no business state, no relational store and no secret (gateway role GW-03). The repository ConnectSoft.AI.SoftwareFactory.KnowledgeHost is created and scaffolded in I0 by AIFACTORY-TASK-466 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-822), token, tenant, project and scope on every read route (AIFACTORY-US-823), the pass-through of a shared-write call with its idempotency key (AIFACTORY-US-824), the production, publication and external routes whose gate stays in the fronted service (AIFACTORY-US-825), and health, modules, limits and telemetry with the three failure modes of a gateway (AIFACTORY-US-826). 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. Two operations of the platform name the project in their path, ExportArtifacts of ArtifactService and SetCollection of KnowledgeIngestionService: 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 an artifact, a run, a source or a memory, 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 gateway is delivered in I1 (D125): it is the only route by which a person reads or exports an artifact, and in this increment it serves the five public routes of ArtifactService, GetArtifact, PreviewArtifact, ListArtifactVersions, ListRunArtifacts and ExportArtifacts, against the service that is delivered complete in the same increment. The other five services reach the gateway unevenly. ContextBuilderService, KnowledgeIngestionService and VectorMemoryService are delivered thin in I1 and host none of their public REST operations before their complete deliveries in I5. RepositoryIntelligenceService has no deployed instance before its complete delivery in I5, because in I1 its seven read tools run inside the sandbox of the run and pass no gateway (D125). MemoryPromotionService arrives in I5. The fronts file holds the routes of all six services from the start, and the routes of the other knowledge services begin to serve as the complete deliveries appear in I5, without a change of the gateway. Until then a route whose service is not deployed answers 503 with a problem response that names the service, and a route whose operation a thin delivery does not host returns the answer of that service unchanged; the refusals and the failure branches of every route class are proven against fakes generated from the fronts file. Of the three callers the model names, ToolExecutorHost is delivered in the same increment, and AgentRuntimeWorker and StudioBff arrive in I3; each calls the gateway in its own PBIs, and this feature waits for none of them. The feature adds no direct public route to any service of the platform. The gateway invents no response.
Acceptance criteria
| AC1 | Given the repository ConnectSoft.AI.SoftwareFactory.KnowledgeHost created and scaffolded in I0 by AIFACTORY-TASK-466 of feature repository-and-pipeline-conventions, whose first commit is the unchanged output of dotnet new connectsoft-apigateway -n ConnectSoft.AI.SoftwareFactory.KnowledgeHost --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/knowledge/KnowledgeHost.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-823 to AIFACTORY-US-825 prove per route class (ADR-0015, FR-07). |
| 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 KnowledgeHost as a consumer (ADR-0028, model/services/knowledge/KnowledgeHost.yaml). |
| AC4 | Given the gateway deployed with two replicas, when KnowledgeHost/KnowledgeHealth is probed and one replica is stopped, then health reports the identity platform and the six fronted services, a replica stays in rotation while it can validate tokens, the other replica keeps serving and nothing is replayed, because the gateway holds no state (ADR-0017, model/services/knowledge/KnowledgeHost.yaml). |
| Traces: services | KnowledgeHost, ArtifactService, ContextBuilderService, KnowledgeIngestionService, MemoryPromotionService, RepositoryIntelligenceService, VectorMemoryService |
| Traces: apis | KnowledgeHost/KnowledgeHealth |
| Traces: adrs | ADR-0015, ADR-0016, ADR-0017, ADR-0028 |
| Traces: requirements | FR-07, FR-08 |
| Depends on | AIFACTORY-US-822, AIFACTORY-US-823, AIFACTORY-US-824, AIFACTORY-US-825, AIFACTORY-US-826, feature:repository-and-pipeline-conventions, feature:component-api-gateway-template, feature:component-extensions-ai, feature:artifact-service, feature:context-builder-service-thin, feature:knowledge-ingestion-service-thin, feature:repository-intelligence-service-thin, feature:vector-memory-service-thin |
| Sources | model/services/knowledge/KnowledgeHost.yaml, model/gateways.yaml, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md, docs/planes/knowledge-memory/services/knowledge-host/index.md#purpose-and-responsibilities |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-3306 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 2 to 10, the ports https 7700 and grpc 7702, the liveness and readiness probes on the health operation and one base address per fronted service from configuration, as model/services/knowledge/KnowledgeHost.yaml records them; it leaves Knowledge:Host:FrontedServices at its default, the six 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.KnowledgeHost |
AIFACTORY-TASK-762 Verify knowledge-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-081, 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 TwoReplicas (dotnet test -c Release --filter "Category=Acceptance&Feature=TwoReplicas"), which hosts two instances of the gateway behind one test balancer with the fakes of the fronted services, probes KnowledgeHost/KnowledgeHealth on both, stops one instance and asserts that the other keeps serving and that no call is replayed. |
ConnectSoft.AI.SoftwareFactory.KnowledgeHost |
AIFACTORY-US-822: Knowledge fronts file: named clients and REST and gRPC routes of the six fronted services, generated at build¶
enabling · persona platform-admin
As a platform admin, I want the route table of the knowledge 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 Knowledge platform. It lists the six services of deployment.fronts in model/services/knowledge/KnowledgeHost.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 ArtifactService these are the five REST operations GetArtifact, PreviewArtifact, ListArtifactVersions, ListRunArtifacts and ExportArtifacts and the three gRPC methods Artifacts.Store, Artifacts.Fetch and Artifacts.RecordValidation. For ContextBuilderService these are ListContextSnapshots and GetContextSnapshot and the gRPC method ContextAssembly.Assemble. For KnowledgeIngestionService these are the six REST operations RegisterSource, ListSources, SyncSource, DeleteSource, GetSnapshot and SetCollection and the gRPC method Ingestion.GetSourceScope. For MemoryPromotionService these are the five REST operations ListMemory, GetMemory, PromoteMemory, ArchiveMemory and SetMemoryConsent and the gRPC methods Memory.RetrieveMemory and Memory.Observe. For RepositoryIntelligenceService these are ListRepositoryIndexSets and RebuildRepositoryIndexes and the seven gRPC methods of RepositoryIntelligence. For VectorMemoryService these are the four REST operations Search, QueryGraph, ListIndexRevisions and RebuildIndexes and the gRPC methods Retrieval.Retrieve and Retrieval.ExpandGraph. That is twenty-four REST routes and sixteen gRPC routes; Artifacts.Store is a client stream, Artifacts.Fetch a server stream and the other fourteen are unary. The file holds the whole surface of the model, also for operations that a thin delivery does not host yet and for RepositoryIntelligenceService and MemoryPromotionService, which have no deployed instance before I5: the route exists, and what it answers until then is the answer of the service or 503 (AIFACTORY-US-081). The REST operations are the public surface that StudioBff and a typed client call; the gRPC methods are the internal surface that AgentRuntimeWorker and ToolExecutorHost call for context assembly, artifact writes and the knowledge and repository tools. In I1 the repository read tools do not pass this gateway, because they run inside the sandbox of the run (D125); their seven gRPC routes serve from the complete delivery of RepositoryIntelligenceService in I5. 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. ExportArtifacts and SetCollection name it in the path parameter projectId. The operations whose path names an artifact, a run, a context snapshot, a source, a snapshot, a memory or a collection are marked as addressed by a resource identifier only. ListSources, RegisterSource, Search, QueryGraph and ListMemory read or write 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. SetMemoryConsent of MemoryPromotionService, PUT /factory/memory/consent, fits none of these three: it grants or revokes the consent of the tenant for shared memory, so it acts on the tenant of the token by design and names no project because none applies. It is marked as tenant-wide by design, a fourth marking that is no gap of the model and no part of that correction. The four markings cover all twenty-four REST operations: two by the path parameter projectId, sixteen by a resource identifier only, five by the tenant of the token until their service files name a project parameter, and one tenant-wide by design. A test lists the emitted route table against the file and against the six 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 KnowledgeHealth and KnowledgeModules, transforms no payload and composes no response from two services. The option Knowledge: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 Knowledge:Host:FrontedServices in model/services/knowledge/KnowledgeHost.yaml names the same six service identifiers (D125), so the deployment manifest does not set the option. The pipeline of this repository publishes the OpenAPI document of the twenty-four public REST operations as a build output, checked against the fronts file and the six service files. This feature builds and publishes no client package: the typed client of this gateway is published by feature typed-gateway-clients of the same increment, which generates it from this OpenAPI document. That feature is aligned with the delivery of this gateway in I1 in its own PBIs, so the dependency is stated here in words and adds no client work to this feature.
Acceptance criteria
| AC1 | Given the fronts file of the Knowledge 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, twenty-four REST routes and sixteen gRPC routes, each with the scope, side-effect class, idempotency and streaming mode of the operation, and the route table test passes against model/services/knowledge/KnowledgeHost.yaml and the six service files under model/services/knowledge (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 Knowledge:Host:FrontedServices at its default, the six service identifiers of deployment.fronts in model/services/knowledge/KnowledgeHost.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-07). |
| AC4 | Given the built gateway, when its pipeline publishes the OpenAPI document of the public REST routes, then the document holds exactly the twenty-four 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 six service files under model/services/knowledge (docs/architecture/api-governance.md). |
| Traces: services | KnowledgeHost, ArtifactService, ContextBuilderService, KnowledgeIngestionService, MemoryPromotionService, RepositoryIntelligenceService, VectorMemoryService |
| Traces: adrs | ADR-0015, ADR-0028 |
| Traces: requirements | FR-07 |
| Depends on | feature:component-api-gateway-template, feature:artifact-service, feature:context-builder-service-thin, feature:knowledge-ingestion-service-thin, feature:repository-intelligence-service-thin, feature:vector-memory-service-thin |
| Sources | model/services/knowledge/KnowledgeHost.yaml, model/services/knowledge/ArtifactService.yaml, model/services/knowledge/ContextBuilderService.yaml, model/services/knowledge/KnowledgeIngestionService.yaml, model/services/knowledge/MemoryPromotionService.yaml, model/services/knowledge/RepositoryIntelligenceService.yaml, model/services/knowledge/VectorMemoryService.yaml, model/gateways.yaml, docs/architecture/catalogs/gateways.md, docs/architecture/api-governance.md, docs/planes/knowledge-memory/services/knowledge-host/index.md#context-and-boundaries |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-467 Fronts file with the REST and gRPC operations of ArtifactService, ContextBuilderService, KnowledgeIngestionService, MemoryPromotionService, RepositoryIntelligenceService and VectorMemoryService |
implementation | The fronts file lists the six 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 twenty-four operations: by the path parameter projectId for ExportArtifacts and SetCollection; by a resource identifier only for the sixteen operations whose path names an artifact, a run, a context snapshot, a source, a snapshot, a memory or a collection; by the tenant of the token for ListSources, RegisterSource, Search, QueryGraph and ListMemory, whose service files name no project parameter, which is reported as a correction of those files; and tenant-wide by design for SetMemoryConsent, which acts on the consent of the tenant and is no part of that correction; a test fails when a REST operation carries none or more than one of the four markings; the build emits the named clients, the twenty-four REST routes, the sixteen gRPC routes and the route table; at startup the option Knowledge:Host:FrontedServices, whose default is the six 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.KnowledgeHost |
AIFACTORY-TASK-3307 Fakes of the six 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, answers a configured status and serves a client stream and a server stream for the two streaming methods of ArtifactService, a switch that makes a fake stop answering, also in the middle of a stream, 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.KnowledgeHost |
AIFACTORY-TASK-3308 OpenAPI document of the public REST routes of the gateway as a published build output |
contract | The pipeline publishes one OpenAPI document with the twenty-four 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 six service files under model/services/knowledge 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.KnowledgeHost |
AIFACTORY-TASK-3309 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-822: one route per operation of the six service files under model/services/knowledge, 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.KnowledgeHost |
AIFACTORY-US-823: A read route of the knowledge gateway forwards a call only under a validated token, the tenant of the token and the scope of its operation¶
behavior · persona requester
As a requester, I want my read calls to reach the artifact, context, source, memory, repository and retrieval services only with the tenant and the scope my token grants, so that I see the artifacts, snapshots, sources and search results I am entitled to and nobody reads across a tenant through the gateway, while the project rule of a read is applied by the fronted service until the service files name a project parameter.
A caller reaches a read operation of the Knowledge platform through the gateway: a requester reads an artifact, its preview and its version chain and the artifacts and context snapshots of a run, lists sources and memories, searches knowledge and queries the graph, and an Observer reads the same; a worker of the Agent Mesh assembles context and reads promoted memories, and the tool gateway calls the repository and retrieval tools 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.artifacts.read for GetArtifact, PreviewArtifact and ListArtifactVersions, factory.runs.read for ListRunArtifacts, ListContextSnapshots and GetContextSnapshot, factory.knowledge.read for ListSources, GetSnapshot, ListRepositoryIndexSets, Search, QueryGraph and ListIndexRevisions, and factory.memory.read for ListMemory and GetMemory. It takes the tenant from the tid claim and overwrites any tenant header of the caller. No read operation of the six service files names a project in its path, in a query parameter or in a body member. Ten of the fourteen name a resource by identifier, an artifact, a run, a context snapshot, a snapshot, a memory, a repository source or a collection, 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. ListSources, Search, QueryGraph and ListMemory read under the scope of the caller and name no resource; until their service files name the parameter that carries a project (AIFACTORY-US-822), 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. A project header a caller sends is dropped and establishes nothing; the gateway sets the project header only from a project it admitted from a path, a query parameter or a body member. 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 thirteen read methods: Artifacts.Fetch, ContextAssembly.Assemble, Ingestion.GetSourceScope, Memory.RetrieveMemory, the seven methods of RepositoryIntelligence, Retrieval.Retrieve and Retrieval.ExpandGraph. 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. Artifacts.Fetch is a server stream: the gateway passes the messages through as they arrive, buffers no artifact content and caches none, and when the service fails in the middle of a stream the stream ends with UNAVAILABLE and nothing is replayed. For every read route the response is served by the fronted service with no side effect and returns unchanged with the correlation id; the gateway keeps nothing of the call and records connectsoft.factory.knowledge.host.requests and connectsoft.factory.knowledge.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. In this increment the read routes a person uses are the four of ArtifactService, GetArtifact, PreviewArtifact, ListArtifactVersions and ListRunArtifacts, and the gateway is the only route by which a person reaches them (D125); the read routes of the other knowledge services serve as their complete deliveries appear in I5. When the fronted service does not answer, or is not deployed yet as RepositoryIntelligenceService and MemoryPromotionService are until I5, 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. A read operation that a thin delivery does not host yet returns the answer of that service unchanged.
Acceptance criteria
| AC1 | Given a user token whose audience is this gateway, with factory.artifacts.read, when the read route of GetArtifact 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, ArtifactService answers, the response returns unchanged with the correlation id and nothing is written by the gateway (SCN-KnowledgeHost-006, ADR-0015, FR-08). |
| AC2 | Given the token matrix of the acceptance suite, when the read routes of the six 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-KnowledgeHost-006, ADR-0015). |
| AC3 | 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 an artifactId, a runId or a sourceId 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 (ADR-0015 amendment D113) return unchanged; given the routes of ListSources, Search, QueryGraph and ListMemory, then they are forwarded under the tenant of the token with the user token unchanged, as model/services/knowledge/KnowledgeHost.yaml and the service files name no project parameter for them (SCN-KnowledgeHost-006). |
| AC4 | Given a workload token that holds the service scope the route names, when the gRPC read routes of Retrieval.Retrieve, RepositoryIntelligence.ReadRange and the server stream Artifacts.Fetch are called with tenant-id and project metadata, then the gateway forwards each call with that metadata unchanged, passes the stream through without buffering content and returns the reply of the service unchanged; given a workload token without the scope, or a user token, then the answer is PERMISSION_DENIED and no fronted service is called; a NOT_FOUND of the fronted service for a resource outside the forwarded tenant returns unchanged (SCN-KnowledgeHost-006, ADR-0015). |
| AC5 | Given a fronted service that does not answer, a fake of ArtifactService that stops in the middle of Artifacts.Fetch, and the routes of MemoryPromotionService while that service is not deployed, when their read 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, the interrupted stream ends with UNAVAILABLE and is not replayed, no response is invented, and the read routes of the other services keep serving (SCN-KnowledgeHost-006, model/services/knowledge/KnowledgeHost.yaml). |
| Traces: services | KnowledgeHost, ArtifactService, ContextBuilderService, KnowledgeIngestionService, MemoryPromotionService, RepositoryIntelligenceService, VectorMemoryService |
| Traces: adrs | ADR-0015, ADR-0028 |
| Traces: requirements | FR-07, FR-08, FUX-06, FUX-09 |
| Traces: scenarios | SCN-KnowledgeHost-006 |
| Relates: screens | artifacts, context-snapshot, knowledge-sources, knowledge-search, memory, repository-intelligence |
| Depends on | AIFACTORY-US-822, feature:component-api-gateway-template, feature:component-extensions-ai, feature:artifact-service, feature:context-builder-service-thin, feature:knowledge-ingestion-service-thin, feature:repository-intelligence-service-thin, feature:vector-memory-service-thin |
| Sources | model/services/knowledge/KnowledgeHost.yaml, model/services/knowledge/ArtifactService.yaml, model/services/knowledge/ContextBuilderService.yaml, model/services/knowledge/VectorMemoryService.yaml, docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md, docs/planes/knowledge-memory/services/knowledge-host/index.md#purpose-and-responsibilities |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-3310 Issuer, audience, scope, tenant and project configuration of the read 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 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; 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; ListSources, Search, QueryGraph and ListMemory 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 server stream of Artifacts.Fetch is passed through without buffering; the user token is forwarded unchanged and no token is exchanged (ADR-0015 amendment D117); refusals are counted per route and logged with the correlation id and without the token. | ConnectSoft.AI.SoftwareFactory.KnowledgeHost |
AIFACTORY-TASK-3311 Verify the read routes through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&Scenario=SCN-KnowledgeHost-006"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-823 over the token matrix: 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 four routes forwarded under the tenant of the token, a workload token refused on a REST route, the gRPC routes of Retrieval.Retrieve and RepositoryIntelligence.ReadRange with and without the service scope, the server stream of Artifacts.Fetch passed through and interrupted, a fake that stops answering and the routes of the service that is not deployed. |
ConnectSoft.AI.SoftwareFactory.KnowledgeHost |
AIFACTORY-US-824: A shared-write route of the knowledge gateway passes the idempotency key through and the gateway keeps nothing between calls¶
behavior · persona workspace-admin
As a workspace admin, I want a write I repeat after a failure to be applied once, so that a lost answer or a restarted gateway never registers a second source, starts a second rebuild or stores an artifact twice.
A shared-write operation changes state that others read. The Knowledge platform has six on its public surface: RegisterSource, SyncSource and SetCollection of KnowledgeIngestionService, ArchiveMemory of MemoryPromotionService, RebuildRepositoryIndexes of RepositoryIntelligenceService and RebuildIndexes of VectorMemoryService; and three on its internal gRPC surface: Artifacts.Store and Artifacts.RecordValidation of ArtifactService and Memory.Observe of MemoryPromotionService. The caller sends each through the gateway under the token, tenant and scope rules of AIFACTORY-US-823: factory.knowledge.admin for the five operations on sources, collections and rebuilds, factory.memory.review for ArchiveMemory, and on a gRPC route a workload token that holds the service scope the route names. SetCollection is the one shared-write route that names its project, in the path parameter projectId: 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. The other routes name a source, a memory, a repository source or a collection by identifier, or, for RegisterSource, write under the scope of the caller; 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. RegisterSource, SyncSource, RebuildRepositoryIndexes and RebuildIndexes declare idempotency key-header and are called with an Idempotency-Key; the gateway forwards the header unchanged and the fronted service applies the request once under its own rule: the same key with the same body returns the same result, and the answer of the fronted service for a key reused with a different body returns to the caller unchanged, whatever its status. The gateway states no status for that case, because the model states none: model/services/knowledge/KnowledgeIngestionService.yaml lists 409 among the codes of RegisterSource without a meaning, and no PBI of that service, which stays thin until I5, has decided its answer for a reused key. The 409 of RegisterSource is one example of a domain answer that returns unchanged, whatever it stands for. SetCollection and ArchiveMemory are naturally idempotent and need no key. Artifacts.Store is a client stream that stores content by hash and is idempotent on tenant and hash within a chain: the gateway passes the messages through as they arrive, buffers no content and writes none to the shared cache, and returns the reply of the service. The gateway is no party to idempotency. It stores neither a key nor a result, keeps no session and no pending call, has no outbox and writes no event, so a gateway replica that crashes during a call loses nothing: the replica restarts, nothing is replayed, and the caller retries with the same key, or stores the same content again, and receives from the service the result of the one application (failure mode of a gateway replica crash in the model). 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 retries with its key. A refusal by the gateway, 401, 403 or the 403 for a project the token does not grant, reaches no fronted service, so it applies nothing. A missing key, an invalid body and every domain refusal are answers of the fronted service and return unchanged with the correlation id. In this increment the two gRPC writes of ArtifactService are served by the deployed service. The thin deliveries of KnowledgeIngestionService and VectorMemoryService do not host their shared-write operations before I5, and RepositoryIntelligenceService and MemoryPromotionService have no deployed instance before I5 (D125), so those routes are proven against the fakes generated from the fronts entries; on a deployed instance the first return the answer of the thin service unchanged and the routes of RepositoryIntelligenceService and MemoryPromotionService answer 503 with the service named. 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.knowledge.admin and the route of RegisterSource, whose operation declares idempotency key-header, when the call arrives with an Idempotency-Key, then the gateway forwards the request with the header and the body unchanged, the fake of KnowledgeIngestionService applies it once and the response returns unchanged with the correlation id (SCN-KnowledgeHost-007, ADR-0015). |
| AC2 | Given the same call repeated with the same key, and then with the same key and a different body, when both pass the gateway, then the first returns the result of the first application and the second returns the answer of the fronted service for a reused key unchanged, whatever its status; the gateway has stored neither the key nor a result in the shared cache or anywhere else (SCN-KnowledgeHost-007, ADR-0028). |
| AC3 | Given a workload token that holds the service scope and the client stream Artifacts.Store, when a gateway replica is stopped while the stream is in flight and the caller stores the same content again through another replica, then the second replica passes the repeated stream through message by message, the fake of ArtifactService received the first stream as interrupted and the second stream complete, the gateway replayed nothing and neither replica buffered or cached content; that ArtifactService holds one artifact for a tenant and hash is the rule of that service and is proven by the PBIs of feature artifact-service, not by the suite of the gateway (SCN-KnowledgeHost-007, model/services/knowledge/KnowledgeHost.yaml). |
| AC4 | Given the route of SetCollection with a projectId in its path, when the token holds a role claim for that project or the tenant-wide Platform admin role, then the call is forwarded with the project in the project header the gateway sets, and when the token holds none, then the gateway answers 403 itself and no fronted service is called; given a shared-write route addressed by a sourceId, a memoryId or a collectionId, when the fronted service answers 403 for a missing role or 404 for a resource of another tenant (ADR-0015 amendment D113), then the gateway returns that answer unchanged (SCN-KnowledgeHost-007, ADR-0015). |
| AC5 | Given a call without a token, a token that lacks the scope, a fronted service that does not answer and the routes of MemoryPromotionService while that service is not deployed, when a shared-write route is called, then the answer is 401, 403 or 503 respectively, a call the gateway refuses reaches no fronted service and applies nothing, and the 503 names the service and carries a retry hint while the other routes keep serving (SCN-KnowledgeHost-007, model/services/knowledge/KnowledgeHost.yaml). |
| Traces: services | KnowledgeHost, ArtifactService, KnowledgeIngestionService, MemoryPromotionService, RepositoryIntelligenceService, VectorMemoryService |
| Traces: adrs | ADR-0015, ADR-0028 |
| Traces: requirements | FR-08, FUX-09 |
| Traces: scenarios | SCN-KnowledgeHost-007 |
| Relates: screens | knowledge-sources, memory |
| Depends on | AIFACTORY-US-822, AIFACTORY-US-823, feature:component-api-gateway-template, feature:artifact-service, feature:knowledge-ingestion-service-thin |
| Sources | model/services/knowledge/KnowledgeHost.yaml, model/services/knowledge/KnowledgeIngestionService.yaml, model/services/knowledge/ArtifactService.yaml, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md, docs/planes/knowledge-memory/services/knowledge-host/index.md#failure-and-recovery |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-3312 Forwarded headers and metadata of a write route, the project of SetCollection and a stateless call path |
implementation | A shared-write route forwards the Idempotency-Key header, the body and the established scope unchanged and returns the status and the body of the fronted service unchanged; the route of SetCollection 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 and answers 403 itself otherwise; the client stream of Artifacts.Store is passed through message by message; no key, body, content or result is written to the shared cache or to any store; request count and latency are recorded for the route with the returned status. | ConnectSoft.AI.SoftwareFactory.KnowledgeHost |
AIFACTORY-TASK-3313 Verify the shared-write routes through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&Scenario=SCN-KnowledgeHost-007"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-824 with a fake that applies a key once and answers a configured conflict status for the same key with a different body, run with two different configured statuses and asserted as the pass-through of each status and body unchanged, a replica stopped during the client stream of Artifacts.Store, after which the fake holds the first stream as interrupted and the repeated stream through the second replica as complete and the gateway replayed nothing, the route of SetCollection with a granted and a refused project, a route addressed by a resource id whose 403 and 404 come from the fake and return unchanged, a fake that stops answering, the routes of the service that is not deployed and an inspection of the shared cache that finds no key and no content. |
ConnectSoft.AI.SoftwareFactory.KnowledgeHost |
AIFACTORY-US-825: A production, publication or external route of the knowledge gateway is forwarded under its scope and the gate of the action stays in the fronted service¶
behavior · persona workspace-admin
As a workspace admin, I want a deletion, a promotion, a consent change or an 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 an approval is never decided twice or by a component that holds no state.
Three side-effect classes of the Knowledge platform carry a gate beyond the scope. The production routes are DeleteSource of KnowledgeIngestionService, which deletes a source and every derived item with deletion lineage, and SetMemoryConsent of MemoryPromotionService, by which a Platform admin grants or revokes the consent of the tenant for shared memory. The publication route is PromoteMemory of MemoryPromotionService, the promotion of a reviewed candidate, an approval-gated action bound to the content hash of the memory. The external route is ExportArtifacts of ArtifactService, the export of the artifacts, the lineage and the metadata of a project in open formats (XL-14). 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.knowledge.admin for DeleteSource, factory.memory.admin for SetMemoryConsent, factory.memory.review for PromoteMemory and factory.artifacts.admin for ExportArtifacts, and forwards the call with the established scope. ExportArtifacts 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. DeleteSource and PromoteMemory name a source or a memory by identifier and SetMemoryConsent acts on 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. The gate itself is decided where the state is. KnowledgeIngestionService decides a deletion and moves the source to Deleting. MemoryPromotionService promotes a memory only through a review decision bound to its exact content hash and, for shared scope, with the consent record of the tenant, and answers 409 or 412 when a precondition does not hold; the approval is requested from and decided in RunControlService and reaches the service as an event. ArtifactService accepts an export with 202 and its own worker produces the package; the Idempotency-Key of the export passes through unchanged. The gateway evaluates no policy and no approval, holds no approval reference and no consent, calls no connector, 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 202, 409 and 412, 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. In this increment ExportArtifacts is proven against ArtifactService, which is delivered complete in the same increment, and the gateway is the only route by which a person starts an export (D125). DeleteSource is not hosted by the thin KnowledgeIngestionService before I5 and MemoryPromotionService arrives in I5, so the production and the publication routes are proven against fakes generated from the fronts entries: on a deployed instance the route of DeleteSource returns the answer of the thin service unchanged and the routes of MemoryPromotionService answer 503 with a problem response that names the service.
Acceptance criteria
| AC1 | Given a token with factory.artifacts.admin and a role claim for the project of the path, when the external route of ExportArtifacts 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, ArtifactService 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 ArtifactService is not called (SCN-KnowledgeHost-003, ADR-0028, XL-14). |
| AC2 | Given a token with factory.knowledge.admin, when the production route of DeleteSource is called against the fake of KnowledgeIngestionService that answers 202, 403 or 404, then the gateway forwards the call under the tenant of the token and the scope of the operation, because the route names only the sourceId, and returns each answer unchanged; given a token with factory.memory.admin, when the production route of SetMemoryConsent is called against the fake of MemoryPromotionService, then the call is forwarded and its answer returns unchanged; the gateway evaluated no approval and holds no consent (SCN-KnowledgeHost-004, ADR-0028). |
| AC3 | Given a token with factory.memory.review, when the publication route of PromoteMemory is called against the fake of MemoryPromotionService that answers 200, 409 or 412, then the gateway forwards the call under the established scope and returns each answer unchanged, holding no approval reference of its own (SCN-KnowledgeHost-005, ADR-0028, model/services/knowledge/MemoryPromotionService.yaml). |
| 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, publication 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 sourceId of a deletion or the memoryId of a promotion, when the fronted service answers 403 for a missing role or 404 for a resource of another tenant (ADR-0015 amendment D113), then the gateway returns that answer unchanged (SCN-KnowledgeHost-003, SCN-KnowledgeHost-004, SCN-KnowledgeHost-005, ADR-0015). |
| AC5 | Given a deployed instance of this increment, when the routes of SetMemoryConsent and PromoteMemory are called while MemoryPromotionService is not deployed, then each answers 503 with a problem response that names the service and carries a retry hint, the gateway invents no response, and the external route of ExportArtifacts and every route of the other services keep serving (SCN-KnowledgeHost-004, SCN-KnowledgeHost-005, model/services/knowledge/KnowledgeHost.yaml). |
| Traces: services | KnowledgeHost, ArtifactService, KnowledgeIngestionService, MemoryPromotionService |
| Traces: adrs | ADR-0015, ADR-0019, ADR-0028 |
| Traces: requirements | FR-08, NFR-03, XL-14 |
| Traces: scenarios | SCN-KnowledgeHost-003, SCN-KnowledgeHost-004, SCN-KnowledgeHost-005 |
| Relates: screens | artifacts, knowledge-sources, memory |
| Depends on | AIFACTORY-US-822, AIFACTORY-US-823, feature:component-api-gateway-template, feature:artifact-service, feature:knowledge-ingestion-service-thin |
| Sources | model/services/knowledge/KnowledgeHost.yaml, model/services/knowledge/ArtifactService.yaml, model/services/knowledge/KnowledgeIngestionService.yaml, model/services/knowledge/MemoryPromotionService.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-3314 Project check of the export route and the route class register of the gateway |
implementation | The route of ExportArtifacts 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; a register test lists every route of class production, publication 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 consent, an export or a receipt. | ConnectSoft.AI.SoftwareFactory.KnowledgeHost |
AIFACTORY-TASK-3315 Fakes of the production and publication routes for the acceptance suite |
fixture | The acceptance suite holds a fake of DeleteSource of KnowledgeIngestionService that answers 202, 403 and 404, a fake of SetMemoryConsent of MemoryPromotionService that answers 200 and 403 and a fake of PromoteMemory that answers 200, 409 and 412, each generated from its fronts entry, and a configuration in which MemoryPromotionService has no instance behind its base address. | ConnectSoft.AI.SoftwareFactory.KnowledgeHost |
AIFACTORY-TASK-3316 Verify the production, publication and external routes through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-KnowledgeHost-003\|Scenario=SCN-KnowledgeHost-004\|Scenario=SCN-KnowledgeHost-005)"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-825: the export forwarded with its key and its admitted project and refused for a project without a role, the answers 202, 403, 404, 409 and 412 of the fakes returned unchanged, the refusals of the gateway without a call to a fronted service, the 503 of the routes whose service is not deployed and the register of gated routes. |
ConnectSoft.AI.SoftwareFactory.KnowledgeHost |
AIFACTORY-US-826: Health, modules, limits and telemetry of the knowledge gateway while the identity platform, a fronted service or a replica fails¶
behavior · persona operator
As an operator, I want to see whether the knowledge gateway, the identity platform and each fronted service answer, and which services and index profiles this installation runs, so that I can tell a failing service from a failing gateway and act on the right one.
An operator and the probes of the cluster read the state of the gateway through its two own operations. KnowledgeHost/KnowledgeHealth reports liveness and readiness of the gateway with the aggregated health of the six 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 KnowledgeHealth 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, KnowledgeHealth 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 RepositoryIntelligenceService and MemoryPromotionService are until I5, 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. KnowledgeHost/KnowledgeModules returns to a caller whose scope carries factory.meta.read the six fronted services with their versions and repositories, as deployment.fronts lists them, and two further members the model names: the vector profile in use (ADR-0013) and the embedding profile versions of the indexes. The gateway holds no state and reads no index. Both values belong to VectorMemoryService, which owns the vector profile selection and the index revisions, and the model gives that service no operation that returns the profile in use or the versions across collections, so the source of these two members is an open point reported to the owner. Until it is decided the two 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 the six services and states the vector profile and the embedding profile versions as not reported, and invents no value. That matches what exists in this increment, where VectorMemoryService is thin, binds no vector backend and holds no index; the reply with both members filled is proven against a fake metadata source of the acceptance suite only. 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 gateway emits connectsoft.factory.knowledge.host.requests with the dimensions service, route and status and connectsoft.factory.knowledge.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, whose objective is an acknowledgement within 2 seconds at p95; the duration series is what it is measured against once the system is deployed, and no value is claimed here. Logs, activities and metrics never contain a token, an artifact, a query, a search result or any other payload. A replica that crashes is detected by the readiness probe and restarts; because the gateway holds no state, nothing is replayed and callers retry with their idempotency key. 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 KnowledgeHost/KnowledgeHealth 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 six 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-KnowledgeHost-001, NFR-18). |
| AC2 | Given the identity platform is unreachable and a cached signing key still validates tokens, when calls arrive and KnowledgeHost/KnowledgeHealth 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, KnowledgeHost/KnowledgeHealth answers 503 with a problem response that names the identity platform and no state changes (SCN-KnowledgeHost-001, model/services/knowledge/KnowledgeHost.yaml). |
| AC3 | Given one fronted service does not answer and MemoryPromotionService is not deployed, when KnowledgeHost/KnowledgeHealth 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-KnowledgeHost-001, ADR-0028). |
| AC4 | Given a caller with factory.meta.read, when KnowledgeHost/KnowledgeModules is called on an instance whose metadata port has no source, then the response is 200 with the six fronted services, each with its version and repository, as model/services/knowledge/KnowledgeHost.yaml lists them under deployment.fronts, and with the vector profile and the embedding profile versions stated as not reported; given the fake metadata source of the acceptance suite bound to the port, then the reply names the vector profile and the embedding profile versions the source reported (ADR-0013); a call without a token is answered 401 and a token without the scope 403, no operation of VectorMemoryService was called and nothing is written (SCN-KnowledgeHost-002). |
| AC5 | Given routed calls and a call above the rate limit of its route, when the metrics and logs are read, then connectsoft.factory.knowledge.host.requests counts every call by service, route and status, the call above the limit was refused with 429 and called no fronted service, connectsoft.factory.knowledge.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 or a payload (ADR-0019, NFR-10, model/services/knowledge/KnowledgeHost.yaml). |
| Traces: services | KnowledgeHost, VectorMemoryService |
| Traces: apis | KnowledgeHost/KnowledgeHealth, KnowledgeHost/KnowledgeModules |
| Traces: adrs | ADR-0005, ADR-0013, ADR-0015, ADR-0017, ADR-0019, ADR-0028 |
| Traces: requirements | NFR-10, NFR-18 |
| Traces: scenarios | SCN-KnowledgeHost-001, SCN-KnowledgeHost-002 |
| Relates: nfrs | NFR-07 |
| Depends on | AIFACTORY-US-822, feature:component-api-gateway-template, feature:component-observability-factory-conventions, feature:vector-memory-service-thin |
| Sources | model/services/knowledge/KnowledgeHost.yaml, model/services/knowledge/VectorMemoryService.yaml, docs/architecture/adr/0013-vector-store-profiles.md, docs/planes/knowledge-memory/services/knowledge-host/index.md#metrics-and-observability, docs/planes/knowledge-memory/services/knowledge-host/index.md#failure-and-recovery |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-468 Health, modules 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 six 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 modules operation serves, under factory.meta.read, the six fronted services with version and repository and the vector profile and the embedding profile versions its metadata port returns, states both as not reported when the port has no source, and calls no operation of VectorMemoryService; the port has no production binding; every routed call records connectsoft.factory.knowledge.host.requests and connectsoft.factory.knowledge.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.KnowledgeHost |
AIFACTORY-TASK-3317 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.knowledge.host.requests; the limit values are configuration of the deployment and none is fixed in code. | ConnectSoft.AI.SoftwareFactory.KnowledgeHost |
AIFACTORY-TASK-3318 Runbook of the three failure modes of the gateway |
documentation | The repository documentation holds one runbook entry per failure mode of model/services/knowledge/KnowledgeHost.yaml (identity platform unreachable, fronted service unavailable, gateway replica crash) 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 RepositoryIntelligenceService and MemoryPromotionService as not deployed before I5; the entry of the replica crash states that nothing is replayed and that callers retry with their idempotency key (NFR-18). | ConnectSoft.AI.SoftwareFactory.KnowledgeHost |
AIFACTORY-TASK-3319 Verify health, modules, limits and telemetry through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-KnowledgeHost-001\|Scenario=SCN-KnowledgeHost-002)"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-826 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 modules operation without a metadata source, with the fake metadata source and without its scope, a call above its limit, the two series connectsoft.factory.knowledge.host.requests and connectsoft.factory.knowledge.host.request_duration with service, route and status, the tenant of the call and the project of a project-scoped route, and a scan of the captured logs and activities for token and payload content. |
ConnectSoft.AI.SoftwareFactory.KnowledgeHost |