Skip to content

AIFACTORY-FEAT-015: ModelRouterService: complete 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 Model & Compute Platform (PF-03) · Increment I1 Generate a microservice · State elaborated · Route backend-developer · Build order 60 of 185 (Factory code)

ModelRouterService is the service of bounded context BC-07 (Model Access). The model gateway pipeline — resolves a pinned model profile into a route plan from capability evidence, privacy class, policy, region, cost and availability; invokes the provider adapter with streaming, structured outputs and tool calls; and records an invocation receipt with the actual deployment and the usage status (BC-07). Its own repository is ConnectSoft.AI.SoftwareFactory.ModelRouterService.

Delivers ModelRouterService (complete)
Stubs —
Realizes adrs: ADR-0002, ADR-0013, ADR-0014, ADR-0021
Requirements FR-04, FR-09, FUX-08, FUX-10, NFR-03, NFR-07, NFR-11, NFR-12, NFR-13, XL-04, XL-08, XL-12, XL-16
Depends on —
Sources model/services/model-compute/ModelRouterService.yaml

Scenarios to trace (21, catalog): SCN-ModelRouterService-001 ✓, SCN-ModelRouterService-002 ✓, SCN-ModelRouterService-003 ✓, SCN-ModelRouterService-004 ✓, SCN-ModelRouterService-005 ✓, SCN-ModelRouterService-006 ✓, SCN-ModelRouterService-020 ✓, SCN-ModelRouterService-007 ✓, SCN-ModelRouterService-008 ✓, SCN-ModelRouterService-021 ✓, SCN-ModelRouterService-009 ✓, SCN-ModelRouterService-010 ✓, SCN-ModelRouterService-011 ✓, SCN-ModelRouterService-012 ✓, SCN-ModelRouterService-013 ✓, SCN-ModelRouterService-014 ✓, SCN-ModelRouterService-015 ✓, SCN-ModelRouterService-016 ✓, SCN-ModelRouterService-017 ✓, SCN-ModelRouterService-018 ✓, SCN-ModelRouterService-019 ✓

AIFACTORY-US-058: ModelRouterService serves its scope end to end: a pinned profile becomes a route plan, a provider call and a receipt

behavior · persona platform-admin As a platform admin, I want one service that resolves a model profile to an approved deployment, calls the provider and records what was used, so that the Model Access context has one owner that the rest of the Factory calls through its contract and no other service holds a provider credential.

This is the integration PBI of the feature: it proves on a deployed instance that the behaviours of ModelRouterService work together along one model call of a run, as the first outcome demands. ModelRouterService is the model gateway pipeline of bounded context BC-07 and the only service that calls model providers; ModelGatewayHost is the only route to it (ADR-0028 decision 3). The chain it proves is this. The profile releases of the first outcome are loaded from AgentRegistryService by alias, their definitions are fetched from ArtifactService and the profile versions are active (AIFACTORY-US-569). A Platform admin registers a deployment as Candidate (AIFACTORY-US-570), capability evidence moves it to Evaluated (AIFACTORY-US-571), and the Platform admin approves it after the license and evidence checks, while the health probe keeps it Approved or Degraded (AIFACTORY-US-572). Where no capability suite runs, a Platform admin approves a Candidate or an Evaluated deployment by attestation with a required reason, and that is how the first Approved deployment of a deployed instance comes into being (AIFACTORY-US-757, decisions D121 and D123). AgentRuntimeService resolves the route plan of a run and profile once (AIFACTORY-US-573) and invokes the model through the Factory model client of the AI libraries and the gateway; the router asks PolicyEngineService for the decision, takes a short-lived credential from SecretBrokerService, calls the provider adapter with streaming and writes the receipt, with the deployment that answered and the usage status, together with ModelInvoked in one transaction (AIFACTORY-US-574). A user of an in-tenant client reaches the same pipeline through the OpenAI-compatible route of ModelGatewayHost, which calls ModelGateway.Invoke with the forwarded token of the caller, as a run-bound call under the token of an attempt that counts on the reservation of its run or as a call outside a run under a user token that is metered on the budget of its project without a reservation (AIFACTORY-US-574, decisions D121, D123 and D125). The router applies a fallback only where the profile allows it (AIFACTORY-US-575), serves embeddings and reranking the same way (AIFACTORY-US-576) and lets a caller read the receipts of the run (AIFACTORY-US-577) and the receipts of a project that name no run (AIFACTORY-US-901). CostUsageService records the input tokens and the output tokens of each receipt on its two meters and stores a receipt without a valid price or with an unknown quantity as Uncertain, so the router never keeps and repeats a receipt for a missing price (D117). The repository, the aggregates and the store are delivered by AIFACTORY-US-566, the hosted surface by AIFACTORY-US-567 and secrets, tenancy and telemetry by AIFACTORY-US-568. Throughout, a resource of another tenant is answered 404, over gRPC NOT_FOUND, a missing scope or role inside the tenant 403, and prompt and completion content is never stored in model-router-sql, logged or put on an activity. The delivery states its limits, and those the owner has not decided are reported. QualityScoreService is delivered thin in this increment and runs no capability suite, so on a deployed instance capability evidence arrives only once a service publishes EvaluationCompleted of the kind capability-suite; the acceptance environment publishes it by fixture, and until a suite runs a deployment of a deployed instance is approved by attestation (AIFACTORY-US-757). The thin AgentRegistryService publishes no release event, so profiles are loaded by alias and the handlers of the release events are proven by fixture. ComputePoolService arrives in I8: no placement is asked for and the handlers of its three events are not registered. RetentionResidencyService arrives in I4: the handlers of ResidencyRuleChanged and DeletionOrderIssued are not built here. No PBI of the backlog builds the handlers ApplyResidencyRule and UpdateDeploymentAvailability yet. The handler ApplyClassification of ClassificationChanged is registered with the least effect the model words (AIFACTORY-US-567). No source of provider statements is modelled, so the reconciler confirms nothing on a deployed instance. The thin AgentRegistryService seeds all eleven model profiles of model/model-profiles.yaml as Draft releases that are loadable by alias (decision D123), and the Draft allowance covers ModelProfile releases until the complete registry arrives in I4 (decision D121), so the chain of this PBI starts on a deployed instance from the seeded releases (AIFACTORY-US-569). ModelGateway.Embed and ModelGateway.Rerank stay in I1 behind ports and are proven with fixtures (decision D121): the rerank adapter is a port of the service until the AI library publishes the keyed rerank adapter abstraction of feature component-extensions-ai, so ModelGateway.Rerank has no provider behind it on a deployed instance of this increment (AIFACTORY-US-576). The scripted provider of the acceptance environment has no provider value of its own: the acceptance configuration binds it in place of the adapter of one of the six modelled provider values (AIFACTORY-TASK-2297), and the deployment of the chain is registered with that value. This PBI proves the one chain and its tenancy and content rules; every other scenario of the service is proven by the suite of the PBI that traces it and is not repeated here, and the scaffold and its pipeline are accepted by AIFACTORY-US-566. Decision D125 adds two rules to the path of the OpenAI-compatible route, both delivered by their own PBIs: a run-bound call presents the token of an attempt and takes its project, classification and profile version from the route plan of its run (AIFACTORY-US-574), and the calls outside a run of a project whose budget CostUsageService announced as exceeded are refused while the router keeps a budget mark for it (AIFACTORY-US-1508).

Acceptance criteria

AC1 Given a deployed instance behind ModelGatewayHost with an active profile and an Approved deployment whose provider value is the one the acceptance environment binds the scripted adapter to, when a workload resolves the route plan of a run through ModelRouterService/ModelGateway.ResolveRoutePlan and calls ModelRouterService/ModelGateway.Invoke, then the stream ends with a receipt that names the profile, the deployment that answered, the policy decision and the usage status, ModelRouterService/ModelInvoked is published once for the receipt, and ModelRouterService/ListRunReceipts returns that receipt for the run (ADR-0014, FR-04).
AC2 Given the receipt of AC1 with reported usage and a second call whose provider reports none, when CostUsageService has handled ModelRouterService/ModelInvoked for both, then the first receipt appears as one usage record on each of the meters ModelInputTokens and ModelOutputTokens and the second as Uncertain without a quantity, the router published each event once and holds no pending receipt for a missing price (FR-09, XL-12, model/services/control-plane/CostUsageService.yaml).
AC3 Given two tenants on the deployed instance, when a caller of one addresses a deployment, a profile that belongs to the other tenant and not to the platform tenant, or the receipts of a run of the other, then the REST answers are 404 and the gRPC answers NOT_FOUND, the same as for an identifier that does not exist, a caller without the scope or the role is answered 403 or PERMISSION_DENIED, and no state changes (ADR-0015).
AC4 Given the chain test of the acceptance suite, when it runs against the deployed instance, then the chain of the description passes in one sequence: the profile loaded and active (SCN-ModelRouterService-013), the deployment registered (SCN-ModelRouterService-004), the evidence imported from a fixture publisher (SCN-ModelRouterService-016), the approval and its state change (SCN-ModelRouterService-006, SCN-ModelRouterService-015), the route plan (SCN-ModelRouterService-009, SCN-ModelRouterService-017), the invocation with its receipt (SCN-ModelRouterService-010, SCN-ModelRouterService-018), the usage on the two meters and the read (SCN-ModelRouterService-008); no captured log record, activity, metric or event of the chain holds a prompt, a completion or a provider key; the other scenarios of model/scenarios/ModelRouterService.yaml are proven by the suites of their PBIs and are not demanded here (ADR-0019).
Traces: services ModelRouterService, ModelGatewayHost, PolicyEngineService, SecretBrokerService, CostUsageService, AgentRegistryService, ArtifactService
Traces: aggregates ModelRouterService/ModelProfile, ModelRouterService/ModelDeployment, ModelRouterService/RoutePlan, ModelRouterService/InvocationReceipt
Traces: apis ModelRouterService/ModelGateway.ResolveRoutePlan, ModelRouterService/ModelGateway.Invoke, ModelRouterService/ListRunReceipts
Traces: events ModelRouterService/ModelInvoked
Traces: descriptors model-invocation-v1
Traces: adrs ADR-0014, ADR-0015, ADR-0019, ADR-0028
Traces: requirements FR-04, FR-09, XL-12
Traces: scenarios SCN-ModelRouterService-004, SCN-ModelRouterService-006, SCN-ModelRouterService-008, SCN-ModelRouterService-009, SCN-ModelRouterService-010, SCN-ModelRouterService-013, SCN-ModelRouterService-015, SCN-ModelRouterService-016, SCN-ModelRouterService-017, SCN-ModelRouterService-018
Depends on AIFACTORY-US-566, AIFACTORY-US-567, AIFACTORY-US-568, AIFACTORY-US-569, AIFACTORY-US-570, AIFACTORY-US-571, AIFACTORY-US-572, AIFACTORY-US-573, AIFACTORY-US-574, AIFACTORY-US-575, AIFACTORY-US-576, AIFACTORY-US-577, AIFACTORY-US-757, AIFACTORY-US-901, AIFACTORY-US-1508, feature:model-gateway-host, feature:agent-registry-service-thin, feature:policy-engine-service, feature:secret-broker-service, feature:cost-usage-service-complete, feature:artifact-service
Sources model/services/model-compute/ModelRouterService.yaml, model/scenarios/ModelRouterService.yaml, docs/planes/model-compute/model-gateway.md, docs/planes/model-compute/workflows.md, docs/planes/model-compute/services/model-router-service/index.md#purpose-and-responsibilities

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-2275 Deployment values of ModelRouterService: replica range, secret references, dependency addresses and the gateway as the only caller operations The deployment manifest of the service states the replica range 2 to 12 of model/services/model-compute/ModelRouterService.yaml, the liveness and readiness probes, the messaging service name model-router, one base address per dependency (PolicyEngineService, CostUsageService, SecretBrokerService, AgentRegistryService, ArtifactService) from configuration, the two secret references provider-credentials and messaging-transport by name and never by value, and a network rule that admits inbound calls from ModelGatewayHost only (ADR-0028 decision 3); the same image runs in the saas-default, hybrid, on-prem and hybrid-compute topologies. ConnectSoft.AI.SoftwareFactory.ModelRouterService
AIFACTORY-TASK-767 Verify model-router-service-serves-its-scope by running the declared command verification Run dotnet build -c Release and dotnet test -c Release --filter "Category=Acceptance" against the deployed instance with ModelGatewayHost, the thin AgentRegistryService, PolicyEngineService, SecretBrokerService, CostUsageService and ArtifactService of the same environment and the scripted provider adapter bound in place of the adapter of one modelled provider value; a filter that matches no test counts as a failure; the chain profile, deployment, evidence by fixture, approval, route plan, invocation, receipt, usage on two meters and read passes, which exercises SCN-ModelRouterService-004, SCN-ModelRouterService-006, SCN-ModelRouterService-008, SCN-ModelRouterService-009, SCN-ModelRouterService-010, SCN-ModelRouterService-013, SCN-ModelRouterService-015, SCN-ModelRouterService-016, SCN-ModelRouterService-017 and SCN-ModelRouterService-018 and no other scenario, the two-tenant answers of AC3 hold, and the captured logs, activities, metrics and events of the chain are scanned and hold no content and no key, which proves AC1 to AC4 of AIFACTORY-US-058; the chain loads its profiles by alias from the eleven Draft model-profile releases the thin AgentRegistryService of the environment seeds (D121, D123). ConnectSoft.AI.SoftwareFactory.ModelRouterService

AIFACTORY-US-566: ModelRouterService repository: scaffolded from the base template with the Factory profile, with its four aggregates and the store model-router-sql

enabling The repository ConnectSoft.AI.SoftwareFactory.ModelRouterService is created and scaffolded in I0 by AIFACTORY-TASK-047 of feature repository-and-pipeline-conventions (D140), and this feature starts from that scaffold, with the scaffold command of ADR-0028 and its amendment on the Factory profile switch (D114): dotnet new connectsoft-base -n ConnectSoft.AI.SoftwareFactory.ModelRouterService --UseFactoryProfile true, from the template package at the version the gate of feature component-base-template-factory-profile published (AIFACTORY-US-230), after the findings of feature component-base-template-findings are closed (AIFACTORY-US-235). The generated output is committed unchanged and the repository records the version of the template package it was generated from. What the profile generates, that is the Orleans messaging profile with an outbox and an inbox of the service, the propagation of the trusted tenant and project scope, the role policies, the REST and gRPC hosts from a service descriptor, health and telemetry, is the work of the template feature; it is consumed by that version pin and is neither rewritten nor forked here. The run event envelope and the descriptor model-invocation-v1 come from the contracts package by a version pin, and the provider adapters, the Anthropic adapter the first solution pack requires among them (D16), from the pinned ConnectSoft.Extensions.AI package of feature component-extensions-ai. On that scaffold this PBI adds the domain and the store. The ModelProfile is the runtime read model of a model-profile release: profile id, version, release, tenant, modality, required capabilities, privacy class, latency class, context and output limits, allowed regions, allowed deployments in preference order, fallback chain, fallback switch, embedding compatibility and price basis. Its invariants are those of the model: every entry of the fallback chain has the same or a stricter privacy class and the same tool and structured-output guarantees, and clients reference profiles, never provider model names. The ModelDeployment is one provider, model revision and endpoint in a region with its CapabilityScore entities, its license metadata, its health and its state. It has exactly eight transitions: Candidate to Evaluated (CapabilityEvidenceRecorded), Candidate to Approved and Evaluated to Approved (PlatformAdminAttestation, the approval by attestation of decision D121, allowed from both states since decision D123), Evaluated to Approved (PlatformAdminApproval), Approved to Degraded (HealthProbeFailed), Degraded to Approved (HealthProbeRecovered), and Approved or Degraded to Retired (Retire); it is routable only when Approved and healthy, is never Approved without recorded license metadata that permits the use, is approved through PlatformAdminApproval only with capability evidence that meets the thresholds of every profile that lists it and through PlatformAdminAttestation only with a stated reason, keeps the basis of its approval in approvalBasis, attestation or capability-suite, with approvalReason and attestedBy for an attestation, all three absent until it is Approved, and Retired is terminal. The RoutePlan holds the ordered candidates of one run and profile under one policy revision with the constraints every candidate satisfies; it is immutable, at most one exists per run and profile, and no candidate is added after resolution. The InvocationReceipt is the record of one model call: scope, run and attempt where the call has them, profile, the deployment that produced the output, route plan, fallback flag, request hash, idempotency key, policy decision, outcome, usage status, tokens, cost estimate, pricing revision, latency, output artifact reference and times. At most one exists per tenant, project and idempotency key, usage Unknown is recorded as such and never as zero, and it has no field for prompt or completion content. The store model-router-sql is owned by this service alone (ADR-0028 decision 5). This PBI migrates five of its six tables, ModelProfiles, ModelDeployments, CapabilityScores, RoutePlans and InvocationReceipts, with the keys and columns of the model, the three approval columns of ModelDeployments and the columns ProjectId and Classification of RoutePlans (decision D125) among them; the sixth table, ProjectBudgetMarks, is migrated with the budget mark it holds (AIFACTORY-US-1508). It also migrates the index over tenant, provider, region and state of deployments, the unique index over run and profile of route plans, the unique index over tenant, project and idempotency key of receipts and the indexes over run and attempt and over tenant and start. The primary keys of ModelProfiles, ModelDeployments and CapabilityScores include the tenant, so that a deployment id, or a profile id and version, of one tenant never collides with the same id of another tenant or of the platform tenant (decision D121). Every mapping carries the tenant row filter of the Factory profile; the filter of ModelProfiles also admits the rows of the platform tenant for reading, as the model defines for ConnectSoft profiles. The retention of receipts, one year by default and seven years for a receipt that audit evidence references, is recorded with the table; no deletion job and no deletion-order handler is built here, because those arrive with RetentionResidencyService in I4.

Acceptance criteria

AC1 Given the repository created and scaffolded in I0 by AIFACTORY-TASK-047 of feature repository-and-pipeline-conventions with dotnet new connectsoft-base -n ConnectSoft.AI.SoftwareFactory.ModelRouterService --UseFactoryProfile true from the base template package at the version the gate of feature component-base-template-factory-profile published, when its pipeline runs, then the committed output equals the generated output, the solution builds in Release, the generated tests pass, a container image is published and the repository records the template version (ADR-0028, model/template-parameters/connectsoft-base.yaml).
AC2 Given the ModelRouterService/ModelDeployment, ModelRouterService/ModelProfile, ModelRouterService/RoutePlan and ModelRouterService/InvocationReceipt aggregates, when their unit tests run, then the deployment accepts exactly the eight transitions of model/services/model-compute/ModelRouterService.yaml and refuses every other one, a transition out of Retired among them; an approval through PlatformAdminApproval without license metadata or with a capability score below a threshold is refused, an approval through PlatformAdminAttestation without a reason is refused, and an Approved deployment states the basis of its approval, attestation or capability-suite; a profile whose fallback chain names a weaker privacy class is refused; a second route plan for one run and profile, a candidate added to a resolved plan and a second receipt for one tenant, project and idempotency key are refused; and a receipt with unknown usage holds no token count and no zero.
AC3 Given model-router-sql created by the migrations of the repository on an isolated test database, when the mapping tests run, then the five tables exist with their keys and indexes, the same deploymentId and the same profile id and version are stored for two tenants without a key violation, because the keys include the tenant, a second route plan for one run and profile and a second receipt for one tenant, project and idempotency key each violate their unique index, a query made for one tenant never returns a deployment, a route plan or a receipt of another, a profile of the platform tenant is readable for every tenant, and no table has a column for prompt, completion or tool output (ADR-0015, ADR-0019).
Traces: services ModelRouterService
Traces: aggregates ModelRouterService/ModelProfile, ModelRouterService/ModelDeployment, ModelRouterService/RoutePlan, ModelRouterService/InvocationReceipt
Traces: descriptors model-invocation-v1
Traces: adrs ADR-0015, ADR-0019, ADR-0028
Traces: requirements NFR-03, NFR-13
Depends on feature:repository-and-pipeline-conventions, feature:component-base-template-factory-profile, feature:component-base-template-findings, feature:contracts-package, feature:component-extensions-ai
Sources model/services/model-compute/ModelRouterService.yaml, model/template-parameters/connectsoft-base.yaml, model/stores.yaml, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md, docs/planes/model-compute/services/model-router-service/index.md#domain-model, docs/reference/schemas/model-invocation.schema.json

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-048 Domain model: ModelProfile, ModelDeployment with CapabilityScore, RoutePlan, InvocationReceipt implementation The four aggregates and the CapabilityScore entity enforce the invariants of the model as it words them; the ModelDeployment accepts only CapabilityEvidenceRecorded and PlatformAdminAttestation out of Candidate, PlatformAdminApproval and PlatformAdminAttestation out of Evaluated (D123), HealthProbeFailed and Retire out of Approved and HealthProbeRecovered and Retire out of Degraded, and records the approval basis capability-suite with PlatformAdminApproval and the basis attestation, the reason and the attesting subject with PlatformAdminAttestation (D121); the RoutePlan is immutable after creation; the InvocationReceipt keeps usage Unknown without a number; unit tests cover every invariant, each of the eight transitions and the refusal of every other one. ConnectSoft.AI.SoftwareFactory.ModelRouterService
AIFACTORY-TASK-049 Persistence in model-router-sql: ModelProfiles, ModelDeployments, CapabilityScores, RoutePlans, InvocationReceipts migration Mappings and migrations for the five tables with the columns the model lists, the columns ApprovalBasis, ApprovalReason and AttestedBy of ModelDeployments and the columns ProjectId and Classification of RoutePlans (D125) among them, the tenant as part of the primary keys of ModelProfiles, ModelDeployments and CapabilityScores (D121), the index IX_Deployments_Provider_Region, the unique indexes UX_RoutePlans_Run_Profile and UX_Receipts_Scope_Idempotency, the indexes IX_Receipts_Run and IX_Receipts_Tenant_StartedAt, the row version of ModelDeployments and the tenant filter in every mapping, the filter of ModelProfiles admitting the platform tenant for reading; the retention of InvocationReceipts is recorded as table metadata; mapping tests run against an isolated test database, never a shared one. ConnectSoft.AI.SoftwareFactory.ModelRouterService
AIFACTORY-TASK-2276 Verify the scaffold, the aggregates and the store of ModelRouterService verification Run dotnet build -c Release and dotnet test -c Release --no-build in the repository pipeline; the generated tests, the unit tests of the four aggregates and the mapping tests on an isolated database pass, and a diff of the committed tree against a fresh generation at the recorded template version shows only the files this PBI added, which proves AC1 to AC3 of AIFACTORY-US-566 (ADR-0028). ConnectSoft.AI.SoftwareFactory.ModelRouterService

AIFACTORY-US-567: ModelRouterService host: ten REST routes and four gRPC methods behind scope policies, the model-router messaging profile with nine subscriptions and the three hosted workers

enabling This PBI turns the scaffold of AIFACTORY-US-566 into a host on which the behaviour PBIs of the feature land. From the service descriptor the host exposes the ten REST operations of the model, AttestDeployment of decision D121 and ListProjectReceipts of decision D123 among them, for its platform gateway and the internal gRPC service ModelGateway with the methods ResolveRoutePlan, Invoke as a server stream, Embed and Rerank, with their contract documents, an OpenAPI document and a proto. A user token reaches the service forwarded by ModelGatewayHost: the service validates it again through the resource-server library the profile wires and accepts the audience of its own gateway (ADR-0015 amendment D117). Each route requires its scope: factory.models.read for ListModelProfiles, GetModelProfile, PreviewRoutePlan and ListProjectReceipts, factory.models.admin for the five deployment operations, factory.runs.read for ListRunReceipts. The role policies narrow the admin scope as the model words it: ListModelDeployments admits a Platform admin and an Observer, and RegisterDeployment, EvaluateDeployment, ApproveDeployment and AttestDeployment admit a Platform admin only, since an Observer issues no command. The tenant of a user call comes from the token. The gRPC methods require a workload identity whose token holds the service scope that names ModelRouterService; the model names AgentRuntimeService as the caller of ResolveRoutePlan and Invoke and the Knowledge services as callers of Embed and Rerank, and a method admits a workload by that scope. Invoke has a second caller since decision D121: ModelGatewayHost calls it for a call of its OpenAI-compatible route with the user token of the caller forwarded unchanged, and the method admits such a user token when its audience is the gateway of the service and its scope carries factory.models.invoke, the fourth scope of the model, for a call outside a run. A run-bound call of that route presents the token of an attempt, which the gateway forwards in place of a user token and which names run, step and attempt in its claims; the method admits it (decision D125). The tenant of either call comes from the token; the project of a run-bound call comes from the route plan of its run and the project of a call outside a run is the one the caller named and the gateway checked (AIFACTORY-US-574, decisions D123 and D125). ResolveRoutePlan, Embed and Rerank admit neither a user token nor the token of an attempt. A workload token carries no tenant claim, and the service reads the tenant and project a workload forwards only because the token holds that service scope (ADR-0015 amendment D114). A resource of another tenant is invisible under the tenant row filter and is answered 404, over gRPC NOT_FOUND, while a missing scope or role inside the tenant of the caller is answered 403, over gRPC PERMISSION_DENIED (D113); the filter is wired here and the answers are proven by the behaviour PBIs. Every modelled refusal code has a problem response, and RegisterDeployment and EvaluateDeployment run behind the Idempotency-Key filter. The messaging profile of the service is named model-router: the outbox writer enlists in the unit of work of a command, and the dispatcher publishes the seven events of the model in the run event envelope of the contracts package with their routes declared in the OrleansMessaging section. The inbox subscribes, with deduplication on the event id, to AssetReleasePublished, AssetReleaseDeprecated and AssetReleaseRevoked of AgentRegistryService, EvaluationCompleted of QualityScoreService, SecretRotated and SecretReferenceRevoked of SecretBrokerService, ClassificationChanged of AuditService, and BudgetExceeded and BudgetUpdated of CostUsageService (decision D125); what the first six handlers do is delivered by AIFACTORY-US-568, AIFACTORY-US-569, AIFACTORY-US-571 and AIFACTORY-US-572, and the handlers MarkProjectBudgetExceeded and ClearProjectBudgetMark of the two budget events by AIFACTORY-US-1508. The seventh is delivered here. AuditService is delivered complete in this increment (feature audit-service-complete) and lists ModelRouterService as a consumer of ClassificationChanged, so the subscription is registered and the handler ApplyClassification is built with the least effect the model words, that routing which follows uses the changed label: idempotent on the event id, it drops every cached decision and every classification-dependent routing datum the service holds for the tenant of the event in its cache store, so that the next resolution or invocation asks PolicyEngineService for its decision again with the classification the caller sends, and it logs the label id, the resource type and the data class. It changes no stored route plan, which is immutable for its run, no deployment and no profile, and publishes nothing. This delivery caches no decision, so the handler has nothing else to drop; what else a changed label has to change in the router, given that the payload names a resource and no profile, is reported to the owner. The three workers of the model are hosted with their triggers and limits: DeploymentHealthProbe every two minutes, two attempts 15 seconds apart, four in parallel partitioned by provider, keyed by deployment and probe window; ReceiptReconciler at minute 30 of every hour, five attempts with exponential backoff from 60 seconds, two in parallel partitioned by tenant, keyed by invocation and statement reference; CapabilityEvidenceImporter on EvaluationCompleted, five attempts with exponential backoff from 30 seconds, two in parallel partitioned by tenant, keyed by deployment, suite version and evidence reference. A duplicate trigger has no second effect. The seven options of the model are bound and validated at start: ModelAccess:Routing:FallbackEnabledByDefault, ModelAccess:Routing:Weights, ModelAccess:Invocation:DefaultTimeoutSeconds, ModelAccess:Invocation:PromptCaching, ModelAccess:Privacy:LogContent, ModelGateway:Adapters:Enabled and OrleansMessaging:ServiceName. The chat and embedding adapters the list names are loaded at start from the pinned AI library. The values of the option, which are also the provider values of a ModelDeployment, are not the keyed registration names of the library: the modelled default names openai, azure-openai, azure-ai-inference, ollama and anthropic, and the library registers its keyed clients as openAI, azureOpenAI, azureAIInference and ollama (docs/planes/model-compute/providers-and-profiles.md). The service therefore holds one mapping from each option value to the keyed registration name of the pinned library, openai to openAI, azure-openai to azureOpenAI, azure-ai-inference to azureAIInference, ollama to ollama and anthropic to the key under which feature component-extensions-ai registers the Anthropic adapter, so the modelled default starts. A value without a mapping, or a mapped key the library does not register, stops the start with the value named, and a start with ModelAccess:Privacy:LogContent true in the Production environment is refused. The naming difference between the option values and the registration names is reported to the owner. The four reloadable options, ModelAccess:Routing:FallbackEnabledByDefault, ModelAccess:Routing:Weights, ModelAccess:Invocation:DefaultTimeoutSeconds and ModelAccess:Invocation:PromptCaching, take a changed value without a restart: it applies to calls and resolutions that start later and never to a resolved route plan or to a call in flight. Readiness reports the store, the messaging profile and the loaded adapters; the health detail names PolicyEngineService, CostUsageService, SecretBrokerService and ArtifactService and the health of each provider adapter, and a call that needs a required dependency that does not answer fails fast. The delivery states its limits. The handlers of ResidencyRuleChanged and DeletionOrderIssued are not part of it: RetentionResidencyService is first delivered in I4 by feature retention-residency-service, and the deletion-order handler ExecuteDeletionOrder is built and proven there with it (D119). Neither are the handlers of ComputePoolStateChanged, ModelWarmed and ModelEvicted of ComputePoolService, which arrives in I8 with feature compute-pool-service. These five events are not subscribed in this delivery. No PBI of the backlog builds the router handlers ApplyResidencyRule and UpdateDeploymentAvailability yet: the two later features deliver the publishers, the handlers live in this repository, and which feature takes them is reported to the owner.

Acceptance criteria

AC1 Given the hosted service, when each of the ten REST operations of model/services/model-compute/ModelRouterService.yaml is called without a token and with a token that lacks the scope of the route, then the answers are 401 and 403 with a problem response; when a command of the deployment operations is called by an Observer who holds factory.models.admin, then the answer is 403; a gRPC call without a token is refused with UNAUTHENTICATED and one whose workload token lacks the service scope with PERMISSION_DENIED; a user token is refused with PERMISSION_DENIED on every gRPC method except ModelGateway.Invoke, which admits it only with factory.models.invoke, and the token of an attempt is admitted by ModelGateway.Invoke alone; a user token whose audience is not the gateway of the service is refused with 401; no state changes (ADR-0015).
AC2 Given a handler that changes a ModelRouterService/ModelDeployment and publishes one of the seven declared events, when its unit of work commits, then one outbox record in run-event-envelope-v1 with event id, tenant id, project id and run id where the event has them, correlation id and payload is committed in the same transaction; when the unit of work rolls back, neither the change nor the record exists; a publish of an event the OrleansMessaging section does not declare throws (ADR-0012, ADR-0014).
AC3 Given the same event id delivered twice to the inbox of the model-router messaging profile, or the same trigger of a hosted worker fired twice under one idempotency key, when it is dispatched, then the handler or the worker runs once and the second delivery has no effect; a handler that keeps failing is retried with backoff and never applied twice; given a fixture publisher of AuditService/ClassificationChanged, when the event is delivered, the same event id twice, then the ApplyClassification handler runs once, drops the classification-dependent routing data the service caches for the tenant of the event, changes no stored route plan, no deployment and no profile, publishes nothing, and the next resolution asks PolicyEngineService for its decision again; an event the delivery does not subscribe to reaches no handler (ADR-0012).
AC4 Given the service starts, when liveness and readiness are probed, then readiness answers ready only after model-router-sql is migrated, the messaging profile has started and every adapter of ModelGateway:Adapters:Enabled is loaded, and it names what is missing while it is unready; the seven options of model/services/model-compute/ModelRouterService.yaml are bound; the modelled default of ModelGateway:Adapters:Enabled starts, because each of its values is mapped to the keyed registration name of the pinned AI library; a value without a mapping, a mapped key the library does not register, or ModelAccess:Privacy:LogContent true in the Production environment stops the start with the value or the key named; a reloaded value of one of the four reloadable options applies to later calls and resolutions and never to a resolved route plan or a call in flight; and traces and logs carry the tenant, project and run scope of the call (ADR-0015, ADR-0019).
Traces: services ModelRouterService, AuditService
Traces: aggregates ModelRouterService/ModelDeployment
Traces: events AuditService/ClassificationChanged
Traces: descriptors run-event-envelope-v1, model-invocation-v1
Traces: adrs ADR-0012, ADR-0014, ADR-0015, ADR-0019, ADR-0028
Traces: requirements NFR-07, NFR-13
Depends on AIFACTORY-US-566, feature:component-base-template-factory-profile, feature:contracts-package, feature:component-extensions-ai, feature:audit-service-complete
Sources model/services/model-compute/ModelRouterService.yaml, model/services/governance/AuditService.yaml, docs/planes/model-compute/providers-and-profiles.md, model/gateways.yaml, docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md, docs/architecture/adr/0014-run-and-lifecycle-envelopes.md, docs/planes/model-compute/services/model-router-service/index.md#apis, docs/planes/model-compute/services/model-router-service/index.md#workers-and-jobs

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-050 API hosting skeleton: REST and gRPC hosts, scope and role policies, problem responses and contract documents for the 10 REST operations and 4 gRPC methods implementation The ten REST routes, ListProjectReceipts of decision D123 among them, and the gRPC methods ModelGateway.ResolveRoutePlan, ModelGateway.Invoke as a server stream, ModelGateway.Embed and ModelGateway.Rerank are hosted from the service descriptor with token validation that accepts the audience of ModelGatewayHost, scope enforcement per route, the role policies of the deployment operations, AttestDeployment among them, the workload identity and service scope check per gRPC method, the admission of a forwarded user token with factory.models.invoke and of the forwarded token of an attempt on ModelGateway.Invoke alone (D121, D125), problem responses for every modelled refusal code, the Idempotency-Key filter of RegisterDeployment and EvaluateDeployment, and the OpenAPI and proto documents; one mapping turns each value of ModelGateway:Adapters:Enabled, which is also a provider value of ModelDeployment, into the keyed registration name of the pinned AI library (openai to openAI, azure-openai to azureOpenAI, azure-ai-inference to azureAIInference, ollama to ollama, anthropic to the key of the Anthropic adapter of feature component-extensions-ai), the modelled default starts, and a value without a mapping or a key the library does not register stops the start with the value named; the four reloadable options are read through a monitor so that a changed value applies to later calls and never to a resolved plan; the proto messages are fixed by the contract task AIFACTORY-TASK-2293, and the behaviour of each operation is delivered by AIFACTORY-US-569 to AIFACTORY-US-577 and AIFACTORY-US-901, not here. ConnectSoft.AI.SoftwareFactory.ModelRouterService
AIFACTORY-TASK-051 Messaging skeleton: outbox and inbox wiring of the model-router profile for 7 published and 9 consumed events, with the ApplyClassification handler implementation The outbox writer enlists in the unit of work and the dispatcher of the model-router messaging profile publishes ModelProfileActivated, ModelProfileRetired, DeploymentStateChanged, CapabilityEvidenceRecorded, RoutePlanResolved, ModelInvoked and ModelFallbackUsed in the run event envelope of the pinned contracts package, each declared with its route in the OrleansMessaging section; the inbox registers AssetReleasePublished, AssetReleaseDeprecated, AssetReleaseRevoked, EvaluationCompleted, SecretRotated, SecretReferenceRevoked, ClassificationChanged of AuditService, and BudgetExceeded and BudgetUpdated of CostUsageService (D125) with idempotency on the event id; the handler ApplyClassification drops the cached decisions and the classification-dependent routing data of the tenant of the event from the cache store, logs the label id, the resource type and the data class, and changes no route plan, deployment or profile; ResidencyRuleChanged, DeletionOrderIssued, ComputePoolStateChanged, ModelWarmed and ModelEvicted are not subscribed in this delivery; what the eight other handlers do is delivered by the behaviour PBIs of this feature, the two budget handlers by AIFACTORY-US-1508. ConnectSoft.AI.SoftwareFactory.ModelRouterService
AIFACTORY-TASK-052 Worker hosting skeleton: schedules, partitioning and retry policies of DeploymentHealthProbe, ReceiptReconciler and CapabilityEvidenceImporter implementation The three workers are hosted with their modelled triggers (every two minutes, minute 30 of every hour, the event EvaluationCompleted), retry policies (fixed 2 attempts 15 seconds apart, exponential 5 attempts from 60 seconds, exponential 5 attempts from 30 seconds), partitioning by provider or tenant with the modelled parallelism, and idempotency keys, and a duplicate trigger has no second effect; what each worker does is delivered by AIFACTORY-US-571, AIFACTORY-US-572 and AIFACTORY-US-577. ConnectSoft.AI.SoftwareFactory.ModelRouterService
AIFACTORY-TASK-2277 Verify the hosted surface of ModelRouterService with a two-tenant fixture verification Run dotnet test -c Release --no-build --filter "Category=Acceptance&Area=Hosting"; a filter that matches no test counts as a failure; the tests call every route without a token, without its scope and with a token of another audience, call the deployment commands as an Observer, call the four gRPC methods with and without the service scope and with a user token with and without factory.models.invoke, commit and roll back a publishing handler, deliver one event id twice, deliver ClassificationChanged from a fixture publisher twice and assert one run of ApplyClassification and no changed route plan, fire one worker trigger twice, start with the modelled default of ModelGateway:Adapters:Enabled, with a value that has no mapping and with a key the library does not register, change a reloadable option while a route plan is resolved and a call is in flight, and probe readiness with the store stopped, which proves AC1 to AC4 of AIFACTORY-US-567 (ADR-0015, ADR-0012). ConnectSoft.AI.SoftwareFactory.ModelRouterService

AIFACTORY-US-568: ModelRouterService starts only with its secret references, keeps provider keys and content out of every log, event and metric, and filters every query by tenant

enabling · persona platform-admin As a platform admin, I want the one service that holds provider credentials to prove that it never starts without its secret references and never writes a key or a prompt anywhere, so that credential isolation and content privacy of the model gateway are a tested fact and not an intention.

ModelRouterService is the only service that calls model providers, so it is the only place where a provider credential exists (ADR-0028 decision 3, and decision 7 places secrets with the service that owns the behaviour). The readiness epic left the proof of that to this feature: the local start page of feature local-development-environment states that the start of this service without its secret reference fails with the name of the missing reference and that the failing start is recorded when the feature that delivers the service runs the steps. This PBI delivers the rule and records the proof. The model lists two secrets of the service, provider-credentials and messaging-transport, both in the key vault with a rotation of 90 days. The service reads them through secret references only: configuration names the reference and never a value, a start without a declared reference or with a reference that does not resolve stops with the name of the missing reference, and no file of the repository, no deployment manifest and no page holds a key value. What the secret provider-credentials holds once every provider call runs on a brokered credential the model does not say. This delivery checks at start that both references resolve, as the start rule demands, reads the value of provider-credentials at no other time and passes it to no adapter; whether it is the vault entry the references of the broker point to, in which case the router should hold no reference to it, is reported to the owner. The rule for the brokered credential is one, and AIFACTORY-US-572 and AIFACTORY-US-574 follow it: one credential per invocation and one per probe. Each is a short-lived, scoped credential issued by SecretBrokerService/SecretBroker.Issue for the purpose model-invoke under the policy decision of that call; it lives in memory for that one call, is passed to the adapter call alone and is kept for no later invocation, because an issuance of the broker outlives neither its invocation nor its lease. It is never written to model-router-sql, to the outbox, to a receipt, to an event, to a log record, to an activity or to a metric. A redaction guard of the logging pipeline masks any value issued by the broker or resolved from a reference, and a test scans everything the service emitted for the fixture key. Because no credential is kept across invocations, the inbox handler RefreshProviderCredential of SecretBrokerService/SecretRotated has no credential to drop. It invalidates the adapter client instances and the reference metadata the service caches for the deployments whose endpointRef resolves to the rotated reference, so the following invocations build their client anew and run on the credential the broker issues from the new vault version, as every invocation asks the broker; an invocation in flight ends on the credential it holds or fails as the provider answers. The handler is idempotent on the event id and changes no deployment. The caller workload identity, the delegated scope of a user and the provider credential are three different things and are never merged. Tenancy is enforced in the service and not only at the gateway: every query of the five tables runs under the tenant row filter, the tenant of a user call comes from the token, the tenant and project of a workload call are read only under the service scope, a resource of another tenant is answered 404 or NOT_FOUND and a missing scope or role 403 or PERMISSION_DENIED (ADR-0015 amendments D113 and D114). Telemetry follows the Factory conventions of feature component-observability-factory-conventions (ADR-0019): the eight metrics of the model are registered with their dimensions through the helper of the pinned observability libraries, which puts tenant and project on every instrument by default; run, step and attempt are on activities and log records and never on a metric; an activity of a model call carries the generative AI attributes with model.profile, model.deployment, route_plan.id, receipt.id, policy.decision.id and fallback.used, as docs/planes/model-compute/observability.md lists them, and has one child activity per adapter call. No prompt, completion or tool output reaches a log record, an activity, a metric or an event by default: the content guard of the observability libraries refuses it and carries the request hash or the artifact reference in its place, and ModelAccess:Privacy:LogContent, which is not reloadable, is false in every deployed environment. The model gives the service two objectives under nfr.objectives, and the observability page adds two; this PBI delivers the series each is measured on and claims no value, because a value exists only once the system is deployed. The objective model-access-overhead, 150 ms at p95 for gateway and router without provider time, is measured on the duration of the invocation activity minus the duration of its adapter activities, recorded as an attribute of the invocation activity; the gateway adds its own duration histogram (feature model-gateway-host). The objective receipt-coverage, a receipt for 100 percent of the invocations that reached an adapter, is measured as the invocations whose adapter activity started against the receipts written for them, the second taken from connectsoft.factory.model_gateway.invocations without the outcome Denied. The reconciliation of Unknown receipts within 24 hours is measured on the age of the oldest receipt with usage Unknown, which the ReceiptReconciler records at every run beside connectsoft.factory.model_gateway.usage_unknown. The detection of provider health within 2 minutes rests on the probe interval of two minutes and is read from the changes of connectsoft.factory.model_gateway.provider_health and the time of DeploymentStateChanged. The model lists no instrument for the overhead and for the age of the oldest Unknown receipt, which is reported to the owner.

Acceptance criteria

AC1 Given the configuration of the service without the secret reference provider-credentials, or without messaging-transport, or with a reference that does not resolve, when the service starts, then the start stops with an error that names the missing reference and holds no value; given both references resolved from the secret store, when it starts, then it becomes ready; the failing and the passing start are recorded in the repository as the proof the local start steps ask for (ADR-0028, model/services/model-compute/ModelRouterService.yaml).
AC2 Given invocations that ran with a fixture credential issued by SecretBrokerService/SecretBroker.Issue, among them a failing provider call and a start with debug logging, when every log record, activity, metric, outbox record and stored row the service produced is scanned, then the fixture key appears in none of them, and no file of the repository or of the deployment manifest holds a key value (ADR-0019, ADR-0028).
AC3 Given invocations of a deployment, each of which ran on its own credential from SecretBrokerService/SecretBroker.Issue and kept none after the call, and SecretBrokerService/SecretRotated for the reference of the deployment, when the RefreshProviderCredential handler runs, then the adapter client instances and the cached reference metadata of that reference are invalidated, the next invocation builds its client anew and asks SecretBrokerService/SecretBroker.Issue as every invocation does, no deployment changes state and a redelivery of the same event id has no second effect; the reference provider-credentials is resolved at start only and its value reaches no adapter (ADR-0012).
AC4 Given model calls of two tenants, when the metrics, activities and log records are read, then every instrument of model/services/model-compute/ModelRouterService.yaml carries its modelled dimensions with tenant and project, run, step and attempt appear on activities and log records only, an activity of a model call carries profile, deployment, route plan id, receipt id, policy decision id and the fallback flag, and no prompt, completion or tool output is present anywhere, the request hash or the artifact reference standing in its place; the series of the objectives of model/services/model-compute/ModelRouterService.yaml and of docs/planes/model-compute/observability.md exist, that is the access overhead as the duration of the invocation activity minus its adapter activities, receipt coverage as adapter calls started against receipts written, the age of the oldest receipt with usage Unknown beside connectsoft.factory.model_gateway.usage_unknown, and the probe interval of two minutes for the detection of provider health, and no value of an objective is claimed before the system is deployed (ADR-0019).
AC5 Given rows of two tenants in each of the five tables, when every repository query of the service is run for one tenant, then no row of the other tenant is returned, a workload call without the service scope never sets a tenant, and the answers for a resource of another tenant are 404 and NOT_FOUND (ADR-0015).
Traces: services ModelRouterService, SecretBrokerService
Traces: apis SecretBrokerService/SecretBroker.Issue
Traces: events SecretBrokerService/SecretRotated
Traces: adrs ADR-0012, ADR-0015, ADR-0019, ADR-0028
Traces: requirements NFR-03, NFR-12
Depends on AIFACTORY-US-567, feature:secret-broker-service, feature:component-observability-factory-conventions, feature:local-development-environment
Sources model/services/model-compute/ModelRouterService.yaml, docs/planes/model-compute/security.md, docs/planes/model-compute/observability.md, docs/architecture/adr/0019-data-governance.md, docs/planes/model-compute/services/model-router-service/index.md#security, docs/planes/model-compute/services/model-router-service/index.md#metrics-and-observability

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-053 Security, tenancy and telemetry of ModelRouterService implementation The four scopes and the role policies of the model are enforced, every query of the five tables is tenant-filtered, the tenant and project of a workload call are read only under the service scope, the eight metrics of the model are registered with their dimensions through the helper of the pinned observability libraries with tenant and project by default, run, step and attempt are on activities and log records, an activity of a model call carries model.profile, model.deployment, route_plan.id, receipt.id, policy.decision.id and fallback.used and has one child activity per adapter call, and the content guard keeps prompt, completion and tool output out of logs, activities, metrics and events; the series of the four objectives are in place: the overhead of an invocation as its activity duration minus the duration of its adapter activities, recorded as an attribute of the invocation activity (objective model-access-overhead of model/services/model-compute/ModelRouterService.yaml), the adapter activities started against the receipts written (objective receipt-coverage), the age of the oldest receipt with usage Unknown recorded by the ReceiptReconciler at every run beside connectsoft.factory.model_gateway.usage_unknown, and the probe interval of two minutes read from connectsoft.factory.model_gateway.provider_health; no value of an objective is claimed before the system is deployed. ConnectSoft.AI.SoftwareFactory.ModelRouterService
AIFACTORY-TASK-2278 Secret references at start, one brokered credential per call in memory only and the RefreshProviderCredential handler implementation The service binds provider-credentials and messaging-transport as secret references and stops its start with the name of a missing or unresolvable reference; the value of provider-credentials is read at no other time and reaches no adapter; a credential issued by SecretBroker.Issue for the purpose model-invoke under the decision of the call is held in memory for that one invocation or probe, passed to the adapter call alone, kept for no later call and masked by the redaction guard of the logging pipeline; the handler of SecretRotated invalidates the adapter client instances and the cached reference metadata of the deployments whose endpointRef resolves to the rotated reference, idempotent on the event id, and holds no credential to drop; no key value is in a file of the repository or in the deployment manifest. ConnectSoft.AI.SoftwareFactory.ModelRouterService
AIFACTORY-TASK-2279 Verify the failing start without a secret reference, the key scan and the telemetry content guard verification Run dotnet test -c Release --filter "Category=Acceptance&Area=SecretsAndTelemetry"; a zero-match filter counts as a failure; the tests start the service without each secret reference and assert the named error, scan logs, activities, metrics, outbox records and rows for the fixture key and for prompt and completion text, run two invocations of one deployment and assert two calls of SecretBroker.Issue and no credential kept between them, deliver SecretRotated twice and assert the invalidated adapter client, read the attributes of an invocation activity and the series of the four objectives, and run every repository query against a two-tenant fixture, which proves AC1 to AC5 of AIFACTORY-US-568; the local start steps of feature local-development-environment are run once for this service and the failing and the passing start are recorded in the repository documentation (ADR-0019). ConnectSoft.AI.SoftwareFactory.ModelRouterService

AIFACTORY-US-569: Load the model profile releases by alias with their definitions from ArtifactService, activate and retire profile versions, and read the active profiles

behavior · persona platform-admin As a platform admin, I want the profiles agents reference to be the releases the registry holds, active in the router with their limits and fallback chains, so that no agent names a provider model and a retired profile is never selected for a new run.

Agents and workflows reference logical profiles, never provider model names (decision D32); a profile is a release of the asset kind model-profile in AgentRegistryService, and ModelProfile in this service is its runtime read model. In this increment AgentRegistryService is delivered thin: it holds seeded Draft releases, resolves them by alias and publishes no release event (feature agent-registry-service-thin). The thin delivery seeds all eleven model profiles of model/model-profiles.yaml as Draft releases that are loadable by alias (decision D123), and the Draft allowance of decision D83 covers ModelProfile releases until I4 (decision D121). Model profiles are therefore loaded as seeded Draft releases by alias in I1, and the approval of a model-profile release by a Platform admin who is not its author becomes required with the complete AgentRegistryService in I4 (decision D119); the invariant of the model on Published releases is enforced with feature agent-registry-service-complete. At start a profile loader resolves each alias of its configured list through AgentRegistryService/AssetPublication.ResolveRelease and loads the release through AgentRegistryService/AssetPublication.LoadRelease, with its workload token, which holds the service scope that names AgentRegistryService. The manifest release-manifest-v1 holds release id, asset kind, asset id, version, state, source, closure and hash and no field of a profile, and the registry never streams content: a reference names content held by ArtifactService and the caller fetches it there (AIFACTORY-US-403). The loader therefore takes the release id, the version and the content reference of the profile definition from the loaded release, fetches the definition through ArtifactService/Artifacts.Fetch under its workload token, compares the hash of what it read with the hash the release states, and validates the document against model-profile-v1, the definition ModelProfile of docs/reference/schemas/asset-manifests.schema.json, before it activates anything. The list of aliases is one configuration key of this thin path, ModelAccess:Profiles:SeedAliases, which the model does not list and which is removed in I4, when the seeded model profile releases are published through the evaluation gate by AIFACTORY-US-421 (D140). The authoring schema follows the aggregate since decision D121, so the loader projects the validated document through one mapping in which every member the aggregate holds has one counterpart, and the contract task of this PBI fixes it: id, version, modality and privacyClass with the values of the aggregate, allowedRegions, allowedDeployments in preference order, fallbackChain, fallbackEnabled, priceBasis, embeddingCompatibility, limits.contextWindow as the context limit, limits.maxOutputTokens and limits.latencyClass; the release id and the tenant come from the release. An absent fallbackChain is an empty chain and an absent fallbackEnabled is false, the default of the schema. The providers of the document, the single fallback member of documents written before the chain and the other members the aggregate does not hold are not projected, and the documents this PBI authors state fallbackChain. One difference remains: each name in capabilities is a required capability that a verdict pass meets, because the schema holds no threshold, and that is reported to the owner. A document without modality, allowedRegions, allowedDeployments, priceBasis, limits.contextWindow or limits.maxOutputTokens, which the schema leaves optional and the aggregate requires, fails activation with the member named. The activation is one command: it writes the profile version as active together with the ModelProfileActivated outbox record in one transaction, is idempotent on profile id, version and release, and refuses a profile whose fallback names a profile with a weaker privacy class or without the same tool and structured-output guarantees, with the entry named. The same command is the inbox handler ActivateProfile of AssetReleasePublished, and RetireProfile handles AssetReleaseDeprecated and AssetReleaseRevoked: the profile version is marked inactive with ModelProfileRetired in the same transaction, a revoked version at once. A retired version is no longer selectable, and runs that pinned it finish on their route plans. The three handlers are built and proven with fixture publishers, because no service publishes these events in I1: AssetReleasePublished arrives with the publication path of feature agent-registry-service-publication in I2 (D140), and AssetReleaseDeprecated and AssetReleaseRevoked with feature agent-registry-service-complete in I4; an event of another asset kind is acknowledged without effect. Readiness stays unready until every configured alias is loaded, so the service never answers NOT_FOUND for a profile the first outcome pins, and it names what is missing. Three branches keep an alias unloaded: AgentRegistryService does not answer; AgentRegistryService answers NOT_FOUND for the alias; ArtifactService does not answer or the content does not match the hash of the release. In each the loader logs the alias, the reason and the number of the attempt, retries with backoff in the running process without a restart, and readiness names the alias, in the second case as the missing alias; content that does not match its hash is never used. The gRPC dependency on AgentRegistryService degrades (decision D125): once a profile version is loaded, its copy in ModelProfiles serves resolution and invocation, so while the registry does not answer the router keeps serving the profile versions it already loaded, a restart of a replica reads them from its store and does not wait for the registry, and readiness stays unready only for an alias that was never loaded. For each of the eleven profiles of model/model-profiles.yaml, code-fast, code-agent, code-agent-strong, reasoning, reasoning-high, structured, vision, long-context, embedding, reranker and pii-local, this PBI authors two files: the authoring document model-profile-v1, and the seed entry in the file shape the seed loader of the thin registry reads, with its two members manifest and alias. The allowedDeployments, allowedRegions and priceBasis values of the documents, for which the schema states no value, and the output limit are inputs of the owner and are not invented here; the acceptance suite uses fixture values. Feature agent-registry-service-thin registers the eleven entries with its seed, as Draft releases under their aliases, and the router loads all eleven by alias (decisions D121 and D123). A loaded release has to name the content reference of its authoring document, which ArtifactService holds; the decision does not say which step stores that document for a seeded release, and that one point is reported to the owner. The suite of this PBI proves the path against a fake of the two registry methods and a fake of ArtifactService/Artifacts.Fetch, and the chain of AIFACTORY-US-058 runs it against the seeded registry of the environment. A caller whose scope carries factory.models.read lists the active profiles through ListModelProfiles with capabilities, privacy class, limits and fallback chains, and reads one through GetModelProfile with its allowed deployments and their evidence summary, that is the state, the health and the capability verdicts of each allowed deployment the tenant filter admits. Profiles of the platform tenant are readable by every tenant; a profile of another tenant is answered 404, the same answer as for an unknown profileId (ADR-0015 amendment D113), and a missing scope 403. No read writes anything, and no response holds a credential. This PBI proves what the publisher can prove for the two events; StudioBff, DashboardService and AuditService, which records each as evidence, handle them in their own PBIs.

Acceptance criteria

AC1 Given a fake of the two registry methods that serves seeded Draft releases of the kind model-profile under their aliases, a fake of ArtifactService/Artifacts.Fetch that holds their authoring documents, and ModelAccess:Profiles:SeedAliases naming the aliases, when the service starts, then each alias is resolved through AgentRegistryService/AssetPublication.ResolveRelease, its release is loaded through AgentRegistryService/AssetPublication.LoadRelease, the definition is fetched through ArtifactService/Artifacts.Fetch, matches the hash of the release and is valid against model-profile-v1 of docs/reference/schemas/asset-manifests.schema.json, one active ModelRouterService/ModelProfile exists per profile version with the values of the mapping, readiness turns ready only after the last alias is loaded, and a second start activates nothing twice; an alias the registry answers NOT_FOUND for, a registry or an ArtifactService that does not answer, and content that does not match its hash each leave the alias unloaded and readiness unready with the alias named, are logged and retried with backoff; a document that fails the schema, lacks a member the aggregate requires or names a profile of a weaker privacy class in its fallback chain is refused with the member named; given every alias loaded and the registry then stops answering, when a replica restarts and a route plan is resolved, then the loaded profile versions are served from ModelProfiles and readiness turns ready without the registry (SCN-ModelRouterService-013, ADR-0021, model/services/model-compute/ModelRouterService.yaml).
AC2 Given a profile version was activated, when the outbox dispatcher of the model-router messaging profile publishes ModelRouterService/ModelProfileActivated on model-access.profiles.v1.model-profile-activated, then the outbox record was written in the same transaction as the activation, the event is sent in the run event envelope with profileId, version, tenantId, releaseId and privacyClass, and a transport outage is retried with backoff so the event is neither lost nor duplicated under its event id (SCN-ModelRouterService-013, ADR-0012).
AC3 Given an active profile version and a fixture publisher of AssetReleaseDeprecated or AssetReleaseRevoked for its release, when the RetireProfile handler runs, then the version is inactive, ModelRouterService/ModelProfileRetired with profileId, version and tenantId is written in the same transaction and published on model-access.profiles.v1.model-profile-retired, the version is absent from ModelRouterService/ListModelProfiles, a route plan of a run that pinned it stays usable, and a redelivery of the same event id retires nothing twice (SCN-ModelRouterService-014, ADR-0012).
AC4 Given active profiles of the platform tenant, of the tenant of the caller and of another tenant, when a caller with factory.models.read calls ModelRouterService/ListModelProfiles, then the response is 200 with the active versions of the platform tenant and of the own tenant only, each with capabilities, privacy class, limits and fallback chain; a call without the scope is answered 403 and nothing is written (SCN-ModelRouterService-001, ADR-0015).
AC5 Given the same profiles, when ModelRouterService/GetModelProfile is called for a readable profileId, then the response is 200 with the profile, its allowed deployments and the state, health and capability verdicts of each; for a profileId of another tenant or one that does not exist the response is 404 with a problem response, the same in both cases, and for a missing scope 403 (SCN-ModelRouterService-002, ADR-0015).
Traces: services ModelRouterService, AgentRegistryService, ArtifactService
Traces: aggregates ModelRouterService/ModelProfile
Traces: apis ModelRouterService/ListModelProfiles, ModelRouterService/GetModelProfile, AgentRegistryService/AssetPublication.ResolveRelease, AgentRegistryService/AssetPublication.LoadRelease, ArtifactService/Artifacts.Fetch
Traces: events ModelRouterService/ModelProfileActivated, ModelRouterService/ModelProfileRetired
Traces: descriptors model-profile-v1, release-manifest-v1
Traces: adrs ADR-0012, ADR-0015, ADR-0021
Traces: requirements FR-04
Traces: scenarios SCN-ModelRouterService-001, SCN-ModelRouterService-002, SCN-ModelRouterService-013, SCN-ModelRouterService-014
Relates: screens model-profiles, run-submit
Depends on AIFACTORY-US-567, feature:agent-registry-service-thin, feature:artifact-service
Sources model/services/model-compute/ModelRouterService.yaml, model/services/control-plane/AgentRegistryService.yaml, model/services/knowledge/ArtifactService.yaml, model/model-profiles.yaml, docs/reference/schemas/asset-manifests.schema.json, docs/reference/schemas/release-manifest.schema.json, docs/architecture/adr/0021-quality-gates.md, docs/architecture/catalogs/model-profiles.md, docs/planes/model-compute/workflows.md

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-2280 Authoring documents and seed entries of the eleven Draft model-profile releases fixture The repository holds two files per profile of model/model-profiles.yaml, eleven in all (code-fast, code-agent, code-agent-strong, reasoning, reasoning-high, structured, vision, long-context, embedding, reranker, pii-local): the authoring document model-profile-v1, valid against the definition ModelProfile of docs/reference/schemas/asset-manifests.schema.json, with id, version, name, capabilities, modality, privacyClass with the values of the aggregate, providers, fallbackChain, fallbackEnabled and limits written from model/model-profiles.yaml through the mapping of AIFACTORY-TASK-2309, and the seed entry in the file shape the seed loader of the thin AgentRegistryService reads, with the member manifest (a Draft manifest of the kind model-profile with releaseId, assetKind, assetId, version, state Draft, source, closure and hash, the hash being that of the authoring document) and the member alias; allowedDeployments, allowedRegions, priceBasis and the output limit are filled only from values the owner supplies, the acceptance suite using fixture values; feature agent-registry-service-thin registers the eleven entries with its seed as Draft releases under their aliases (D121, D123). ConnectSoft.AI.SoftwareFactory.ModelRouterService
AIFACTORY-TASK-2309 Mapping of the authoring document model-profile-v1 onto the ModelProfile aggregate contract The repository documentation holds one table that maps every member of the definition ModelProfile of docs/reference/schemas/asset-manifests.schema.json onto the aggregate of model/services/model-compute/ModelRouterService.yaml; since the schema follows the aggregate (D121), id, version, modality, privacyClass, allowedRegions, allowedDeployments, fallbackChain, fallbackEnabled, priceBasis and embeddingCompatibility map one to one, maxContextTokens comes from limits.contextWindow and maxOutputTokens and latencyClass from limits; the one row where the two shapes still differ is marked with the value this delivery applies until the owner decides, a capability name as a required capability met by a verdict pass; the members the schema leaves optional and the aggregate requires (modality, allowedRegions, allowedDeployments, priceBasis and the two limits) are listed as required for activation; the members of the document the aggregate does not hold (name, providers, the single fallback of documents written before the chain, reliableContext, costClass, capabilityEvidence and license) are listed as not projected; one golden document per row is checked in the pipeline, and the marked row changes only with the decision of the owner that closes its open question. ConnectSoft.AI.SoftwareFactory.ModelRouterService
AIFACTORY-TASK-2281 Profile loader by alias with the definition fetched from ArtifactService, the ActivateProfile and RetireProfile handlers and the two profile events implementation At start the loader resolves each alias of ModelAccess:Profiles:SeedAliases through AssetPublication.ResolveRelease and loads the release through AssetPublication.LoadRelease with the workload token of the service, takes the release id, the version and the content reference of the definition from the loaded release, fetches the definition through Artifacts.Fetch, compares its hash with the hash of the release and validates it against model-profile-v1; one activation command projects the valid document through the mapping of AIFACTORY-TASK-2309 into ModelProfiles with the ModelProfileActivated outbox record in the same transaction, idempotent on profile id, version and release, refusing a fallback chain entry of a weaker privacy class or other guarantees and a document without a member the aggregate requires; ActivateProfile runs the same command for AssetReleasePublished of the kind model-profile; RetireProfile marks the version inactive with ModelProfileRetired in the same transaction for AssetReleaseDeprecated and AssetReleaseRevoked; an alias answered NOT_FOUND, a registry or an ArtifactService that does not answer and content that does not match its hash leave the alias unloaded, are logged with the alias, the reason and the number of the attempt and retried with backoff, and readiness stays unready and names the alias until every alias is loaded; an alias already loaded counts as loaded from its copy in ModelProfiles, so a replica that restarts while the registry does not answer serves the loaded profile versions and turns ready (D125). ConnectSoft.AI.SoftwareFactory.ModelRouterService
AIFACTORY-TASK-2282 ListModelProfiles and GetModelProfile over the active profile versions implementation ListModelProfiles returns the active profile versions of the platform tenant and of the tenant of the token with capabilities, privacy class, limits and fallback chain; GetModelProfile returns one profile with its allowed deployments in preference order and, for each deployment the tenant filter admits, state, health and capability verdicts; a profile of another tenant and an unknown profileId are answered 404 alike and a missing scope 403; no response holds an endpoint secret. ConnectSoft.AI.SoftwareFactory.ModelRouterService
AIFACTORY-TASK-2283 Verify the profile loading, activation, retirement and reads through the acceptance suite verification Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-ModelRouterService-001\|Scenario=SCN-ModelRouterService-002\|Scenario=SCN-ModelRouterService-013\|Scenario=SCN-ModelRouterService-014)"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-569 with a fake of the two registry methods, a fake of Artifacts.Fetch that holds the authoring documents, can return content that does not match its hash and can be stopped, an alias the fake registry answers NOT_FOUND for, which is logged, retried with backoff and named by readiness as the missing alias until the fake serves it, a registry that stops answering, the golden rows of the mapping, fixture publishers of the three release events, a three-tenant fixture, a document refused by the schema, by a missing member the aggregate requires and by its fallback chain, and the publication and payload of ModelProfileActivated and ModelProfileRetired; consumer handling is proven by the suites of the consumers. ConnectSoft.AI.SoftwareFactory.ModelRouterService

AIFACTORY-US-570: Register a model deployment as Candidate without posting a credential, and list the deployments of the tenant with state, health and license metadata

behavior · persona platform-admin As a platform admin, I want to register a provider deployment by reference and see every deployment of my tenant with its state, so that a model enters the Factory as a named, licensed candidate and never as a key pasted into a form.

A Platform admin, with a user token whose scope carries factory.models.admin, registers one concrete provider, model revision and endpoint in a region through the gateway route of RegisterDeployment with an Idempotency-Key. The body names deploymentId, provider (one of openai, azure-openai, azure-ai-inference, ollama, anthropic and self-hosted), model, region, privacyClass, endpointRef, the license metadata (commercial use, redistribution, fine-tuning, customer deployment) and, for a self-hosted deployment, the computePoolId. Credentials are brokered, never posted: endpointRef is a connection or pool reference, the credential comes from the Secret Broker at invocation, and a body that carries a credential value is refused. The tenant comes from the token (ADR-0015). The service writes the ModelDeployment in state Candidate together with a DeploymentStateChanged outbox record in one transaction and answers 201 with the deployment. The fromState of the event is optional and a new deployment has no previous state, so the event of a registration carries toState Candidate and no fromState (decision D121): an event without fromState announces a registration. A Candidate is never routed: the router considers only deployments that are Approved and healthy. The same key with the same body returns the same deployment and writes nothing; the same key with a different body, or a deploymentId that already exists in the tenant, is answered 409; a caller without the scope, and a caller who holds the scope but not the Platform admin role, such as an Observer, is answered 403. A body that fails validation is answered 400, which the model lists for the operation since decision D121. Beyond a missing or malformed member, three bodies fail it: one that carries a credential value, one that names a provider outside the six values of the model, and one that names openai, azure-openai, azure-ai-inference, ollama or anthropic while ModelGateway:Adapters:Enabled does not load the adapter of that value. The value self-hosted is exempt from the adapter rule. The option names no adapter of that name and the model does not say which adapter serves a self-hosted deployment, so such a deployment, with or without a computePoolId, is registered as Candidate like any other, the routing function of AIFACTORY-US-573 excludes it with the reason that no adapter serves its provider, and the question is reported to the owner. The scripted adapter of the acceptance suite has no provider value of its own: the acceptance configuration binds it in place of the adapter of one of the modelled provider values (AIFACTORY-TASK-2297), so the deployment of a test or of the acceptance environment is registered with that value through this operation unchanged. No refusal writes a deployment or publishes anything. The primary key of the table ModelDeployments is the deploymentId together with the tenant (decision D121). A deploymentId that another tenant already uses is therefore no conflict: the deployment is registered for the tenant of the token, and no answer tells a caller whether an id is used elsewhere. The placement and warm state of a deployment with a computePoolId come from ComputePoolService, an optional dependency that arrives in I8; until then no placement is asked for, and such a deployment of a provider value with an adapter, ollama for example, is called at its endpointRef when it is routed. A Platform admin or an Observer whose scope carries factory.models.admin lists the deployments through ListModelDeployments: provider, model, region, privacy class, state, health, license metadata and evidence reference, paged, filtered by the tenant of the token over the index on tenant, provider, region and state. A deployment of another tenant never appears. Whether a deployment of the platform tenant is visible to, and routable for, another tenant, as a profile of the platform tenant is readable by every tenant, the model does not state; it is reported to the owner, and this delivery shows and routes the deployments the tenant row filter admits. A caller without the scope, or with a role other than Platform admin or Observer, is answered 403. This PBI proves what the publisher can prove for the registration event; AIFACTORY-US-572 proves every other publication of DeploymentStateChanged and traces its scenario.

Acceptance criteria

AC1 Given a Platform admin with factory.models.admin and a valid body without a credential, when ModelRouterService/RegisterDeployment is called with an Idempotency-Key, then the response is 201 with the deployment, the ModelRouterService/ModelDeployment is in state Candidate with the tenant of the token, the ModelRouterService/DeploymentStateChanged outbox record with toState Candidate and no fromState, which announces a registration, is written in the same transaction, and the deployment is not routable (SCN-ModelRouterService-004, ADR-0014).
AC2 Given the same call repeated with the same Idempotency-Key and the same body, when it arrives, then the same deployment is returned and no second row and no second outbox record exists; given the same key with a different body, or a deploymentId that already exists in the tenant, when ModelRouterService/RegisterDeployment is called, then the answer is 409; given a deploymentId that only another tenant uses, then the deployment is registered for the tenant of the token and the answer is 201, because the key of the table includes the tenant; given a body that lacks a required member, carries a credential value, names a provider outside the six values of the model, or names one of the five provider values with an adapter while ModelGateway:Adapters:Enabled does not load it, then the answer is 400; a 409 and a 400 write nothing and publish nothing; given a body with the provider self-hosted, or with the provider value the acceptance configuration binds the scripted adapter to, then the deployment is registered as Candidate (SCN-ModelRouterService-004, ADR-0014).
AC3 Given a caller without factory.models.admin, or an Observer who holds it, when ModelRouterService/RegisterDeployment is called, then the answer is 403 with a problem response, no deployment is written and nothing is published (SCN-ModelRouterService-004, ADR-0015).
AC4 Given deployments of two tenants in several states, when a Platform admin or an Observer with factory.models.admin calls ModelRouterService/ListModelDeployments, then the response is 200 with the deployments of the tenant of the token only, paged, each with provider, model, region, privacy class, state, health, license metadata and evidence reference and without any credential; a caller without the scope or with another role is answered 403 and nothing is written (SCN-ModelRouterService-003, ADR-0015).
Traces: services ModelRouterService
Traces: aggregates ModelRouterService/ModelDeployment
Traces: apis ModelRouterService/RegisterDeployment, ModelRouterService/ListModelDeployments
Traces: events ModelRouterService/DeploymentStateChanged
Traces: adrs ADR-0014, ADR-0015
Traces: requirements FR-04, NFR-13
Traces: scenarios SCN-ModelRouterService-003, SCN-ModelRouterService-004
Relates: screens model-profiles
Depends on AIFACTORY-US-567
Sources model/services/model-compute/ModelRouterService.yaml, docs/planes/model-compute/capability-router.md, docs/planes/model-compute/security.md, docs/planes/model-compute/services/model-router-service/index.md#apis

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-2284 Contract of the deployment registration and of the deployment view contract The OpenAPI document of the service fixes the request of RegisterDeployment (deploymentId, provider from the enumeration of the model, model, region, privacyClass, endpointRef, licenseMetadata with its four fields, optional computePoolId, no credential field) and the deployment view of the 201 and of ListModelDeployments, as model/services/model-compute/ModelRouterService.yaml lists the fields; it records that a registration is announced by DeploymentStateChanged with toState Candidate and no fromState, which the model makes optional for this case (D121), the modelled response codes 201, 400, 403 and 409, and that the provider value self-hosted is accepted without an adapter check. ConnectSoft.AI.SoftwareFactory.ModelRouterService
AIFACTORY-TASK-2285 RegisterDeployment with idempotency and role checks, and the ListModelDeployments read implementation RegisterDeployment validates the body, refuses with 400 a credential value, a provider outside the six values of the model and one of the five provider values with an adapter whose adapter is not loaded, accepts the value self-hosted without an adapter check, writes the deployment as Candidate with its DeploymentStateChanged outbox record (toState Candidate, no fromState) in one transaction and returns 201; the idempotent repeat, the 409 of a reused key with another body and of a deploymentId that already exists in the tenant, the registration of a deploymentId that only another tenant uses, which the key of the table admits because it includes the tenant (D121), and the 403 of a missing scope or role are covered by acceptance tests; ListModelDeployments returns the deployments of the tenant of the token paged, for a Platform admin or an Observer, without any credential. ConnectSoft.AI.SoftwareFactory.ModelRouterService
AIFACTORY-TASK-2286 Verify the registration and the list of deployments through the acceptance suite verification Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-ModelRouterService-003\|Scenario=SCN-ModelRouterService-004)"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-570 with a two-tenant fixture, the role matrix of Platform admin, Observer and Requester, the idempotent repeat, both conflicts, a deploymentId another tenant already uses, which is registered with 201, a body without a required member, the refused credential, a provider outside the enumeration, a provider whose adapter is not loaded, a self-hosted deployment registered as Candidate without an adapter, a deployment registered with the provider value the acceptance configuration binds the scripted adapter of AIFACTORY-TASK-2297 to, and the outbox record of the registration with toState Candidate and no fromState. ConnectSoft.AI.SoftwareFactory.ModelRouterService

AIFACTORY-US-571: Request the capability evaluation of a deployment and import the capability evidence that moves a Candidate to Evaluated

behavior · persona platform-admin As a platform admin, I want a deployment to gain its capability scores from the evaluation suite and nowhere else, so that a model is routed on evidence of tool calling, structured output and the other gated capabilities and never on its name.

A model enters routing only on evidence (ADR-0021, decision D32): the evaluation suite of bounded context BC-22 is the only source of capability scores. A Platform admin whose scope carries factory.models.admin asks for the capability suite to be run against a deployment of the tenant through the gateway route of EvaluateDeployment with an Idempotency-Key. It is a sandbox action: it changes no shared state of this service and answers 202; the state of the deployment changes only when evidence arrives. A repeated call with the same key returns the same 202 and asks for no second run; a deploymentId of another tenant or one that does not exist is answered 404 (ADR-0015 amendment D113); a caller without the scope or without the Platform admin role is answered 403. How the suite run is requested is not decided by the model: ModelRouterService has only an event dependency on QualityScoreService, the method Evaluation.RunSuite of that service names model deployments as a target but is not among the dependencies of the router, no method invokes a deployment that is not yet Approved, and the thin QualityScoreService of this increment runs no suite. This PBI therefore delivers the request behind one evaluation request port: the operation validates, applies its idempotency rule, hands the deployment and the request to the port and answers 202. No adapter to a suite is built or invented here, and the point is reported to the owner. The request itself is not written as audit evidence: it changes no state and publishes nothing, the action values of audit-evidence-v1 name none for an evaluation request, and the evaluation becomes evidence when it has a result, through DeploymentStateChanged of the transition to Evaluated, which AuditService records. Whether the request needs an evidence record of its own, with a new action value, is reported to the owner. The evidence path is delivered in full. The CapabilityEvidenceImporter is triggered by EvaluationCompleted of QualityScoreService of the kind capability-suite; an event of another kind is acknowledged without effect. Evaluation records are artifacts (ADR-0021 decision 3), so the evidence reader port has one binding: it reads the record the event references by evidenceRef through ArtifactService/Artifacts.Fetch under the workload token of the service. The importer takes from the record the deployment, the suite version and one verdict per capability (pass, fail or a score) with its time, and in one transaction writes one CapabilityScore per capability under the suite version, sets capabilityEvidenceRef of the deployment, writes the CapabilityEvidenceRecorded outbox record with deploymentId, tenantId, suiteVersion and evidenceRef, and, for a deployment in state Candidate, applies the transition to Evaluated through the trigger CapabilityEvidenceRecorded with a DeploymentStateChanged outbox record. A deployment in another state keeps its state and gains the scores. A failing verdict is recorded as it is; whether the scores meet the thresholds of a profile is checked at approval (AIFACTORY-US-572), not here. The importer retries five times with exponential backoff from 30 seconds, runs two tenants in parallel and is idempotent on deployment, suite version and evidence reference, so a redelivered event writes nothing twice. When the five attempts are exhausted, nothing was written, the deployment keeps its state and the failed delivery stays with the poison handling of the messaging profile (ADR-0012 decision 2). An event for a deployment that does not exist in the tenant of the envelope is acknowledged and logged without effect. The event carries targetReleaseId, suiteId and evidenceRef and no deployment id, suite version or score, so the content shape of the evaluation record, that is how it names the deployment, the suite version and the verdicts, is reported to the owner; the acceptance suite serves fixture records from a fake of ArtifactService/Artifacts.Fetch. When ArtifactService does not answer or holds nothing under the reference, the attempt of the importer fails and is retried under its policy. When no evidence arrives, because the suite is unavailable or, as in this increment, no service runs it, the deployment stays Candidate and is never routed (failure mode of the model), until a Platform admin approves it by attestation with a stated reason (AIFACTORY-US-757, decision D121). This PBI proves what the publisher can prove for CapabilityEvidenceRecorded; StudioBff and DashboardService handle it in their own PBIs.

Acceptance criteria

AC1 Given a Platform admin with factory.models.admin and a Candidate deployment of the tenant, when ModelRouterService/EvaluateDeployment is called with an Idempotency-Key, then the response is 202, the request reached the evaluation request port once, the deployment is still Candidate and nothing is published; a repeated call with the same key returns the same 202 and reaches the port no second time (SCN-ModelRouterService-005, ADR-0021).
AC2 Given a caller without factory.models.admin, an Observer who holds it, or a deploymentId that belongs to another tenant or does not exist, when ModelRouterService/EvaluateDeployment is called, then the answer is 403, 403 or 404 respectively, the 404 the same in both cases, the port is not reached and no state changes (SCN-ModelRouterService-005, ADR-0015).
AC3 Given a Candidate deployment and a fixture publisher of EvaluationCompleted of the kind capability-suite whose record names it, when the CapabilityEvidenceImporter runs and reads the record at evidenceRef through ArtifactService/Artifacts.Fetch, then one capability score per capability of the record exists under its suite version, the evidence reference of the deployment is set, the ModelRouterService/ModelDeployment is Evaluated, and the ModelRouterService/CapabilityEvidenceRecorded and ModelRouterService/DeploymentStateChanged outbox records are written in the same transaction; the same event delivered again, or the same deployment, suite version and evidence reference, writes nothing twice; an event of another kind or for a deployment outside the tenant of the envelope has no effect (SCN-ModelRouterService-016, ADR-0021).
AC4 Given the evidence was imported, when the outbox dispatcher publishes ModelRouterService/CapabilityEvidenceRecorded on model-access.deployments.v1.capability-evidence-recorded, then the event is sent in the run event envelope with deploymentId, tenantId, suiteVersion and evidenceRef, and a transport outage is retried with backoff so the event is neither lost nor duplicated under its event id; given no evidence arrives for a Candidate, then it stays Candidate and no route plan lists it while it is Candidate (SCN-ModelRouterService-016, ADR-0012).
Traces: services ModelRouterService
Traces: aggregates ModelRouterService/ModelDeployment
Traces: apis ModelRouterService/EvaluateDeployment, ArtifactService/Artifacts.Fetch
Traces: events ModelRouterService/CapabilityEvidenceRecorded, ModelRouterService/DeploymentStateChanged
Traces: adrs ADR-0012, ADR-0015, ADR-0021
Traces: requirements FUX-10, NFR-11, XL-08
Traces: scenarios SCN-ModelRouterService-005, SCN-ModelRouterService-016
Relates: screens model-profiles
Depends on AIFACTORY-US-567, AIFACTORY-US-570, feature:artifact-service
Sources model/services/model-compute/ModelRouterService.yaml, model/services/observability/QualityScoreService.yaml, model/services/knowledge/ArtifactService.yaml, docs/reference/schemas/audit-evidence.schema.json, docs/architecture/adr/0021-quality-gates.md, docs/architecture/quality-gates.md, docs/planes/model-compute/workflows.md

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-2287 EvaluateDeployment behind the evaluation request port implementation EvaluateDeployment checks scope and the Platform admin role, finds the deployment under the tenant filter (404 otherwise), applies the Idempotency-Key rule, hands the deployment and the request to the evaluation request port and answers 202 without changing the deployment; the port has a recording fake in the acceptance suite and no adapter to a suite, which waits for the decision of the owner on the call that requests a capability suite run. ConnectSoft.AI.SoftwareFactory.ModelRouterService
AIFACTORY-TASK-2288 CapabilityEvidenceImporter with the evidence reader port, the capability scores and the Candidate to Evaluated transition implementation The handler of EvaluationCompleted of the kind capability-suite reads the evaluation record at evidenceRef through the evidence reader port, whose one binding fetches the artifact through Artifacts.Fetch of ArtifactService under the workload token of the service, writes one CapabilityScore per capability under the suite version, sets capabilityEvidenceRef, writes the CapabilityEvidenceRecorded outbox record and, for a Candidate, applies CapabilityEvidenceRecorded to Evaluated with a DeploymentStateChanged outbox record, all in one transaction; it is idempotent on deployment, suite version and evidence reference, acknowledges without effect an event of another kind or for a deployment outside the tenant of the envelope, and retries five times with exponential backoff from 30 seconds. ConnectSoft.AI.SoftwareFactory.ModelRouterService
AIFACTORY-TASK-2289 Verify the evaluation request and the evidence import through the acceptance suite verification Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-ModelRouterService-005\|Scenario=SCN-ModelRouterService-016)"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-571 with the recording fake of the request port, which also asserts that the request leaves no audit evidence record, a fixture publisher of EvaluationCompleted, a fake of Artifacts.Fetch that holds records of passing and failing verdicts under their evidence references, holds nothing under one reference and can be stopped, a redelivery, an event of another kind, a deployment of another tenant, a Candidate that never receives evidence, and the publication and payload of CapabilityEvidenceRecorded; consumer handling is proven by the suites of the consumers. ConnectSoft.AI.SoftwareFactory.ModelRouterService

AIFACTORY-US-572: Approve an Evaluated deployment after license and evidence checks, keep it Approved or Degraded by the health probe, and announce every state change

behavior · persona platform-admin As a platform admin, I want to approve a deployment only when its license and its evidence allow it, and to see it leave routing when it is unhealthy, so that only licensed, evaluated and healthy deployments ever answer a run.

A Platform admin whose scope carries factory.models.admin approves a deployment through the gateway route of ApproveDeployment, a publication-class action whose gate is in this service and not in the gateway. The service checks, in this order: the deployment exists in the tenant of the token, and a deploymentId of another tenant or one that does not exist is answered 404 (ADR-0015 amendment D113); it is in state Evaluated, and a Candidate, a Degraded or a Retired deployment is answered 409, while a repeated approval of a deployment that is already Approved returns 200 and changes nothing, because the operation is naturally idempotent; its license metadata is recorded and permits the intended use, and its capability scores meet the thresholds in requiredCapabilities of every active profile that lists it in allowedDeployments, and otherwise the answer is 412 with a problem response that names the failed check, the profile and the capability. On success the deployment moves to Approved through the trigger PlatformAdminApproval together with a DeploymentStateChanged outbox record in one transaction, under optimistic concurrency on the row version, and the response is 200. The approval records the basis capability-suite in approvalBasis of the deployment; the approval of a Candidate or an Evaluated deployment by attestation, which records the basis attestation, is the operation AttestDeployment of AIFACTORY-US-757 (decisions D121 and D123). Only a deployment that is Approved and healthy is routable. Which of the four license fields forbids which use the model does not state; the check is one rule with those four inputs, and its rule is reported to the owner. A caller without the scope or without the Platform admin role is answered 403. The DeploymentHealthProbe runs every two minutes over the deployments in Approved or Degraded, four in parallel partitioned by provider, with two attempts 15 seconds apart, idempotent on deployment and probe window. It sends a minimal request through the adapter of the deployment. SecretBrokerService issues only for a purpose among the allowed purposes of a reference and for a subject with a policy decision Allow, and an issuance carries the id of that decision. The probe therefore asks PolicyEngineService/Policy.Decide once per deployment and probe window for the probe of that deployment by the workload identity of the service, and passes the decision id and the purpose model-invoke to SecretBrokerService/SecretBroker.Issue, which issues one short-lived credential for that one probe (the rule of AIFACTORY-US-568: one credential per call, none kept). Whether a probe needs a decision of its own, and which rule of the policy bundle allows it, is reported to the owner. A probe counts as failed only when the provider call fails on both attempts, or when the broker refuses the issuance because the reference is revoked. When Policy.Decide or SecretBroker.Issue does not answer, or the decision denies, the probe of that deployment is skipped: its state and healthy stay unchanged, the skip is logged with the deployment and the dependency named and counted, and the next window probes again. An outage of the broker or of the policy engine therefore never moves the Approved deployments to Degraded and never ends every invocation with UNAVAILABLE for a reason the providers do not have. The model lists no instrument for a skipped probe, which is reported. A failed probe moves an Approved deployment to Degraded with healthy false (trigger HealthProbeFailed), and a successful probe moves a Degraded one back to Approved with healthy true (trigger HealthProbeRecovered), each with a DeploymentStateChanged outbox record in the same transaction; a probe that confirms the current state writes nothing. The probe sets connectsoft.factory.model_gateway.provider_health per provider and region and records its latency in connectsoft.factory.model_gateway.latency. A probe is no invocation of a caller: it writes no receipt and publishes no ModelInvoked, and that its provider tokens are recorded by no receipt is reported to the owner. A Degraded deployment is skipped by the router without a change to the constraints of a route plan. The inbox handler DisableDeploymentOnRevocation of SecretBrokerService/SecretReferenceRevoked takes every deployment of the tenant whose endpointRef resolves to the revoked reference out of routing at once: an Approved one moves to Degraded with healthy false, by the same transition as a failed probe, and stays there while no credential can be issued for it. Whether a revoked reference should retire the deployment instead is reported to the owner. The aggregate implements the transitions Approved to Retired and Degraded to Retired through the trigger Retire; a Retired deployment is terminal and never routed. The model names no operation, command or consumed event that retires a deployment, although the scope factory.models.admin names retiring, so the transition is unit-tested and announced when applied, no route calls it in this delivery, and that is reported to the owner. DeploymentStateChanged is published on model-access.deployments.v1.deployment-state-changed with deploymentId, tenantId, fromState, which is absent only for a registration, toState and healthy; the event of an approval also carries approvalBasis, which is capability-suite for the approval of this PBI, and the event of an approval by attestation carries the stated approvalReason and attestedBy as well, so that the audit record of an approval holds its basis (decision D123); this PBI proves what the publisher can prove, and StudioBff, DashboardService and AuditService, which records each change as evidence, handle it in their own PBIs.

Acceptance criteria

AC1 Given a Platform admin with factory.models.admin and an Evaluated deployment of the tenant whose license metadata permits the use and whose capability scores meet the thresholds of every active profile that lists it, when ModelRouterService/ApproveDeployment is called, then the response is 200, the ModelRouterService/ModelDeployment is Approved with the approval basis capability-suite, the ModelRouterService/DeploymentStateChanged outbox record with fromState Evaluated, toState Approved and approvalBasis capability-suite is written in the same transaction, and the deployment is routable while it is healthy; a second call returns 200 and writes nothing (SCN-ModelRouterService-006, ADR-0021).
AC2 Given a caller without factory.models.admin or without the Platform admin role, a deploymentId of another tenant, a deployment that is Candidate, Degraded or Retired, or an Evaluated one with a forbidding license or a score below a threshold of a profile that lists it, when ModelRouterService/ApproveDeployment is called, then the answer is 403, 404, 409 or 412 respectively, the 412 naming the failed check, the profile and the capability, the state does not change and nothing is published (SCN-ModelRouterService-006, ADR-0015).
AC3 Given an Approved deployment whose provider stops answering, when the DeploymentHealthProbe runs with a decision of PolicyEngineService/Policy.Decide and a credential that SecretBrokerService/SecretBroker.Issue issued for the purpose model-invoke under that decision, and both attempts of the provider call fail, then the deployment is Degraded with healthy false and ModelRouterService/DeploymentStateChanged is written in the same transaction; when a later probe succeeds, then it is Approved with healthy true and the event is written again; when the decision or the issuance does not answer, then the probe of that deployment is skipped, its state and healthy stay unchanged, the skip is logged and counted and the next window probes again; a probe that confirms the state writes nothing, the same probe window fired twice probes once, and no receipt is written for a probe (SCN-ModelRouterService-015, XL-16).
AC4 Given an Approved deployment whose endpointRef resolves to a secret reference and SecretBrokerService/SecretReferenceRevoked for that reference, when the DisableDeploymentOnRevocation handler runs, then the deployment is Degraded with healthy false, ModelRouterService/DeploymentStateChanged is written in the same transaction, the router skips it from then on, a deployment of another reference is untouched and a redelivery of the same event id has no second effect (SCN-ModelRouterService-015, ADR-0012).
AC5 Given any transition of the deployment was applied, the trigger Retire out of Approved and out of Degraded in the unit tests among them, when the outbox dispatcher publishes ModelRouterService/DeploymentStateChanged on model-access.deployments.v1.deployment-state-changed, then the event is sent in the run event envelope with deploymentId, tenantId, fromState, toState and healthy and, for an approval, approvalBasis, and a transport outage is retried with backoff so the event is neither lost nor duplicated under its event id (SCN-ModelRouterService-015, ADR-0012).
Traces: services ModelRouterService, SecretBrokerService, PolicyEngineService
Traces: aggregates ModelRouterService/ModelDeployment
Traces: apis ModelRouterService/ApproveDeployment, SecretBrokerService/SecretBroker.Issue, PolicyEngineService/Policy.Decide
Traces: events ModelRouterService/DeploymentStateChanged, SecretBrokerService/SecretReferenceRevoked
Traces: adrs ADR-0012, ADR-0015, ADR-0021
Traces: requirements NFR-11, XL-08, XL-16
Traces: scenarios SCN-ModelRouterService-006, SCN-ModelRouterService-015
Relates: screens model-profiles
Depends on AIFACTORY-US-567, AIFACTORY-US-568, AIFACTORY-US-570, AIFACTORY-US-571, feature:secret-broker-service, feature:policy-engine-service
Sources model/services/model-compute/ModelRouterService.yaml, model/services/governance/SecretBrokerService.yaml, model/services/governance/PolicyEngineService.yaml, docs/architecture/adr/0021-quality-gates.md, docs/planes/model-compute/capability-router.md, docs/planes/model-compute/services/model-router-service/index.md#domain-model

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-2290 ApproveDeployment with the state, license and threshold checks implementation ApproveDeployment checks scope and the Platform admin role, finds the deployment under the tenant filter (404), requires the state Evaluated (409, and 200 without effect for an Approved one), evaluates the license rule over the four license fields and the capability scores against requiredCapabilities of every active profile that lists the deployment (412 with the failed check, the profile and the capability named), and applies PlatformAdminApproval, which records the approval basis capability-suite (D121), with the DeploymentStateChanged outbox record, whose payload carries approvalBasis capability-suite (D123), in one transaction under the row version; the license rule is one replaceable rule whose content waits for the decision of the owner. ConnectSoft.AI.SoftwareFactory.ModelRouterService
AIFACTORY-TASK-2291 DeploymentHealthProbe, the DisableDeploymentOnRevocation handler and the Retire transition implementation For each Approved or Degraded deployment the probe asks Policy.Decide once per deployment and probe window, passes the decision id and the purpose model-invoke to SecretBroker.Issue and sends a minimal request through the adapter with the one credential issued for that probe; when Policy.Decide or SecretBroker.Issue does not answer, or the decision denies, the probe of that deployment is skipped, its state and healthy stay unchanged, the skip is logged with the deployment and the dependency named and counted, and the next window probes again; only a provider call that fails on both attempts, or an issuance refused for a revoked reference, is a failed probe; the probe applies HealthProbeFailed or HealthProbeRecovered with a DeploymentStateChanged outbox record in the same transaction, writes nothing when the state is confirmed, sets connectsoft.factory.model_gateway.provider_health and records latency, and writes no receipt; the handler of SecretReferenceRevoked moves the Approved deployments whose endpointRef resolves to the revoked reference to Degraded with healthy false, idempotent on the event id; the aggregate applies Retire out of Approved and Degraded with its event, and no route calls it. ConnectSoft.AI.SoftwareFactory.ModelRouterService
AIFACTORY-TASK-2292 Verify the approval, the health probe and the state change event through the acceptance suite verification Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-ModelRouterService-006\|Scenario=SCN-ModelRouterService-015)"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-572 with deployments in every state, a forbidding license, a score below a threshold of a listing profile, the scripted provider adapter failing and recovering under the probe, fakes of Policy.Decide and SecretBroker.Issue that stop answering during a probe window, after which the deployment is still Approved and healthy, the skip is logged and counted and the next window probes it, an issuance refused for a revoked reference, which counts as a failed probe, the decision id and the purpose model-invoke received by the fake of SecretBroker.Issue, one probe window fired twice, a fixture publisher of SecretReferenceRevoked, the unit tests of Retire and the publication and payload of DeploymentStateChanged; consumer handling is proven by the suites of the consumers. ConnectSoft.AI.SoftwareFactory.ModelRouterService

AIFACTORY-US-757: Approve a Candidate or an Evaluated deployment by attestation of a Platform admin with a required reason, keep the basis of the approval and announce the state change with it

behavior · persona platform-admin As a platform admin, I want to approve a deployment on my stated reason while no capability suite can evaluate it, so that the first deployment of an instance becomes routable through an audited act and its approval is known to rest on an attestation and not on evidence.

A deployment is routable only when it is Approved and healthy, and ApproveDeployment approves only an Evaluated deployment on capability evidence (AIFACTORY-US-572). In this increment no service runs the capability suite, so no deployment of a deployed instance reaches Evaluated. Decision D121 therefore gives the model a second approval: a Platform admin approves a deployment by attestation, and that is how the first Approved deployment of an instance comes into being. The attestation is allowed from Candidate and from Evaluated (decision D123), so a deployment that capability evidence moved to Evaluated can be attested as well. A Platform admin, with a user token whose scope carries factory.models.admin, calls the gateway route of AttestDeployment, POST /factory/model-deployments/{deploymentId}/attest, with a body that states the reason. It is a publication-class action whose gate is in this service and not in the gateway. The service checks, in this order: the caller holds the scope and the Platform admin role, and a caller without either, an Observer who holds the scope among them, is answered 403; the body states a reason that is not empty, and a body without one is answered 400; the deployment exists in the tenant of the token, and a deploymentId of another tenant or one that does not exist is answered 404 (ADR-0015 amendment D113); the deployment is in state Candidate or Evaluated, and a Degraded or a Retired deployment and one that was Approved on capability evidence is answered 409 with the state named. No capability evidence is asked for and no capability score is read; the scores an Evaluated deployment already holds are kept and decide nothing here. The invariant on license metadata holds for every approval, and an attestation is no exception: a deployment whose license metadata forbids the intended use is never Approved. A deployment whose license forbids the use is answered 409 (decision D123), with a problem response that names the license check, under the one license rule of AIFACTORY-US-572. On success the deployment moves from Candidate or from Evaluated to Approved through the trigger PlatformAdminAttestation, under optimistic concurrency on the row version, and keeps the basis of its approval: approvalBasis is attestation, approvalReason is the stated reason and attestedBy is the subject of the token. The DeploymentStateChanged outbox record with fromState Candidate or Evaluated, toState Approved, healthy, approvalBasis attestation, the stated approvalReason and attestedBy is written in the same transaction, and the response is 200 with the deployment. The operation is naturally idempotent: a repeated call for a deployment that is already Approved on the basis attestation answers 200 without effect (decision D123), so nothing changes, nothing is published, and the reason and the attesting subject of the first call stay as they are. A deployment approved by attestation is routable like any Approved deployment: the router lists it as a candidate without capability scores (AIFACTORY-US-573), the DeploymentHealthProbe keeps it Approved or Degraded, and a revoked secret reference takes it out of routing (AIFACTORY-US-572). Capability evidence that arrives later is imported into its scores and leaves its state and its basis unchanged (AIFACTORY-US-571). The deployment view of ListModelDeployments and of the 200 of this operation shows the three approval fields, so that an operator sees on which basis a deployment answers runs. The act is audited. AuditService records DeploymentStateChanged as evidence, and the event is the evidence path the model gives this service. Since decision D123 its payload carries, beside the deployment, the tenant, the two states and the health, the optional members approvalBasis, approvalReason and attestedBy, so that the audit record of the approval holds the basis, the reason and who attested; the three values are also kept on the deployment, where a read returns them. The attestation is the approval of I1 and no lasting substitute for evidence: arriving in I4, the capability suite evidence is required for a new approval and the deployments approved by attestation are evaluated again (decision D121). Neither rule is built here, and approvalBasis is what lets that later work find the attested deployments. This PBI proves what the publisher can prove for the event of the attestation; AIFACTORY-US-572 traces the scenario of DeploymentStateChanged, and StudioBff, DashboardService and AuditService handle the event in their own PBIs.

Acceptance criteria

AC1 Given a Platform admin with factory.models.admin and a Candidate or an Evaluated deployment of the tenant whose license metadata permits the use, when ModelRouterService/AttestDeployment is called with a reason, then the response is 200, the ModelRouterService/ModelDeployment is Approved with approvalBasis attestation, the stated approvalReason and the subject of the token as attestedBy, the ModelRouterService/DeploymentStateChanged outbox record with fromState Candidate or Evaluated, toState Approved, approvalBasis attestation, the stated approvalReason and attestedBy is written in the same transaction, and no capability evidence was asked for and no capability score read; a second call answers 200 without effect, writes nothing and publishes nothing (SCN-ModelRouterService-020, ADR-0021).
AC2 Given a caller without factory.models.admin or without the Platform admin role, a body without a reason, a deploymentId of another tenant or one that does not exist, a deployment that is Degraded, Retired or Approved on the basis capability-suite, or a Candidate or an Evaluated one whose license metadata forbids the use, when ModelRouterService/AttestDeployment is called, then the answer is 403, 400, 404, 409 or 409 respectively, the 404 the same in both cases and the last 409 naming the license check; the state and the approval fields of the deployment do not change and nothing is published (SCN-ModelRouterService-020, ADR-0015).
AC3 Given a deployment approved by attestation, when a route plan is resolved for a profile that lists it, the DeploymentHealthProbe runs and the deployments of the tenant are listed, then the deployment is a candidate of the plan like any Approved deployment although it has no capability score, the probe moves it between Approved and Degraded as it does every Approved deployment, and the deployment view shows its approval basis, its reason and the attesting subject; capability evidence imported later adds scores and changes neither its state nor its basis (SCN-ModelRouterService-020, model/services/model-compute/ModelRouterService.yaml).
AC4 Given the attestation was committed, when the outbox dispatcher publishes ModelRouterService/DeploymentStateChanged on model-access.deployments.v1.deployment-state-changed, then the event is sent in the run event envelope with deploymentId, tenantId, fromState Candidate or Evaluated, toState Approved, healthy, approvalBasis attestation, approvalReason and attestedBy, and a transport outage is retried with backoff so the event is neither lost nor duplicated under its event id; the event, with the basis, the reason and the attesting subject, is what AuditService records as the evidence of the act, as model/services/governance/AuditService.yaml lists its handler (SCN-ModelRouterService-020, ADR-0012).
Traces: services ModelRouterService
Traces: aggregates ModelRouterService/ModelDeployment
Traces: apis ModelRouterService/AttestDeployment
Traces: events ModelRouterService/DeploymentStateChanged
Traces: adrs ADR-0012, ADR-0015, ADR-0021
Traces: requirements NFR-11, XL-08
Traces: scenarios SCN-ModelRouterService-020
Relates: screens model-profiles
Depends on AIFACTORY-US-567, AIFACTORY-US-570, AIFACTORY-US-572, AIFACTORY-US-573
Sources model/services/model-compute/ModelRouterService.yaml, model/services/governance/AuditService.yaml, docs/architecture/adr/0021-quality-gates.md, docs/planes/model-compute/capability-router.md, docs/planes/model-compute/services/model-router-service/index.md#domain-model

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-3055 Contract of the attestation and of the approval fields in the deployment view contract The OpenAPI document of the service fixes the request of AttestDeployment, a body with the one required member reason, its response codes 200, 400, 403, 404 and 409 of model/services/model-compute/ModelRouterService.yaml with their problem responses, the 409 of a forbidding license told apart from the 409 of a state by its problem type, and adds approvalBasis with the values attestation and capability-suite, approvalReason and attestedBy to the deployment view of AIFACTORY-TASK-2284, all three absent until the deployment is Approved; the event contract of DeploymentStateChanged gains the same three optional members, present on the event of an approval (D123); it records that a repeated call for a deployment already Approved on the basis attestation returns 200 without effect. ConnectSoft.AI.SoftwareFactory.ModelRouterService
AIFACTORY-TASK-3056 AttestDeployment with the role, reason, state and license checks and the kept basis of the approval implementation AttestDeployment checks scope and the Platform admin role (403), requires a reason that is not empty (400), finds the deployment under the tenant filter (404), requires the state Candidate or Evaluated (D123; 409 for every other state, and 200 without effect and without an event for a deployment already Approved on the basis attestation), evaluates the license rule of AIFACTORY-TASK-2290 (409 with the license check named), asks for no capability evidence, and applies PlatformAdminAttestation with approvalBasis attestation, the reason, the subject of the token as attestedBy and the DeploymentStateChanged outbox record (fromState Candidate or Evaluated, toState Approved, approvalBasis, approvalReason and attestedBy) in one transaction under the row version; the deployment view of the 200 and of ListModelDeployments returns the three approval fields. ConnectSoft.AI.SoftwareFactory.ModelRouterService
AIFACTORY-TASK-3057 Verify the approval by attestation through the acceptance suite verification Run dotnet test -c Release --filter "Category=Acceptance&Scenario=SCN-ModelRouterService-020"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-757 with a two-tenant fixture, the role matrix of Platform admin, Observer and Requester, a body without a reason and with an empty one, deployments in every state, a Candidate and an Evaluated one that are attested, one Approved on the basis capability-suite, a Candidate and an Evaluated one with a forbidding license, a repeated attestation that publishes nothing, a route plan that lists the attested deployment without capability scores, the scripted provider failing and recovering under the probe for the attested deployment, evidence imported after the attestation, the deployment view with its three approval fields, and the publication and payload of DeploymentStateChanged with fromState Candidate or Evaluated, toState Approved, approvalBasis attestation, approvalReason and attestedBy; consumer handling is proven by the suites of the consumers. ConnectSoft.AI.SoftwareFactory.ModelRouterService

AIFACTORY-US-573: Resolve the route plan of a run and profile once under the policy revision in force, preview it without persisting, and announce the resolved plan

behavior · persona operator As an operator, I want every attempt of a run to route the same way, and to see why a deployment was or was not a candidate, so that a changed policy or a new deployment never changes a run in flight and a routing decision can be explained.

A route plan is the ordered list of deployments one run may use for one profile; it is resolved once and reused by every attempt, so that every attempt routes the same way and a changed policy affects future runs only. AgentRuntimeService, with a workload identity whose token holds the service scope that names ModelRouterService, calls the internal gRPC method ModelGateway.ResolveRoutePlan through the gateway with the tenant and project of the run, forwarded and read only under that scope (ADR-0015 amendment D114), the runId, the profileId with the profile version the run pinned at acceptance, the policy revision the run pinned, the classification of the data and the capabilities the run needs. The router loads the active profile version the tenant can read, asks PolicyEngineService/Policy.Decide for the decision on profile, data class, region and tools under the policy revision the request names, which is the revision in force for the run and not the one that happens to be active when the call arrives, and builds the candidates from allowedDeployments of the profile. It keeps the deployments in state Approved or Degraded that the tenant row filter admits, whose privacy class is the class of the profile or a stricter one, whose region is in allowedRegions, that the decision permits, whose capability scores meet requiredCapabilities and whose provider value has a loaded adapter, so that a deployment of the provider self-hosted, which no adapter serves in this delivery (AIFACTORY-US-570), is excluded with that reason; a Degraded deployment stays a candidate, because health is checked at invocation and does not change the constraints. A deployment approved by attestation is routable like any Approved deployment (decision D121, AIFACTORY-US-757): it passes the capability filter on its attestation instead of on scores; one attested from Candidate has no capability scores, and its capability term in the ordering is neutral, like every term without a value. One attested from Evaluated (decision D123) holds scores, and whether they take part in the filter and in the ordering of an attested deployment is not stated by the decision and is reported to the owner. How the ordering ranks an attested deployment against an evaluated one beyond that is not stated by the decision and is reported to the owner. It orders them by the weights of ModelAccess:Routing:Weights (capability, cost, latency, history) and keeps the preference order of allowedDeployments between equal scores. Only the capability term has a source in the store of the service, the capability scores; the model names no source for the cost, latency and history terms, so a term without a value is neutral, and the point is reported to the owner. When the profile enables fallback, the deployments of the profiles in its fallbackChain that satisfy the same constraints are appended at resolution, never at invocation (AIFACTORY-US-575). The plan is written to RoutePlans with run, tenant, the project and the classification of the request, profile, profile version, policy revision, candidates, constraints (privacy class, region, tool and output guarantees) and the time, together with the RoutePlanResolved outbox record, in one transaction. The project and the classification are kept in the columns ProjectId and Classification because a run-bound call of the OpenAI-compatible route takes them, with the pinned profile version, from this plan (decision D125, AIFACTORY-US-574). The method is idempotent per run and profile under the unique index over both: a repeated call with the same input returns the stored plan, writes nothing and asks for no second decision. The same key with a different input is a conflict (ADR-0014 decision 3): a repeated call for the same run and profile whose profile version, policy revision, classification or capabilities differ from those of the stored plan, which keeps the first three in its columns and the capabilities in its constraints, is refused with FAILED_PRECONDITION and the differing field named, the status an idempotency key reused with another request hash has in Invoke; the stored plan stays unchanged and nothing is published. The reply names the route plan, the profile version and the candidates. The model declares model-invocation-v1 as request and reply of the four gRPC methods; the schema of that descriptor has no field for a route plan, for chat content, for vectors or for rerank scores, so the proto of the service carries the descriptor as the header of each message and adds the fields a method needs, which is fixed by the contract task of this PBI and reported to the owner. A call without a workload identity is refused with UNAUTHENTICATED, a token without the service scope with PERMISSION_DENIED, an invalid request with INVALID_ARGUMENT, and a profile that is unknown, retired or of another tenant with NOT_FOUND, which an attempt takes as the failure class permanent. A decision that denies the profile for the scope is answered PERMISSION_DENIED with the decision id and counted in connectsoft.factory.model_gateway.denials. When PolicyEngineService does not answer, the call fails closed with UNAVAILABLE and no plan is written. When no deployment passes the filters, the call is refused with FAILED_PRECONDITION and the excluded deployments with their reasons, and no empty plan is stored; the error detail tells this refusal from the conflict of a repeated call. RoutePlanResolved is published on model-access.routing.v1.route-plan-resolved with routePlanId, runId, tenantId, profileId and candidates; DashboardService projects it in its own PBI. A caller whose scope carries factory.models.read dry-runs the router through the gateway route of PreviewRoutePlan for a profile and a scope: the response is 200 with the candidates in order, the filters applied and, for every excluded deployment, the reason. The preview runs the same filters and scoring and asks for the same decision, persists no plan and publishes nothing. A profileId that is unknown, retired or of another tenant is answered 404, a missing scope 403, and an unreachable policy engine 503, because no route is shown without a decision.

Acceptance criteria

AC1 Given a workload identity with the service scope, an active profile version and allowed deployments of which one is Approved, one Degraded, one Candidate, one of a weaker privacy class and one outside the allowed regions, when ModelRouterService/ModelGateway.ResolveRoutePlan is called for a run, then PolicyEngineService/Policy.Decide is asked once under the policy revision the request names, the ModelRouterService/RoutePlan holds the Approved and the Degraded deployment in score order with the constraints, the policy revision and the project and the classification of the request, the ModelRouterService/RoutePlanResolved outbox record is written in the same transaction and the reply names the plan, the profile version and the candidates (SCN-ModelRouterService-009, ADR-0014, FR-04).
AC2 Given a resolved plan of a run and profile, when ModelRouterService/ModelGateway.ResolveRoutePlan is called again for the same run and profile with the same profile version, policy revision, classification and capabilities, also after a new deployment was approved or a newer policy revision became active, then the stored plan is returned unchanged, no second plan and no second outbox record exists and no second decision is asked for; when it is called again for the same run and profile with another profile version, policy revision, classification or capability set, then the status is FAILED_PRECONDITION with the differing field named, the stored plan stays unchanged and nothing is published (SCN-ModelRouterService-009, XL-04, ADR-0014).
AC3 Given a caller without a workload identity, a token without the service scope, an invalid request, a profile of another tenant or a retired one, a denying decision, no deployment that passes the filters, or a policy engine that does not answer, when ModelRouterService/ModelGateway.ResolveRoutePlan is called, then the status is UNAUTHENTICATED, PERMISSION_DENIED, INVALID_ARGUMENT, NOT_FOUND, PERMISSION_DENIED with the decision id, FAILED_PRECONDITION with the exclusion reasons, or UNAVAILABLE respectively, and no plan is written and nothing is published (SCN-ModelRouterService-009, ADR-0015).
AC4 Given a plan was resolved, when the outbox dispatcher publishes ModelRouterService/RoutePlanResolved on model-access.routing.v1.route-plan-resolved, then the event is sent in the run event envelope with routePlanId, runId, tenantId, profileId and candidates, and a transport outage is retried with backoff so the event is neither lost nor duplicated under its event id (SCN-ModelRouterService-017, ADR-0012).
AC5 Given a caller with factory.models.read and the deployments of AC1, when ModelRouterService/PreviewRoutePlan is called for the profile and a scope, then the response is 200 with the same candidates in the same order as a resolution would produce, the filters applied and the reason of exclusion of each other deployment, no ModelRouterService/RoutePlan is written and nothing is published; a profileId of another tenant is answered 404, a missing scope 403 and an unreachable policy engine 503 (SCN-ModelRouterService-007, ADR-0015).
Traces: services ModelRouterService, PolicyEngineService
Traces: aggregates ModelRouterService/RoutePlan, ModelRouterService/ModelProfile, ModelRouterService/ModelDeployment
Traces: apis ModelRouterService/ModelGateway.ResolveRoutePlan, ModelRouterService/PreviewRoutePlan, PolicyEngineService/Policy.Decide
Traces: events ModelRouterService/RoutePlanResolved
Traces: descriptors model-invocation-v1, policy-decision-v1
Traces: adrs ADR-0012, ADR-0014, ADR-0015
Traces: requirements FR-04, XL-04
Traces: scenarios SCN-ModelRouterService-007, SCN-ModelRouterService-009, SCN-ModelRouterService-017
Relates: screens model-profiles
Depends on AIFACTORY-US-567, AIFACTORY-US-569, AIFACTORY-US-572, feature:policy-engine-service
Sources model/services/model-compute/ModelRouterService.yaml, model/services/governance/PolicyEngineService.yaml, docs/reference/schemas/model-invocation.schema.json, docs/planes/model-compute/capability-router.md, docs/planes/model-compute/workflows.md, docs/planes/model-compute/services/model-router-service/index.md#sagas-and-long-running-flows

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-2293 Proto of the ModelGateway service and its mapping onto model-invocation-v1 contract The proto of the service fixes the request and reply messages of ResolveRoutePlan, Invoke, Embed and Rerank: each request carries the fields of model-invocation-v1 of docs/reference/schemas/model-invocation.schema.json as its header, the run and the attempt as optional members (D123), and the messages add what the schema does not hold, that is the route plan, profile version and candidates of a resolution, the messages, tool definitions and stream items of an invocation, and the vectors and scores of Embed and Rerank; the document records which fields a caller sends and which the service assigns, the mapping of the receipt statuses of the schema onto the five outcomes and three usage statuses of the model, and the gRPC status of every refusal in one table: UNAUTHENTICATED without a workload identity; PERMISSION_DENIED without the service scope and for a denying decision; INVALID_ARGUMENT for an invalid request, a capability the profile lacks and a profile of another modality; NOT_FOUND, failure class permanent, for a profile the tenant cannot read and for a runId for which the tenant of the caller holds no route plan of the profile, whether the run belongs to another tenant, does not exist or was never resolved; FAILED_PRECONDITION only for an idempotency key of Invoke, Embed or Rerank reused with another request hash, for a repeated ResolveRoutePlan of the same run and profile with a different input, and for a resolution in which no deployment passes the filters, each told apart by its error detail; DEADLINE_EXCEEDED for a provider call that exceeds the timeout or the deadline; UNAVAILABLE when PolicyEngineService or SecretBrokerService does not answer or no candidate is healthy; UNIMPLEMENTED for a rerank call whose deployment has no adapter behind the rerank adapter port; the request of ResolveRoutePlan names the policy revision the run pinned; golden files of the messages are checked in the pipeline. ConnectSoft.AI.SoftwareFactory.ModelRouterService
AIFACTORY-TASK-2294 Router filters and scoring, ResolveRoutePlan and the RoutePlanResolved event implementation One routing function filters the allowed deployments of a profile by state, tenant, privacy class, region, policy decision, capability thresholds, which a deployment whose approval basis is attestation passes without scores (D121), and a loaded adapter for the provider value, orders them by the weights of ModelAccess:Routing:Weights with a neutral value for a term without a source and the preference order between equal scores, appends the candidates of the fallback chain when the profile enables fallback, and returns the candidates with the reason of every exclusion; ResolveRoutePlan asks Policy.Decide under the policy revision the request names, persists the plan with the RoutePlanResolved outbox record in one transaction, keeps the project and the classification of the request in the columns ProjectId and Classification of the plan (D125) and the capabilities in its constraints, returns the stored plan on a repeat for the same run and profile with the same input, refuses a repeat whose profile version, policy revision, classification or capabilities differ with FAILED_PRECONDITION and the differing field named without changing the stored plan or publishing anything, and maps its refusals to the gRPC statuses of the contract. ConnectSoft.AI.SoftwareFactory.ModelRouterService
AIFACTORY-TASK-2295 PreviewRoutePlan as a dry run of the routing function implementation PreviewRoutePlan runs the routing function of AIFACTORY-TASK-2294 for a profile and a scope with the decision of Policy.Decide and returns the candidates in order, the filters applied and the exclusion reasons; it writes no plan and no outbox record; a profile of another tenant is answered 404, a missing scope 403 and an unreachable policy engine 503. ConnectSoft.AI.SoftwareFactory.ModelRouterService
AIFACTORY-TASK-2296 Verify the resolution, the preview and the route plan event through the acceptance suite verification Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-ModelRouterService-007\|Scenario=SCN-ModelRouterService-009\|Scenario=SCN-ModelRouterService-017)"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-573 with a fake of Policy.Decide that permits, denies and stops answering, deployments in every state and of every excluded kind, a self-hosted deployment excluded because no adapter serves its provider, a deployment approved by attestation that is a candidate without capability scores, a repeat with the same input after a newer policy revision became active, a repeat for the same run and profile with another profile version, another policy revision, another classification and another capability set, each refused with FAILED_PRECONDITION while the stored plan and the outbox stay unchanged, a two-tenant fixture, the golden files of the proto and the publication and payload of RoutePlanResolved; consumer handling is proven by the suite of the consumer. ConnectSoft.AI.SoftwareFactory.ModelRouterService

AIFACTORY-US-574: Invoke a chat model through the route plan under a policy decision and a brokered credential, stream the output and end with a receipt that names the deployment and the usage status

behavior · persona requester As a requester, I want every model call of my run to be allowed by policy, made with a brokered credential and recorded with the model that really answered and what it used, so that I can trust the cost and the provenance of what the Factory produced for me.

An agent host calls a model only through the Factory model client of the AI libraries (feature component-extensions-ai) and the gateway; it never names a provider and never holds a provider credential. AgentRuntimeService, with a workload identity whose token holds the service scope that names ModelRouterService, calls the internal gRPC server stream ModelGateway.Invoke with model-invocation-v1: invocation id, profile, the trusted scope with tenant and project, run, step and attempt, the hash of the canonical request, an idempotency key, the classification, the capabilities asked for, the budget (input and output token limits, cost limit, deadline), the stream switch and the reference of an output schema when structured output is required. The messages and tool definitions travel in the request and are never stored. The pipeline has eight steps. First, the idempotency key is looked up within tenant and project: the same key with the same request hash returns the existing receipt and makes no second provider call, and the same key with another hash is refused with FAILED_PRECONDITION (ADR-0014 decision 3). Second, the route plan of the run and profile is read under the tenant row filter. The router holds no run: a run is known to it only through a route plan or a receipt of the tenant (AIFACTORY-US-577). A runId for which the tenant of the caller holds no route plan of that profile is therefore answered NOT_FOUND, failure class permanent for the attempt (ADR-0015 amendments D113 and D114), whether the run belongs to another tenant, does not exist or was never resolved: under the row filter the three cases are one observable condition, and one answer never confirms that a run exists elsewhere. Third, PolicyEngineService/Policy.Decide decides the invocation from profile, data class, region and the tools of the request under the policy revision of the plan, and its decision id goes on the receipt. The tool definitions of the request are part of that decision: a tool outside the set the decision permits for the caller, that is outside the closure of its release, makes the decision deny, so the pipeline refuses it as it refuses every denial and forwards no such tool to a provider. A denial writes a receipt with the outcome Denied, calls no adapter, counts connectsoft.factory.model_gateway.denials and ends the call with PERMISSION_DENIED and the decision id. The column DeploymentId of a receipt and the field deploymentId of ModelInvoked are required, and a denied call has no deployment that produced an output; the Denied receipt therefore names the first candidate of the route plan, the deployment the plan would have tried first, with no token count, and that the model gives a Denied receipt no deployment is reported as a model correction. When the policy engine does not answer the call fails closed with UNAVAILABLE and no adapter is called. Fourth, the first candidate of the plan that is Approved and healthy is chosen, and one short-lived credential for it is issued by SecretBrokerService/SecretBroker.Issue, which receives the decision id of step three and the purpose model-invoke; the credential serves this one invocation and is kept for no later one (the rule of AIFACTORY-US-568). When the broker does not answer the call fails fast with UNAVAILABLE. Fifth, the adapter of the provider, a keyed chat client of the pinned AI library, is called with streaming, tools and structured output, bounded by the lower of the token limits of the profile and of the budget and by the lower of ModelAccess:Invocation:DefaultTimeoutSeconds and the deadline, with provider prompt caching when ModelAccess:Invocation:PromptCaching is on and the adapter supports it, the cache keys being hashes. Sixth, tokens are streamed to the caller as they arrive and a cancellation of the caller is propagated to the adapter. Seventh, the output is stored by hash through ArtifactService/Artifacts.Store under the retention of the tenant and its reference goes on the receipt; when ArtifactService does not answer, the output still reaches the caller and the receipt carries no output reference. Eighth, the InvocationReceipt is written with invocation, tenant, project, run, attempt, profile, the deployment that produced the output, route plan, request hash, idempotency key, policy decision, outcome, usage status, tokens, latency and times, together with the ModelInvoked outbox record, in one transaction, and the stream ends with the receipt. The outcome is Completed, Partial, Failed, Denied or Cancelled. The usage status is Reported when the adapter response carries usage, with input and output tokens as the provider stated them, and Unknown when it carries none; Unknown is never written as zero, counts in connectsoft.factory.model_gateway.usage_unknown and waits for reconciliation (AIFACTORY-US-577). Three ends of a call other than completion are fixed here. When the provider exceeds the lower of ModelAccess:Invocation:DefaultTimeoutSeconds and the deadline before any output, the adapter call is cancelled, the receipt is Failed with usage Unknown and the status is DEADLINE_EXCEEDED. When the caller cancels before any output, the adapter call is cancelled and the receipt is Cancelled with usage Unknown. Neither proves that no billable work happened, which is why the usage is Unknown and never zero. When the call ends after output was emitted, by a cancellation of the caller, by a broken connection, which the router cannot tell from a cancellation, or by the timeout, the receipt is Partial under the rule of AIFACTORY-US-575. One case stays open. A replica of the router that stops after the adapter was reached and before the receipt was committed leaves no receipt, although the invariant of the model demands one for every invocation that reached an adapter. The outcome of a receipt is required and has five terminal values and none for a call in flight, so this delivery opens no receipt row before the adapter call; the caller repeats under the same idempotency key, finds no receipt and the call runs again, and the gap shows in the series of the objective receipt-coverage (AIFACTORY-US-568). How the invariant is kept across a stopped replica is reported to the owner. The receipt holds the priceBasis of the profile as its pricing revision. ModelRouterService owns no price table, so estimatedCostUsd stays empty and the cost limit of a budget is not evaluated by the router in this delivery; prices, units and estimation rules are inputs of the owner and are not invented, and the point is reported. After the commit the router calls CostUsageService/Usage.RecordUsage once per token meter with the receipt as the source. When CostUsageService does not answer, the call fails fast and is not repeated, the output and the receipt stand, and the usage reaches CostUsageService through ModelInvoked, which it records once per meter under the same receipt. CostUsageService stores a receipt without a valid price or with an unknown quantity as Uncertain and prices it later, so the router never keeps and repeats a receipt for a missing price, and a budget overrun stops only the run whose usage crossed the limit, through RunControlService and not through the router (D117, D119). The dependency row of the model also names reservation checks against the run budget; CostUsageService admits ModelRouterService to Usage.RecordUsage only and RunControlService reserves the budget of a run, so the router makes no reservation call, which is reported. Since decision D121 the method has a second caller. ModelGatewayHost serves the OpenAI-compatible route CreateChatCompletion (feature model-gateway-host), translates the call into model-invocation-v1 and calls ModelGateway.Invoke with the token the caller presented, forwarded unchanged. The router validates that token again and accepts the audience of its own gateway (ADR-0015 amendment D117); the tenant of the call comes from the token and never from the message. A call of that route is of one of two kinds (decision D123), and the kind of token decides the kind of call (decision D125). A run-bound call presents the token of an attempt: the short-lived token that RunControlService hands out in the attemptToken member of the lease answer, which the Authorization Server issues by a token exchange (feature component-auth-server-template-factory-tokens) and which names the run, the step and the attempt in the claims run_id, step_id and attempt_id beside the tenant claim tid. The router takes run, step and attempt from those claims and never from the message. It is an invocation of that run: the router reads the route plan of the run and profile, and takes the project, the classification and the pinned profile version from that plan, which keeps the project and the classification of the request of ResolveRoutePlan (AIFACTORY-US-573); the pipeline runs its eight steps with that plan, the receipt carries the run and the attempt, the usage counts on the reservation of the run, and the receipt is listed with the other receipts of the run (AIFACTORY-US-577). A run of the token for which the tenant holds no route plan of the profile is answered NOT_FOUND like every unknown run. A call that presents a user token is a call outside a run, and the user token must carry the scope factory.models.invoke. A call outside a run names no run and no attempt, which are optional members of model-invocation-v1. Its project is the one the caller named in the OpenAI-Project header and the gateway checked against the roles of the token, and its classification is the one the gateway took from ModelGateway:Protocols:OpenAiCompatibleClassification. The candidates are resolved for the call under the same filters, the same policy decision and the same scoring as a resolution, with no plan persisted, the rule of a call outside a run (AIFACTORY-US-576). From there the pipeline is the one of steps three to eight, and the call produces a receipt like any other invocation, without run, attempt and route plan, with the tenant and the project of the call and with ModelInvoked in the same transaction. Its usage is recorded through CostUsageService/Usage.RecordUsage without a run, and CostUsageService meters it on the budget of the project without a reservation; the receipt is read back through the receipt read of the project, which needs no run (AIFACTORY-US-901). In both kinds the profile of the invocation is named by its model profile id, the model name the caller sent: for a run-bound call it resolves to the version pinned by the snapshot of the run, the version the route plan of the run and profile holds, and otherwise to the active version of the profile the tenant can read. A user token without factory.models.invoke is refused with PERMISSION_DENIED, and a model name that no profile the tenant can read answers to with NOT_FOUND. The router still makes no reservation call and evaluates no cost limit itself; what stops the calls outside a run of a project whose budget is above its limit is the budget mark (decision D125, AIFACTORY-US-1508). ModelRouterService keeps a mark for a project from BudgetExceeded of CostUsageService, whether or not the event names a run, and clears it on a BudgetUpdated that puts the committed amount at or below the limit or at the turn of the budget period. Before step three, while a mark is in force for the project of a call outside a run, the call is refused with RESOURCE_EXHAUSTED, which the gateway translates to 429, and no decision, credential, adapter call or receipt follows. A run-bound call is not refused by the mark, because the budget of a run is reserved and stopped by RunControlService. A call without a workload identity, without a forwarded user token and without the token of an attempt is refused with UNAUTHENTICATED, a workload token that is not the token of an attempt and lacks the service scope with PERMISSION_DENIED, a call outside a run of a project under a budget mark with RESOURCE_EXHAUSTED, with an invalid request, a capability the profile does not provide or a profile of another modality with INVALID_ARGUMENT, and for a profile the tenant cannot read, or a run for which the tenant holds no route plan of the profile, with NOT_FOUND, which the attempt takes as the failure class permanent. FAILED_PRECONDITION is the answer for one case only, the idempotency key reused with another request hash. ModelInvoked is published on model-access.invocations.v1.model-invoked with invocationId, tenantId, projectId, runId and attemptId, both absent for a call outside a run (decision D123), profileId, deploymentId, outcome, usageStatus, inputTokens, outputTokens and estimatedCostUsd, the three last absent when unknown; this PBI proves what the publisher can prove, and CostUsageService, DashboardService and QualityScoreService handle it in their own PBIs. No prompt, completion or tool output is stored in model-router-sql, logged, put on an activity or carried by the event (ADR-0019). The acceptance environment runs a scripted provider adapter in place of a commercial provider.

Acceptance criteria

AC1 Given a workload identity with the service scope, a resolved route plan whose first candidate is Approved and healthy, a permitting decision and the scripted provider reporting usage, when ModelRouterService/ModelGateway.Invoke is called with a model-invocation-v1 and the stream switch on, then PolicyEngineService/Policy.Decide and SecretBrokerService/SecretBroker.Issue are each called once, the second with the decision id of the first and the purpose model-invoke, the tokens reach the caller in order, the stream ends with the receipt, and the ModelRouterService/InvocationReceipt with the deployment that answered, the decision id, the outcome Completed and usage Reported is written together with the ModelRouterService/ModelInvoked outbox record in one transaction; given a user token forwarded by ModelGatewayHost whose scope carries factory.models.invoke and an invocation that names a profile by its model profile id and no run, when the method is called, then the receipt carries the tenant of the token and the project of the invocation, the active version of the profile is used, the candidates are resolved for the call, no ModelRouterService/RoutePlan is persisted, the receipt, without run, attempt and route plan, is written with its ModelRouterService/ModelInvoked record, and CostUsageService/Usage.RecordUsage receives the usage without a run; given the token of an attempt forwarded by ModelGatewayHost, whose claims run_id, step_id and attempt_id name a run with a resolved plan, then the run, the step and the attempt are taken from the claims, the project, the classification and the profile version are taken from the ModelRouterService/RoutePlan of the run and profile, and the receipt carries the run and the attempt; a user token without that scope is answered PERMISSION_DENIED and no adapter is called (SCN-ModelRouterService-010, ADR-0014, FR-04, docs/reference/schemas/attempt-outcome.schema.json).
AC2 Given a completed invocation, when ModelRouterService/ModelGateway.Invoke is called again with the same idempotency key and the same request hash, then the existing receipt is returned and the provider is not called; with the same key and another hash the status is FAILED_PRECONDITION, the only case of that status; without a workload identity UNAUTHENTICATED, without the service scope PERMISSION_DENIED, with an invalid request or a capability the profile lacks INVALID_ARGUMENT; for a runId for which the tenant of the caller holds no route plan of the profile the status is NOT_FOUND, failure class permanent, the same answer whether the run belongs to another tenant, does not exist or was never resolved; for a call outside a run of a project under a budget mark the status is RESOURCE_EXHAUSTED, while a run-bound call of the same project is served; none of these refusals calls an adapter or writes a receipt (SCN-ModelRouterService-010, ADR-0015).
AC3 Given a decision of PolicyEngineService/Policy.Decide that denies, for the profile or because the request holds a tool definition outside the set the decision permits, when the model is invoked, then a receipt with the outcome Denied, the decision id and, as its deployment, the first candidate of the route plan is written with its ModelRouterService/ModelInvoked record, no adapter is called, no tool definition reaches a provider and the status is PERMISSION_DENIED; given the policy engine or SecretBrokerService/SecretBroker.Issue does not answer, then the status is UNAVAILABLE and no adapter is called, because no invocation runs without a decision and a credential (SCN-ModelRouterService-010, XL-04).
AC4 Given the scripted provider exceeds the lower of ModelAccess:Invocation:DefaultTimeoutSeconds and the deadline before any output, when ModelRouterService/ModelGateway.Invoke runs, then the adapter call is cancelled, the ModelRouterService/InvocationReceipt is Failed with usage Unknown and the status is DEADLINE_EXCEEDED; given the caller cancels before any output, then the adapter call is cancelled and the receipt is Cancelled with usage Unknown; given the call ends after output was emitted, by a cancellation of the caller, by a broken connection or by the timeout, then the receipt is Partial; in each case ModelRouterService/ModelInvoked is written with the receipt and no usage is written as zero (SCN-ModelRouterService-010, ADR-0014).
AC5 Given a provider that reports no usage, when the invocation completes, then the receipt has the usage status Unknown and no token count, never zero, and connectsoft.factory.model_gateway.usage_unknown rises (SCN-ModelRouterService-018); given CostUsageService/Usage.RecordUsage fails after the commit, then the call is not repeated, the output and the receipt stand and the router keeps no pending receipt (FR-09, model/services/control-plane/CostUsageService.yaml); given a receipt was written, when the outbox dispatcher publishes ModelRouterService/ModelInvoked on model-access.invocations.v1.model-invoked, then the event is sent in the run event envelope with invocationId, tenantId, projectId, runId and attemptId, both absent for a call outside a run, profileId, deploymentId, outcome and usageStatus and with the token counts only when known, it holds no prompt and no completion, and a transport outage is retried with backoff so the event is neither lost nor duplicated under its event id (SCN-ModelRouterService-018, ADR-0012, ADR-0019).
Traces: services ModelRouterService, PolicyEngineService, SecretBrokerService, CostUsageService, ArtifactService
Traces: aggregates ModelRouterService/InvocationReceipt, ModelRouterService/RoutePlan
Traces: apis ModelRouterService/ModelGateway.Invoke, PolicyEngineService/Policy.Decide, SecretBrokerService/SecretBroker.Issue, CostUsageService/Usage.RecordUsage, ArtifactService/Artifacts.Store
Traces: events ModelRouterService/ModelInvoked
Traces: descriptors model-invocation-v1, policy-decision-v1, usage-record-v1
Traces: adrs ADR-0002, ADR-0012, ADR-0014, ADR-0015, ADR-0019
Traces: requirements FR-04, FR-09, NFR-12, XL-04, XL-12
Traces: scenarios SCN-ModelRouterService-010, SCN-ModelRouterService-018
Relates: screens run-detail
Depends on AIFACTORY-US-567, AIFACTORY-US-568, AIFACTORY-US-573, AIFACTORY-US-1508, feature:policy-engine-service, feature:secret-broker-service, feature:cost-usage-service-complete, feature:artifact-service, feature:component-extensions-ai, feature:component-auth-server-template-factory-tokens
Sources model/services/model-compute/ModelRouterService.yaml, model/services/control-plane/CostUsageService.yaml, docs/reference/schemas/model-invocation.schema.json, docs/reference/schemas/attempt-outcome.schema.json, docs/planes/model-compute/model-gateway.md, docs/planes/model-compute/security.md, docs/planes/model-compute/services/model-router-service/index.md#context-and-boundaries

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-2297 Scripted provider adapter for the acceptance suite and the acceptance environment fixture A scripted chat adapter and a scripted embedding adapter take the keyed registration of one of the six modelled provider values, and a scripted rerank adapter is bound to the rerank adapter port of the service (AIFACTORY-US-576); a setting of the acceptance configuration names the provider value whose registration the scripted adapters take, so that RegisterDeployment accepts a deployment of that value without a provider value of its own for the scripted adapter; no production configuration holds the setting, and a start in the Production environment with the setting present stops with the setting named; the scripts answer with reported usage, answer without usage, stream and break after a number of tokens, fail before any output with a transient or a provider error, time out and stop answering, so that the suites of this feature and of the callers run without a commercial provider and without a key. ConnectSoft.AI.SoftwareFactory.ModelRouterService
AIFACTORY-TASK-2298 Invocation pipeline: idempotency, route plan, policy decision, brokered credential and the streamed adapter call implementation ModelGateway.Invoke looks up the idempotency key within tenant and project, reads the route plan of the run and profile under the tenant filter and answers NOT_FOUND when the tenant holds none, whether the run belongs to another tenant, does not exist or was never resolved, asks Policy.Decide under the policy revision of the plan with the tools of the request, chooses the first Approved and healthy candidate, takes one credential for this invocation from SecretBroker.Issue with the decision id and the purpose model-invoke, calls the keyed adapter with streaming, tools and structured output within the limits of profile and budget and the lower of the default timeout and the deadline, with prompt caching by hash where the adapter supports it, streams tokens to the caller, cancels the adapter call when the timeout or the deadline is exceeded (DEADLINE_EXCEEDED) and propagates a cancellation of the caller; a denial, also for a tool outside the set the decision permits (PERMISSION_DENIED), a missing plan (NOT_FOUND), a reused key with another hash (FAILED_PRECONDITION, the only case of that status) and an unreachable policy engine or broker (UNAVAILABLE) end as the contract of AIFACTORY-TASK-2293 states and call no adapter. ConnectSoft.AI.SoftwareFactory.ModelRouterService
AIFACTORY-TASK-3063 ModelGateway.Invoke under the forwarded token of an attempt for the run-bound calls and under a forwarded user token for the calls outside a run of the OpenAI-compatible route implementation ModelGateway.Invoke admits, beside a workload token with the service scope, the token of an attempt and a user token forwarded by ModelGatewayHost whose audience is the gateway of the service, the user token with the scope factory.models.invoke (D121), and serves the two kinds of call of the OpenAI-compatible route, the kind of token deciding the kind of call (D123, D125); the tenant is taken from the token in both; for the token of an attempt the run, the step and the attempt come from the claims run_id, step_id and attempt_id, the project, the classification and the profile version come from the route plan of the run and profile, the pipeline of AIFACTORY-TASK-2298 runs unchanged with that plan, and the receipt carries the run and the attempt; for a user token, an invocation that names no run and no attempt the project and the classification are those of the invocation, the model profile id is matched against the active profile versions the tenant can read (NOT_FOUND otherwise), the candidates are resolved for the call with the routing function of AIFACTORY-TASK-2294 and no plan is persisted, steps three to eight of the pipeline run unchanged and end with a receipt without run, attempt and route plan and its ModelInvoked outbox record, and the usage record of the call names no run; a call outside a run of a project under a budget mark is refused with RESOURCE_EXHAUSTED by the check of AIFACTORY-US-1508 and a run-bound call is not; a user token without the scope is refused with PERMISSION_DENIED before any decision, credential or adapter call. ConnectSoft.AI.SoftwareFactory.ModelRouterService
AIFACTORY-TASK-2299 Receipt with the ModelInvoked outbox record, the output artifact reference and the usage record implementation When a call ends, the InvocationReceipt is written with the deployment that answered, or for a Denied receipt the first candidate of the route plan because the column and the payload field are required, the decision id, the outcome (Failed with usage Unknown for a timeout before output, Cancelled with usage Unknown for a cancellation before output, Partial for an end after output), the usage status Reported or Unknown without a zero, the token counts where known, the price basis of the profile as pricing revision and no cost estimate, together with the ModelInvoked outbox record in one transaction; the output is stored through Artifacts.Store by hash and only its reference is kept, and a failed store leaves the reference empty; after the commit Usage.RecordUsage is called once per token meter with the receipt as source, with the run of the receipt or, for the receipt of a call outside a run, without a run (D123), and a failure is not repeated; the metrics invocations, latency, tokens, denials and usage_unknown are recorded. ConnectSoft.AI.SoftwareFactory.ModelRouterService
AIFACTORY-TASK-2300 Verify the invocation and the receipt event through the acceptance suite verification Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-ModelRouterService-010\|Scenario=SCN-ModelRouterService-018)"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-574 with the scripted provider adapter, fakes of Policy.Decide, SecretBroker.Issue, Usage.RecordUsage and Artifacts.Store that answer, deny and stop answering, an idempotent repeat, a reused key with another hash, a call under a forwarded user token with factory.models.invoke and without a run, whose receipt carries the tenant of the token, the project of the invocation and no run, attempt or route plan while no plan is persisted and whose usage record names no run, a run-bound call under the token of an attempt, whose run, step and attempt come from the claims and whose project, classification and profile version come from the route plan of its run, and whose receipt carries the run and the attempt, a call outside a run of a marked project (RESOURCE_EXHAUSTED) beside a run-bound call of the same project that is served, the call outside a run without the scope (PERMISSION_DENIED) and with a model profile id no active profile answers to (NOT_FOUND), a two-tenant fixture in which a run of the other tenant, an unknown run and a run without a resolved plan are each answered NOT_FOUND alike, a Denied receipt that names the first candidate of the plan, a request with a tool outside the permitted set, the scripted provider timing out before output (Failed, usage Unknown, DEADLINE_EXCEEDED), the caller cancelling before output (Cancelled, usage Unknown), a call ending after output by cancellation and by a broken connection (Partial), the decision id and the purpose model-invoke received by the fake of SecretBroker.Issue, a fake of Artifacts.Store that does not answer, after which the output reached the caller and the receipt has no output reference, a provider without usage, a scan of the stored rows and of the event for content, and the publication and payload of ModelInvoked; consumer handling is proven by the suites of the consumers. ConnectSoft.AI.SoftwareFactory.ModelRouterService

AIFACTORY-US-575: Skip a degraded deployment, fall back only to an equivalent-constraint candidate the profile allows, fail as transient when no candidate is healthy, and never splice a broken stream

behavior · persona operator As an operator, I want a failing provider to be handled by the rules of the profile and to be visible on the receipt, so that a run never silently changes its privacy class or its output guarantees to keep going.

What the router does when a provider fails is fixed by the profile and the route plan, never improvised at the call (XL-16). There are four cases. First, a candidate that is Degraded, unhealthy or Retired at the moment of the call is skipped without a call and without a change to the constraints of the plan, and the next candidate of the plan that is Approved and healthy is chosen; the skip is ordinary routing among deployments that met the same thresholds, the receipt names the deployment that answered, and no fallback is recorded for it. Second, a failed call. Runtime fallback is off unless the pinned profile sets fallbackEnabled. The option ModelAccess:Routing:FallbackEnabledByDefault, false by default, is read when a route plan is resolved: when it is true, a profile that names a fallback chain is treated as fallback enabled for that plan although its own switch is off, the chain still has to satisfy the same constraints, and a profile without a chain stays without fallback. The effective switch is fixed at resolution and kept with the plan, so a reloaded value of the option applies to plans resolved later and never to a resolved plan. This reading of the option is reported to the owner. With fallback off, a provider failure of the chosen candidate ends the invocation with a receipt of the outcome Failed, counted in connectsoft.factory.model_gateway.provider_errors by provider and class, and the caller decides. With fallback on, a provider failure of the class transient or provider that happens before any output was emitted moves the call to the next candidate of the plan that is Approved and healthy, within the deadline and the token limits of the budget. The receipt then names the deployment that produced the output and sets fallbackUsed, and the ModelFallbackUsed outbox record with invocationId, tenantId, profileId, fromDeploymentId, toDeploymentId and reason is written in the same transaction as the receipt and ModelInvoked; connectsoft.factory.model_gateway.fallbacks counts it by profile and reason. One invocation has one receipt. The candidates are fixed at resolution: for a profile with fallback enabled they include the deployments of the profiles in its fallbackChain that have the same or a stricter privacy class and the same tool and structured-output guarantees. A fallback never crosses to a less private class, a confidential workload never falls back to an external provider, and the router never adds a candidate at invocation time. A failure of the class policy or validation is never a reason for a fallback. Third, no healthy candidate. When every candidate of the plan is Degraded or Retired, no adapter is called and no receipt is written, the call ends with UNAVAILABLE and a reason that lists the degraded deployments, the attempt takes the failure class transient and retries within its budget, and operators see the degraded deployments through DeploymentStateChanged and the provider health gauge. When candidates were called and the last one failed, the receipt is Failed and names the last deployment that was called. Fourth, a stream that ends after output was emitted without the completion of the provider: the adapter stream throws, the call from the gateway breaks, the caller cancels, which the router cannot tell from a broken connection, or the timeout of AIFACTORY-US-574 is reached. The receipt has the outcome Partial with the output tokens emitted up to the break counted; the provider reported no final usage, so the usage status is Estimated when tokens were counted and Unknown otherwise, which is reported to the owner as the one rule of estimation this delivery applies. No fallback follows a partial stream: the output of another model is never spliced onto it, the stream ends with an error that carries the receipt reference, and the runtime decides what to do with the attempt. The router repeats no call on the same deployment. A retry is a new invocation of the caller under a new idempotency key; the same key returns the receipt of the failed call and makes no provider call. ModelFallbackUsed is published on model-access.invocations.v1.model-fallback-used; this PBI proves what the publisher can prove, and AuditService, which records it as evidence, and DashboardService handle it in their own PBIs.

Acceptance criteria

AC1 Given a route plan whose first candidate is Degraded and whose second is Approved and healthy, when ModelRouterService/ModelGateway.Invoke is called, then the first candidate is not called, the second answers, the receipt names the second deployment with fallbackUsed false, no fallback event is written and the constraints of the ModelRouterService/RoutePlan are unchanged (XL-16, model/services/model-compute/ModelRouterService.yaml).
AC2 Given a profile without fallback and a scripted provider that fails before any output, when the model is invoked, then no other candidate is called, the ModelRouterService/InvocationReceipt has the outcome Failed, connectsoft.factory.model_gateway.provider_errors counts the failure by provider and class and ModelRouterService/ModelInvoked is written with the receipt; a repeat under the same idempotency key returns that receipt and calls no provider (XL-04, FR-04).
AC3 Given a profile with fallback enabled, a plan whose candidates satisfy the same constraints and a first candidate that fails with a transient error before any output, when the model is invoked, then the next Approved and healthy candidate answers, the receipt names it and sets fallbackUsed, the ModelRouterService/ModelFallbackUsed outbox record with invocationId, tenantId, profileId, fromDeploymentId, toDeploymentId and reason is written in the same transaction as the receipt, and the dispatcher publishes it on model-access.invocations.v1.model-fallback-used with retry and without loss or duplicate under its event id; no candidate of a less private class is ever called (SCN-ModelRouterService-019, ADR-0012).
AC4 Given a plan whose candidates are all Degraded, when the model is invoked, then no adapter is called, no receipt is written, the status is UNAVAILABLE with a reason that lists the degraded deployments, and the attempt can retry as transient; given every candidate was called and failed, then the receipt is Failed and names the last deployment called (XL-16, model/services/model-compute/ModelRouterService.yaml).
AC5 Given a stream that breaks after output was emitted, when the invocation ends, then the receipt has the outcome Partial with the emitted output tokens counted and a usage status that is not Reported, no other candidate is called and no output of another model is appended, the stream ends with an error that carries the receipt reference, and ModelRouterService/ModelInvoked announces the Partial receipt; the same holds when the caller cancels after output was emitted (ADR-0014, model/services/model-compute/ModelRouterService.yaml).
Traces: services ModelRouterService
Traces: aggregates ModelRouterService/InvocationReceipt, ModelRouterService/RoutePlan, ModelRouterService/ModelDeployment, ModelRouterService/ModelProfile
Traces: apis ModelRouterService/ModelGateway.Invoke
Traces: events ModelRouterService/ModelFallbackUsed, ModelRouterService/ModelInvoked
Traces: adrs ADR-0012, ADR-0014
Traces: requirements FR-04, NFR-13, XL-04, XL-16
Traces: scenarios SCN-ModelRouterService-019
Relates: screens run-detail
Depends on AIFACTORY-US-572, AIFACTORY-US-574
Sources model/services/model-compute/ModelRouterService.yaml, docs/planes/model-compute/capability-router.md, docs/planes/model-compute/workflows.md, docs/planes/model-compute/services/model-router-service/index.md#failure-and-recovery

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-2301 Candidate selection at invocation, the fallback rule, the ModelFallbackUsed event and the Partial receipt implementation At invocation the pipeline skips a candidate that is not Approved and healthy, classifies an adapter failure as transient, policy, validation or provider, moves to the next healthy candidate only when the effective fallback switch of the plan is on, that is the profile sets fallbackEnabled or ModelAccess:Routing:FallbackEnabledByDefault was true at resolution for a profile that names a fallback chain, and no output was emitted, writes ModelFallbackUsed in the transaction of the receipt, ends with UNAVAILABLE and the list of degraded deployments when no candidate is healthy, writes a Partial receipt with the emitted tokens counted when a stream breaks and calls no further candidate after output; the metrics fallbacks and provider_errors are recorded and no call is repeated on the same deployment. ConnectSoft.AI.SoftwareFactory.ModelRouterService
AIFACTORY-TASK-2302 Runbook of the five failure modes of ModelRouterService documentation The repository documentation holds one runbook entry per failure mode of model/services/model-compute/ModelRouterService.yaml (provider reports no usage, all candidates degraded, stream broken after partial output, evaluation suite unavailable, policy engine unreachable) with its detection signal, the answer of the service, the receipt it leaves and the recovery step, and states that no fallback crosses a privacy class and that a broken stream is never spliced (XL-16). ConnectSoft.AI.SoftwareFactory.ModelRouterService
AIFACTORY-TASK-2303 Verify the skip, the fallback, the exhausted candidates and the partial stream through the acceptance suite verification Run dotnet test -c Release --filter "Category=Acceptance&Scenario=SCN-ModelRouterService-019"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-575 with the scripts of the scripted provider adapter: a Degraded first candidate, a failure with fallback off and on, a fallback chain with a weaker privacy class that is never called, all candidates Degraded, all candidates failing, a stream that breaks after output, a caller that cancels after output, a profile without its own fallback switch resolved once with ModelAccess:Routing:FallbackEnabledByDefault true and once false, the option reloaded after a plan was resolved without a change to that plan, and the publication and payload of ModelFallbackUsed; consumer handling is proven by the suites of the consumers. ConnectSoft.AI.SoftwareFactory.ModelRouterService

AIFACTORY-US-576: Serve embeddings and reranking through an embedding or reranker profile with a receipt for every call

behavior · persona operator As an operator, I want embedding and reranking calls to pass the same pipeline as a chat call, so that they are allowed by policy, attributed to a tenant and a project and receipted like every other model call.

The Knowledge services need embeddings and reranking without an agent host: the model names KnowledgeIngestionService as the caller of Embed and KnowledgeSearchService as the caller of Rerank and Embed. A caller reaches the internal gRPC methods ModelGateway.Embed and ModelGateway.Rerank through the gateway with a workload identity whose token holds the service scope that names ModelRouterService and forwards the tenant and project of its own call, which the router reads only under that scope (ADR-0015 amendment D114). Embedding and reranking stay in I1 behind ports and are proven with fixtures (decision D121). In this increment the two methods have no caller: the Knowledge services are delivered thin in I1 and call nothing, their complete deliveries arrive in I5 and their gateway in I3. Their profiles are seeded: embedding and reranker are among the eleven profiles of model/model-profiles.yaml that the thin AgentRegistryService seeds as Draft releases and the router loads (decision D123, AIFACTORY-US-569), so a call on a deployed I1 instance finds its profile and then needs an Approved and healthy deployment that the profile allows. The methods are delivered and proven here with fixture profiles and the scripted adapters. Both methods are unary and of the class spend and run the pipeline of AIFACTORY-US-574 with three differences. The profile must be of the modality of the method, Embedding for Embed and Rerank for Rerank; another modality is refused with INVALID_ARGUMENT. The run and the attempt are optional on a receipt: a call inside a run uses the route plan of the run and profile, and a runId for which the tenant of the caller holds no route plan of that profile is answered NOT_FOUND, failure class permanent, whether the run belongs to another tenant, does not exist or was never resolved, the one answer Invoke gives (AIFACTORY-US-574); a call outside a run, such as an ingestion, resolves the candidates for the call under the same filters, the same policy decision and the same scoring and persists no plan, because a plan belongs to a run. The usage of a call outside a run is recorded without a run and metered on the budget of its project without a reservation, and its receipt is listed with the receipts of its project that name no run (AIFACTORY-US-901, decision D123). The reply carries the vectors or the ranked scores with the receipt; they are returned to the caller, are not stored by this service and no output artifact is written for them. For an embedding profile the reply names the embeddingCompatibility of the profile version, the embedding space a knowledge index is pinned to (ADR-0013 decision 1), so that a caller can refuse to mix spaces; the router never changes it for a profile version. The two ports differ. Embed runs behind the embedding generator abstraction of the pinned AI library and calls the generator the library registers for the provider of the deployment. For Rerank the AI library has no adapter today: ConnectSoft.Extensions.AI registers keyed chat clients and embedding generators only (docs/planes/model-compute/providers-and-profiles.md). A provider adapter is library code and is not written in this repository (AIFACTORY-US-566). ModelGateway.Rerank is therefore delivered behind one rerank adapter port of the service and proven with the scripted rerank adapter of AIFACTORY-TASK-2297 bound to that port, and the port stays a port of the service until the AI library publishes a rerank adapter (decision D121). Feature component-extensions-ai delivers the keyed rerank adapter abstraction in the repository ConnectSoft.Extensions.AI (AIFACTORY-US-758), and this PBI depends on that feature by its version pin: from the pinned version on, the port resolves the keyed rerank adapter the library registers for the provider of the deployment, as the keyed chat clients are resolved, and the scripted adapter of the acceptance suite implements the same abstraction. The abstraction brings no provider implementation with it, so a rerank call whose candidate has no adapter behind the port, as on a deployed instance of this increment, calls no provider, writes no receipt, because no adapter was reached, and ends with UNIMPLEMENTED and the provider named. Everything else is the same: the policy decision per call with the fail-closed rule, a Denied receipt that names the first candidate of the plan or, outside a run, of the candidates resolved for the call, the brokered credential issued for the one call, the receipt with the deployment that answered, ModelInvoked in the same transaction, the usage to CostUsageService, the skip of a degraded candidate and the fallback rule of AIFACTORY-US-575. The idempotency key within tenant and project returns the existing receipt and makes no second provider call; the vectors are not kept by the router, so a caller that lost the reply repeats under a new key. The usage a provider reports for an embedding or a rerank call is recorded as input tokens; a provider that reports none leaves the receipt Unknown. In which unit a rerank call is metered and priced is an input of the owner and is not invented here. A call without a workload identity is refused with UNAUTHENTICATED, without the service scope with PERMISSION_DENIED, with an invalid request with INVALID_ARGUMENT and for a profile of another tenant, or inside a run without a route plan of the tenant for the profile, with NOT_FOUND; when PolicyEngineService or the Secret Broker does not answer, or no candidate is healthy, the status is UNAVAILABLE and no provider is called. The run and the attempt are optional members of model-invocation-v1 since decision D123, as they are on the receipt of the model, and the proto of AIFACTORY-TASK-2293 carries both as optional.

Acceptance criteria

AC1 Given a workload identity with the service scope and an active profile of the modality Embedding with an Approved and healthy deployment, when ModelRouterService/ModelGateway.Embed is called inside a run with a resolved plan, then the reply carries the vectors, the embedding compatibility of the profile version and the receipt, the ModelRouterService/InvocationReceipt with the deployment that answered and the ModelRouterService/ModelInvoked outbox record are written in one transaction, and the vectors are stored nowhere in model-router-sql (SCN-ModelRouterService-011, ADR-0013).
AC2 Given an active fixture profile of the modality Rerank and the scripted rerank adapter bound to the rerank adapter port of the service, when ModelRouterService/ModelGateway.Rerank is called, then the reply carries the ranked scores and the receipt, the receipt and ModelRouterService/ModelInvoked are written in one transaction, and a provider that reports no usage leaves the receipt Unknown without a zero; given a candidate whose provider has no adapter behind the port, as on a deployed instance until a keyed rerank adapter of the pinned ConnectSoft.Extensions.AI serves that provider, then no provider is called, no receipt is written and the status is UNIMPLEMENTED with the provider named (SCN-ModelRouterService-012, FR-04, docs/planes/model-compute/providers-and-profiles.md).
AC3 Given a Knowledge caller outside a run, when ModelRouterService/ModelGateway.Embed is called without a run and an attempt, then the candidates are resolved for the call under the same filters and the same policy decision, no route plan is persisted, the receipt has no run, no attempt and no route plan, and it carries the tenant and project the caller forwarded under the service scope (SCN-ModelRouterService-011, ADR-0015).
AC4 Given a caller without a workload identity, a token without the service scope, a profile of the wrong modality, a profile of another tenant, a call inside a run for which the tenant of the caller holds no route plan of the profile, a denying decision, or a policy engine that does not answer, when either method is called, then the status is UNAUTHENTICATED, PERMISSION_DENIED, INVALID_ARGUMENT, NOT_FOUND, NOT_FOUND, PERMISSION_DENIED or UNAVAILABLE respectively and no provider is called; the NOT_FOUND of the run is the same whether the run belongs to another tenant, does not exist or was never resolved; a repeat under the same idempotency key returns the existing receipt and calls no provider (SCN-ModelRouterService-011, SCN-ModelRouterService-012, ADR-0015).
Traces: services ModelRouterService
Traces: aggregates ModelRouterService/InvocationReceipt
Traces: apis ModelRouterService/ModelGateway.Embed, ModelRouterService/ModelGateway.Rerank
Traces: events ModelRouterService/ModelInvoked
Traces: descriptors model-invocation-v1
Traces: adrs ADR-0013, ADR-0015
Traces: requirements FR-04, NFR-13
Traces: scenarios SCN-ModelRouterService-011, SCN-ModelRouterService-012
Depends on AIFACTORY-US-574, AIFACTORY-US-575, feature:component-extensions-ai
Sources model/services/model-compute/ModelRouterService.yaml, docs/planes/model-compute/providers-and-profiles.md, docs/architecture/adr/0013-vector-store-profiles.md, docs/planes/model-compute/workflows.md, docs/planes/model-compute/services/model-router-service/index.md#apis

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-2304 ModelGateway.Embed and ModelGateway.Rerank on the invocation pipeline implementation Embed and Rerank run the pipeline of ModelGateway.Invoke as unary calls: Embed calls the embedding generator the pinned AI library registers for the provider of the deployment, and Rerank calls one rerank adapter port of the service, which stays a port of the service until the AI library publishes a rerank adapter (D121) and behind which this repository binds no provider adapter, because a provider adapter is library code; once the service pins the version of ConnectSoft.Extensions.AI that holds the keyed rerank adapter abstraction of AIFACTORY-US-758, the port resolves the keyed rerank adapter the library registers for the provider of the deployment and the scripted adapter implements that abstraction; a rerank call whose candidate has no adapter behind the port ends with UNIMPLEMENTED and the provider named, calls no provider and writes no receipt; both methods require a profile of their modality, use the route plan of a run, answer NOT_FOUND for a run for which the tenant holds no route plan of the profile, or resolve the candidates for a call outside a run without persisting a plan, return the vectors with the embedding compatibility of the profile version or the ranked scores together with the receipt, store neither vectors nor scores, write the receipt with the ModelInvoked outbox record in one transaction and record reported usage as input tokens or leave it Unknown. ConnectSoft.AI.SoftwareFactory.ModelRouterService
AIFACTORY-TASK-2305 Verify the embedding and rerank calls through the acceptance suite verification Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-ModelRouterService-011\|Scenario=SCN-ModelRouterService-012)"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-576 with fixture profiles of the modalities Embedding and Rerank, the scripted embedding adapter and the scripted rerank adapter of AIFACTORY-TASK-2297 bound to the rerank adapter port, a rerank call with no adapter behind the port (UNIMPLEMENTED, no provider call, no receipt), a call inside a run and one outside a run, a call inside a run of another tenant, of an unknown run and of a run without a resolved plan, each answered NOT_FOUND alike, a profile of the wrong modality, a two-tenant fixture, a denying decision, an idempotent repeat and a scan of the store for vectors. ConnectSoft.AI.SoftwareFactory.ModelRouterService

AIFACTORY-US-577: Read the invocation receipts of a run and reconcile receipts whose usage is unknown or estimated

behavior · persona requester As a requester, I want to see for my run which model answered each call, what it used and how certain that usage is, so that I can account for the run without anybody presenting unknown usage as zero.

Receipts are the evidence of every model call (FR-04, FUX-08). A caller whose scope carries factory.runs.read, a requester on the run detail, an operator or an observer, reads the receipts of a run through the gateway route of ListRunReceipts: per receipt the invocation, the attempt, the profile, the deployment that answered, the request hash, the outcome, the usage status with tokens where known, whether a fallback was taken, the policy decision id, the latency, the output artifact reference and the times, ordered by start and paged, over the index on run and attempt. Unknown usage is shown as unknown, never as zero. The tenant comes from the token and the query runs under the tenant row filter. The router holds no run: a run is known to it when a route plan or a receipt of the tenant names it, and a runId for which neither exists is answered 404, the same answer for a run of another tenant and for a run that does not exist (ADR-0015 amendment D113); a run with a plan and no receipt yet is answered 200 with an empty list. The receipt of a run-bound call of the OpenAI-compatible route of ModelGatewayHost carries the run and the attempt of its token and is listed here with the other receipts of the run; a receipt that names no run is never returned by this operation and is read through ListProjectReceipts (AIFACTORY-US-901, decision D123). A caller without the scope is answered 403. The project check has one limit that comes from the model. A receipt names its project, so for a run with at least one receipt a caller whose role claims do not admit the project the receipts name is answered 403. A route plan names no project: RoutePlans holds run, tenant, profile, version, revision, candidates, constraints and time, although ResolveRoutePlan receives the project of the run. For a run that has a plan and no receipt the project is therefore unknown to this service and the check cannot be made, so such a run is answered 200 with an empty list to every caller of the tenant who holds the scope. An empty list holds no data of the project and discloses only that a run of the tenant resolved a plan, but the same caller can receive 200 before the first receipt and 403 after it. The limit is named here, and that RoutePlan carries no projectId is reported as a model correction; this delivery adds no column the model does not list. No response holds prompt or completion content, which this service never stores. The ReceiptReconciler runs at minute 30 of every hour over the receipts whose usage status is Unknown or Estimated and that are older than one hour, two tenants in parallel, with five attempts and exponential backoff from 60 seconds, idempotent on invocation and statement reference. For each receipt it asks one statement port for the usage a provider statement confirms. When a confirmation is found, the receipt gets the confirmed input and output tokens and the usage status Reported, a ModelInvoked outbox record with the corrected usage is written in the same transaction, which forwards the correction to CostUsageService as a later receipt of the same source, and connectsoft.factory.model_gateway.usage_unknown falls for a receipt that was Unknown. A receipt without a confirmation is left as it is: it is never zeroed, never guessed and never aged out. When the statement port fails and the five attempts are exhausted, the receipt is left unchanged and the next hourly run takes it up again. The model lists no route, no table and no consumed event through which a provider statement reaches this service, so no statement adapter is built or invented here: the worker, its schedule, its idempotency and the port are delivered and proven with a fixture source, a deployed instance confirms nothing until an adapter exists, and that is reported to the owner. CostUsageService meanwhile holds the same usage as Uncertain and reconciles it by its own worker, so nothing is lost while the port has no source.

Acceptance criteria

AC1 Given a run of the tenant of the caller with receipts of the outcomes Completed, Partial and Denied, one of them with usage Unknown, when a caller with factory.runs.read and a role in the project calls ModelRouterService/ListRunReceipts, then the response is 200 with the receipts ordered by start and paged, each with attempt, profile, deployment, request hash, outcome, usage status, fallback flag, decision id and output artifact reference, the Unknown receipt without a token count and never with zero, and no prompt or completion content (SCN-ModelRouterService-008, FUX-08).
AC2 Given a runId that only another tenant has receipts for, or that nobody has a plan or a receipt for, when ModelRouterService/ListRunReceipts is called, then the answer is 404, the same in both cases; given a run with a route plan and no receipt, then the answer is 200 with an empty list for every caller of the tenant who holds the scope, because a ModelRouterService/InvocationReceipt names the project and a route plan does not, as model/services/model-compute/ModelRouterService.yaml lists its columns; given a caller without factory.runs.read, then the answer is 403; given a run with at least one receipt and a caller without a role in the project the receipts name, then the answer is 403; nothing is written (SCN-ModelRouterService-008, ADR-0015).
AC3 Given a receipt with usage Unknown that is older than one hour and a fixture source behind the statement port that confirms its tokens, when the ReceiptReconciler runs, then the ModelRouterService/InvocationReceipt has the confirmed tokens and the usage status Reported, a ModelRouterService/ModelInvoked outbox record with the corrected usage is written in the same transaction, connectsoft.factory.model_gateway.usage_unknown falls by one, and the same confirmation offered again or the worker triggered twice confirms once (FR-09, XL-12).
AC4 Given receipts with usage Unknown or Estimated and no source behind the statement port, as on a deployed instance of this delivery, when the ReceiptReconciler runs, then no receipt changes, none is written as zero or dropped, nothing is published, and ModelRouterService/ListRunReceipts keeps showing the usage as unknown or estimated (FR-09, model/services/model-compute/ModelRouterService.yaml).
Traces: services ModelRouterService
Traces: aggregates ModelRouterService/InvocationReceipt
Traces: apis ModelRouterService/ListRunReceipts
Traces: events ModelRouterService/ModelInvoked
Traces: adrs ADR-0015, ADR-0019
Traces: requirements FR-09, FUX-08, NFR-12, XL-12
Traces: scenarios SCN-ModelRouterService-008
Relates: screens run-detail
Depends on AIFACTORY-US-574
Sources model/services/model-compute/ModelRouterService.yaml, model/services/control-plane/CostUsageService.yaml, docs/planes/trust-operations/finops.md, docs/planes/model-compute/services/model-router-service/index.md#workers-and-jobs

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-2306 ListRunReceipts over the receipts of a run under the tenant filter and the project role implementation ListRunReceipts returns the receipts of a run ordered by start and paged with attempt, profile, deployment, request hash, outcome, usage status, tokens where known, fallback flag, decision id, latency, output artifact reference and times; it answers 404 when neither a route plan nor a receipt of the tenant names the run, 403 for a missing scope, 403 for a caller without a role in the project that the receipts of the run name, and 200 with an empty list for a run with a plan only, for every caller of the tenant who holds the scope, because a route plan carries no project and the project check needs a receipt; the documentation of the operation states that limit; unknown usage is never serialised as zero. ConnectSoft.AI.SoftwareFactory.ModelRouterService
AIFACTORY-TASK-2307 ReceiptReconciler with the statement port implementation The worker reads the receipts with usage Unknown or Estimated older than one hour, asks the statement port for a confirmation keyed by invocation and statement reference, and on a confirmation sets the tokens and the usage status Reported with a ModelInvoked outbox record in the same transaction and lowers connectsoft.factory.model_gateway.usage_unknown; without a confirmation it changes nothing; the port has a fixture source in the acceptance suite and no adapter, because the model names no source of provider statements. ConnectSoft.AI.SoftwareFactory.ModelRouterService
AIFACTORY-TASK-2308 Verify the receipt read and the reconciliation through the acceptance suite verification Run dotnet test -c Release --filter "Category=Acceptance&Scenario=SCN-ModelRouterService-008" and dotnet test -c Release --filter "Category=Acceptance&Feature=ReceiptReconciliation"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-577 with a two-tenant fixture, receipts of every outcome, a run with a plan only read by a caller with and without a role in the project of the run (200 with an empty list for both), the same run after its first receipt (403 for the caller without the role), the role matrix, a fixture source behind the statement port, a repeated confirmation and a run of the worker without a source. ConnectSoft.AI.SoftwareFactory.ModelRouterService

AIFACTORY-US-901: Read the invocation receipts of a project that name no run, the receipts of the model calls made outside a run

behavior · persona requester As a requester, I want to see for my project which model answered each call made outside a run, what it used and how certain that usage is, so that the calls of my tools on the OpenAI-compatible route are accounted for like the calls of a run.

A call of the OpenAI-compatible route of ModelGatewayHost that is outside a run produces a receipt that names no run and no attempt (AIFACTORY-US-574, decision D123). ListRunReceipts never returns such a receipt, because it reads by run (AIFACTORY-US-577). Decision D123 therefore gives the service a second receipt read that needs no run: ListProjectReceipts, GET /factory/projects/{projectId}/model-receipts, a read operation on gateway role GW-03 with the scope factory.models.read. A caller whose token carries that scope and grants the project reads through the gateway route the invocation receipts of the project that name no run: per receipt the invocation, the profile, the deployment that answered, the request hash, the outcome, the usage status with tokens where known, whether a fallback was taken, the policy decision id, the latency, the output artifact reference and the times, ordered by start and paged. Unknown usage is shown as unknown, never as zero, and no response holds prompt or completion content, which this service never stores. The rule of the read is the receipt and not the route the call came by: every receipt of the tenant and the project whose run is empty is returned. In this increment these are the receipts of the calls outside a run on the OpenAI-compatible route; the receipt of an Embed or a Rerank call outside a run (AIFACTORY-US-576) names no run either and is returned by the same rule. A receipt that names a run is never returned here, the receipt of a run-bound call of the OpenAI-compatible route among them; it is listed with the receipts of its run. The project of the path is checked before the read is served. ModelGatewayHost fronts the operation and checks the projectId of the path against the role claims of the token: a project the token does not grant is answered 403, and the call does not reach this service (feature model-gateway-host, AIFACTORY-US-562). The service is reachable through its gateway only (ADR-0028 decision 3). It validates the forwarded token again, accepts the audience of its own gateway (ADR-0015 amendment D117), requires factory.models.read and answers 403 without it, takes the tenant from the token and runs the query under the tenant row filter with the project of the path. The operation lists the codes 200 and 403 and no 404: a project the token grants that has no such receipt is answered 200 with an empty list, and a receipt of another tenant is never returned, so the read confirms nothing about another tenant. Whether the service repeats the project check of the gateway on the role claims of the forwarded token is not stated by the model and is reported to the owner; this delivery builds the check the model names, the one of the gateway, and the scope check and the tenant filter of the service. The model lists no index for this read beyond the indexes of InvocationReceipts, and this delivery adds no index and no column the model does not list. The read writes nothing and publishes nothing. The receipts it returns were metered like every receipt: their usage was recorded without a run on the budget of the project without a reservation (AIFACTORY-US-574), and one whose usage is Unknown or Estimated is taken up by the ReceiptReconciler like any other receipt (AIFACTORY-US-577).

Acceptance criteria

AC1 Given receipts of a project of the tenant of the caller that name no run, of the outcomes Completed, Partial and Denied, one of them with usage Unknown, and receipts of the same project that name a run, when a caller with factory.models.read whose token grants the project calls ModelRouterService/ListProjectReceipts, then the response is 200 with the receipts that name no run only, ordered by start and paged, each with invocation, profile, deployment, request hash, outcome, usage status, fallback flag, decision id and output artifact reference, the Unknown receipt without a token count and never with zero, and no prompt or completion content; nothing is written (SCN-ModelRouterService-021, FUX-08).
AC2 Given a call outside a run under a forwarded user token that ended with a ModelRouterService/InvocationReceipt, a run-bound call under the token of an attempt for a run of the same project, and an embedding call outside a run of the same project, when ModelRouterService/ListProjectReceipts is called for the project, then the receipts of the first and the third call are returned with the tenant and the project of the call and without run, attempt and route plan, and the receipt of the run-bound call is absent, because it names its run and is listed with the receipts of that run (SCN-ModelRouterService-021, model/services/model-compute/ModelRouterService.yaml).
AC3 Given a caller without factory.models.read, when ModelRouterService/ListProjectReceipts is called, then the answer is 403 with a problem response; given a project the token grants that has no receipt without a run, then the answer is 200 with an empty list; given receipts of two tenants, then a caller of one tenant never receives a receipt of the other, because the query runs under the tenant row filter; no answer is 404 and no state changes (SCN-ModelRouterService-021, ADR-0015).
Traces: services ModelRouterService, ModelGatewayHost
Traces: aggregates ModelRouterService/InvocationReceipt
Traces: apis ModelRouterService/ListProjectReceipts
Traces: adrs ADR-0015, ADR-0019, ADR-0028
Traces: requirements FR-04, FUX-08
Traces: scenarios SCN-ModelRouterService-021
Depends on AIFACTORY-US-567, AIFACTORY-US-574
Sources model/services/model-compute/ModelRouterService.yaml, model/services/model-compute/ModelGatewayHost.yaml, model/services/control-plane/CostUsageService.yaml, docs/reference/schemas/model-invocation.schema.json, docs/planes/model-compute/services/model-router-service/index.md#apis

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-3631 Contract of the receipt read of a project contract The OpenAPI document of the service lists ListProjectReceipts, GET /factory/projects/{projectId}/model-receipts, with the scope factory.models.read, the codes 200 and 403 of model/services/model-compute/ModelRouterService.yaml, the paging members and the receipt view of ListRunReceipts without run, attempt and route plan; the description of the operation states that it returns only the receipts of the project that name no run, that a receipt with a run is read through ListRunReceipts, and that ModelGatewayHost checks the project of the path against the role claims of the token before it forwards the call (D123). ConnectSoft.AI.SoftwareFactory.ModelRouterService
AIFACTORY-TASK-3632 ListProjectReceipts over the receipts of a project that name no run under the tenant filter implementation ListProjectReceipts returns the receipts of the tenant of the token and the project of the path whose run is empty, ordered by start and paged, with invocation, profile, deployment, request hash, outcome, usage status, tokens where known, fallback flag, decision id, latency, output artifact reference and times; it requires factory.models.read (403), runs under the tenant row filter, answers 200 with an empty list for a project without such receipts and never 404, returns no receipt that names a run, adds no index and no column the model does not list, writes nothing and never serialises unknown usage as zero. ConnectSoft.AI.SoftwareFactory.ModelRouterService
AIFACTORY-TASK-3633 Verify the receipt read of a project through the acceptance suite verification Run dotnet test -c Release --filter "Category=Acceptance&Scenario=SCN-ModelRouterService-021"; a zero-match filter counts as a failure; the tests prove AC1 to AC3 of AIFACTORY-US-901 with a two-tenant fixture, receipts of one project with and without a run and of every outcome, one with usage Unknown, a receipt written by a call outside a run under a forwarded user token, one written by a run-bound call under the token of an attempt and one written by an embedding call outside a run, a project without receipts, a caller without the scope, more receipts than one page, and a scan of the response for prompt and completion content. ConnectSoft.AI.SoftwareFactory.ModelRouterService

AIFACTORY-US-1508: Keep a budget mark for a project from BudgetExceeded, clear it from BudgetUpdated or at the turn of the period, and refuse the calls outside a run of a marked project

behavior · persona operator As an operator, I want model calls made outside a run to stop for a project whose budget is exceeded, so that a project cannot keep spending through the OpenAI-compatible route after its budget has run out.

A run stops on its budget through RunControlService, which reserves the budget of the run; a call of the OpenAI-compatible route that is made outside a run has no reservation, and the router makes no reservation call and evaluates no cost limit itself. What stops such calls is a mark the router keeps for the project (decision D125). ModelRouterService consumes BudgetExceeded and BudgetUpdated of CostUsageService through the inbox of the model-router messaging profile (AIFACTORY-US-567), with deduplication on the event id. The handler MarkProjectBudgetExceeded keeps, for the tenant and the project the event names, one ProjectBudgetMark in the table ProjectBudgetMarks with the budget id, the turn of the budget period from periodEndsAt, which is absent for a total budget, and the time it was marked. An event sets the mark whether or not it names a run: CostUsageService publishes it for the project without a run when usage recorded outside a run crosses the limit, and once per run when the usage of a run crosses it. A second event for a project already marked keeps one mark and updates its budget and its period. An event that names no project sets no mark, because the mark is kept per project. The handler ClearProjectBudgetMark removes the mark of the project when a BudgetUpdated puts committedUsd at or below limitUsd; an event that leaves the committed amount above the limit changes nothing. The mark of a monthly budget is no longer in force from the instant it keeps in PeriodEndsAt, so the turn of the period clears it without an event; the mark of a total budget keeps no such instant and is cleared by BudgetUpdated alone. ModelGateway.Invoke checks the mark before the policy decision of its pipeline (AIFACTORY-US-574). While a mark is in force for the project of a call outside a run, the call is refused with RESOURCE_EXHAUSTED, which ModelGatewayHost translates to 429, and no decision, credential, adapter call or receipt follows. A run-bound call, which presents the token of an attempt, is not refused by the mark, because its budget is the reservation of its run. The handlers publish nothing. A mark is a row of the tenant under the row filter, and a mark of one tenant never refuses a call of another. The mark lives in the store of the service, so every replica reads the same mark and a restart keeps it; an event that arrives while the store does not answer is retried by the inbox and is not lost.

Acceptance criteria

AC1 Given a fixture publisher of CostUsageService/BudgetExceeded for a project, once without a run and once with a run, each delivered twice, when the handler MarkProjectBudgetExceeded runs, then one mark for the tenant and the project is kept in ProjectBudgetMarks with the budget id, the turn of the period and the time it was marked, the second delivery of an event id has no effect, and nothing is published (model/services/model-compute/ModelRouterService.yaml, ADR-0012).
AC2 Given a marked project, when ModelRouterService/ModelGateway.Invoke is called outside a run of that project under a user token, then the status is RESOURCE_EXHAUSTED and no policy decision, credential, adapter call or ModelRouterService/InvocationReceipt follows; when a run-bound call of the same project is made under the token of an attempt, then it is served and ends with its receipt; a call of another project or of another tenant is not refused (FR-09, model/services/control-plane/CostUsageService.yaml).
AC3 Given a marked project, when a CostUsageService/BudgetUpdated with committedUsd at or below limitUsd is delivered, then the mark is removed and the next call outside a run is served; when one with committedUsd above limitUsd is delivered, then the mark stays; given the mark of a monthly budget, when the instant of its PeriodEndsAt has passed, then the call outside a run is served without an event (model/services/model-compute/ModelRouterService.yaml).
AC4 Given model-router-sql created by the migrations on an isolated test database, when the mapping tests run, then the table ProjectBudgetMarks exists with the key over tenant and project and the columns BudgetId, PeriodEndsAt and MarkedAt, a query for one tenant never returns a mark of another, and a restarted replica refuses the same calls as before the restart (ADR-0015, model/services/model-compute/ModelRouterService.yaml).
Traces: services ModelRouterService, CostUsageService
Traces: aggregates ModelRouterService/InvocationReceipt
Traces: apis ModelRouterService/ModelGateway.Invoke
Traces: events CostUsageService/BudgetExceeded, CostUsageService/BudgetUpdated
Traces: adrs ADR-0012, ADR-0015
Traces: requirements FR-09
Depends on AIFACTORY-US-566, AIFACTORY-US-567, feature:cost-usage-service-complete
Sources model/services/model-compute/ModelRouterService.yaml, model/services/control-plane/CostUsageService.yaml

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-6125 Persistence of the budget mark: the table ProjectBudgetMarks with its mapping migration Mapping and migration of ProjectBudgetMarks with the primary key over TenantId and ProjectId and the columns BudgetId, PeriodEndsAt, nullable for a total budget, and MarkedAt, under the tenant row filter; mapping tests run against an isolated test database, never a shared one. ConnectSoft.AI.SoftwareFactory.ModelRouterService
AIFACTORY-TASK-6126 The handlers MarkProjectBudgetExceeded and ClearProjectBudgetMark of the two budget events of CostUsageService implementation MarkProjectBudgetExceeded keeps one mark per tenant and project from BudgetExceeded, with or without a run, with the budget id and the turn of the period, and sets none for an event without a project; ClearProjectBudgetMark removes the mark when BudgetUpdated puts committedUsd at or below limitUsd and changes nothing otherwise; both are idempotent on the event id and publish nothing. ConnectSoft.AI.SoftwareFactory.ModelRouterService
AIFACTORY-TASK-6127 The budget mark check of ModelGateway.Invoke for the calls outside a run implementation Before the policy decision ModelGateway.Invoke reads the mark of the tenant and the project of a call outside a run and refuses the call with RESOURCE_EXHAUSTED while the mark is in force, that is until PeriodEndsAt where the mark keeps one; it writes no receipt and calls no decision, broker or adapter for a refused call, and a run-bound call under the token of an attempt is never refused by the mark. ConnectSoft.AI.SoftwareFactory.ModelRouterService
AIFACTORY-TASK-6128 Verify the budget mark through the acceptance suite verification Run dotnet test -c Release --filter "Category=Acceptance&Feature=ProjectBudgetMark"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-1508 with fixture publishers of BudgetExceeded and BudgetUpdated, a duplicate event id, a call outside a run refused with RESOURCE_EXHAUSTED beside a served run-bound call, the clear on a committed amount at the limit, the mark that stays above it, the turn of a monthly period, a two-tenant fixture and a restarted replica. ConnectSoft.AI.SoftwareFactory.ModelRouterService