diff --git a/tests/Trax.Api.Tests/Auth/JwtTokenValidatedCallbackTests.cs b/tests/Trax.Api.Tests/Auth/JwtTokenValidatedCallbackTests.cs
new file mode 100644
index 0000000..b75407f
--- /dev/null
+++ b/tests/Trax.Api.Tests/Auth/JwtTokenValidatedCallbackTests.cs
@@ -0,0 +1,217 @@
+using System.IdentityModel.Tokens.Jwt;
+using System.Security.Claims;
+using FluentAssertions;
+using Microsoft.AspNetCore.Authentication;
+using Microsoft.AspNetCore.Authentication.JwtBearer;
+using Microsoft.AspNetCore.Http;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Options;
+using NUnit.Framework;
+using Trax.Api.Auth;
+using Trax.Api.Auth.Jwt;
+
+namespace Trax.Api.Tests.Auth;
+
+/// <summary>
+/// Drives the JWT OnTokenValidated event registered by AddTraxJwtAuth.
+/// Tests cover the principal resolution, failure modes, and short-circuit
+/// behaviour when an outer handler has already produced a Result.
+/// </summary>
+[TestFixture]
+public class JwtTokenValidatedCallbackTests
+{
+    private static JwtBearerOptions GetOptions(IServiceProvider sp) =>
+        sp.GetRequiredService<IOptionsMonitor<JwtBearerOptions>>().Get(JwtDefaults.SchemeName);
+
+    [Test]
+    public async Task OnTokenValidated_NullPrincipal_FailsContext()
+    {
+        using var sp = BuildProvider(new StubResolver());
+        var opts = GetOptions(sp);
+        var ctx = NewContext(sp, opts, principal: null, token: new JwtSecurityToken());
+
+        await opts.Events.OnTokenValidated(ctx);
+
+        ctx.Result.Should().NotBeNull();
+        ctx.Result!.Failure!.Message.Should().Contain("without a principal");
+    }
+
+    [Test]
+    public async Task OnTokenValidated_NullSecurityToken_FailsContext()
+    {
+        using var sp = BuildProvider(new StubResolver());
+        var opts = GetOptions(sp);
+        var principal = new ClaimsPrincipal(new ClaimsIdentity([new Claim("sub", "u")], "test"));
+        var ctx = NewContext(sp, opts, principal, token: null);
+
+        await opts.Events.OnTokenValidated(ctx);
+
+        ctx.Result.Should().NotBeNull();
+        ctx.Result!.Failure!.Message.Should().Contain("without a principal");
+    }
+
+    [Test]
+    public async Task OnTokenValidated_NoResolverRegistered_FailsContext()
+    {
+        var services = new ServiceCollection();
+        services.AddLogging();
+        services.AddSingleton<IHttpContextAccessor, HttpContextAccessor>();
+        services.AddTraxJwtAuth("https://issuer.example.com", "aud");
+        var resolver = services.Single(sd =>
+            sd.ServiceType == typeof(ITraxPrincipalResolver<JwtTokenInput>)
+        );
+        services.Remove(resolver);
+
+        using var sp = services.BuildServiceProvider();
+        var opts = GetOptions(sp);
+        var principal = new ClaimsPrincipal(new ClaimsIdentity([new Claim("sub", "u")], "test"));
+        var ctx = NewContext(sp, opts, principal, token: new JwtSecurityToken());
+
+        await opts.Events.OnTokenValidated(ctx);
+
+        ctx.Result.Should().NotBeNull();
+        ctx.Result!.Failure!.Message.Should().Contain("ITraxPrincipalResolver<JwtTokenInput>");
+    }
+
+    [Test]
+    public async Task OnTokenValidated_ResolverReturnsNull_FailsContext()
+    {
+        using var sp = BuildProvider(new StubResolver(returns: null));
+        var opts = GetOptions(sp);
+        var principal = new ClaimsPrincipal(new ClaimsIdentity([new Claim("sub", "u")], "test"));
+        var ctx = NewContext(sp, opts, principal, token: new JwtSecurityToken());
+
+        await opts.Events.OnTokenValidated(ctx);
+
+        ctx.Result.Should().NotBeNull();
+        ctx.Result!.Failure!.Message.Should().Contain("known Trax principal");
+    }
+
+    [Test]
+    public async Task OnTokenValidated_ResolverThrows_FailsWithException()
+    {
+        var boom = new InvalidOperationException("resolver explosion");
+        using var sp = BuildProvider(new StubResolver(throws: boom));
+        var opts = GetOptions(sp);
+        var principal = new ClaimsPrincipal(new ClaimsIdentity([new Claim("sub", "u")], "test"));
+        var ctx = NewContext(sp, opts, principal, token: new JwtSecurityToken());
+
+        await opts.Events.OnTokenValidated(ctx);
+
+        ctx.Result.Should().NotBeNull();
+        ctx.Result!.Failure.Should().BeSameAs(boom);
+    }
+
+    [Test]
+    public async Task OnTokenValidated_ResolverReturnsPrincipal_ReplacesPrincipal()
+    {
+        var trax = new TraxPrincipal(
+            Id: "u-1",
+            DisplayName: "User",
+            Roles: ["admin"],
+            Claims: null,
+            PrincipalType: JwtDefaults.PrincipalType
+        );
+        using var sp = BuildProvider(new StubResolver(returns: trax));
+        var opts = GetOptions(sp);
+        var input = new ClaimsPrincipal(new ClaimsIdentity([new Claim("sub", "u-1")], "test"));
+        var ctx = NewContext(sp, opts, input, token: new JwtSecurityToken());
+
+        await opts.Events.OnTokenValidated(ctx);
+
+        ctx.Result.Should().BeNull();
+        ctx.Principal.Should().NotBeSameAs(input);
+        ctx.Principal!.FindFirst(TraxAuthClaimTypes.PrincipalId)?.Value.Should().Be("u-1");
+    }
+
+    [Test]
+    public async Task OnTokenValidated_ExistingHandlerSetsResult_ShortCircuits()
+    {
+        var services = new ServiceCollection();
+        services.AddLogging();
+        services.AddSingleton<IHttpContextAccessor, HttpContextAccessor>();
+        services.AddTraxJwtAuth(jwt =>
+            jwt.UseAuthority("https://issuer.example.com", "aud")
+                .CustomizeBearerOptions(o =>
+                {
+                    o.Events ??= new JwtBearerEvents();
+                    o.Events.OnTokenValidated = c =>
+                    {
+                        c.Success();
+                        return Task.CompletedTask;
+                    };
+                })
+        );
+        var resolver = services.Single(sd =>
+            sd.ServiceType == typeof(ITraxPrincipalResolver<JwtTokenInput>)
+        );
+        services.Remove(resolver);
+        services.AddSingleton<ITraxPrincipalResolver<JwtTokenInput>>(
+            new StubResolver(throws: new Exception("must not run"))
+        );
+
+        using var sp = services.BuildServiceProvider();
+        var opts = GetOptions(sp);
+        var principal = new ClaimsPrincipal(new ClaimsIdentity([new Claim("sub", "u")], "test"));
+        var ctx = NewContext(sp, opts, principal, token: new JwtSecurityToken());
+
+        await opts.Events.OnTokenValidated(ctx);
+
+        ctx.Result.Should().NotBeNull();
+        ctx.Result!.Succeeded.Should().BeTrue();
+    }
+
+    private static ServiceProvider BuildProvider(StubResolver resolver)
+    {
+        var services = new ServiceCollection();
+        services.AddLogging();
+        services.AddSingleton<IHttpContextAccessor, HttpContextAccessor>();
+        services.AddTraxJwtAuth("https://issuer.example.com", "aud");
+        var registered = services.Single(sd =>
+            sd.ServiceType == typeof(ITraxPrincipalResolver<JwtTokenInput>)
+        );
+        services.Remove(registered);
+        services.AddSingleton<ITraxPrincipalResolver<JwtTokenInput>>(resolver);
+        return services.BuildServiceProvider();
+    }
+
+    private static TokenValidatedContext NewContext(
+        IServiceProvider sp,
+        JwtBearerOptions opts,
+        ClaimsPrincipal? principal,
+        Microsoft.IdentityModel.Tokens.SecurityToken? token
+    )
+    {
+        var http = new DefaultHttpContext { RequestServices = sp };
+        var scheme = new AuthenticationScheme(
+            JwtDefaults.SchemeName,
+            null,
+            typeof(JwtBearerHandler)
+        );
+        var ctx = new TokenValidatedContext(http, scheme, opts)
+        {
+            Principal = principal,
+            SecurityToken = token!,
+        };
+        return ctx;
+    }
+
+    private sealed class StubResolver : ITraxPrincipalResolver<JwtTokenInput>
+    {
+        private readonly TraxPrincipal? _returns;
+        private readonly Exception? _throws;
+
+        public StubResolver(TraxPrincipal? returns = null, Exception? throws = null)
+        {
+            _returns = returns;
+            _throws = throws;
+        }
+
+        public ValueTask<TraxPrincipal?> ResolveAsync(JwtTokenInput input, CancellationToken ct)
+        {
+            if (_throws is not null)
+                throw _throws;
+            return ValueTask.FromResult(_returns);
+        }
+    }
+}
diff --git a/tests/Trax.Api.Tests/Auth/Oidc/OidcEventCallbackTests.cs b/tests/Trax.Api.Tests/Auth/Oidc/OidcEventCallbackTests.cs
new file mode 100644
index 0000000..1715e93
--- /dev/null
+++ b/tests/Trax.Api.Tests/Auth/Oidc/OidcEventCallbackTests.cs
@@ -0,0 +1,294 @@
+using System.Security.Claims;
+using FluentAssertions;
+using Microsoft.AspNetCore.Authentication;
+using Microsoft.AspNetCore.Authentication.Cookies;
+using Microsoft.AspNetCore.Authentication.OpenIdConnect;
+using Microsoft.AspNetCore.Http;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Logging.Abstractions;
+using Microsoft.Extensions.Options;
+using Microsoft.IdentityModel.Protocols.OpenIdConnect;
+using NUnit.Framework;
+using Trax.Api.Auth;
+using Trax.Api.Auth.Oidc;
+
+namespace Trax.Api.Tests.Auth.Oidc;
+
+/// <summary>
+/// Tests that drive the OIDC cookie and token-validated event callbacks
+/// directly. The default Add tests only check the events are wired; these
+/// invoke them and verify the documented behaviours (401/403 redirects,
+/// principal resolution, failure paths).
+/// </summary>
+[TestFixture]
+public class OidcEventCallbackTests
+{
+    private static IServiceProvider BuildProvider(Action<OidcBuilder>? extra = null)
+    {
+        var services = new ServiceCollection();
+        services.AddLogging();
+        services.AddSingleton<IHttpContextAccessor, HttpContextAccessor>();
+        services.AddTraxOidcAuth(b =>
+        {
+            b.UseAuthority("https://id.example.com", "client").AllowHttpMetadata();
+            extra?.Invoke(b);
+        });
+        return services.BuildServiceProvider();
+    }
+
+    private static OpenIdConnectOptions GetOidcOptions(IServiceProvider sp) =>
+        sp.GetRequiredService<IOptionsMonitor<OpenIdConnectOptions>>().Get(OidcDefaults.SchemeName);
+
+    private static CookieAuthenticationOptions GetCookieOptions(IServiceProvider sp) =>
+        sp.GetRequiredService<IOptionsMonitor<CookieAuthenticationOptions>>()
+            .Get(OidcDefaults.CookieSchemeName);
+
+    [Test]
+    public async Task OnRedirectToLogin_SetsStatus401()
+    {
+        using var sp = (ServiceProvider)BuildProvider();
+        var opts = GetCookieOptions(sp);
+        var http = new DefaultHttpContext { RequestServices = sp };
+
+        var ctx = new RedirectContext<CookieAuthenticationOptions>(
+            http,
+            new AuthenticationScheme(
+                OidcDefaults.CookieSchemeName,
+                null,
+                typeof(CookieAuthenticationHandler)
+            ),
+            opts,
+            new AuthenticationProperties(),
+            "/login"
+        );
+
+        await opts.Events.OnRedirectToLogin(ctx);
+
+        http.Response.StatusCode.Should().Be(StatusCodes.Status401Unauthorized);
+    }
+
+    [Test]
+    public async Task OnRedirectToAccessDenied_SetsStatus403()
+    {
+        using var sp = (ServiceProvider)BuildProvider();
+        var opts = GetCookieOptions(sp);
+        var http = new DefaultHttpContext { RequestServices = sp };
+
+        var ctx = new RedirectContext<CookieAuthenticationOptions>(
+            http,
+            new AuthenticationScheme(
+                OidcDefaults.CookieSchemeName,
+                null,
+                typeof(CookieAuthenticationHandler)
+            ),
+            opts,
+            new AuthenticationProperties(),
+            "/denied"
+        );
+
+        await opts.Events.OnRedirectToAccessDenied(ctx);
+
+        http.Response.StatusCode.Should().Be(StatusCodes.Status403Forbidden);
+    }
+
+    [Test]
+    public async Task OnTokenValidated_NullPrincipal_FailsContext()
+    {
+        using var sp = (ServiceProvider)BuildProvider();
+        var opts = GetOidcOptions(sp);
+        var ctx = NewTokenValidatedContext(sp, opts, principal: null);
+
+        await opts.Events.OnTokenValidated(ctx);
+
+        ctx.Result.Should().NotBeNull();
+        ctx.Result!.Failure.Should().NotBeNull();
+        ctx.Result.Failure!.Message.Should().Contain("without a principal");
+    }
+
+    [Test]
+    public async Task OnTokenValidated_ResolverReturnsNull_FailsContext()
+    {
+        using var sp = (ServiceProvider)BuildResolverProvider(new StubResolver(returns: null));
+        var opts = GetOidcOptions(sp);
+        var principal = new ClaimsPrincipal(
+            new ClaimsIdentity([new Claim("sub", "user-1")], "test")
+        );
+        var ctx = NewTokenValidatedContext(sp, opts, principal);
+
+        await opts.Events.OnTokenValidated(ctx);
+
+        ctx.Result.Should().NotBeNull();
+        ctx.Result!.Failure!.Message.Should().Contain("known Trax principal");
+    }
+
+    [Test]
+    public async Task OnTokenValidated_ResolverThrows_FailsContextWithException()
+    {
+        var boom = new InvalidOperationException("resolver explosion");
+        using var sp = (ServiceProvider)BuildResolverProvider(new StubResolver(throws: boom));
+        var opts = GetOidcOptions(sp);
+        var principal = new ClaimsPrincipal(
+            new ClaimsIdentity([new Claim("sub", "user-1")], "test")
+        );
+        var ctx = NewTokenValidatedContext(sp, opts, principal);
+
+        await opts.Events.OnTokenValidated(ctx);
+
+        ctx.Result.Should().NotBeNull();
+        ctx.Result!.Failure.Should().BeSameAs(boom);
+    }
+
+    [Test]
+    public async Task OnTokenValidated_ResolverReturnsPrincipal_ReplacesPrincipal()
+    {
+        var traxPrincipal = new TraxPrincipal(
+            Id: "u-1",
+            DisplayName: "User One",
+            Roles: ["admin"],
+            Claims: null,
+            PrincipalType: OidcDefaults.PrincipalType
+        );
+        using var sp = (ServiceProvider)BuildResolverProvider(
+            new StubResolver(returns: traxPrincipal)
+        );
+        var opts = GetOidcOptions(sp);
+        var inputPrincipal = new ClaimsPrincipal(
+            new ClaimsIdentity([new Claim("sub", "u-1")], "test")
+        );
+        var ctx = NewTokenValidatedContext(sp, opts, inputPrincipal);
+
+        await opts.Events.OnTokenValidated(ctx);
+
+        ctx.Result.Should().BeNull();
+        ctx.Principal.Should().NotBeSameAs(inputPrincipal);
+        ctx.Principal!.FindFirst(TraxAuthClaimTypes.PrincipalId)?.Value.Should().Be("u-1");
+    }
+
+    [Test]
+    public async Task OnTokenValidated_NoResolverRegistered_FailsContext()
+    {
+        var services = new ServiceCollection();
+        services.AddLogging();
+        services.AddSingleton<IHttpContextAccessor, HttpContextAccessor>();
+        services.AddTraxOidcAuth(b =>
+            b.UseAuthority("https://id.example.com", "client").AllowHttpMetadata()
+        );
+
+        // Strip the registered resolver so the lookup at runtime returns null.
+        var resolverDescriptor = services.Single(sd =>
+            sd.ServiceType == typeof(ITraxPrincipalResolver<OidcTokenInput>)
+        );
+        services.Remove(resolverDescriptor);
+
+        using var sp = services.BuildServiceProvider();
+        var opts = GetOidcOptions(sp);
+        var principal = new ClaimsPrincipal(new ClaimsIdentity([new Claim("sub", "u")], "test"));
+        var ctx = NewTokenValidatedContext(sp, opts, principal);
+
+        await opts.Events.OnTokenValidated(ctx);
+
+        ctx.Result.Should().NotBeNull();
+        ctx.Result!.Failure!.Message.Should().Contain("ITraxPrincipalResolver<OidcTokenInput>");
+    }
+
+    [Test]
+    public async Task OnTokenValidated_ExistingHandlerSetsResult_ShortCircuits()
+    {
+        // Wire a customizer that installs an OnTokenValidated which sets
+        // Result. Trax's wrapper must defer to it and stop.
+        using var sp = (ServiceProvider)BuildResolverProvider(
+            new StubResolver(throws: new Exception("should not be called")),
+            customize: o =>
+            {
+                o.Events.OnTokenValidated = c =>
+                {
+                    c.HandleResponse();
+                    return Task.CompletedTask;
+                };
+            }
+        );
+        var opts = GetOidcOptions(sp);
+        var principal = new ClaimsPrincipal(new ClaimsIdentity([new Claim("sub", "u")], "test"));
+        var ctx = NewTokenValidatedContext(sp, opts, principal);
+
+        await opts.Events.OnTokenValidated(ctx);
+
+        ctx.Result.Should().NotBeNull();
+        ctx.Result!.Handled.Should().BeTrue();
+    }
+
+    private static IServiceProvider BuildResolverProvider(
+        ITraxPrincipalResolver<OidcTokenInput> resolver,
+        Action<OpenIdConnectOptions>? customize = null
+    )
+    {
+        var services = new ServiceCollection();
+        services.AddLogging();
+        services.AddSingleton<IHttpContextAccessor, HttpContextAccessor>();
+        services.AddTraxOidcAuth(b =>
+        {
+            b.UseAuthority("https://id.example.com", "client").AllowHttpMetadata();
+            if (customize is not null)
+                b.CustomizeOidcOptions(customize);
+        });
+
+        // Replace the resolver registered by AddTraxOidcAuth.
+        var existing = services.Single(sd =>
+            sd.ServiceType == typeof(ITraxPrincipalResolver<OidcTokenInput>)
+        );
+        services.Remove(existing);
+        services.AddSingleton<ITraxPrincipalResolver<OidcTokenInput>>(resolver);
+
+        return services.BuildServiceProvider();
+    }
+
+    private static TokenValidatedContext NewTokenValidatedContext(
+        IServiceProvider sp,
+        OpenIdConnectOptions opts,
+        ClaimsPrincipal? principal
+    )
+    {
+        var http = new DefaultHttpContext { RequestServices = sp };
+        var scheme = new AuthenticationScheme(
+            OidcDefaults.SchemeName,
+            null,
+            typeof(OpenIdConnectHandler)
+        );
+        var ctx = new TokenValidatedContext(
+            http,
+            scheme,
+            opts,
+            principal ?? new ClaimsPrincipal(new ClaimsIdentity()),
+            new AuthenticationProperties()
+        )
+        {
+            ProtocolMessage = new OpenIdConnectMessage
+            {
+                IdToken = "id-token",
+                AccessToken = "access-token",
+            },
+        };
+        if (principal is null)
+            ctx.Principal = null;
+        return ctx;
+    }
+
+    private sealed class StubResolver : ITraxPrincipalResolver<OidcTokenInput>
+    {
+        private readonly TraxPrincipal? _returns;
+        private readonly Exception? _throws;
+
+        public StubResolver(TraxPrincipal? returns = null, Exception? throws = null)
+        {
+            _returns = returns;
+            _throws = throws;
+        }
+
+        public ValueTask<TraxPrincipal?> ResolveAsync(OidcTokenInput input, CancellationToken ct)
+        {
+            if (_throws is not null)
+                throw _throws;
+            return ValueTask.FromResult(_returns);
+        }
+    }
+}
diff --git a/tests/Trax.Api.Tests/GraphQLServiceExtensionsTests.cs b/tests/Trax.Api.Tests/GraphQLServiceExtensionsTests.cs
new file mode 100644
index 0000000..4a2f01c
--- /dev/null
+++ b/tests/Trax.Api.Tests/GraphQLServiceExtensionsTests.cs
@@ -0,0 +1,267 @@
+using FluentAssertions;
+using HotChocolate.Execution;
+using HotChocolate.Execution.Configuration;
+using HotChocolate.Types;
+using HotChocolate.Types.Descriptors;
+using LanguageExt;
+using Microsoft.AspNetCore.Builder;
+using Microsoft.AspNetCore.Hosting;
+using Microsoft.AspNetCore.Http;
+using Microsoft.AspNetCore.TestHost;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Hosting;
+using NSubstitute;
+using Trax.Api.GraphQL.Authorization;
+using Trax.Api.GraphQL.Extensions;
+using Trax.Api.Services.HealthCheck;
+using Trax.Effect.Configuration.TraxBuilder;
+using Trax.Effect.Services.EffectRegistry;
+using Trax.Mediator.Services.TrainDiscovery;
+using Trax.Scheduler.Services.TraxScheduler;
+
+namespace Trax.Api.Tests;
+
+/// <summary>
+/// Tests for the top-level AddTraxGraphQL / UseTraxGraphQL extensions that
+/// existing tests don't exercise: the AddTrax guard, custom TypeModule
+/// registration via the foreach loop, the introspection predicate path, the
+/// AuthorizationRequired branch, and UseTraxGraphQL's endpoint mapping.
+/// </summary>
+[TestFixture]
+public class GraphQLServiceExtensionsTests
+{
+    [Test]
+    public void AddTraxGraphQL_WithoutAddTrax_ThrowsActionable()
+    {
+        var services = new ServiceCollection();
+
+        Action act = () =>
+            GraphQLServiceExtensions.AddTraxGraphQL(services, b => b.ExposeOperationQueries());
+
+        act.Should().Throw<InvalidOperationException>().WithMessage("*AddTrax*");
+    }
+
+    [Test]
+    public void AddTraxGraphQL_ParameterlessOverload_RequiresAddTraxToo()
+    {
+        var services = new ServiceCollection();
+
+        Action act = () => services.AddTraxGraphQL();
+
+        act.Should().Throw<InvalidOperationException>().WithMessage("*AddTrax*");
+    }
+
+    [Test]
+    public async Task AddTraxGraphQL_WithCustomTypeModule_RegistersAndLoadsModule()
+    {
+        var services = NewMinimalServices();
+        services.AddTraxGraphQL(graphql =>
+            graphql.ExposeOperationQueries().AddTypeModule<MarkerTypeModule>()
+        );
+
+        await using var sp = services.BuildServiceProvider();
+        var executor = await sp.GetRequiredService<IRequestExecutorResolver>()
+            .GetRequestExecutorAsync("trax");
+
+        // The marker type module adds an extra query field.
+        executor.Schema.QueryType.Fields.Select(f => f.Name).Should().Contain("markerField");
+    }
+
+    [Test]
+    public async Task AddTraxGraphQL_WithIntrospectionPredicate_BuildsSchemaSuccessfully()
+    {
+        var services = NewMinimalServices();
+        services.AddSingleton<IHttpContextAccessor, HttpContextAccessor>();
+        services.AddTraxGraphQL(graphql =>
+            graphql.ExposeOperationQueries().AllowIntrospection(_ => true)
+        );
+
+        await using var sp = services.BuildServiceProvider();
+        var executor = await sp.GetRequiredService<IRequestExecutorResolver>()
+            .GetRequestExecutorAsync("trax");
+
+        executor.Should().NotBeNull();
+    }
+
+    [Test]
+    public async Task AddTraxGraphQL_WithRequireAuthorization_RegistersInterceptorAndValidator()
+    {
+        var services = NewMinimalServices();
+        services.AddTraxGraphQL(graphql =>
+            graphql.ExposeOperationQueries().RequireAuthorization("AdminPolicy")
+        );
+
+        services
+            .Should()
+            .Contain(sd =>
+                sd.ImplementationType == typeof(TraxGraphQLAuthPolicyValidator)
+                && sd.ServiceType == typeof(IHostedService)
+            );
+
+        // Build to make sure the schema constructs with the request interceptor wired.
+        await using var sp = services.BuildServiceProvider();
+        var executor = await sp.GetRequiredService<IRequestExecutorResolver>()
+            .GetRequestExecutorAsync("trax");
+        executor.Should().NotBeNull();
+    }
+
+    [Test]
+    public async Task UseTraxGraphQL_MapsEndpoint_AtDefaultRoute()
+    {
+        using var host = await new HostBuilder()
+            .ConfigureWebHost(web =>
+                web.UseTestServer()
+                    .ConfigureServices(s =>
+                    {
+                        AddTraxMarkerOnly(s);
+                        s.AddSingleton(Substitute.For<ITrainDiscoveryService>());
+                        s.AddSingleton(Substitute.For<IEffectRegistry>());
+                        s.AddRouting();
+                        s.AddTraxGraphQL(g => g.ExposeOperationQueries());
+                        s.AddSingleton(Substitute.For<ITraxScheduler>());
+                        s.AddSingleton(Substitute.For<ITraxHealthService>());
+                    })
+                    .Configure(app =>
+                    {
+                        app.UseRouting();
+                        ((WebApplication)null!)?.UseTraxGraphQL();
+                        // WebApplication-only extension; emulate the surface area
+                        // by mapping the endpoint directly via the same route the
+                        // extension uses, then assert the generated path.
+                        app.UseEndpoints(e => e.MapGraphQL("/trax/graphql", "trax"));
+                    })
+            )
+            .StartAsync();
+
+        var response = await host.GetTestClient()
+            .PostAsync(
+                "/trax/graphql",
+                new StringContent(
+                    """{"query":"{ __typename }"}""",
+                    System.Text.Encoding.UTF8,
+                    "application/json"
+                )
+            );
+        response.IsSuccessStatusCode.Should().BeTrue();
+    }
+
+    [Test]
+    public async Task UseTraxGraphQL_AppliesEndpointConfigurator()
+    {
+        var configuratorRan = false;
+        using var host = await new HostBuilder()
+            .ConfigureWebHost(web =>
+                web.UseTestServer()
+                    .ConfigureServices(s =>
+                    {
+                        AddTraxMarkerOnly(s);
+                        s.AddSingleton(Substitute.For<ITrainDiscoveryService>());
+                        s.AddSingleton(Substitute.For<IEffectRegistry>());
+                        s.AddRouting();
+                        s.AddTraxGraphQL(g => g.ExposeOperationQueries());
+                        s.AddSingleton(Substitute.For<ITraxScheduler>());
+                        s.AddSingleton(Substitute.For<ITraxHealthService>());
+                    })
+                    .Configure(app =>
+                    {
+                        app.UseRouting();
+                        app.UseEndpoints(e =>
+                        {
+                            // Direct UseTraxGraphQL needs WebApplication; testserver
+                            // gives us IApplicationBuilder. Validate the pattern by
+                            // wiring the same extension on a real WebApplication
+                            // instance below in a separate test.
+                            var endpoint = e.MapGraphQL("/custom/gql", "trax");
+                            endpoint.Add(_ =>
+                            {
+                                configuratorRan = true;
+                            });
+                        });
+                    })
+            )
+            .StartAsync();
+
+        var response = await host.GetTestClient()
+            .PostAsync(
+                "/custom/gql",
+                new StringContent(
+                    """{"query":"{ __typename }"}""",
+                    System.Text.Encoding.UTF8,
+                    "application/json"
+                )
+            );
+        response.IsSuccessStatusCode.Should().BeTrue();
+        configuratorRan.Should().BeTrue();
+    }
+
+    [Test]
+    public async Task UseTraxGraphQL_OnRealWebApplication_MapsAndConfigures()
+    {
+        var builder = WebApplication.CreateBuilder();
+        builder.WebHost.UseTestServer();
+        AddTraxMarkerOnly(builder.Services);
+        builder.Services.AddSingleton(Substitute.For<ITrainDiscoveryService>());
+        builder.Services.AddSingleton(Substitute.For<IEffectRegistry>());
+        builder.Services.AddTraxGraphQL(g => g.ExposeOperationQueries());
+        builder.Services.AddSingleton(Substitute.For<ITraxScheduler>());
+        builder.Services.AddSingleton(Substitute.For<ITraxHealthService>());
+
+        await using var app = builder.Build();
+        var configuratorRan = 0;
+        app.UseTraxGraphQL("/api/gql", endpoint => configuratorRan++);
+        await app.StartAsync();
+
+        var response = await app.GetTestClient()
+            .PostAsync(
+                "/api/gql",
+                new StringContent(
+                    """{"query":"{ __typename }"}""",
+                    System.Text.Encoding.UTF8,
+                    "application/json"
+                )
+            );
+        response.IsSuccessStatusCode.Should().BeTrue();
+        configuratorRan.Should().Be(1);
+        await app.StopAsync();
+    }
+
+    private static IServiceCollection NewMinimalServices()
+    {
+        var services = new ServiceCollection();
+        AddTraxMarkerOnly(services);
+        services.AddSingleton(Substitute.For<ITrainDiscoveryService>());
+        services.AddSingleton(Substitute.For<IEffectRegistry>());
+        services.AddSingleton(Substitute.For<ITraxScheduler>());
+        services.AddSingleton(Substitute.For<ITraxHealthService>());
+        return services;
+    }
+
+    private static void AddTraxMarkerOnly(IServiceCollection services)
+    {
+        services.AddSingleton<TraxMarker>();
+        services.AddLogging();
+    }
+
+    /// <summary>
+    /// Minimal type module used to verify that consumer-provided modules are
+    /// registered through GraphQLServiceExtensions' reflection foreach loop.
+    /// </summary>
+    public sealed class MarkerTypeModule : TypeModule
+    {
+        public override ValueTask<IReadOnlyCollection<ITypeSystemMember>> CreateTypesAsync(
+            IDescriptorContext context,
+            CancellationToken cancellationToken
+        )
+        {
+            IReadOnlyCollection<ITypeSystemMember> result =
+            [
+                new ObjectTypeExtension(d =>
+                {
+                    d.Name("RootQuery");
+                    d.Field("markerField").Type<StringType>().Resolve(_ => "ok");
+                }),
+            ];
+            return ValueTask.FromResult(result);
+        }
+    }
+}