Skip to content

AIFACTORY-FEAT-178: Typed client libraries for the Factory gateways from the API library template

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 Engineering readiness · Increment I1 Generate a microservice · State elaborated · Route backend-developer · Build order 25 of 185 (Templates and libraries)

Every Factory service, the command-line client and the agent host call the control-plane, model and tool gateways; the Factory would otherwise hand-write those clients in each repository. The API library template (connectsoft-api-library) scaffolds a typed HTTP client library with the house conventions; once it carries the Factory's scope headers, workload-token acquisition and OpenAPI generation (FEAT-180), three client packages are generated from the gateways' OpenAPI documents, versioned with the contracts package and consumed by the CLI and the agent host switches. Component: API library template (extend).

Delivers —
Stubs —
Realizes components: cmp-api-library-template
adrs: ADR-0022, ADR-0028
Requirements —
Depends on AIFACTORY-FEAT-090 Contracts package from the published schemas
AIFACTORY-FEAT-180 API library template: OpenAPI generation, scope and propagation before the gateway clients
Sources model/components.yaml, model/templates.yaml

AIFACTORY-US-381: Gateway clients: typed libraries for the control plane, model, tool and template catalog gateways, three of them in two layouts, are generated from OpenAPI with the API library template

enabling · persona asset-maintainer As an asset maintainer, I want the clients of the four Factory gateways to be generated from the contracts of the gateways, so that no repository writes a gateway client by hand and none drifts from the contract.

The command-line client and, where an operation admits them, Factory services call the public REST surface of the control plane, model, tool and template catalog gateways. ADR-0028 decision 2 makes each gateway the one route to the services of its platform, decision 3 makes the model gateway and the tool gateway the only routes to ModelRouterService and ToolAdapterService, and ADR-0022 decision 2 sends every tool call through the governed executor. A client written by hand in each caller would repeat every contract and drift from it. This PBI generates them. The repository ConnectSoft.AI.SoftwareFactory.Clients holds seven libraries for the four gateways: two for ControlPlaneApi, one in the user-token layout and one in the workload layout (decision D117), two for ModelGatewayHost and two for ToolExecutorHost, each in the workload layout and in the user-token layout for StudioBff, which calls the model and the tool gateway with a user token of the audience of each (D141), and one for TemplateCatalogHost, the gateway of the Template and Library platform, which is delivered in I1 like the other gateways (decision D123). The gateways KnowledgeHost, GovernanceHost and IntegrationHost moved to I1 as well (decisions D125, D127 and D129); their three libraries are generated in the same repository, in the same way and in the user-token layout by AIFACTORY-US-1510, so the repository holds ten libraries for seven gateways. The library of the template catalog gateway is generated in the user-token layout, because the caller that reaches that gateway with a typed client is the command-line client, which calls the gateway and reaches no service host directly. The two libraries of each of the control plane, model and tool gateways are generated from the same OpenAPI document and differ only in the authentication layout of the template (D141). Each is generated with dotnet new connectsoft-api-library, with the generation switch, the document path and UseFactoryProfile that AIFACTORY-US-301 to AIFACTORY-US-304 of feature component-api-library-template-factory-clients deliver. The template is consumed by a pin on the package version that passed its gate; this feature changes nothing in the template, and a gap found while generating is recorded for the template feature and not patched in the generated output. What each package holds is named by the operations of the model. The control plane client, in both layouts, holds the public REST operations of the services the gateway fronts whose delivery increment in model/backlog/features is I1 or earlier: of ProjectService CreateProject, ListProjects, GetProject, SetMembership, Delegate, RevokeDelegation, SetSourceScope, CloseProject, SuspendProject and ResumeProject; of RunControlService SubmitRun, GetRun, ListRuns, CancelRun, DecideApproval and ListApprovals; of EnvironmentService CreateEnvironment, ListEnvironments, FreezeEnvironment and UnfreezeEnvironment; of CostUsageService GetProjectUsage, GetRunUsage and SetProjectBudget. The model gateway client holds the public REST operations of ModelRouterService: ListModelProfiles, GetModelProfile, ListModelDeployments, RegisterDeployment, EvaluateDeployment, ApproveDeployment, PreviewRoutePlan and ListRunReceipts. The tool gateway client holds those of ToolAdapterService: ListTools, GetTool, DryRunTool, ListRunToolReceipts, GetToolInvocation and ConfirmToolEffect. The template catalog gateway client holds the seventeen public REST operations of the three services its gateway fronts, all of increment I1: of BlueprintService ListBlueprints, GetBlueprintVersion, CreateBlueprintVersion, ValidateBlueprint and SubmitBlueprint; of GenerationRecipeService ListRecipes, GetRecipe, DraftRecipe, ValidateRecipe, ApproveRecipe and ListGeneratedOutputs; of TemplateRegistryService ListTemplates, GetTemplateVersion, ListLibraries, QueryCompatibility, DiscoverTemplates and PublishTemplateVersion. The project of a project-scoped operation travels where the operation declares it: in the path of ListGeneratedOutputs, in the required query parameter projectId of ListBlueprints and ListRecipes and in the required body member projectId of CreateBlueprintVersion and DraftRecipe (decision D123), so the generated request types carry it and no header names it. The internal gRPC methods of the three services, Catalog.ResolveManifest among them, are not in the package. The operations of a service or of a delivery of a later increment, such as AgentCardService, FactoryCommercialService or the release operations of the complete AgentRegistryService, enter with the package version of their increment. The libraries are typed HTTP clients of the public REST surface only. The calls by which an agent host invokes a model or a tool are not in them: ModelGateway.Invoke, Embed and Rerank of ModelRouterService and ToolExecutor.Invoke of ToolAdapterService are internal gRPC methods with server streaming, and a REST client generated from an OpenAPI document cannot implement the gateway transport port of the Factory model client (AIFACTORY-US-196). The UseFactoryModelRouter and UseFactoryToolAdapter switches of the agent host therefore do not pin these packages. Whether the invoke path stays with the transport of the Factory AI libraries, or the API library template gains gRPC client generation from the proto, which would be a gap of feature component-api-library-template-factory-clients, is open for the owner. The input of each library is an OpenAPI document. The APIs of the Factory are contract-first (docs/architecture/api-governance.md): the document is the source of truth and is reviewed before the implementation. No gateway publishes an OpenAPI document today, so the four documents are written contract-first in the client repository from an intake of the model and are the source of truth until a gateway publishes its own, which then takes the place of the document of the client repository as the input of its library (decision D117). The template catalog gateway publishes the document of its seventeen public REST operations as a build output of its repository (AIFACTORY-TASK-2856 of feature template-catalog-host), and from its first published version on that document is the input of the template catalog gateway client. The intake is built like the intake of the contracts package (AIFACTORY-TASK-1567): an intake file records the revision of this repository and the content hash of the operation list of the service files, and one documented command refreshes it from a checkout of this repository. A contract check compares each document with the intake and fails on an operation the model has and the document lacks, or on a differing method, path, scope or response code. Shared contract types are not generated a second time: a type the contracts package declares comes from the pinned contracts package, and an architecture test fails on a copy. Generated types are not committed; every build regenerates them, and a missing or unparsable document fails the build with the path and the parser message.

Acceptance criteria

AC1 Given the four OpenAPI documents and the pinned template package, when the seven libraries are generated and built, then each holds the client interface, the client, the request types and the response types generated from its document and registered by the dependency injection extension of the template: the two control plane clients, one in the user-token layout and one in the workload layout from the same document, for the operations of ProjectService, RunControlService, EnvironmentService and CostUsageService, the two model gateway clients, in the workload layout and in the user-token layout for StudioBff (D141), for ListModelProfiles to ListRunReceipts of ModelRouterService, the two tool gateway clients, in the same two layouts (D141), for ListTools to ConfirmToolEffect of ToolAdapterService, and the template catalog gateway client, in the user-token layout, for the seventeen public REST operations of BlueprintService, GenerationRecipeService and TemplateRegistryService, with projectId as a required query parameter of ListBlueprints and ListRecipes and as a required body member of CreateBlueprintVersion and DraftRecipe; no internal gRPC method is in a package, no generated type is under version control, and the generation manifest of each library records the template version and the parameter values (ADR-0028 decision 2; model/template-parameters/connectsoft-api-library.yaml).
AC2 Given the four documents and the intake of the model, when the contract check runs, then every public REST operation that a service file lists for a service the gateway fronts and whose delivery increment in model/backlog/features is I1 or earlier is in the document of that gateway with the same method, path, scope and response codes, a difference fails the check with the operation named, and the operations of a service of a later increment are absent until the package version of their increment (docs/architecture/api-governance.md; model/gateways.yaml names what each gateway fronts).
AC3 Given a contract type that the contracts package declares, such as the run submission of run-submission-v1, when a library is generated, then the type comes from the pinned contracts package, and an architecture test fails when one of the libraries declares a second type for a descriptor of that package (ADR-0028; model/descriptors.yaml).
AC4 Given a document path that does not exist or a document that does not parse, when a library builds, then the build fails with the path and the parser message named and no client of an earlier build is packed (ADR-0028 decision 2; docs/architecture/ecosystem-composition.md names OpenAPI generation as the need of this component).
Traces: descriptors run-submission-v1
Traces: adrs ADR-0022, ADR-0028
Depends on feature:component-api-library-template-factory-clients, feature:contracts-package
Sources model/components.yaml, model/templates.yaml, model/gateways.yaml, model/template-parameters/connectsoft-api-library.yaml, docs/architecture/api-governance.md, docs/architecture/ecosystem-composition.md, model/services/model-compute/ModelRouterService.yaml, model/services/tools-mcp/ToolAdapterService.yaml, model/services/control-plane/ControlPlaneApi.yaml, model/services/template-library/TemplateCatalogHost.yaml

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-640 Client packages for the control-plane, model, tool and template catalog gateways implementation Seven client libraries in the repository ConnectSoft.AI.SoftwareFactory.Clients, the control plane client, the model gateway client and the tool gateway client each in the user-token layout and in the workload layout, the user-token layout of the model and tool gateway clients for StudioBff (D141), and the template catalog gateway client in the user-token layout, generated with dotnet new connectsoft-api-library with the generation switch and UseFactoryProfile from the OpenAPI documents of the control plane, model, tool and template catalog gateways, each holding the public REST operations of the services of increment I1 or earlier that its gateway fronts, versioned with the contracts package they pin and published to the feed, so that the command-line client pins the control plane client of the user-token layout in place of its hand-written adapter (AIFACTORY-TASK-2111 of feature command-line-client-commands); the invoke path of the agent host is not served by these packages. ConnectSoft.AI.SoftwareFactory.Clients
AIFACTORY-TASK-1556 OpenAPI documents of the four gateways with their hashes and the comparison with the model contract The client repository holds one OpenAPI document per gateway with its content hash, written contract-first from an intake of the model and the source of truth until a gateway publishes its own; the intake is built like the intake of AIFACTORY-TASK-1567 (an intake file with the source revision of this repository and the content hash of the operation list, one documented refresh command, a pipeline stage that fails when the refreshed hash differs); each document describes the public REST operations of the services of increment I1 or earlier that model/gateways.yaml and the gateway file let the gateway front, with the schemas of the descriptors from the pinned contracts package; a contract check fails on a missing operation or on a differing method, path, scope or response code, with the operation named, and lists per package the operations whose scope is an svc. scope. ConnectSoft.AI.SoftwareFactory.Clients
AIFACTORY-TASK-1557 Verify the generated libraries, the contract check and the single definition of shared types verification Run dotnet build -c Release and dotnet test -c Release --no-build on the client solution; the seven libraries build from the four documents, the contract check against the model passes and fails on a planted differing scope, the architecture test finds no copy of a type of the contracts package, and a planted unparsable document fails the build, which proves AC1 to AC4 of AIFACTORY-US-381 (ADR-0028). ConnectSoft.AI.SoftwareFactory.Clients

AIFACTORY-US-382: Gateway clients: each package is registered for its caller, a user token goes only to the gateway that is its one audience, and no public REST operation admits a workload token today

enabling · persona asset-maintainer As an asset maintainer, I want each gateway client to send the token its caller is allowed to send and the scope the call runs under, so that a token never reaches a gateway it was not issued for and a call never leaves without a scope.

The amendments of ADR-0015 (decision D114) settle which token a caller sends. A user token has one audience, the gateway that fronts its scopes, so a client that calls two gateways requests two tokens. A workload token carries service scopes, no audience of a user API and no tenant claim, and a gateway or service reads the tenant and project a workload forwards only when the token holds the service scope that names it. The template delivers the mechanics for both under AIFACTORY-US-302 of feature component-api-library-template-factory-clients: one delegating handler that is the single writer of the scope headers and obtains a workload token by client credentials, the refusal of a call without a scope, the distinct typed errors for 404 and 403 with the single refresh on 401, and a JWT bearer choice for a caller that already holds a user token. Those behaviours are proven on the generated library of the template and are not proven a second time here; this PBI writes no handler and patches no generated output. It states the caller of each package and proves only what differs per package. Three points do. First, the callers. The command-line client holds a user token and calls the control plane client; a Factory service calls a gateway as a workload. In the template AuthenticationType is one choice per generated library, so one package with both layouts is not what the template generates. Decision D117 settles how the two callers of the control plane are served: the control plane client is generated as two libraries from the same document, one in the JWT bearer layout for a caller that holds a user token and one in the workload layout, which makes four packages with the model and tool gateway clients of the workload layout. The model and tool gateway clients are generated in the JWT bearer layout as well, for StudioBff, which calls the model and the tool gateway with a user token exchanged for the audience of each gateway (D141), which makes six. The template catalog gateway client, added by decision D123, is the seventh; it is generated in the JWT bearer layout only, because the caller that reaches the template catalog gateway with a typed client is the command-line client, which holds a user token. The command-line client is the consumer of the user-token layout of the control plane client; the workload layout is generated, registered and published beside it and has no consumer among the modelled routes today, as the third point states. Second, the user-token layout has no scope accessor behind it, because the command-line client has none. The rule proposed here is that in this layout the client sends no tenant header, the project travels in the route, and a missing scope in the accessor does not refuse the call; the gateway takes the tenant from the token and overwrites a tenant header in any case (ADR-0015 decision 2). The owner may choose another rule, and the criterion follows it; if the scope handler of the Factory profile refuses such a call in the generated library, that is recorded as a gap for the template feature and not patched. The user token is attached only to requests to the base address of the control plane gateway and is never handed to the model or the tool gateway client. The model gateway and the tool gateway are two more audiences of a user token: StudioBff requests one token for each, and the user-token layout of each client attaches it only to requests to the base address of its own gateway (D141). The template catalog gateway is a second audience: a user token has one audience, so the command-line client requests a second token for that gateway, and the template catalog gateway client attaches it only to requests to the base address of the template catalog gateway; neither client is given the token of the other. The project of a call through the template catalog gateway client travels where the operation declares it, in the path, in the required query parameter projectId or in the required body member projectId (decision D123). Third, the workload layout. Every public REST operation of the model names a factory. scope and none names an svc. scope, and a gateway admits a workload token only on a route whose operation names an svc. scope the token holds (AIFACTORY-US-237). No public REST operation therefore admits a workload token today, which decision D117 records as the state of the model and not as a question. The contract check lists per package the operations whose scope is an svc. scope; the list is empty today and grows only with a change of the model. No test of this PBI asserts that a modelled route admits a workload token: the workload layout of the control plane client and the model and tool gateway clients are proven against the stubs, on the token they request and on the headers they write. No token and no header value is written to a log.

Acceptance criteria

AC1 Given the registrations of the packages, when they are read against the generated output of the pinned template, then every handler, header name and claim name comes from the template and from the pinned ConnectSoft.Extensions.AI.Factory.Abstractions, no package declares one of its own, the options are validated at start, and the workload token, the refusal without a scope and the typed errors are referred to AC1, AC2 and AC3 of AIFACTORY-US-302 and are not tested a second time (ADR-0015 amendment on the workload token; descriptor execution-scope-v1; model/backlog/pbis/component-extensions/component-api-library-template-factory-clients.yaml).
AC2 Given the control plane client in the user-token layout, the layout of the command-line client, when it is called and the gateway stub redirects to a second host, then the user token is attached only to requests to the base address of the control plane gateway, the second host receives none, and the model and tool gateway clients are never given that token; given the model or the tool gateway client in the user-token layout and the user token issued for its gateway, when StudioBff calls it, then that token is attached only to requests to the base address of that gateway (D141); given the template catalog gateway client and the user token issued for the template catalog gateway, when it is called, then that token is attached only to requests to the base address of that gateway, and the token issued for the control plane gateway is never attached to them (ADR-0015 amendment on the one audience of a user token).
AC3 Given the control plane client in the user-token layout and no scope in the accessor, when it is called, then it sends no tenant header, the project travels in the route, and the call is not refused for the missing scope, because the gateway takes the tenant from the token (ADR-0015 decision 2, descriptor execution-scope-v1); this is the proposed rule, and the criterion follows the rule the owner chooses if it differs.
AC4 Given the contract check of the client repository, when it lists per package the operations whose scope in the model is an svc. scope, then the list is what the model states, which is empty today because every public REST operation names a factory. scope, so no public REST operation admits a workload token today; the control plane client in the workload layout is generated and registered beside the user-token layout from the same document, and no test asserts that a modelled route admits a workload token (ADR-0015 amendment on the workload token; ADR-0022 decision 2; model/gateways.yaml).
Traces: descriptors execution-scope-v1
Traces: adrs ADR-0015, ADR-0022, ADR-0028
Depends on AIFACTORY-US-381, feature:component-api-library-template-factory-clients, feature:component-extensions-ai, feature:component-auth-server-template-factory-tokens
Sources docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md, docs/architecture/adr/0022-mcp-as-tool-protocol.md, model/components.yaml, model/gateways.yaml

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-1558 Token and scope registration of the seven client packages implementation The registrations of the packages: the control plane client is generated as two libraries from the same document, one in the JWT bearer layout of the template for the command-line client, which holds a user token, and one in the workload layout with the workload token of the Factory profile; the template catalog gateway client is generated in the JWT bearer layout of the template for the same caller, with the template catalog gateway as the one audience of its token; the model and tool gateway clients are generated with the workload token of the Factory profile and the svc. scopes of their registration, and a second time in the JWT bearer layout of the template for StudioBff, with their own gateway as the one audience of its token (D141); no library writes a handler, a header name or a claim name of its own, the generated output is not patched, a difference between the generated library and the rule of AC3 is recorded as a gap for feature component-api-library-template-factory-clients, and the options are validated at start. ConnectSoft.AI.SoftwareFactory.Clients
AIFACTORY-TASK-1559 Stubs of the four gateways and of the token endpoint fixture A fixture of the client solution with a stub server per gateway that answers from its OpenAPI document and can answer 401, 403, 404 and a redirect to a second host, and a stub of the token endpoint of the authorization server that records the requested scopes and parameters of each token request. ConnectSoft.AI.SoftwareFactory.Clients
AIFACTORY-TASK-1560 Verify the token of each caller, the refusal without a scope and the typed errors verification Run dotnet test -c Release --no-build on the client solution; the comparison of the registrations with the generated output, the user token of the control plane client with the redirect, the token of the template catalog gateway client and the user tokens of the model and tool gateway clients of the user-token layout each attached to its own gateway only (D141), the user-token call without a scope and without a tenant header, the list of operations with an svc. scope and the search of the log for a token value pass and prove AC1 to AC4 of AIFACTORY-US-382 (ADR-0015, ADR-0022). ConnectSoft.AI.SoftwareFactory.Clients

AIFACTORY-US-383: Gateway clients: the seven client packages are published to the ConnectSoft feed with versions tied to the contracts package, and a probe consumer calls a stub of each gateway from the feed alone

evidence · persona asset-maintainer As an asset maintainer, I want proof that the five client packages are on the ConnectSoft feed with versions a consumer can pin, so that the command-line client restores the control plane client from the feed and can drop its hand-written adapter.

This PBI is the publication proof of the feature. The pipeline of the repository ConnectSoft.AI.SoftwareFactory.Clients generates the seven libraries, builds them, runs their tests against the stubs, packs them and publishes them to the ConnectSoft feed, the Azure Artifacts feed the ConnectSoft libraries already publish to. It is the pipeline the template generates and it runs unchanged: the repository adds only the probe stage, the intake stage and, in its test project, the version tie test, and a gap of the generated pipeline is reported to the template feature and not patched. A publication is reached only after the tests pass, and a version that is already on the feed is refused with the reason. The packages are versioned with the contracts package: each package records the version of the contracts package it pins and the hash of the OpenAPI document it was generated from, and a test fails when the pinned contracts version or the document changed while the package version did not. A probe then proves the result from the side of a consumer. A clean console host with the ConnectSoft feed as its only source and no project reference restores the seven published versions, registers each client in the mode without inbound requests that the template offers for such a host, and calls a stub of each gateway; the stubs assert the token and the headers of the layout of the package: the workload token with the tenant header and the project header for the model and tool gateway clients and for the control plane client of the workload layout, the user token without a tenant header for the control plane, model and tool gateway clients of the user-token layout (D141) and for the template catalog gateway client. The published versions are recorded on the Runbook page of the client repository, which is where a consumer reads its pins. The one consumer named today is the command-line client, which pins the control plane client of the user-token layout in place of its hand-written adapter. The template catalog gateway client is published for the same caller: by decision D123 the command-line client calls the template catalog gateway and reaches no service host directly, and the commands that call it, recipe show and recipe approve of AIFACTORY-US-1507 of feature command-line-client-commands, are work of ConnectSoft.AI.SoftwareFactory.Cli and no part of this feature. The change of the adapter is AIFACTORY-TASK-2111 of AIFACTORY-US-376 in the feature command-line-client-commands of increment I1 (decision D117); it is a task in ConnectSoft.AI.SoftwareFactory.Cli, and this template and library feature does not hold it. The UseFactoryModelRouter and UseFactoryToolAdapter switches of the agent host are not consumers of these packages while the question of the invoke path is open. This PBI ends with the packages on the feed, the probe green and the versions recorded. A run with a planted change of a document under an unchanged version proves that such a package is not published.

Acceptance criteria

AC1 Given the pipeline of the client repository, when it runs after the work of the feature, then the seven packages are generated, built, tested, packed and pushed to the ConnectSoft feed with versions that were not on the feed, each package records the version of the contracts package it pins and the hash of its OpenAPI document, and the versions are recorded on the Runbook page of the repository (ADR-0028 amendment on the Factory profile switch names the feed; model/components.yaml).
AC2 Given a clean console host with the ConnectSoft feed as its only package source and no project reference, when it restores the seven published versions, registers each client and calls a stub of each gateway, then each call succeeds and the stub asserts the token and the headers of the layout of the package: the workload token with the tenant header and the project header for the model and tool gateway clients and for the control plane client of the workload layout, the user token without a tenant header for the control plane, model and tool gateway clients of the user-token layout (D141) and for the template catalog gateway client (ADR-0015 decision 2, ADR-0022 decision 2).
AC3 Given an OpenAPI document or a pinned contracts package version that changed while the package version did not, or a version that is already on the feed, when the pipeline reaches the publication stage, then the stage is refused with the reason and nothing is pushed; a run with a planted changed document proves the refusal (ADR-0028 decision 2).
Traces: adrs ADR-0015, ADR-0022, ADR-0028
Depends on AIFACTORY-US-381, AIFACTORY-US-382, feature:contracts-package
Sources model/components.yaml, model/templates.yaml, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md, docs/architecture/ecosystem-composition.md

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-1561 First publishing run of the generated pipeline of the client repository operations The pipeline generated by the template runs unchanged: one green run publishes the seven packages to the ConnectSoft feed after the tests of the solution pass, and one run with a repeated version is refused with the reason; the repository adds only the probe stage of AIFACTORY-TASK-1562, the intake stage and, in its test project, the version tie test that fails when the pinned contracts package version or the hash of an OpenAPI document changed under an unchanged package version; a gap in the generated pipeline is reported to feature component-api-library-template-factory-clients and not patched. ConnectSoft.AI.SoftwareFactory.Clients
AIFACTORY-TASK-1562 Feed probe consumer for the seven client packages fixture A probe console host with the ConnectSoft feed as its only source and no project reference restores the seven published versions, registers each client in the mode without inbound requests, and calls a stub of each gateway; the stubs assert the workload token, the tenant header and the project header for the model and tool gateway clients and for the control plane client of the workload layout, and the user token without a tenant header for the control plane, model and tool gateway clients of the user-token layout (D141) and for the template catalog gateway client; the probe runs as the last stage of the pipeline. ConnectSoft.AI.SoftwareFactory.Clients
AIFACTORY-TASK-1563 Published versions of the client packages recorded on the Runbook page documentation The Runbook page of the client repository names, per package, the published version, the version of the contracts package it pins, the hash of its OpenAPI document and the consumer that pins it: the command-line client for the control plane client of the user-token layout; the template catalog gateway client names the command-line client as its caller (decision D123), whose commands recipe show and recipe approve pin it (AIFACTORY-US-1507 of feature command-line-client-commands); the control plane client of the workload layout names no consumer while no public REST operation admits a workload token; the model and tool gateway clients of the workload layout name no consumer while the question of the invoke path of the agent host is open, and those of the user-token layout name StudioBff as their caller (D141); the typed clients of the later gateways, AIFACTORY-TASK-6601 (DeliveryHost), AIFACTORY-TASK-6602 (RuntimeCloudHost), AIFACTORY-TASK-6603 (ObservabilityHost) and AIFACTORY-TASK-6604 (DataEventFoundations), are held by their gateway features and recorded on the same page with the package version of their increment (D140); the documentation site of the repository builds without warnings. ConnectSoft.AI.SoftwareFactory.Clients
AIFACTORY-TASK-1564 Verify the published packages by the probe and by a planted failing run verification One run of the pipeline publishes the seven packages and the probe passes; one run with a planted changed OpenAPI document under an unchanged version stops before publication and pushes nothing; both runs prove AC1 to AC3 of AIFACTORY-US-383 (ADR-0028). ConnectSoft.AI.SoftwareFactory.Clients

AIFACTORY-US-119: Typed client libraries for the Factory gateways from the API library template is delivered and proven by its consumers

enabling · persona asset-maintainer As an asset maintainer, I want typed client libraries for the Factory gateways from the API library template, so that it serves typed client libraries for the control-plane, model, tool, template catalog, knowledge, governance and integration gateways; consumed by the command-line client without later rework.

This is the integration PBI of the feature. An asset maintainer takes the contracts of the seven Factory gateways of I1 to ten published client packages, the control plane client in a user-token layout and in a workload layout and the client of the template catalog gateway, which decision D123 delivers in I1, among them: the libraries generated from the OpenAPI documents of the gateways with the API library template and checked against the model (AIFACTORY-US-381), the token and scope rules of each caller (AIFACTORY-US-382), the publication to the ConnectSoft feed with a probe consumer (AIFACTORY-US-383), and the clients of the knowledge, governance and integration gateways, which decisions D125, D127 and D129 move to I1 (AIFACTORY-US-1510). The implementation lives in those PBIs; this one proves them together from the side of the consumers. The clients are generated and not written: the template with its OpenAPI generation, its Factory profile and its gate is delivered by AIFACTORY-US-301 to AIFACTORY-US-304 of feature component-api-library-template-factory-clients and is consumed by a pin, and the shared contract types come from the pinned contracts package. The rules the packages carry are the decided ones: a user token has one audience, the gateway that fronts its scopes; a workload token carries service scopes, no audience of a user API and no tenant claim; a resource of another tenant is answered 404 and a missing scope inside the tenant 403, and the two surface as distinct errors. The feature is done when the eight packages are on the feed with recorded versions tied to the contracts package and a consumer that has only the feed calls a stub of each gateway through its client, so that the command-line client can pin the control plane client of the user-token layout in place of its hand-written adapter. The task that makes that change in ConnectSoft.AI.SoftwareFactory.Cli is AIFACTORY-TASK-2111 of AIFACTORY-US-376 in the feature command-line-client-commands of increment I1 (decision D117); it is Factory code and no part of this feature. The agent host switches are no consumer of these packages: the calls that invoke a model or a tool are internal gRPC methods with server streaming, and whether they stay with the transport of the Factory AI libraries or the template gains gRPC client generation is open for the owner. No public REST operation admits a workload token today, so the workload layouts are proven against the stubs and on no modelled route. Repository of the feature: ConnectSoft.AI.SoftwareFactory.Clients.

Acceptance criteria

AC1 Given the library repository ConnectSoft.AI.SoftwareFactory.Clients, when its pipeline runs, then the ten packages build, the three of AIFACTORY-US-1510 among them, their tests pass and they publish to the ConnectSoft feed with verified versions that the consuming repositories pin (ADR-0028; model/components.yaml).
AC2 Given the work of AIFACTORY-TASK-640 (client packages for the control-plane, model, tool and template catalog gateways) is done, then seven client packages generated with dotnet new connectsoft-api-library from the OpenAPI documents of the gateways, the control plane client in the user-token layout and in the workload layout and the template catalog gateway client among them, are versioned with the contracts package and published to the feed, and the package of the user-token layout is the one the command-line client pins in place of its hand-written adapter by AIFACTORY-TASK-2111 of the feature command-line-client-commands of increment I1, which is no part of this feature (ADR-0022 decision 2, ADR-0028 decision 3).
AC3 Given a consumer that restores the published packages from the feed alone, when a workload calls the stub of the model or the tool gateway through its client and a caller with a user token calls the stub of the control plane gateway through the control plane client and the stub of the template catalog gateway through its client with the token issued for that gateway, then the workload sends a token with service scopes and no tenant claim together with the scope headers, each user token reaches only the gateway it was issued for, and a 404 for a resource of another tenant and a 403 for a missing scope are distinct errors (ADR-0015 amendments on the audience, the workload token and a resource of another tenant).
Traces: adrs ADR-0015, ADR-0022, ADR-0028
Depends on AIFACTORY-US-381, AIFACTORY-US-382, AIFACTORY-US-383, AIFACTORY-US-1510, feature:component-api-library-template-factory-clients, feature:contracts-package
Sources model/components.yaml, model/templates.yaml, docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md, docs/architecture/ecosystem-composition.md

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-1565 Call each gateway stub from a web host and from a console host that pin the published packages verification A consumer test project restores the eight published packages from the ConnectSoft feed and calls the stub of each gateway from a web host with an inbound request and from a console host without one: the model and tool gateway clients and the control plane client of the workload layout as a workload, the control plane client of the user-token layout, the template catalog gateway client and the knowledge, governance and integration gateway clients as a caller with a user token, each with the token issued for its own gateway; every call carries the token and the headers of its layout, which proves AC3 of AIFACTORY-US-119 and the published half of AC2; the consumer change of the command-line client is not part of this task. ConnectSoft.AI.SoftwareFactory.Clients
AIFACTORY-TASK-719 Verify typed-gateway-clients-delivered by running the declared command verification Run dotnet build -c Release and dotnet test -c Release --no-build; they pass and prove AC1 to AC3 of AIFACTORY-US-119. ConnectSoft.AI.SoftwareFactory.Clients

AIFACTORY-US-1510: Gateway clients: the knowledge, governance and integration gateways of I1 get typed libraries in the user-token layout, generated, checked, registered and published like the other seven

enabling · persona asset-maintainer As an asset maintainer, I want typed clients for the knowledge, governance and integration gateways from their contracts, so that the command-line client reads artifacts, audit records and policies and registers connections through those gateways without a hand-written adapter.

Decisions D125, D127 and D129 move the gateways KnowledgeHost, GovernanceHost and IntegrationHost from I3 to I1, like the template catalog gateway, so a person reaches the artifact, governance and integration routes of the first outcome through them and through no service host. Their clients are added to the repository ConnectSoft.AI.SoftwareFactory.Clients by the rules of AIFACTORY-US-381 to AIFACTORY-US-383, which this PBI applies and does not repeat: generated with dotnet new connectsoft-api-library and UseFactoryProfile from one OpenAPI document per gateway, written contract-first from the intake of the model until the gateway publishes its own, checked against the model by the contract check, with the shared types from the pinned contracts package. Each of the three is generated in the user-token layout, because the caller that reaches these gateways with a typed client is the command-line client, which holds a user token, and each gateway is one more audience: the client requests one token per gateway and each library attaches its token only to requests to the base address of its own gateway. What each package holds is named by the public REST operations of the services the gateway fronts whose delivery increment is I1 or earlier. The knowledge gateway client holds the five artifact routes of ArtifactService, GetArtifact, PreviewArtifact, ListArtifactVersions, ListRunArtifacts and ExportArtifacts; the other knowledge routes enter with the complete services of I5. The governance gateway client holds the routes of the three services of I1: of PolicyEngineService ListPolicyBundles, GetPolicyBundle, ValidateProjectPolicy, SimulatePolicy and ListRunDecisions; of SecretBrokerService ListSecretReferences, RegisterSecretReference, RotateSecret, RevokeSecretReference and ListRunIssuances; of AuditService SearchAudit, ExportAudit, ListClassifications, SetClassification, ListFindings and ResolveFinding. ApprovalPolicyService arrives in I4, so ListApprovalRules, ValidateProjectApprovalRules and GetApprovalRouting enter with the package version of I4. The integration gateway client holds the routes of the two thin services of I1: of ConnectorRegistryService ListConnectors, CertifyConnector, CreateSubscription, ListDeliveries and ReplayDelivery; of IntegrationService RegisterConnection, ListConnections, VerifyConnection, SetGrant, RotateCredential and RevokeConnection; a route whose operation the thin service does not host returns the answer of that service, and the client surfaces it as a typed error. The caller named today is the command-line client: the audit commands of AIFACTORY-TASK-309 call the governance gateway with the token of its audience. The commands are work of ConnectSoft.AI.SoftwareFactory.Cli and no part of this feature. The gateways of later increments get their typed clients in the user-token layout by the same rules, each in a task held by its own gateway feature and not by this I1 feature (D140): AIFACTORY-TASK-6601 for DeliveryHost (feature delivery-host, I2), AIFACTORY-TASK-6602 for RuntimeCloudHost (feature runtime-cloud-host, I2), AIFACTORY-TASK-6603 for ObservabilityHost (feature observability-host, I3) and AIFACTORY-TASK-6604 for DataEventFoundations (feature data-event-foundations, I4). The published versions are recorded on the Runbook page beside the seven others.

Acceptance criteria

AC1 Given the OpenAPI documents of the knowledge, governance and integration gateways and the pinned template package, when the three libraries are generated and built in the user-token layout, then the knowledge gateway client holds the five artifact routes of ArtifactService, the governance gateway client the sixteen routes of PolicyEngineService, SecretBrokerService and AuditService and none of ApprovalPolicyService, and the integration gateway client the eleven routes of ConnectorRegistryService and IntegrationService, and no internal gRPC method and no generated type under version control is in a package (model/services/knowledge/KnowledgeHost.yaml, model/services/governance/GovernanceHost.yaml, model/services/integration/IntegrationHost.yaml).
AC2 Given the three documents and the intake of the model, when the contract check runs, then every public REST operation of a service the gateway fronts whose delivery increment is I1 or earlier is in the document with the same method, path, scope and response codes, and the operations of ApprovalPolicyService of I4 and of the complete knowledge services of I5 are absent until the package version of their increment (model/gateways.yaml, docs/architecture/api-governance.md).
AC3 Given each of the three clients and the user token issued for its gateway, when it is called against the stub of its gateway that redirects to a second host, then that token is attached only to requests to the base address of its gateway, the tokens of the other gateways are never attached, a 404 for a resource of another tenant and a 403 for a missing scope are distinct errors, and no token is written to a log (ADR-0015 amendment on the one audience of a user token).
AC4 Given the pipeline of the client repository, when it publishes, then the three packages are on the ConnectSoft feed with versions tied to the contracts package, the probe consumer restores them from the feed alone and calls the stub of each gateway with the user token of that gateway and without a tenant header, and the Runbook page names their versions and the command-line client as their caller (ADR-0028, model/components.yaml).
Traces: adrs ADR-0015, ADR-0028
Depends on AIFACTORY-US-381, AIFACTORY-US-382, AIFACTORY-US-383, feature:component-api-library-template-factory-clients, feature:contracts-package
Sources model/gateways.yaml, model/services/knowledge/KnowledgeHost.yaml, model/services/governance/GovernanceHost.yaml, model/services/integration/IntegrationHost.yaml, docs/architecture/api-governance.md

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-6129 OpenAPI documents of the knowledge, governance and integration gateways with their hashes and the contract check contract The client repository holds one OpenAPI document per gateway for KnowledgeHost, GovernanceHost and IntegrationHost with its content hash, written contract-first from the intake of the model and the source of truth until the gateway publishes its own; each describes the public REST operations of the services of I1 or earlier that the gateway fronts, and the contract check of AIFACTORY-TASK-1556 covers the three documents. ConnectSoft.AI.SoftwareFactory.Clients
AIFACTORY-TASK-6130 Client libraries of the knowledge, governance and integration gateways in the user-token layout implementation Three client libraries generated with dotnet new connectsoft-api-library, the generation switch and UseFactoryProfile from the three documents in the JWT bearer layout of the template, each registered with the base address of its gateway and the token of that gateway as its one audience, without a handler, header name or claim name of its own, versioned with the contracts package and published through the generated pipeline of the repository. ConnectSoft.AI.SoftwareFactory.Clients
AIFACTORY-TASK-6131 Stubs of the three gateways and the probe stage for their packages fixture The fixture of the client solution gains a stub server for each of the three gateways that answers from its document and can answer 401, 403, 404 and a redirect to a second host, and the probe consumer restores the three published packages from the feed alone and calls each stub with the user token of its gateway. ConnectSoft.AI.SoftwareFactory.Clients
AIFACTORY-TASK-6132 Verify the three gateway clients by the solution tests and the probe verification Run dotnet build -c Release and dotnet test -c Release --no-build on the client solution and one publishing run of the pipeline; the three libraries build from their documents, the contract check passes and fails on a planted differing scope, each token reaches only its own gateway, and the probe stage is green, which proves AC1 to AC4 of AIFACTORY-US-1510. ConnectSoft.AI.SoftwareFactory.Clients