Skip to content

AIFACTORY-FEAT-097: AI and Factory libraries: scope in contracts, Anthropic adapter, durable base

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 Ecosystem component extensions · Increment I0 Readiness · State elaborated · Route backend-developer · Phase before development · Build order 3 of 185 (Templates and libraries)

Before development

Template or library work: every task of this feature changes a template or a shared library the Factory builds on, and it lands before the Factory's own repositories of I0 are developed. The mark travels with every task (tag phase:before-development).

The Factory libraries carry tenant and project scope in their contracts, gain an Anthropic model adapter (decision D16), and expose the run, step and attempt abstractions the durable runtime persists. The libraries are verified to build and test as they are before they are extended. Component: Extensions.AI + AgentsFramework + Factory libraries (extend).

Delivers —
Stubs —
Realizes components: cmp-extensions-ai
Requirements —
Depends on —
Sources model/components.yaml, docs/architecture/ecosystem-composition.md

AIFACTORY-US-191: AI and Factory libraries: the libraries build and test as they are, the library types of the recorded agent base work are the single definition and the pin drift is resolved

enabling · persona platform-admin As a platform admin, I want a recorded baseline of the AI and Factory libraries, with every shared type of the recorded agent base work settled in the library that owns it, so that every later change of the libraries starts from packages that are known to build, test and pin one set of versions.

The feature extends libraries that already ship: ConnectSoft.Extensions.AI, ConnectSoft.Extensions.AI.AgentsFramework, ConnectSoft.Extensions.AI.Factory.Abstractions, ConnectSoft.Extensions.AI.Factory, ConnectSoft.Extensions.AI.Factory.Messaging and its MassTransit publisher package ConnectSoft.Extensions.AI.Factory.Messaging.MassTransit, each in a repository of its own with its own solution, pins and pipeline. Before any of them is changed, a maintainer of the libraries records a baseline: every solution restores from the feed, builds in Release and passes its tests, with the package versions each one pins. Two things are settled in the same pass. First, the receiving side of the agent base, envelope and lifecycle work that the page Docs/Generic Agent Implementation Summary.md of the agent template records as applied but not compiled (decision D113). The libraries already hold these types and their tests, which the baseline proves, so the library definitions of IFactoryAgent, FactoryAgentBase, the request, result and validation contracts, AgentEventEnvelope and the five lifecycle events are the single definition. The maintainer compares them with the copies the page records in the template, ports into the library any unit test the page lists that the library lacks, and records per type the package that the package responsibility matrix of the Factory library pages makes its owner. The checklist of that page belongs to the template: compiling the authoring solution, generating the matrix and removing the copies from the template are tasks of the feature component-agent-template-contract, which depends on this one, and they are not repeated here. Second, the pin drift that model/components.yaml records for this component is resolved: the libraries pin one version of Microsoft.Extensions.AI, of Microsoft.Agents.AI and of each sibling ConnectSoft package, and a pipeline check in every repository refuses a solution whose pins differ from the recorded set. A library that does not build or test as it is blocks the PBIs that extend it, and the failure is recorded with the failing project instead of being worked around.

Acceptance criteria

AC1 Given the repositories of the AI and Factory libraries as they are, when each solution is restored from the feed, built in Release and tested, then every project builds and every test passes, and the baseline records the package versions each solution pins; a project that fails is recorded by name and blocks the PBIs that extend it (ADR-0028, model/components.yaml).
AC2 Given the page Docs/Generic Agent Implementation Summary.md of the agent template and the library projects of the baseline, when the types the page records are compared with the libraries, then the library definitions of IFactoryAgent, FactoryAgentBase, the request, result and validation contracts, AgentEventEnvelope and the five lifecycle events are the single definition, every unit test the page lists that a library lacked (first-attempt success, retry then success, escalation after exhaustion, event order, null request, trace-origin stamping and trace-id preservation) is ported and passes in the package that owns the type, and the owning package of each type is recorded against the package responsibility matrix; compiling the template and removing its copies is left to the tasks of the feature component-agent-template-contract (ADR-0014 names these types as the envelopes that exist in code).
AC3 Given the central package files of the six library repositories, when the pins are compared, then every library pins the same version of Microsoft.Extensions.AI, of Microsoft.Agents.AI and of each sibling ConnectSoft package, and a pipeline check in each repository fails a solution whose pins differ from the recorded set, which closes the pin drift model/components.yaml records for the component (ADR-0028).
Traces: adrs ADR-0014, ADR-0028
Sources model/components.yaml, docs/architecture/ecosystem-composition.md, docs/architecture/adr/0014-run-and-lifecycle-envelopes.md, docs/planes/agent-runtime/agent-runtime.md

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-160 Build and test the Factory libraries as they are verification A recorded baseline that proves AC1 of AIFACTORY-US-191: the solutions of the six repositories ConnectSoft.Extensions.AI, ConnectSoft.Extensions.AI.AgentsFramework, ConnectSoft.Extensions.AI.Factory.Abstractions, ConnectSoft.Extensions.AI.Factory, ConnectSoft.Extensions.AI.Factory.Messaging and ConnectSoft.Extensions.AI.Factory.Messaging.MassTransit each restore from the feed, build in Release and pass their tests; the baseline is one record in the Runbook page of the Factory library that holds, per repository, the result of the two commands and the package versions the solution pins. ConnectSoft.Extensions.AI.Factory
AIFACTORY-TASK-951 Settle each shared type of the recorded agent base, envelope and lifecycle work in its library and port the missing unit tests implementation The library definitions are the single definition: the agent contracts in the package ConnectSoft.Extensions.AI.Factory.Abstractions, the base and its options in ConnectSoft.Extensions.AI.Factory, the envelope, the lifecycle events and the mapper in ConnectSoft.Extensions.AI.Factory.Messaging. The task compares them with the copies the page Docs/Generic Agent Implementation Summary.md records in the agent template, ports every unit test the page lists that the library lacks (trace-origin stamping and trace-id preservation among them) into the test project of the owning repository, and records per type, in the migration guide of the Factory library pages, that the package of the responsibility matrix owns it. The check per repository: the Abstractions, the Factory and the Messaging solution each build and pass their tests with the ported tests. The compile of the template and the removal of its copies are tasks of the feature component-agent-template-contract. ConnectSoft.Extensions.AI.Factory
AIFACTORY-TASK-952 One recorded set of pins across the AI and Factory libraries operations The central package file of each of the six repositories (ConnectSoft.Extensions.AI, ConnectSoft.Extensions.AI.AgentsFramework, ConnectSoft.Extensions.AI.Factory.Abstractions, ConnectSoft.Extensions.AI.Factory, ConnectSoft.Extensions.AI.Factory.Messaging, ConnectSoft.Extensions.AI.Factory.Messaging.MassTransit) pins one version of Microsoft.Extensions.AI, of Microsoft.Agents.AI and of each sibling ConnectSoft package. The recorded set is one file kept in the agents framework repository; the pipeline of each of the six repositories has a step that reads that file through a repository resource, compares it with its own central package file and fails the run on a difference. The check per repository is one green run of its pipeline with the comparison step and one failed run on a planted differing pin. ConnectSoft.Extensions.AI.AgentsFramework
AIFACTORY-TASK-953 Verify the baseline, the compiled agent work and the aligned pins verification Run dotnet build -c Release and dotnet test -c Release --no-build on the solution of each of the six library repositories after the pins are aligned; every run passes, the ported tests of AIFACTORY-TASK-951 run in the Abstractions, Factory and Messaging repositories, and the results per repository prove AC1 to AC3 of AIFACTORY-US-191 (ADR-0014). ConnectSoft.Extensions.AI.Factory

AIFACTORY-US-192: Factory libraries: AgentTraceContext and AgentEventEnvelope carry tenant, project, run, step and attempt identity and a schema version

enabling · persona platform-admin As a platform admin, I want the trace context and the event envelope of the Factory libraries to carry the trusted scope, the run, step and attempt identity and a schema version, so that every request and every lifecycle event of an agent is attributable to its tenant, project, run and attempt without a second plumbing pass in the hosts.

ADR-0014 records that AgentTraceContext of ConnectSoft.Extensions.AI.Factory.Abstractions and AgentEventEnvelope of ConnectSoft.Extensions.AI.Factory.Messaging carry trace id, blueprint id, agent origin and workflow step and no tenant, project, run, step, attempt or schema-version field, and its decision 1 makes those fields required on every Factory integration event while the trace id stays diagnostic correlation that is never an authorization or idempotency key. Decision D113 places the change in this feature. The amendment of ADR-0014 on envelopes per event family (decision D114) settles which envelope carries what: a Factory service writes the run event envelope of the contracts package, the descriptor run-event-envelope-v1, for its integration events, and AgentEventEnvelope carries agent lifecycle events only, with the same scope fields. This PBI therefore changes the lifecycle envelope and offers it to no service as the envelope of its integration events. The run, step and attempt abstractions the feature names are delivered here as typed identifiers of the Abstractions package: a run id, a step id and an attempt id over a guid, and a tenant id and a project id over a string, the underlying types model/services/control-plane/RunControlService.yaml gives runId, stepId, attemptId, tenantId and projectId. The trace context gains tenant id, project id, run id, step id, attempt id and a schema version as members a caller must supply, in those types. The envelope gains the same identity together with schema version, correlation id, causation id, producer identity and event type, and keeps trace id, blueprint id and agent origin as diagnostic fields. The scope is taken from the authenticated context of the caller, never from prompt text or a caller-controlled header, as ADR-0015 decision 2 requires. Two kinds of versioning are kept apart. The serialized schema follows the additive rule of ADR-0014 decision 6: the shape the Messaging package writes today, which has no schema-version field, is schema version 1, as decision D114 settles; the new fields arrive in the next schema version; the serialized shape of version 1 is frozen as a reader contract with its own contract test and is not altered; a versioned reader accepts it for a window that is an option of the reader; an unknown version is refused with the reason recorded; and no second incompatible envelope appears under an existing version. The CLR types are not kept side by side: AgentTraceContext and AgentEventEnvelope change in place, a request without scope no longer compiles, and that source-breaking change is released as a new major version of the Abstractions and Messaging packages. The publisher MassTransitAgentLifecyclePublisher lives in a repository of its own and mirrors the envelope to the broker properties there. The grains that persist the same identifiers arrive with the agent runtime in a later increment, so this PBI proves the identifier types against the model and not against a grain. The agent host template consumes the types by a version pin and defines none of its own.

Acceptance criteria

AC1 Given the package ConnectSoft.Extensions.AI.Factory.Abstractions, when a caller builds an AgentTraceContext for a Factory request, then tenant id, project id, run id, step id where the request belongs to a workflow step, attempt id and the schema version are members the caller must supply beside the trace id, as typed identifiers of the package whose underlying types are those of model/services/control-plane/RunControlService.yaml, and a request contract built without the scope does not compile; the trace id stays diagnostic and is never used as an authorization or idempotency key (ADR-0014 decision 1, ADR-0015 decision 2).
AC2 Given the package ConnectSoft.Extensions.AI.Factory.Messaging, when the lifecycle mapper builds an event from a stage and a request, then the AgentEventEnvelope of every lifecycle event carries event id, schema version, occurred-at, tenant id, project id, run id, step id and attempt id where applicable, correlation id, causation id, producer identity and event type, with trace id, blueprint id and agent origin kept as diagnostic fields; the envelope carries agent lifecycle events only, and the serialized names of its scope fields equal those of the run event envelope run-event-envelope-v1 that a Factory service writes for its integration events; a contract test asserts the required fields on every event type and the scope field names against that schema, and docs/reference/event-envelope.md lists the same fields and states which envelope carries which event family (ADR-0014 decision 1 and its amendment on envelopes per event family).
AC3 Given a serialized envelope of schema version 1, the shape the Messaging package wrote before this change, when the versioned reader reads it inside the compatibility window its option sets, then it is accepted and mapped to the current version with the missing identity marked absent, and an envelope of an unknown schema version is refused with the reason recorded; the serialized shape of schema version 1 is kept as a frozen reader contract with its own contract test and is not altered, while the CLR types change in a new major version of the Abstractions and Messaging packages (ADR-0014 decision 6; docs/reference/event-envelope.md records the default of the window).
AC4 Given the MassTransit publisher package of the Factory libraries, when a lifecycle event is published, then the event type, the tenant id, the trace id, the correlation id and the schema version of the envelope are mirrored to the five broker properties cs-event-type, cs-tenant-id, cs-trace-id, cs-correlation-id and cs-schema-version that ADR-0012 decision 5 keeps as the mapping of the MassTransit profile; and a contract test of the Abstractions package asserts the underlying types of the run, step and attempt identifiers against the payload of AttemptOutcomeRecorded in model/services/control-plane/RunControlService.yaml, the record of the durable substrate that ADR-0024 decision 1 keeps on grains.
Traces: descriptors run-event-envelope-v1
Traces: adrs ADR-0012, ADR-0014, ADR-0015, ADR-0024
Depends on AIFACTORY-US-191
Sources model/components.yaml, docs/architecture/ecosystem-composition.md, docs/architecture/adr/0014-run-and-lifecycle-envelopes.md, docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md, docs/reference/event-envelope.md, docs/reference/schemas/run-event-envelope.schema.json, model/services/control-plane/RunControlService.yaml

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-161 Tenant and project scope in the Factory contracts implementation AgentTraceContext of the package ConnectSoft.Extensions.AI.Factory.Abstractions carries tenant id, project id, run id, step id, attempt id and a schema version as members the caller must supply, beside the trace id, blueprint id, agent origin and workflow step; the package defines the typed identifiers they use, a run id, a step id and an attempt id over a guid and a tenant id and a project id over a string, matching runId, stepId, attemptId, tenantId and projectId of model/services/control-plane/RunControlService.yaml; AgentRequest and AgentResult expose them; a request contract built without the scope does not compile, and the change is released as a new major version of the package. ConnectSoft.Extensions.AI.Factory.Abstractions
AIFACTORY-TASK-954 Schema version and run identity on the envelope, the lifecycle events and the mapper contract AgentEventEnvelope, the lifecycle event types and AgentLifecycleEventMapper of the package ConnectSoft.Extensions.AI.Factory.Messaging carry event id, schema version, occurred-at, tenant id, project id, run id, step id, attempt id, correlation id, causation id, producer identity and event type, in the typed identifiers of AIFACTORY-TASK-161; trace id, blueprint id and agent origin stay as diagnostic fields; the envelope stays the envelope of agent lifecycle events, the serialized names of its scope fields equal those of the run event envelope of the contracts package (run-event-envelope-v1), and the pages of the package state that a Factory service writes that run event envelope for its integration events; the change is released as a new major version of the package. ConnectSoft.Extensions.AI.Factory.Messaging
AIFACTORY-TASK-955 Versioned reader for the envelope of schema version 1 implementation A versioned reader in the package ConnectSoft.Extensions.AI.Factory.Messaging accepts a serialized envelope of schema version 1 inside the compatibility window and refuses an unknown version with a reason; the window in which version 1 is read is an option of the reader with its default recorded in docs/reference/event-envelope.md; the serialized shape of version 1 is frozen by a contract test over stored samples and is not altered. ConnectSoft.Extensions.AI.Factory.Messaging
AIFACTORY-TASK-1052 Broker property mapping of the MassTransit lifecycle publisher implementation MassTransitAgentLifecyclePublisher of the package ConnectSoft.Extensions.AI.Factory.Messaging.MassTransit, in the repository of that name with its own solution, pins and pipeline, mirrors the envelope to the five broker properties of ADR-0012 decision 5: cs-event-type, cs-tenant-id, cs-trace-id, cs-correlation-id and cs-schema-version; a unit test of that repository asserts the five properties on a published lifecycle event, and the repository pins the new major version of the Messaging package. ConnectSoft.Extensions.AI.Factory.Messaging.MassTransit
AIFACTORY-TASK-956 Envelope reference page revised to the fields of the library envelope documentation docs/reference/event-envelope.md lists the required fields of ADR-0014 decision 1 as the library envelope carries them, states that AgentEventEnvelope carries agent lifecycle events and that a Factory service writes the run event envelope of the contracts package for its integration events, with the same scope fields, names the schema version, the frozen shape of schema version 1 and the default of the compatibility window of the versioned reader, and no longer describes a field the library does not have. ConnectSoft.AI.SoftwareFactory.Documentation
AIFACTORY-TASK-957 Verify the required fields and the earlier version by contract tests verification Run dotnet test -c Release --no-build on the solutions of the Abstractions, the Messaging and the MassTransit publisher repositories; the contract tests assert the required fields on every event type, the read of a stored envelope of schema version 1, the scope field names against docs/reference/schemas/run-event-envelope.schema.json, the five broker properties and the underlying types of the run, step and attempt identifiers against the payload of AttemptOutcomeRecorded as model/services/control-plane/RunControlService.yaml states it, which proves AC1 to AC4 of AIFACTORY-US-192 (ADR-0014). ConnectSoft.Extensions.AI.Factory.Messaging

AIFACTORY-US-193: Factory libraries: FactoryAgentBase refuses a request without trace metadata before any model call and retries in attempts with a backoff

enabling · persona platform-admin As a platform admin, I want the Factory agent base to refuse a request that carries no trace id or no Factory scope instead of stamping one, so that no agent executes a model call that cannot be attributed to a tenant, a project, a run and an attempt.

The base of the package ConnectSoft.Extensions.AI.Factory runs the pipeline docs/planes/agent-runtime/agent-runtime.md describes: accept, prompt, run, validate, retry, complete or escalate. Today it refuses nothing except a null request: AgentTraceContext generates a trace id when none is supplied and the base stamps its own agent id as the origin, so a request without identity executes and its events cannot be attributed. Decision D113 makes the refusal work of this feature. Before the Accepted stage is published and before any model call, the base validates the trace metadata of the request: the trace id and the Factory scope of the earlier PBI (tenant, project, run and attempt identity, and the step identity where the request belongs to a workflow step). A request that lacks any of them is refused with a typed refusal that names the missing fields; no Accepted event is published, no model is invoked, the refusal is counted on the meter of the library and logged with the agent id. The base no longer generates a trace id for a caller; it still stamps its own agent id as the origin of the outgoing context. The set of required fields is an option of the library with the trace id and the scope as its default. A host can add the blueprint id to the set, and a request without it is then refused in the same way. The agent origin is never a required field a caller supplies, because the base stamps it, so a missing origin cannot be refused. The default set is settled by decision D114: the trace id and the scope are required, the blueprint id only when a host adds it through the option, and the option test covers that case. In the same change the retry vocabulary follows ADR-0026 decision 6: the options say attempts, the total number of tries, with a backoff between them, and the wait honours cancellation.

Acceptance criteria

AC1 Given a request whose trace context lacks the trace id or any of tenant id, project id, run id and attempt id, when ExecuteAsync of FactoryAgentBase is called, then the request is refused before the Accepted stage is published and before any model call, the refusal names the missing fields, it is counted and logged, and a unit test with a scripted agent proves that the model is never invoked; when the required set of the options includes the blueprint id, a request without it is refused in the same way, proven by a unit test, and the agent origin is never a required field of the caller because the base stamps it (ADR-0014 decision 1 makes the scope required and keeps the trace id diagnostic).
AC2 Given a request with complete trace metadata, when the base accepts it, then the outgoing trace context keeps the supplied trace id and scope unchanged and carries the agent id of the base as its origin; the base generates no trace id on behalf of a caller, and the pipeline runs in the order docs/planes/agent-runtime/agent-runtime.md describes (ADR-0014).
AC3 Given the options of the library, when validation fails on an attempt, then the base waits the configured backoff and tries again until the configured number of attempts is used, a cancellation during the wait ends the wait at once, and after the last attempt the escalation sink receives the issues of that attempt; the options say attempts and backoff as ADR-0026 decision 6 requires and the unit tests cover first-attempt success, retry then success and escalation.
Traces: adrs ADR-0014, ADR-0026
Depends on AIFACTORY-US-192
Sources model/components.yaml, docs/architecture/adr/0014-run-and-lifecycle-envelopes.md, docs/architecture/adr/0026-requirements-to-ux-handoff.md, docs/planes/agent-runtime/agent-runtime.md

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-958 Trace metadata validation in FactoryAgentBase before the Accepted stage implementation FactoryAgentBase validates the trace id and the Factory scope of a request before it publishes Accepted; a request that lacks a required field is refused with a typed refusal naming the fields, no model is invoked, the refusal is counted on the meter connectsoft.ai.factory.agent and logged; AgentTraceContext no longer generates a trace id for a caller. ConnectSoft.Extensions.AI.Factory
AIFACTORY-TASK-959 Attempts and backoff in the options and the retry loop of the base implementation AgentFactoryOptions and its validator expose the number of attempts, the backoff and the list of required trace fields; the retry loop of FactoryAgentBase waits the backoff between attempts and ends the wait on cancellation; the earlier maximum setting is read for the compatibility window and mapped to attempts. ConnectSoft.Extensions.AI.Factory
AIFACTORY-TASK-960 Scripted agent and recording doubles for the refusal and backoff tests fixture A scripted agent, a recording lifecycle publisher, a recording escalation sink and a controllable time provider in the unit test project of the library drive the refusal, the retry with backoff and the escalation without a live model. ConnectSoft.Extensions.AI.Factory
AIFACTORY-TASK-961 Verify the refusal of a request without trace metadata and the retry with backoff verification Run dotnet test -c Release --no-build on the Factory library solution; the refusal, origin and backoff tests pass, together with the option test in which the required set includes the blueprint id and a request without it is refused before any model call, and prove AC1 to AC3 of AIFACTORY-US-193 (ADR-0014, ADR-0026). ConnectSoft.Extensions.AI.Factory

AIFACTORY-US-194: Factory libraries: AgentLifecycleStage gains Cancelled and the base reports a terminal Failed with a failure class before it rethrows

enabling · persona platform-admin As a platform admin, I want every run of a Factory agent to end with exactly one terminal lifecycle stage, Cancelled included, so that a cancellation or an unexpected exception is observable on the envelope instead of ending the attempt without a trace.

AgentLifecycleStage of the package ConnectSoft.Extensions.AI.Factory.Abstractions has Accepted, OutputValidated, Completed, Failed and Escalated. The base catches a cancellation and rethrows it, and catches any other exception, logs it, counts it and rethrows it; in both cases no terminal event is published, which the context of ADR-0014 records. Decision 2 of that ADR adds Cancelled as a terminal state distinct from Failed and requires that an exception path emits a terminal Failed event with a failure class before it rethrows; decision D113 places the work here. The enumeration gains Cancelled as an appended member, so that the stored values of the existing members do not change. When the pipeline observes a cancellation the base publishes the Cancelled stage and then rethrows; when it observes any other exception it publishes Failed with a failure class and then rethrows. The terminal publication does not use the cancelled token of the request, is bounded by a publication timeout, and a failure of the publisher is logged and never replaces the original exception. The messaging package gains the event of the Cancelled stage and the mapper maps it, and the MassTransit publisher, which lives in a repository of its own, publishes it; the failed event carries the failure class in the vocabulary model/services/control-plane/RunControlService.yaml names (transient, permanent, policy-denied, validation, cancellation, uncertain). The library reports an observed termination; the request to cancel and the authoritative outcome stay with Run Control, as ADR-0024 decision 5 keeps them.

Acceptance criteria

AC1 Given an attempt in progress, when its cancellation token is cancelled, then FactoryAgentBase publishes the Cancelled stage of AgentLifecycleStage as a terminal stage distinct from Failed and then rethrows the cancellation; no Completed or Failed stage follows, and a unit test proves the order (ADR-0014 decision 2).
AC2 Given an unexpected exception in the prompt, the model call or the validation, when the pipeline unwinds, then the base publishes Failed with a failure class before the exception is rethrown, the publication does not use the cancelled token of the request and is bounded by a timeout, and a failure of the publisher is logged without replacing the original exception (ADR-0014 decision 2).
AC3 Given the packages ConnectSoft.Extensions.AI.Factory.Abstractions and ConnectSoft.Extensions.AI.Factory.Messaging, when the Cancelled stage is mapped, then an event of the cancelled run exists beside the five existing lifecycle events, the failed event carries the failure class in the vocabulary of model/services/control-plane/RunControlService.yaml, exactly one of Completed, Failed and Cancelled ends a run, and a contract test proves that the stored values of the earlier enumeration members are unchanged (ADR-0014 decision 6, ADR-0024 decision 5 keeps the authoritative outcome with Run Control).
Traces: adrs ADR-0014, ADR-0024
Depends on AIFACTORY-US-192, AIFACTORY-US-193
Sources model/components.yaml, model/services/control-plane/RunControlService.yaml, docs/architecture/adr/0014-run-and-lifecycle-envelopes.md, docs/architecture/adr/0024-durable-execution-substrate.md

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-962 Cancelled stage in AgentLifecycleStage and the failure class on the agent result contract AgentLifecycleStage of the package ConnectSoft.Extensions.AI.Factory.Abstractions has Cancelled as an appended member and AgentResult exposes a failure class with the values transient, permanent, policy-denied, validation, cancellation and uncertain; the stored values of the earlier members are unchanged. ConnectSoft.Extensions.AI.Factory.Abstractions
AIFACTORY-TASK-963 Terminal Cancelled and Failed publication in FactoryAgentBase before the rethrow implementation FactoryAgentBase publishes Cancelled on an observed cancellation and Failed with a failure class on any other exception before it rethrows; the terminal publication runs on a token that is not the cancelled one, within a publication timeout, and a publisher failure is logged and does not mask the original exception. ConnectSoft.Extensions.AI.Factory
AIFACTORY-TASK-964 Cancelled run event, failure class on the failed event and the mapper implementation The package ConnectSoft.Extensions.AI.Factory.Messaging holds the event of a cancelled run on AgentEventEnvelope, the failed event carries the failure class, and AgentLifecycleEventMapper maps the Cancelled stage; a unit test of the Messaging repository asserts the mapping of every stage. ConnectSoft.Extensions.AI.Factory.Messaging
AIFACTORY-TASK-1053 Cancelled run event and failure class published by the MassTransit lifecycle publisher implementation MassTransitAgentLifecyclePublisher of the package ConnectSoft.Extensions.AI.Factory.Messaging.MassTransit, in the repository of that name, publishes the event of a cancelled run and the failed event with its failure class under the same broker properties as the other lifecycle events; a unit test of that repository asserts both. ConnectSoft.Extensions.AI.Factory.Messaging.MassTransit
AIFACTORY-TASK-965 Verify one terminal stage per run on cancellation and on an exception verification Run dotnet test -c Release --no-build on the solutions of the Abstractions, the Factory, the Messaging and the MassTransit publisher repositories; the tests of the cancelled run, the failed run, the published cancelled event and the enumeration values pass and prove AC1 to AC3 of AIFACTORY-US-194 (ADR-0014). ConnectSoft.Extensions.AI.Factory

AIFACTORY-US-195: Extensions.AI: an Anthropic chat client is registered under the keyed provider pattern with streaming, tool calling and usage

enabling · persona platform-admin As a platform admin, I want an Anthropic adapter behind the chat client abstraction of the AI library, so that the model profiles of the first solution pack that name an Anthropic deployment can be served through the same keyed registration as the other providers.

The Features page of ConnectSoft.Extensions.AI lists OpenAI, Azure OpenAI, Ollama and Azure AI Inference as chat completion providers, each with its own extension class, its options and a keyed IChatClient; docs/planes/model-compute/providers-and-profiles.md records that no Anthropic adapter exists anywhere in the estate and that one is required for the first solution pack (decision D16), registered under the same keyed pattern with tool calling and structured output declared in its capability evidence. This PBI adds the provider: a new value of the provider choice, an extension class, options for the endpoint, the model identifier and the reference to the key, options validation at startup, a keyed chat client and a health check like the other providers have. The adapter supports streaming with cancellation, tool calling and structured output, and reports input and output token usage on the response, which the invocation receipt of the model gateway needs. Its contract tests run against recorded responses, so that the pipeline of the library calls no live provider. A missing key reference or model identifier fails options validation at startup, and the key never appears in a log entry or in telemetry. The adapter is library code for the model router, which ADR-0028 decision 3 makes the only service that calls model providers; an agent host reaches a model through the model gateway and never registers this adapter directly. The provider table of docs/planes/model-compute/providers-and-profiles.md is revised to list the adapter with its keyed name and its capability evidence.

Acceptance criteria

AC1 Given a host configured with the Anthropic provider, when the AI library registers its services, then a keyed IChatClient for Anthropic is resolved in the same way as the clients of the existing providers, with its options bound and validated and its health check registered, and docs/planes/model-compute/providers-and-profiles.md lists the adapter in its provider table with its keyed name and its capability evidence (ADR-0028 decision 3 keeps the model router the only caller of a provider).
AC2 Given recorded provider responses, when the contract tests of the adapter run, then a streamed completion with cancellation, a completion with a tool call, a completion with structured output and the input and output token usage of each are asserted without a live provider call, and the results are kept as the capability evidence a model profile needs under ADR-0021 decision 1.
AC3 Given a configuration without the key reference or without the model identifier, when the host starts, then options validation fails with the missing setting named, and a test proves that the key appears in no log entry and in no telemetry attribute of a completion (docs/planes/model-compute/model-gateway.md, ADR-0021).
Traces: adrs ADR-0021, ADR-0028
Depends on AIFACTORY-US-191
Sources model/components.yaml, docs/architecture/ecosystem-composition.md, docs/planes/model-compute/providers-and-profiles.md, docs/planes/model-compute/model-gateway.md

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-162 Anthropic model adapter implementation An adapter behind the model client abstraction of ConnectSoft.Extensions.AI with streaming, tool use, structured output and usage reporting, registered as a keyed chat client through its own extension class; contract tests run against recorded responses. ConnectSoft.Extensions.AI
AIFACTORY-TASK-966 Anthropic options, startup validation and health check implementation The provider choice of the AI library has the Anthropic value; its options carry the endpoint, the model identifier and the key reference, are validated at startup with the missing setting named, and a health check of the provider is registered like those of the other providers. ConnectSoft.Extensions.AI
AIFACTORY-TASK-967 Recorded response fixtures for the Anthropic contract tests fixture Recorded responses for a streamed completion, a tool call, a structured output and a provider error are stored in the test project with every secret removed, and a replay handler serves them to the adapter so that no test calls a live provider. ConnectSoft.Extensions.AI
AIFACTORY-TASK-1054 Provider table of the documentation site lists the Anthropic adapter documentation The provider table of docs/planes/model-compute/providers-and-profiles.md lists the Anthropic adapter of ConnectSoft.Extensions.AI with its keyed name and its capability evidence (streaming, tool calling, structured output and usage), and the page no longer states that no Anthropic adapter exists in the estate. ConnectSoft.AI.SoftwareFactory.Documentation
AIFACTORY-TASK-968 Verify the Anthropic adapter against the recorded responses verification Run dotnet test -c Release --no-build on the AI library solution; the contract tests of streaming, tool calling, structured output, usage and startup validation pass, and the provider table revised by AIFACTORY-TASK-1054 lists the adapter, which proves AC1 to AC3 of AIFACTORY-US-195 (ADR-0021). ConnectSoft.Extensions.AI

AIFACTORY-US-196: Factory libraries: a Factory model client sends scope, profile and correlation to the model gateway and returns the invocation receipt

enabling · persona platform-admin As a platform admin, I want a chat client of the Factory libraries that reaches models only through the model gateway, under the scope of the attempt, and keeps the receipt, so that a generated agent host needs no provider registration and every completion is attributable and accounted.

docs/architecture/ecosystem-composition.md names model profile and receipt contracts as part of the extension of this component, and docs/planes/model-compute/model-gateway.md records that the AI library has no profile, policy, reservation or receipt contract today. The agent host template registers the Factory model client of the AI libraries as the chat client of a generated host when its Factory model switch is on, so the client is a deliverable of this feature. This PBI adds the contracts and the client to the Factory packages, where the scoped trace context already lives. The contracts are a reference to a logical model profile, which names a profile such as code agent and never a vendor model, and an invocation receipt with the invocation id, the actual route, the policy receipt, the usage status, the validation status and the references to redacted diagnostics, as the gateway page lists them for the response. The client implements the chat client abstraction over a gateway transport port: it sends the tenant, project, run, step and attempt identity of the trace context, the profile reference and the correlation id with every completion and returns the output together with the receipt. A completion without scope is refused before any network call. A gateway that is unreachable ends the completion with a failure class and never falls back to a direct provider, because ADR-0028 decision 3 keeps the gateway the only route to the model router. The transport port keeps the library free of a dependency on a gateway client package of a later increment.

Acceptance criteria

AC1 Given the package ConnectSoft.Extensions.AI.Factory.Abstractions, when a host references it, then a model profile reference that names a logical profile and an invocation receipt with invocation id, actual route, policy receipt, usage status, validation status and the references to redacted diagnostics are available as contracts, which are the fields docs/planes/model-compute/model-gateway.md lists for the response of the gateway (ADR-0021 decision 1 makes profiles the assets a client references).
AC2 Given a scoped trace context and a profile reference, when the Factory model client runs a completion, streamed or not, then the transport port receives the tenant, project, run, step and attempt identity, the profile reference and the correlation id, and the caller receives the output together with the receipt; a test with a fake transport proves the values (ADR-0028 decision 3, ADR-0014 decision 1).
AC3 Given a completion without scope or a transport that reports the gateway unreachable, when the client is called, then the first is refused before any network call and the second ends with a failure class and no direct provider call; the package references no provider adapter, which an architecture test asserts (ADR-0028 decision 3).
Traces: adrs ADR-0014, ADR-0021, ADR-0028
Depends on AIFACTORY-US-192, AIFACTORY-US-194
Sources model/components.yaml, docs/architecture/ecosystem-composition.md, docs/planes/model-compute/model-gateway.md, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-969 Model profile reference and invocation receipt contracts contract The package ConnectSoft.Extensions.AI.Factory.Abstractions holds a model profile reference, an invocation receipt (invocation id, actual route, policy receipt, usage status, validation status and the references to redacted diagnostics) and the gateway transport port the client calls; none of them names a vendor model or a provider type. ConnectSoft.Extensions.AI.Factory.Abstractions
AIFACTORY-TASK-970 Factory model client as a chat client over the gateway transport port implementation The package ConnectSoft.Extensions.AI.Factory holds a chat client that sends scope, profile reference and correlation id through the transport port for plain and streamed completions, returns the receipt with the output, refuses a completion without scope and maps an unreachable gateway to a failure class; a registration extension makes it the chat client of a host. ConnectSoft.Extensions.AI.Factory
AIFACTORY-TASK-971 Fake gateway transport for the tests of the client and of its consumers fixture A fake transport in the test support of the Factory library returns a receipt for a completion, streams a completion and simulates an unreachable gateway; it is published with the test support so that a consuming template can run its host tests against it. ConnectSoft.Extensions.AI.Factory
AIFACTORY-TASK-972 Verify the scope, the receipt and the absence of a provider path verification Run dotnet test -c Release --no-build on the Factory library solution; the fake transport tests and the architecture test pass and prove AC1 to AC3 of AIFACTORY-US-196 (ADR-0028). ConnectSoft.Extensions.AI.Factory

AIFACTORY-US-220: Factory libraries: one scope accessor, its middleware and the Factory token contract names live in the abstractions package

enabling · persona platform-admin As a platform admin, I want the scope accessor, the middleware that fills it and the names of the Factory token contract to exist once in the abstractions package, so that every template pins one definition of the trusted scope and of the role claims before any Factory service is generated.

ADR-0015 decision 2 requires every Factory contract to carry the trusted tenant id and project id derived from the authenticated context, never from caller-controlled headers, and decisions 5 and 6 have the authorization server issue the seven Factory roles as claims that every service enforces. The base, gateway, identity and authorization server templates all need the same scope type, the same accessor and the same claim and role names before a Factory service exists, so this work belongs to the library phase and not to a development feature. The package ConnectSoft.Extensions.AI.Factory.Abstractions holds one scope object (tenant and project, with run, step and attempt while a run is in flight), one accessor that returns it in REST, gRPC and message handlers and throws when no scope was established, the middleware and the message filter that fill it from the validated token and from the envelope of ADR-0014, and the Factory token contract: the claim type names, the seven role names and one formatter and parser of the scoped role value. The templates pin the package and type none of the names. The gateway side of the chain, the resolution of the project membership and the refusal tests through a running gateway, stays with the feature trusted-scope-chain, which consumes this package.

Acceptance criteria

AC1 Given a host that registers the scope middleware of ConnectSoft.Extensions.AI.Factory.Abstractions, when a REST call, a gRPC call and a message handler run under a validated token or a received envelope, then the single accessor returns the same tenant and project in all three and throws a typed exception when no scope was established; unit tests of the package prove the three entry points and the missing-scope case (ADR-0015 decision 2).
AC2 Given a request that carries a tenant or project header a caller typed, when the middleware fills the scope, then the values come from the validated token and the header is ignored, and when a message is published the scope travels in the envelope fields and the handler reads it from there; unit tests prove that a forged header never reaches the accessor (ADR-0015 decision 2, ADR-0014 decision 1).
AC3 Given the token contract types of the package, when a scoped role value is formatted and parsed, then the role, the scope kind, the scope identifier and, for a delegated role, the delegation identifier round-trip, a malformed value is refused with a typed error, and the claim type names and the seven role names exist once as constants the templates reference; round-trip and refusal tests pass (ADR-0015 decisions 5 and 6).
Traces: descriptors execution-scope-v1
Traces: adrs ADR-0014, ADR-0015
Depends on AIFACTORY-US-192
Sources model/components.yaml, docs/architecture/adr/0014-run-and-lifecycle-envelopes.md, docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-186 Scope accessor and middleware in the Factory abstractions implementation One accessor returns the scope in REST, gRPC and message handlers; it throws when no scope was established. ConnectSoft.Extensions.AI.Factory.Abstractions
AIFACTORY-TASK-142 Scope propagation over REST, gRPC and messaging from the validated token implementation A scope object is created by the middleware from the validated token and travels in headers between Factory services and in the message envelope; services read it from one accessor and a header a caller typed is ignored. ConnectSoft.Extensions.AI.Factory.Abstractions
AIFACTORY-TASK-1173 Factory token contract names and the scoped role value in the Factory abstractions package contract The package ConnectSoft.Extensions.AI.Factory.Abstractions holds the Factory token contract: the claim type names of the tenant claim, the role claim and the delegated role claim, the seven role names, and one formatter and parser of the scoped role value (role, scope kind, scope identifier and, for a delegated role, the delegation identifier) with round-trip tests and a refusal of a malformed value; the feature component-extensions-ai publishes the package, and the identity, authorization server, base and gateway templates pin it and type none of the names. ConnectSoft.Extensions.AI.Factory.Abstractions
AIFACTORY-TASK-1059 Verify the scope accessor, the forged-header refusal and the token contract round trip verification Run dotnet test -c Release --no-build on the abstractions solution; the accessor tests for REST, gRPC and message handlers, the missing-scope and forged-header tests and the round-trip and refusal tests of the scoped role value pass and prove AC1 to AC3 of AIFACTORY-US-220 (ADR-0014, ADR-0015). ConnectSoft.Extensions.AI.Factory.Abstractions

AIFACTORY-US-197: AI and Factory libraries: the packages are built, tested and published to the ConnectSoft feed in dependency order with the versions the consumers pin

evidence · persona platform-admin As a platform admin, I want proof that the extended AI and Factory packages are on the ConnectSoft feed with versions a consumer can pin, so that the agent host template and the Factory services restore them from the feed and never from a local source.

This PBI is the publication proof of the feature. The epic is done only when each library publishes to the feed before the Factory code that consumes it is built, and decision D114 settles which feed that is: the Factory feed is the Azure Artifacts feed the ConnectSoft libraries already publish to, so this PBI says the ConnectSoft feed and no second feed is created. The agent host template features pin the versions of the Factory packages that carry the scoped trace context, the refusing base, the Cancelled stage and the model client, and the base, gateway, identity and authorization server templates pin the Abstractions package for the scope object, the scope accessor with its middleware and message filter and the Factory token contract of AIFACTORY-US-220. The pipelines of the library repositories build, test, pack and push in dependency order: the Abstractions package first, then the Factory and the Messaging packages, then the MassTransit publisher package, with the AI library before the agents framework library. Each package has its own pipeline in its own repository. A stage publishes only when the tests of its solution pass and a version that is already on the feed is refused. The order is held by pipeline resources: the pipeline of a downstream package is triggered by the pipeline resource of its upstream and restores the upstream version from the feed, so an upstream run that fails publishes no version for the downstream to build on. The Abstractions and Messaging packages, whose CLR types changed in a source-breaking way, publish under a new major version, and every package that references them moves its pin to it. A probe then proves the result from the side of a consumer: a clean project that has the ConnectSoft feed as its only source and no project reference restores the published versions, builds, runs a scripted agent derived from the base through a scoped request to a terminal stage, resolves the scope accessor of the Abstractions package after its middleware ran and round-trips a scoped role value of the Factory token contract. The published versions are recorded in the Runbook pages of the libraries, which is where a consuming template reads its pins. The migration guide of the Factory library pages already forbids mixing a published package reference with a local project reference for the same assembly; the probe is the test of that rule.

Acceptance criteria

AC1 Given the pipelines of the six AI and Factory library repositories, when they run after the work of the feature, then each package is built, tested, packed and pushed to the ConnectSoft feed in dependency order, a stage publishes only after the tests of its solution pass, the Abstractions and Messaging packages, whose contracts changed in a source-breaking way, publish under a new major version that the dependent packages pin, the published Abstractions package holds the scope object, the scope accessor with its middleware and message filter and the Factory token contract of AIFACTORY-US-220 that ADR-0015 decisions 2, 5 and 6 require of every template, and the published versions are recorded in the Runbook pages of the libraries (ADR-0028; model/backlog/epics.yaml states the publication before consumption as the completion of the epic).
AC2 Given a clean consumer project with the ConnectSoft feed as its only package source and no project reference, when it restores the published versions and builds, then a scripted agent derived from FactoryAgentBase runs a scoped request to a terminal stage and its events carry the envelope fields of ADR-0014 decision 1, and the probe resolves the scope accessor of the published Abstractions package after its middleware ran and round-trips a scoped role value of the Factory token contract (ADR-0015 decision 2); the same versions are the pins the agent host template features and the base, gateway, identity and authorization server templates read.
AC3 Given a failing test in a library solution or a version that is already on the feed, when the pipeline reaches the publication stage, then the stage is refused with the reason; because each downstream pipeline is triggered by the pipeline resource of its upstream and restores the upstream version from the feed, no downstream package is published on top of the failed one, and a run with a planted failing test proves the refusal (ADR-0028, docs/architecture/ecosystem-composition.md).
Traces: adrs ADR-0014, ADR-0015, ADR-0028
Depends on AIFACTORY-US-192, AIFACTORY-US-193, AIFACTORY-US-194, AIFACTORY-US-195, AIFACTORY-US-196, AIFACTORY-US-220
Sources model/components.yaml, model/backlog/epics.yaml, docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md, docs/architecture/ecosystem-composition.md, docs/architecture/catalogs/libraries.md

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-973 Publication order and version guard in the library pipelines operations The pipeline of each of the six repositories (ConnectSoft.Extensions.AI, ConnectSoft.Extensions.AI.AgentsFramework, ConnectSoft.Extensions.AI.Factory.Abstractions, ConnectSoft.Extensions.AI.Factory, ConnectSoft.Extensions.AI.Factory.Messaging, ConnectSoft.Extensions.AI.Factory.Messaging.MassTransit) publishes after the tests of its solution pass and refuses a version already on the feed with the reason. The order is the Abstractions package, then the Factory and the Messaging packages, then the MassTransit publisher package, with the AI library before the agents framework library. The order is held by pipeline resources: each downstream pipeline is triggered by the pipeline resource of its upstream and restores the upstream version from the feed, so a failed upstream run publishes no version for the downstream to build on. The Abstractions and Messaging packages publish under a new major version, and the Abstractions package of that version holds the scope accessor, its middleware and the Factory token contract of AIFACTORY-US-220. The check per repository is its pipeline file with the upstream resource and one green publishing run. ConnectSoft.Extensions.AI.Factory
AIFACTORY-TASK-974 Feed probe consumer for the published Factory packages fixture A probe project with the ConnectSoft feed as its only source and no project reference restores the published versions, builds, runs a scripted agent through a scoped request to a terminal stage, resolves the scope accessor of the Abstractions package after its middleware ran and round-trips a scoped role value of the Factory token contract; the probe runs as the last stage of the Factory library pipeline. ConnectSoft.Extensions.AI.Factory
AIFACTORY-TASK-975 Published versions and the changed contracts recorded in the library pages documentation The Runbook page of each of the six library repositories names the version its package published; the Features page and the migration guide of the Factory library pages describe the scoped trace context, the typed identifiers, the scope object and its accessor with the middleware and the message filter, the Factory token contract, the refusal, the Cancelled stage, the failure class and the model client, state the new major version of the Abstractions and Messaging packages with what a consumer changes, and the package responsibility matrix names the package of each new type. The check per repository is a build of its documentation site without warnings. ConnectSoft.Extensions.AI.Factory
AIFACTORY-TASK-976 Verify the published packages by the probe and by a planted failing run verification One run of the six pipelines in their order publishes every package and the probe passes, the scope accessor and the token contract of the published Abstractions package included; one run with a planted failing test in an upstream solution stops before publication and triggers no downstream pipeline; both runs prove AC1 to AC3 of AIFACTORY-US-197 (ADR-0028). ConnectSoft.Extensions.AI.Factory

AIFACTORY-US-097: AI and Factory libraries: scope in contracts, Anthropic adapter, durable base is delivered and proven by its consumers

enabling · persona platform-admin As a platform admin, I want Extensions.AI + AgentsFramework + Factory libraries to carry scope in contracts, Anthropic adapter, durable base, so that it serves model adapters, keyed agents, lifecycle hooks without later rework.

This is the integration PBI of the feature. A platform admin takes the AI and Factory libraries from their recorded baseline to published packages: the scope, the run, step and attempt identity and a schema version on the trace context and the envelope, one scope accessor with its middleware and the Factory token contract in the Abstractions package, a base that refuses a request without trace metadata and retries in attempts with a backoff, the Cancelled stage and a terminal Failed before the rethrow, the Anthropic adapter and the Factory model client with its profile and receipt contracts. The implementation lives in the earlier PBIs of this file; this PBI proves them together from the side of the consumers. The published packages are restored from the ConnectSoft feed, a scripted agent runs through every lifecycle outcome under a scoped request, and the result is what the agent host template features pin. The feature is done when no request without scope executes, every lifecycle event is attributable to tenant, project, run and attempt, a cancellation is observable, and the packages are on the feed with recorded versions. Repository of the feature: the AI and Factory library repositories. The services that reach these libraries in a later increment are the agent registry, the agent runtime and the context builder.

Acceptance criteria

AC1 Given the library repositories of the feature, when their pipelines run, then each package builds, its tests pass and it publishes to the ConnectSoft feed with a verified version that the consuming repositories pin (ADR-0028, model/components.yaml).
AC2 Given the work of AIFACTORY-TASK-160 (build and test the Factory libraries as they are) is done, then a recorded baseline exists: every project of the AI and Factory libraries builds and its tests pass with the package versions of the feed, the library types of the recorded agent base work are the single definition and the pins are aligned (ADR-0028, docs/architecture/ecosystem-composition.md).
AC3 Given the work of AIFACTORY-TASK-161 (tenant and project scope in the Factory contracts) is done, then every request and event contract carries the trusted scope, the run, step and attempt identity and a schema version, and a contract without scope does not compile (ADR-0014 decision 1).
AC4 Given the work of AIFACTORY-TASK-162 (Anthropic model adapter) is done, then an adapter behind the model client abstraction with streaming, tool use and usage reporting exists and its contract tests run against recorded responses (docs/planes/model-compute/providers-and-profiles.md, ADR-0028 decision 3).
AC5 Given the published packages, when a scripted agent runs under a scoped request, then a request without trace metadata is refused before any model call, a cancellation ends with the Cancelled stage and an unexpected exception with a terminal Failed and a failure class before the rethrow, as ADR-0014 decision 2 requires.
Traces: adrs ADR-0014, ADR-0028
Depends on AIFACTORY-US-191, AIFACTORY-US-192, AIFACTORY-US-193, AIFACTORY-US-194, AIFACTORY-US-195, AIFACTORY-US-196, AIFACTORY-US-220, AIFACTORY-US-197
Sources model/components.yaml, docs/architecture/ecosystem-composition.md, docs/architecture/adr/0014-run-and-lifecycle-envelopes.md, docs/planes/model-compute/providers-and-profiles.md

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-977 Run every lifecycle outcome of a scripted agent against the published packages verification A consumer test project restores the published packages from the ConnectSoft feed and runs a scripted agent through success, retry then success, escalation, refusal without trace metadata, cancellation and an unexpected exception; each run ends with the terminal stage and the envelope fields of ADR-0014, which proves AC3 and AC5 of AIFACTORY-US-097. ConnectSoft.Extensions.AI.Factory
AIFACTORY-TASK-680 Verify extensions-ai-delivered by running the declared command verification Run dotnet build -c Release and dotnet test -c Release --no-build on every library solution of the feature; they pass and prove AC1 to AC5 of AIFACTORY-US-097. ConnectSoft.Extensions.AI

AIFACTORY-US-758: Extensions.AI: a rerank adapter abstraction is registered under the keyed provider pattern with a conformance suite and no provider implementation

enabling · persona platform-admin As a platform admin, I want a rerank adapter abstraction beside the chat client and the embedding generator of the AI library, so that the model router binds its rerank port to library code by a version pin and a provider adapter for reranking never has to be written in a service repository.

The Features page of ConnectSoft.Extensions.AI lists chat completion providers and embedding providers, registers a keyed chat client and an embedding generator per provider under the keys openAI, azureOpenAI, ollama and azureAIInference, and names no reranking; docs/planes/model-compute/providers-and-profiles.md lists a reranker profile among the logical profiles and has no adapter row for it. ModelRouterService serves ModelGateway.Rerank in I1 and, because a provider adapter is library code, keeps its rerank adapter as a port of the service until the AI library publishes a rerank adapter. Decision D121 therefore adds this PBI: a keyed rerank adapter abstraction in the AI library. The PBI adds one rerank contract to the library, with one asynchronous operation that takes a query, the candidate texts with the identifiers the caller gave them, an optional number of results and a cancellation token, and returns the candidates ranked by relevance score, each with its identifier and its score, together with the usage the provider reported. Usage is optional on the result: an adapter whose provider reports none leaves it absent and never writes zero, which is what the invocation receipt of the model gateway needs in order to record the usage as Unknown. The contract carries no tenant, no credential and no profile; those belong to the caller. An adapter is registered the way the chat clients and the embedding generators of the library are, as a keyed service under the provider key the library already uses for that provider, through one registration extension of the abstraction, and behind a rerank provider choice whose default is none, so a host that configures no rerank provider registers nothing and starts as before. A configured rerank provider whose adapter is not registered fails options validation at startup with the provider named, and a health check reports whether the adapter of the configured provider is registered and reports healthy with a message when none is configured, as the embedding health check of the library does. A caller resolves the adapter of a provider by its key; a key without a registered adapter resolves nothing, and the caller decides what that means, which for the model router is the refusal of a rerank call whose candidate has no adapter (feature model-router-service). The PBI brings the abstraction, its keyed registration and a conformance suite, and no provider implementation. The suite is a set of contract tests every implementation has to pass: the order by score, ties kept in input order, the number of results, an empty candidate list, a cancellation and absent usage. A scripted adapter in the test project of the library proves them without a provider call. Which provider is implemented first is not decided: model/model-profiles.yaml names azure-ai-inference and ollama for the reranker profile, no PBI holds an adapter for either, and that is reported to the owner. The pipeline of the repository publishes the package version that holds the abstraction to the ConnectSoft feed after its tests pass, under the publication rules of AIFACTORY-US-197, and the Runbook page of the library names that version, which is the pin feature model-router-service reads. The abstraction is library code for the model router, which ADR-0028 decision 3 makes the only service that calls model providers; an agent host reaches reranking through the model gateway and never registers a rerank adapter itself. The Features page of the library and the provider table of docs/planes/model-compute/providers-and-profiles.md are revised to describe the abstraction and to state that no provider adapter implements it yet.

Acceptance criteria

AC1 Given a host that configures no rerank provider, when the AI library registers its services, then nothing of reranking is registered, the host starts as before and the rerank health check reports healthy with a message that no provider is configured; given a host that registers a rerank adapter under a provider key through the registration extension of the abstraction, then the adapter is resolved by that key in the same way as the keyed chat client and the embedding generator of that provider, a key without an adapter resolves nothing, and a configured rerank provider whose adapter is not registered fails options validation at startup with the provider named (docs/planes/model-compute/providers-and-profiles.md; ADR-0028 decision 3 keeps the model router the only caller of a provider).
AC2 Given the conformance suite and the scripted adapter of the test project, when the tests of the library run, then a result is ordered by score with ties in input order, holds at most the number of results asked for, returns the identifiers the caller gave, is empty for an empty candidate list, a cancellation ends the call, and an adapter whose script reports no usage returns a result without usage and never with zero; no test calls a live provider, and the suite is the capability evidence a later provider adapter has to pass under ADR-0021 decision 1.
AC3 Given the pipeline of the repository ConnectSoft.Extensions.AI, when it runs after this work, then the package version that holds the abstraction is published to the ConnectSoft feed only after the tests of the solution pass, the Runbook page of the library names that version as the pin of its consumers, and the Features page of the library and the provider table of docs/planes/model-compute/providers-and-profiles.md describe the abstraction with its keyed registration and state that no provider adapter implements it yet (ADR-0028, docs/planes/model-compute/model-gateway.md).
Traces: adrs ADR-0021, ADR-0028
Depends on AIFACTORY-US-191
Sources model/components.yaml, model/model-profiles.yaml, docs/architecture/ecosystem-composition.md, docs/planes/model-compute/providers-and-profiles.md, docs/planes/model-compute/model-gateway.md

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-3058 Rerank contract of the AI library with its request, result and usage types contract The library holds one rerank contract with one asynchronous operation (a query, candidate texts with caller identifiers, an optional number of results, a cancellation token) and a result of ranked entries with identifier and relevance score and an optional usage that is absent when the provider reports none; the contract carries no tenant, credential or profile, and its public types are documented in the Features page of the library. ConnectSoft.Extensions.AI
AIFACTORY-TASK-3059 Keyed registration, provider choice, startup validation and health check of the rerank abstraction implementation One registration extension registers a rerank adapter as a keyed service under the provider key the library uses for the chat client and the embedding generator of that provider; the rerank provider choice has the default none, under which nothing is registered; a configured provider without a registered adapter fails options validation at startup with the provider named; a rerank health check reports whether the adapter of the configured provider is registered and reports healthy with a message when none is configured. ConnectSoft.Extensions.AI
AIFACTORY-TASK-3060 Conformance suite of the rerank contract and a scripted adapter for the tests fixture The test project of the library holds the contract tests every rerank adapter has to pass (order by score, ties in input order, the number of results, caller identifiers returned, an empty candidate list, cancellation, absent usage never written as zero) as a base that an adapter test derives from, and a scripted adapter with configurable scores and usage that proves them without a provider call. ConnectSoft.Extensions.AI
AIFACTORY-TASK-3061 Provider table of the documentation site lists the rerank abstraction documentation The provider table of docs/planes/model-compute/providers-and-profiles.md gains a row for reranking that names the rerank abstraction of ConnectSoft.Extensions.AI, its keyed registration under the provider keys and the fact that no provider adapter implements it yet, so that the page no longer leaves the reranker profile without an adapter row. ConnectSoft.AI.SoftwareFactory.Documentation
AIFACTORY-TASK-3062 Verify the rerank abstraction by its conformance suite and its published version verification Run dotnet build -c Release and dotnet test -c Release --no-build on the AI library solution; the registration, validation and health check tests and the conformance suite against the scripted adapter pass, the pipeline of the repository publishes the package version that holds the abstraction after those tests and its Runbook page names the version, and the provider table revised by AIFACTORY-TASK-3061 lists the abstraction, which proves AC1 to AC3 of AIFACTORY-US-758 (ADR-0028). ConnectSoft.Extensions.AI