AIFACTORY-FEAT-032: ConnectorRegistryService: thin delivery for the first outcome¶
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 Integration Platform (PF-06) · Increment I1 Generate a microservice · State elaborated · Route backend-developer · Build order 70 of 185 (Factory code)
ConnectorRegistryService is the service of bounded context BC-17 (Connectors & Webhooks). Connector descriptors (capability interfaces, retry and rate-limit profiles, webhook schemes, configuration forms) with provider certification, subscriptions to inbound events, verified inbound deliveries and outbound deliveries with receipts; first-party clients (Azure DevOps, GitHub, Deputy, Braze, Bill, Twilio, Israel019, ACS, GA, Meta) are adapters behind descriptors (BC-17). In this increment it is delivered thin: The Azure DevOps connector for template feeds and for opening the change proposal. Its own repository is ConnectSoft.AI.SoftwareFactory.ConnectorRegistryService.
| Delivers | ConnectorRegistryService (thin): The Azure DevOps connector for template feeds and for opening the change proposal. |
| Stubs | — |
| Realizes | adrs: ADR-0012, ADR-0022 |
| Requirements | FR-05, FR-11, FUX-02, NFR-05, NFR-13, NFR-18, XL-10, XL-15 |
| Depends on | — |
| Sources | model/services/integration/ConnectorRegistryService.yaml |
Scenarios to trace (18, catalog): SCN-ConnectorRegistryService-001 ✓, SCN-ConnectorRegistryService-002 ✓, SCN-ConnectorRegistryService-003 ✓, SCN-ConnectorRegistryService-004 ✓, SCN-ConnectorRegistryService-005, SCN-ConnectorRegistryService-006, SCN-ConnectorRegistryService-007 ✓, SCN-ConnectorRegistryService-015 ✓, SCN-ConnectorRegistryService-016 ✓, SCN-ConnectorRegistryService-017 ✓, SCN-ConnectorRegistryService-018 ✓, SCN-ConnectorRegistryService-008 ✓, SCN-ConnectorRegistryService-009, SCN-ConnectorRegistryService-010 ✓, SCN-ConnectorRegistryService-011 ✓, SCN-ConnectorRegistryService-012, SCN-ConnectorRegistryService-013, SCN-ConnectorRegistryService-014
AIFACTORY-US-066: ConnectorRegistryService answers the chain with its thin contract¶
behavior · persona platform-admin
As a platform admin, I want ConnectorRegistryService to hold the Azure DevOps connector, certified and active, and to resolve its capabilities for the first-outcome chain, so that template feeds are read through one governed connector and the change proposal is opened only once that connector is certified and announced.
This is the integration PBI of the thin delivery. The thin scope stated in model/backlog/features/integration.yaml is the Azure DevOps connector for template feeds and for opening the change proposal, and the delivery holds exactly that: one ConnectorDescriptor of provider Azure DevOps, written in state Draft from the Azure DevOps adapter the build carries and listed through ListConnectors (AIFACTORY-US-1001), certified against a sandbox connection and activated with ConnectorActivated through CertifyConnector (AIFACTORY-US-1002), and the internal gRPC method Connectors.ResolveCapability, which resolves a capability interface of that connector to its adapter and to the connection of the forwarded scope through IntegrationService (AIFACTORY-US-1003). TemplateRegistryService is the only caller of that method in I1: a discovery pass of the platform tenant resolves the repository and package feed capabilities through it, under the template-feed project of the platform tenant, to read template sources and feeds. For the change proposal the thin registry contributes the certified Active Azure DevOps descriptor, announced by ConnectorActivated, which ToolAdapterService consumes (ActivateDescriptors); ToolAdapterService opens the proposal through the connection that IntegrationService/Connections.Resolve returns for the project, with a credential from the Secret Broker, and does not call Connectors.ResolveCapability; the tool opens the pull request itself and records it through Pipelines.RecordProposal of PipelineExecutionService (D135). Nothing else is served. The chain calls no tool of class external: its tools are read, sandbox or shared-write, and propose-change-set is shared-write, so Connectors.Deliver, which the model gives to external-class tools, is not needed before I5. CreateSubscription and ListDeliveries for Azure DevOps inbound subscriptions, the aggregates Subscription and Delivery with the tables Subscriptions and Deliveries, the events ConnectorSubscriptionChanged and DeliveryReceived, the worker InboundDispatcher with the handler RecordAndDispatch of InboundDeliveryVerified, and the four reads Connectors.ReadPipelineRun, Connectors.ReadPullRequest, Connectors.ReadPackageFeed and Connectors.ReadContainerRegistry arrive in I2 with feature connector-registry-service-deliveries (D135); ReplayDelivery, Connectors.Deliver, the dispatch of a delivery to its target, the events ConnectorDeprecated, DeliveryDispatched, DeliveryFailed and DeliveryReplayed, the worker OutboundDeliveryRetrier, the handler PauseOnRevocation of ConnectionStateChanged and the other providers arrive with feature connector-registry-service-complete in I5; the handler of DeletionOrderIssued is built in I4 with RetentionResidencyService and is not registered here. The repository ConnectSoft.AI.SoftwareFactory.ConnectorRegistryService is created and scaffolded in I0 by AIFACTORY-TASK-086 of feature repository-and-pipeline-conventions (D140), by the steps of its repository checklist, and this feature starts from that scaffold; it was scaffolded once from the pinned base template package with UseFactoryProfile (features component-base-template-factory-profile and component-base-template-findings, consumed by their pinned versions), so token validation, the scope chain with its 401, 403 and 404 answers, the tenant row filter, health, readiness and the telemetry wiring come from the profile and are not written again. The messaging profile is the Orleans profile under the service name connector-registry; the service writes the run event envelope of the contracts package through the Orleans outbox in the transaction of its command, for ConnectorActivated and for the audit evidence event AuditEvidenceSubmitted on the topic audit.evidence.v1.evidence-submitted of the pinned audit library, and the thin delivery registers no consumed event. A user token reaches the service with the audience of its own gateway, IntegrationHost, which the service accepts (ADR-0015 amendment D117); a workload token carries service scopes and no tenant claim, and the service reads a forwarded tenant and project only under the service scope that names it (D114). The service holds no credential: it reaches a credential only by reference through SecretBrokerService, and no secret value reaches telemetry, an event, an artifact, a log record or a reply. Tenant and project are on metrics by default and run, step and attempt on activities and log records; no stored content reaches telemetry (ADR-0019). The REST operations are public routes of the IntegrationHost gateway, delivered in I1 like the other gateways (D127, D129), and the delivery builds no direct public route; a Platform admin of the platform tenant certifies the connector on a deployed I1 instance by the provisioning runbook of AIFACTORY-TASK-4069 through that gateway, after the connection of the sandbox project is provisioned by the runbook of IntegrationService.
Acceptance criteria
| AC1 | Given the repository ConnectSoft.AI.SoftwareFactory.ConnectorRegistryService created and scaffolded in I0 by AIFACTORY-TASK-086 of feature repository-and-pipeline-conventions, whose first commit is the unchanged output of dotnet new connectsoft-base -n ConnectSoft.AI.SoftwareFactory.ConnectorRegistryService --UseFactoryProfile true from the pinned template package, when its pipeline runs with the work of this feature, then the solution builds, the unit and acceptance tests pass with complete reports and a container image is published (ADR-0028, model/services/integration/ConnectorRegistryService.yaml). |
| AC2 | Given the service descriptor of the thin delivery, when the contract test of the Factory profile compares it with the hosted surface, then exactly ConnectorRegistryService/ListConnectors, ConnectorRegistryService/CertifyConnector and ConnectorRegistryService/Connectors.ResolveCapability are hosted, as AIFACTORY-US-1001 to AIFACTORY-US-1003 prove one by one, a path of an operation outside the thin scope stated in model/backlog/features/integration.yaml answers 404 over REST and UNIMPLEMENTED over gRPC, and the test fails when such an operation appears (ADR-0022). |
| AC3 | Given the connector-registry messaging profile, when its registration is inspected and a certification is committed, then the outbox publishes ConnectorRegistryService/ConnectorActivated and the audit evidence event under the run event envelope of the pinned contracts package in the transaction of the command, no consumed event is registered, the handler of DeletionOrderIssued included, and no other event of the model is declared (ADR-0012, docs/reference/schemas/run-event-envelope.schema.json). |
| AC4 | Given a call without a token, without a workload identity or without the scope of the operation, or a workload call that forwards no tenant, when it reaches one of the three operations, then it is refused before any handler runs and nothing is read (ADR-0015); given the service starts, when liveness and readiness are probed, then liveness answers and readiness is unready until connector-registry-sql is migrated and the identity authority is reachable; given the captured logs, activities and metrics of the acceptance suite, then none holds a token, a credential, a credential reference or a payload (ADR-0019). |
| Traces: services | ConnectorRegistryService |
| Traces: aggregates | ConnectorRegistryService/ConnectorDescriptor |
| Traces: apis | ConnectorRegistryService/ListConnectors, ConnectorRegistryService/CertifyConnector, ConnectorRegistryService/Connectors.ResolveCapability |
| Traces: events | ConnectorRegistryService/ConnectorActivated |
| Traces: descriptors | run-event-envelope-v1, audit-evidence-v1, execution-scope-v1, tool-invocation-v1 |
| Traces: adrs | ADR-0012, ADR-0015, ADR-0019, ADR-0022, ADR-0028 |
| Traces: requirements | FR-05, NFR-05 |
| Depends on | AIFACTORY-US-1001, AIFACTORY-US-1002, AIFACTORY-US-1003, feature:repository-and-pipeline-conventions, feature:component-base-template-factory-profile, feature:component-base-template-findings, feature:contracts-package, feature:component-audit-factory-evidence, feature:component-observability-factory-conventions |
| Sources | model/services/integration/ConnectorRegistryService.yaml, model/backlog/features/integration.yaml, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md, docs/architecture/adr/0012-messaging-port-and-transport-profiles.md, docs/planes/capability-tools/connectors/services/connector-registry-service/index.md#purpose-and-responsibilities |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-087 Host the thin surface: three operations behind scope policies, the messaging profile with one published event and the deployment values |
implementation | ListConnectors, CertifyConnector and Connectors.ResolveCapability are hosted with the scope policies of the Factory profile; the connector-registry messaging profile publishes ConnectorActivated and the audit evidence event under the run event envelope of the pinned contracts package and registers no consumed event; the deployment manifest states the replica range 2 to 8, the probes, the base addresses of IntegrationService, SecretBrokerService and ArtifactService, the secret reference messaging-transport by name and never by value, Integration:Adapters:Enabled set to azure-devops and Integration:Connectors:DefaultRetry at its modelled default; the metrics of model/services/integration/ConnectorRegistryService.yaml are registered with their modelled dimensions through the pinned observability library. | ConnectSoft.AI.SoftwareFactory.ConnectorRegistryService |
AIFACTORY-TASK-088 Contract of the thin surface: service descriptor, OpenAPI document of the two REST operations and proto of Connectors.ResolveCapability |
contract | The service descriptor file lists exactly ListConnectors (GET /factory/connectors, factory.connections.read, read), CertifyConnector (POST /factory/connectors/{connectorId}/certify, factory.connections.admin, sandbox, key-header, with a body that names only the projectId of the sandbox project and no connection, because the runner certifies against the connection that Connections.Resolve returns for that project) and Connectors.ResolveCapability (internal, no streaming, read); the OpenAPI document fixes the list and the certification request and its 202 reply; the proto fixes the provisional request and reply messages of AIFACTORY-TASK-4038; a contract test with golden files holds the shapes and compares the hosted endpoints with the descriptor file in both directions, so callers run against this service without a fake. | ConnectSoft.AI.SoftwareFactory.ConnectorRegistryService |
AIFACTORY-TASK-4069 Provisioning runbook of the Azure DevOps connector on a deployed I1 instance, inside the cluster and without a public route |
documentation | The repository documentation holds the runbook by which a Platform admin of the platform tenant certifies the connector through the IntegrationHost gateway of I1 (D129): it calls the public route of the gateway, never the cluster-internal address of the service, with a user token of the authorization server whose one audience is IntegrationHost, the audience the service accepts (ADR-0015 amendment D117), and whose tenant is the platform tenant; its precondition is the runbook of IntegrationService, by which the connection of the sandbox project and the connection of the template-feed project are registered, verified and granted, and a secret reference of each connection registered with the Secret Broker with the purposes the callers ask; it names the one call of this service, CertifyConnector with an Idempotency-Key and the projectId of the sandbox project, and the evidence of success, ListConnectors answering 200 with the Azure DevOps descriptor in state Active with its certificationRef, and the ConnectorActivated record in the outbox; it states that the platform bundle allows a credential issuance of the purpose delivery for the service identities of ConnectorRegistryService and WebhookGatewayService, so that on a deployed I1 instance the certification credential is issued to this service, and that the same purpose asked by any other subject is denied (D139, D140), and holds no token, credential, reference value or limit. | ConnectSoft.AI.SoftwareFactory.ConnectorRegistryService |
AIFACTORY-TASK-757 Verify connector-registry-service-thin-contract by running the declared command |
verification | Run dotnet build -c Release and dotnet test -c Release --no-build in the pipeline of the repository; a run that discovers no test counts as a failure; the runs pass and prove AC1 to AC4 of AIFACTORY-US-066, that is the scaffold with the Factory profile, exactly the three hosted operations of the thin scope (SCN-ConnectorRegistryService-001, SCN-ConnectorRegistryService-002, SCN-ConnectorRegistryService-007) and the 404 and UNIMPLEMENTED of the others, the messaging registration with ConnectorActivated (SCN-ConnectorRegistryService-008) and no consumed event, the refusals before any handler, readiness that stays unready until the store is migrated and the scan of logs, activities and metrics for tokens, credentials, credential references and payloads; the runbook of AIFACTORY-TASK-4069 is present in the repository documentation. |
ConnectSoft.AI.SoftwareFactory.ConnectorRegistryService |
AIFACTORY-US-1001: Register the Azure DevOps connector in Draft from the adapter the build carries and list the connectors a tenant may use¶
behavior · persona platform-admin
As a platform admin, I want the Azure DevOps connector to appear as a descriptor with its capabilities, adapter version and certification state, so that I can see which connector the Factory uses for template feeds and change proposals and whether it is certified before anything relies on it.
The model names no operation that creates a ConnectorDescriptor; a connector is the description of an adapter the service loads (Integration:Adapters:Enabled). The thin delivery therefore writes the descriptor of each adapter it loads at startup. The build carries one adapter, Azure DevOps, built on the first-party Azure DevOps client library (ext-client-libraries), and the deployment sets Integration:Adapters:Enabled to azure-devops; a name in the option for which the build carries no adapter fails startup with the name, so no descriptor without an adapter exists. At startup the service writes, idempotently on connectorId and version, a ConnectorDescriptor of the platform tenant in state Draft with provider Azure DevOps, the capability interfaces the adapter implements for repositories (read a repository at a commit, push a branch and open a pull request) and for package feeds (list the versions of a package), the adapter reference with the client library and its version, the retry profile of Integration:Connectors:DefaultRetry where the adapter sets none, the rate-limit profile, the webhook scheme it declares and its configuration form. The model gives no value for an Azure DevOps rate limit and no option that carries one, and a limit is an owner input, so the rate-limit profile is written as an empty profile that applies no limit until the owner supplies one; no limit value is fixed in code or in the adapter, and the input is reported to the owner. A restart writes no second row, and an adapter of a new version writes a new descriptor version in Draft, because a changed adapter version re-runs certification (invariant of the model); the earlier version keeps its state. A caller whose scope carries factory.connections.read (Observer, Operator, Workspace admin or Platform admin) lists the connectors through ConnectorRegistryService/ListConnectors; the tenant comes from the validated token. The response is 200 with the descriptors of the platform tenant and of the tenant of the caller, each with connectorId, version, provider, capabilities, adapter reference, webhook scheme and certification state with its evidence reference; descriptors that another tenant registered never appear. On a deployed instance the list holds the one Azure DevOps descriptor. A call without a token is answered 401 and a token without the scope 403; when connector-registry-sql is unavailable the call fails fast with 503 and a problem response. Nothing is written by the list and no event is published. The store holds the table ConnectorDescriptors with its columns and keys; the tables Subscriptions and Deliveries arrive with their aggregates in I2 with feature connector-registry-service-deliveries (D135). The gauge connectsoft.factory.integration.adapter_health reports the loaded adapter and connectsoft.factory.integration.connectors counts descriptors by provider and state.
Acceptance criteria
| AC1 | Given the deployment with Integration:Adapters:Enabled set to azure-devops, when the service starts twice, then one ConnectorRegistryService/ConnectorDescriptor of the platform tenant exists in state Draft with the capabilities, the adapter reference with the client library version, the retry profile of Integration:Connectors:DefaultRetry, an empty rate-limit profile that applies no limit, because no limit value exists in the model or in code, and the configuration form of the adapter, and the second start wrote no row; given an adapter of a new version, then a new descriptor version is written in Draft and the earlier version keeps its state; given a name in the option without an adapter in the build, then startup fails with the name (model/services/integration/ConnectorRegistryService.yaml). |
| AC2 | Given a caller with factory.connections.read, when ConnectorRegistryService/ListConnectors is called on the deployed instance, then the response is 200 with the Azure DevOps descriptor carrying connectorId, version, provider, capabilities, adapter reference, webhook scheme and certification state, nothing is written and no event is published (SCN-ConnectorRegistryService-001). |
| AC3 | Given fixture descriptors inserted directly into the isolated test database, one of the platform tenant and one registered by tenant A, when a caller of tenant A and a caller of tenant B call ConnectorRegistryService/ListConnectors, then tenant A receives both and tenant B receives only the descriptor of the platform tenant, and the list never reveals the descriptor of tenant A to tenant B (SCN-ConnectorRegistryService-001, ADR-0015). |
| AC4 | Given a call without a token, a token without factory.connections.read, or an unavailable connector-registry-sql, when ConnectorRegistryService/ListConnectors is called, then the answer is 401, 403 or 503 with a problem response, no partial list is returned and no state changes (SCN-ConnectorRegistryService-001). |
| Traces: services | ConnectorRegistryService |
| Traces: aggregates | ConnectorRegistryService/ConnectorDescriptor |
| Traces: apis | ConnectorRegistryService/ListConnectors |
| Traces: adrs | ADR-0015, ADR-0022 |
| Traces: requirements | FUX-02, NFR-13 |
| Traces: scenarios | SCN-ConnectorRegistryService-001 |
| Relates: screens | connectors |
| Depends on | feature:component-base-template-factory-profile |
| Sources | model/services/integration/ConnectorRegistryService.yaml, model/externals.yaml, docs/planes/capability-tools/connectors/services/connector-registry-service/index.md#domain-model, docs/planes/capability-tools/connectors/services/connector-registry-service/index.md#data-model-and-storage |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-4031 Migration and mappings of ConnectorDescriptors in connector-registry-sql |
migration | The table ConnectorDescriptors of model/services/integration/ConnectorRegistryService.yaml exists with its columns and its key on ConnectorId and Version; the mappings carry the tenant row filter of the Factory profile and admit the rows of the platform tenant for reads; mapping tests run against an isolated test database, never a shared one; the tables Subscriptions and Deliveries are not created by this delivery. | ConnectSoft.AI.SoftwareFactory.ConnectorRegistryService |
AIFACTORY-TASK-4032 Azure DevOps adapter and the Draft descriptor written at startup from Integration:Adapters:Enabled |
implementation | The adapter wraps the first-party Azure DevOps client library behind the capability interfaces for repositories and package feeds; at startup each name of Integration:Adapters:Enabled is matched with an adapter of the build and its descriptor is written in Draft for the platform tenant idempotently on connectorId and version, with the retry profile of Integration:Connectors:DefaultRetry where the adapter sets none and an empty rate-limit profile in the not-nullable column RateLimitProfileJson, which applies no limit until the owner supplies one; no limit value is fixed in the adapter or anywhere in code, and a test fails when the written profile holds a value; a name without an adapter fails startup with the name; the adapter holds no credential and receives one per call. | ConnectSoft.AI.SoftwareFactory.ConnectorRegistryService |
AIFACTORY-TASK-4033 ListConnectors read model over the platform tenant and the tenant of the caller |
implementation | ListConnectors returns the descriptors of the platform tenant and of the trusted tenant of the caller with connectorId, version, provider, capabilities, adapter reference, webhook scheme, state and certification reference, answers 401 and 403 through the policies of the Factory profile and 503 with a problem response when the store is unavailable, and writes nothing; connectsoft.factory.integration.connectors and connectsoft.factory.integration.adapter_health record their modelled dimensions. | ConnectSoft.AI.SoftwareFactory.ConnectorRegistryService |
AIFACTORY-TASK-4034 Verify the registration and the list of the Azure DevOps connector through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&Scenario=SCN-ConnectorRegistryService-001"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-1001: two starts with one Draft descriptor, a new adapter version, the failing start for a name without an adapter, the list on the deployed configuration, the two-tenant fixture rows, the 401, the 403 and the 503 of an unavailable store. |
ConnectSoft.AI.SoftwareFactory.ConnectorRegistryService |
AIFACTORY-US-1002: Certify the Azure DevOps connector against a sandbox connection and activate it with ConnectorActivated¶
behavior · persona platform-admin
As a platform admin, I want to run the conformance suite of the Azure DevOps connector against a sandbox connection and have it activated only when the suite passes, so that no template feed is read and no change proposal is opened through a connector that has not proven its capabilities.
A connector is Active only with certification evidence from the conformance suite (invariant of the model). A caller whose scope carries factory.connections.admin asks for the certification through ConnectorRegistryService/CertifyConnector with an Idempotency-Key. Who may certify follows the owner of the descriptor. A descriptor of the platform tenant is shared: every tenant reads it (AIFACTORY-US-1001), and its activation makes it usable for every tenant. CertifyConnector on a descriptor of the platform tenant is therefore admitted only for a Platform admin whose token names the platform tenant; a caller of another tenant, who can read that descriptor, is answered 403 whatever role it holds, and nothing runs, as TemplateRegistryService admits writes to rows of the platform tenant. A descriptor that a tenant registered is certified by a Workspace admin or Platform admin of that tenant, and a caller of any other tenant is answered 404 for it, the same answer as for a descriptor that does not exist (ADR-0015 amendment D113); the thin delivery writes descriptors of the platform tenant only, so on a deployed I1 instance only the first rule applies. The body names the projectId of the sandbox project, a project of the tenant of the descriptor whose Project grant holds the connection of a sandbox Azure DevOps organization; the route names its project in that body member, never in a header. The body names no connection: the thin scope holds one Azure DevOps connection per project, and the runner certifies against the connection that IntegrationService/Connections.Resolve returns for the sandbox project (AIFACTORY-US-1008), so the certified connection is always the one granted to that project. The service answers 202 with the reference of the certification and hands the request to the worker ConformanceRunner, one attempt, idempotent on connectorId, version and the suite version, at most two runs in parallel per connector. The runner calls IntegrationService/Connections.Resolve under its workload token with the forwarded tenant and sandbox project; a refusal, no-grant, not-active, degraded, ambiguous or NOT_FOUND, ends the run failed with that reason. It then exchanges the broker ticket of the reply with SecretBrokerService/SecretBroker.Issue for a short-lived credential of the purpose delivery. A certification asks the broker with the purpose delivery (D129); the purpose sandbox is not used, because the broker issues it only for a reference of kind SandboxToken and with a sandbox lease, and a certification holds no lease. The broker issues only when delivery is in allowedPurposes of the secret reference of the sandbox connection and its policy decision allows the issuance, so that reference must be registered with the purpose delivery. When the issuance is refused, PERMISSION_DENIED for a purpose outside allowedPurposes or a decision other than allow, FAILED_PRECONDITION for a revoked reference or an answer that is no decision, the run ends failed with the status and its reason, the descriptor stays Draft and only the audit evidence of the failed run is written; the service retries nothing. With the credential the runner exercises each capability interface of the descriptor against the sandbox connection, so its effect stays in the sandbox system, and stores the evidence, with the suite version, the adapter version and the result of each capability, through ArtifactService/Artifacts.Store. When every capability passes, the descriptor moves from Draft to Certified (ConformanceSuitePassed) and from Certified to Active (Activate) in one transaction with its certificationRef, the ConnectorActivated outbox record and the audit evidence event AuditEvidenceSubmitted on audit.evidence.v1.evidence-submitted. When a capability fails, the descriptor stays Draft, the evidence of the failure is stored and referenced, the audit evidence records the result and no ConnectorActivated is written. A repeated request with the same Idempotency-Key returns the same reference and runs nothing; a request for a version already certified under the same suite version runs nothing and points at the recorded result. A token without the scope is answered 403; a connectorId that does not exist, or a descriptor that another tenant registered, is answered 404, the same answer in both cases (ADR-0015 amendment D113); a body without projectId is answered 400. IntegrationService, SecretBrokerService and ArtifactService are required and fail-fast: when one does not answer, the run ends failed, the descriptor stays Draft, only the audit evidence of the failed run is written, and the admin asks again. The credential is used in memory for the run only and never reaches the evidence, an event, a log record or telemetry. ConnectorActivated carries connectorId, version, tenantId and provider under the run event envelope; StudioBff, AuditService and ToolAdapterService handle it in their own PBIs. The platform bundle allows the connection grant of the sandbox project for the Platform admin (D129), so its Project grant can be set, and allows a credential issuance, the action kind credential-issuance, for the purposes tool-call and sandbox, and for the purpose delivery that a certification asks (D129) only when the subject is the service identity of ConnectorRegistryService or WebhookGatewayService (D127, D139, AIFACTORY-US-917 of feature policy-engine-service), so on a deployed I1 instance the certification credential is issued, and the same purpose asked by any other subject is denied. The transition from Active to Deprecated has no operation in the model and arrives with the complete delivery in I5.
Acceptance criteria
| AC1 | Given a Draft ConnectorRegistryService/ConnectorDescriptor of Azure DevOps of the platform tenant and a Platform admin with factory.connections.admin whose token names the platform tenant, when ConnectorRegistryService/CertifyConnector is called with an Idempotency-Key and the projectId of the sandbox project, then the response is 202, the runner resolves the connection granted to that project through IntegrationService/Connections.Resolve, exchanges its broker ticket through SecretBrokerService/SecretBroker.Issue for a credential of the purpose delivery, stores the evidence through ArtifactService/Artifacts.Store, and on a passing suite the descriptor is Active with its certificationRef, the ConnectorRegistryService/ConnectorActivated outbox record and the audit evidence written in the same transaction (SCN-ConnectorRegistryService-002, ADR-0022). |
| AC2 | Given a suite in which one capability fails, when the runner ends, then the descriptor stays Draft, the evidence of the failure is stored and referenced, the audit evidence records the failed result and no ConnectorRegistryService/ConnectorActivated is written; given the same request repeated with the same Idempotency-Key, or a request for a version already certified under the same suite version, then the same reference is returned and nothing runs (SCN-ConnectorRegistryService-002). |
| AC3 | Given a token without the scope, a caller of another tenant than the platform tenant, Workspace admin or Platform admin, on a descriptor of the platform tenant, a descriptor that tenant B registered asked for by tenant A, a connectorId that does not exist, or a body without projectId, when the certification is asked for, then the answer is 403, 403, 404, 404 (the same for a foreign and an unknown descriptor, ADR-0015 amendment D113) or 400 with a problem response, nothing runs and no state changes; given IntegrationService/Connections.Resolve refusing the sandbox project, SecretBrokerService/SecretBroker.Issue refusing with PERMISSION_DENIED or FAILED_PRECONDITION, or IntegrationService, SecretBrokerService or ArtifactService that does not answer, when the run starts, then it ends failed with the status and reason, the descriptor stays Draft and only the audit evidence of the failed run is written (SCN-ConnectorRegistryService-002, ADR-0015). |
| AC4 | Given the certification committed, when the outbox dispatcher of the connector-registry profile publishes ConnectorRegistryService/ConnectorActivated on connectors.connectors.v1.connector-activated, then the event is sent under the run event envelope with connectorId, version, tenantId and provider, and a transport outage is retried with backoff so the event is neither lost nor duplicated under its event id (SCN-ConnectorRegistryService-008, ADR-0012). |
| AC5 | Given the captured evidence artifact, events, log records and activities of a certification, when they are scanned, then none holds the credential or a payload of the sandbox system, and connectsoft.factory.integration.connectors moved from Draft to Active for provider Azure DevOps (ADR-0019, model/services/integration/ConnectorRegistryService.yaml). |
| Traces: services | ConnectorRegistryService, IntegrationService, SecretBrokerService, ArtifactService |
| Traces: aggregates | ConnectorRegistryService/ConnectorDescriptor |
| Traces: apis | ConnectorRegistryService/CertifyConnector, IntegrationService/Connections.Resolve, SecretBrokerService/SecretBroker.Issue, ArtifactService/Artifacts.Store |
| Traces: events | ConnectorRegistryService/ConnectorActivated |
| Traces: descriptors | run-event-envelope-v1, audit-evidence-v1 |
| Traces: adrs | ADR-0012, ADR-0015, ADR-0019, ADR-0022 |
| Traces: requirements | FR-05, FUX-02, NFR-05 |
| Traces: scenarios | SCN-ConnectorRegistryService-002, SCN-ConnectorRegistryService-008 |
| Relates: screens | connectors |
| Depends on | AIFACTORY-US-1001, feature:integration-service-thin, feature:secret-broker-service, feature:artifact-service, feature:contracts-package, feature:component-audit-factory-evidence |
| Sources | model/services/integration/ConnectorRegistryService.yaml, model/services/integration/IntegrationService.yaml, docs/reference/schemas/audit-evidence.schema.json, docs/planes/capability-tools/connectors/services/connector-registry-service/index.md#workers-and-jobs |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-4035 CertifyConnector with its Idempotency-Key, the ConformanceRunner worker and the two transitions to Active |
implementation | CertifyConnector validates the body, which names the projectId and no connection, admits a descriptor of the platform tenant only for a Platform admin whose token names the platform tenant and answers 403 to a caller of any other tenant, admits a descriptor a tenant registered for a Workspace admin or Platform admin of that tenant and answers 404 to a caller of another tenant, answers 202 with the reference of the certification, 400 without projectId, 403 without the scope and 404 for an unknown descriptor, and returns the same reference for a repeated key; ConformanceRunner runs once per connectorId, version and suite version, resolves the connection of the sandbox project through Connections.Resolve, exchanges the broker ticket through SecretBroker.Issue for a credential of the purpose delivery, exercises every capability interface of the descriptor, stores the evidence through Artifacts.Store and commits Draft to Certified to Active with certificationRef, the ConnectorActivated outbox record and AuditEvidenceSubmitted in one transaction, or keeps Draft with the referenced failure evidence and the audit evidence; a refusal of Connections.Resolve or SecretBroker.Issue, and an unavailable dependency, end the run failed with the descriptor in Draft and only the audit evidence of the failed run written, without a retry; the credential is never written. | ConnectSoft.AI.SoftwareFactory.ConnectorRegistryService |
AIFACTORY-TASK-4036 Fakes of Connections.Resolve, SecretBroker.Issue, Artifacts.Store and the sandbox Azure DevOps system |
fixture | The acceptance suite holds fakes of IntegrationService/Connections.Resolve, which answers a granted connection with its broker ticket, no-grant, not-active and ambiguous, of SecretBrokerService/SecretBroker.Issue, which issues for the purpose delivery and refuses with PERMISSION_DENIED for a purpose outside allowedPurposes or a denying decision and with FAILED_PRECONDITION for a revoked reference, and of ArtifactService/Artifacts.Store, each of which records its calls and can be stopped, tokens of a Platform admin of the platform tenant and of a Workspace admin and a Platform admin of another tenant, fixture descriptors of the platform tenant and of tenant B inserted directly into the isolated test database, and a recording stub of the sandbox Azure DevOps system that answers each capability call and can be made to fail one capability, so the passing, the failing and the interrupted certification run without a real organization. | ConnectSoft.AI.SoftwareFactory.ConnectorRegistryService |
AIFACTORY-TASK-4037 Verify the certification and the activation through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-ConnectorRegistryService-002\|Scenario=SCN-ConnectorRegistryService-008)"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-1002: the passing suite with the descriptor Active and ConnectorActivated in the outbox, the failing capability with the descriptor in Draft, the repeated key and the repeated suite version, the 400, the 403 without the scope, the 403 to a Workspace admin and to a Platform admin of another tenant on the descriptor of the platform tenant, the 404 to tenant A for the descriptor of tenant B and for an unknown descriptor, the refusals of Connections.Resolve and of SecretBroker.Issue with the run failed and the descriptor in Draft, each of the three fakes stopped, the publication of ConnectorActivated under the run event envelope with retry, and the scan of evidence, events, logs and activities for the credential. |
ConnectSoft.AI.SoftwareFactory.ConnectorRegistryService |
AIFACTORY-US-1003: Resolve a capability interface of the Azure DevOps connector to its adapter and to the connection granted to the forwarded scope¶
behavior · persona operator
As an operator, I want the service that reads template sources and feeds to learn from the registry which certified connector and which granted connection it uses, so that no template feed is read from Azure DevOps through a connector that is not active or a connection the project does not hold.
A workload resolves a capability interface before it calls the external system. In I1 the only caller is TemplateRegistryService, whose discovery pass resolves the repository and package feed capabilities to read template sources and feeds; the change proposal is opened by ToolAdapterService through IntegrationService/Connections.Resolve and does not call this method. A discovery pass runs in the platform tenant, and a connection is resolved only for a project with a Project grant (AIFACTORY-US-1008), so the scope under which a pass resolves is the platform tenant and the template-feed project: a project of the platform tenant, supplied by the installation and never fixed here, whose Project grant holds the Azure DevOps connection of the template sources. TemplateRegistryService forwards that project with the platform tenant; the choice is an owner point shared with feature template-registry-service and is reported. A request that forwards no project is not served without a connection: it is answered INVALID_ARGUMENT with the reason project-required, which the template-feed path never meets because it forwards its project. The caller presents a workload token with the service scope that names ConnectorRegistryService and forwards its tenant and project in the gRPC metadata; such a token carries no tenant claim, so the service reads the forwarded tenant and project only under that scope (ADR-0015 amendment D114). ConnectorRegistryService/Connectors.ResolveCapability looks up the Active descriptor that declares the capability among the descriptors of the platform tenant and of the forwarded tenant, and asks IntegrationService/Connections.Resolve for the connection of the forwarded scope, which checks the grant of the project. The reply names the connector and its version, the adapter reference, the capability, the connection, its endpoint policy as narrowed by the grant, and the broker ticket of IntegrationService unchanged; it never carries a credential, which the caller obtains from the Secret Broker with the ticket. The ticket names the credential reference, which the Secret Broker needs; the service passes it through in the reply only and writes it to no log record, activity, metric or event. The method is of class read and writes nothing. A capability that no Active descriptor declares, as for a Draft descriptor, is answered NOT_FOUND, and so is a descriptor of another tenant. The answers of IntegrationService return with their reason: PERMISSION_DENIED with the reason no-grant when the project holds no grant, FAILED_PRECONDITION when the connection is not Active or is Degraded, NOT_FOUND when the tenant has no such connection. A call without a workload identity, or a workload call that forwards no tenant, is refused with UNAUTHENTICATED by the Factory profile; a token without the service scope with PERMISSION_DENIED; a request whose execution scope names another tenant than the forwarded one with PERMISSION_DENIED and the reason scope-mismatch; a request without a capability with INVALID_ARGUMENT, and one without a project with INVALID_ARGUMENT and the reason project-required. IntegrationService is required and fail-fast: when it does not answer, the call fails with UNAVAILABLE and no partial reply, and so it does when connector-registry-sql is unavailable. The model names execution-scope-v1 as the request and tool-invocation-v1 as the reply of the method; the first has no member for a capability and the second describes a tool call with arguments, a policy decision and an idempotency key and no member for an adapter or a connection. That conflict is an open point for the owner: until the descriptors are named the request and reply messages are provisional golden files, the request carrying the execution scope beside the capability name. The found reply is proven with fixture rows inserted directly into the isolated test database and with the fake of IntegrationService/Connections.Resolve.
Acceptance criteria
| AC1 | Given an Active Azure DevOps descriptor of the platform tenant and a workload token of TemplateRegistryService with the service scope that forwards the platform tenant and its template-feed project, when ConnectorRegistryService/Connectors.ResolveCapability is called for the repository capability and for the package feed capability and IntegrationService/Connections.Resolve grants the connection of that project, then each reply names the connector and its version, the adapter reference, the capability, the connection, its narrowed endpoint policy and the broker ticket, carries no credential, nothing is written, and the credential reference of the ticket appears in no log record, activity or metric; given the same call for project P of tenant A, then the connection of project P is resolved the same way (SCN-ConnectorRegistryService-007). |
| AC2 | Given a Draft descriptor, a capability no descriptor declares or a descriptor of another tenant, when the method is called, then the answer is NOT_FOUND; given IntegrationService answering PERMISSION_DENIED with the reason no-grant, FAILED_PRECONDITION for a connection that is not Active or is Degraded, or NOT_FOUND, then that status and its reason return to the caller and nothing is written (SCN-ConnectorRegistryService-007, ADR-0015). |
| AC3 | Given a call without a workload identity, a workload call that forwards no tenant, a token without the service scope, an execution scope of another tenant than the forwarded one, a request without a capability, a request without a project, an unavailable IntegrationService or an unavailable connector-registry-sql, when the method is called, then it is refused with UNAUTHENTICATED, UNAUTHENTICATED, PERMISSION_DENIED, PERMISSION_DENIED with the reason scope-mismatch, INVALID_ARGUMENT, INVALID_ARGUMENT with the reason project-required, UNAVAILABLE or UNAVAILABLE respectively, no partial reply is returned and no state changes (SCN-ConnectorRegistryService-007, ADR-0015). |
| AC4 | Given the proto of the method, when the contract test runs, then the provisional golden files hold the request and the reply messages, a reply validated against the schema finds no credential member, and the test marks both messages provisional because execution-scope-v1 and tool-invocation-v1 cannot carry a capability, an adapter or a connection (docs/reference/schemas/tool-invocation.schema.json, docs/reference/schemas/execution-scope.schema.json). |
| Traces: services | ConnectorRegistryService, IntegrationService |
| Traces: aggregates | ConnectorRegistryService/ConnectorDescriptor |
| Traces: apis | ConnectorRegistryService/Connectors.ResolveCapability, IntegrationService/Connections.Resolve |
| Traces: descriptors | execution-scope-v1, tool-invocation-v1 |
| Traces: adrs | ADR-0015, ADR-0022 |
| Traces: requirements | FR-05, NFR-02 |
| Traces: scenarios | SCN-ConnectorRegistryService-007 |
| Depends on | AIFACTORY-US-1001, feature:integration-service-thin, feature:component-base-template-factory-profile |
| Sources | model/services/integration/ConnectorRegistryService.yaml, model/services/integration/IntegrationService.yaml, docs/reference/schemas/tool-invocation.schema.json, docs/reference/schemas/execution-scope.schema.json, docs/planes/capability-tools/connectors/services/connector-registry-service/index.md#apis |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-4038 Provisional request and reply messages of Connectors.ResolveCapability |
contract | The proto fixes the request message (the execution scope and the capability name) and the reply message (connectorId, version, adapterRef, capability, connectionId, endpoint policy and broker ticket, no credential member) as provisional golden files, marked so in the contract test until the owner names the request and reply descriptors, because docs/reference/schemas/execution-scope.schema.json and docs/reference/schemas/tool-invocation.schema.json have no member for them. | ConnectSoft.AI.SoftwareFactory.ConnectorRegistryService |
AIFACTORY-TASK-4039 Connectors.ResolveCapability over the Active descriptors and Connections.Resolve |
implementation | The method reads the forwarded tenant and project only under the service scope, looks up the Active descriptor that declares the capability among the descriptors of the platform tenant and the forwarded tenant, calls Connections.Resolve through a typed gRPC client under its workload token with the forwarded scope, returns the reply with the broker ticket unchanged and no credential, logs and measures neither the ticket nor its credential reference, returns the refusals of IntegrationService with their reason, answers NOT_FOUND, PERMISSION_DENIED with scope-mismatch, INVALID_ARGUMENT for a missing capability, INVALID_ARGUMENT with project-required for a missing project and UNAVAILABLE as AIFACTORY-US-1003 states, and writes nothing. | ConnectSoft.AI.SoftwareFactory.ConnectorRegistryService |
AIFACTORY-TASK-4040 Verify the capability resolution through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&Scenario=SCN-ConnectorRegistryService-007"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-1003 with fixture descriptors of the platform tenant and of two tenants inserted directly into the isolated test database and the fake of IntegrationService/Connections.Resolve answering a grant for the template-feed project of the platform tenant and for project P of tenant A, no-grant, a Degraded connection, NOT_FOUND and no answer, the scan of logs, activities and metrics for the credential reference of the ticket, the eight refusals and the provisional golden files. |
ConnectSoft.AI.SoftwareFactory.ConnectorRegistryService |