Assert the worker's registrations, and describe the pass it actually has

docs/ROADMAP.md

@@ -20,7 +20,7 @@ iteration. Both tests now require a second dispatch, which is what actually prov
 the first.
 
 The worker has no equivalent of `ToHttpResult()`. Its category-to-disposition mapping — retry, dead
-letter, log once — lives in `RunOnceAsync`, alongside the scope it resolves and the handler it
+letter, log once — lives in the pass, alongside the scope it resolves and the handler it
 dispatches to; `ExecuteAsync` above it only schedules and keeps the loop alive. If a second worker project
 ever wants the same mapping, that is the moment to consider a package for it, not before.
 

docs/agents/10-worker.md

@@ -8,11 +8,25 @@ Applies to `src/MyApp.Worker/`.
 - **`BackgroundService` + `PeriodicTimer`.** No scheduling framework by default — most workers are "every N minutes" or "drain this," and the BCL does both with no dependencies.
 - **Escalate to Quartz.NET only for a stated need:** cron expressions, clustering, or persistent job state. Adding it speculatively buys a database table and a configuration surface you do not want.
 - **Hangfire is out.** `Hangfire.Core` is LGPL v3, which is a licence to adopt deliberately rather than inherit, and its Pro tier is paid. Its dashboard was compensating for missing observability, which Aspire already provides.
-- **`ExecuteAsync` contains no business logic.** It ticks, runs one pass, and refuses to let a failure end the loop. Resolving a scope and dispatching to a handler happens a level down in `RunOnceAsync` — that is the position an endpoint occupies in the API archetype, and keeping the two apart is what makes either testable without the other.
+- **`ExecuteAsync` contains no business logic.** It ticks, runs one pass, and refuses to let a failure end the loop. Resolving a scope and dispatching to a handler belongs to a **pass** of its own — that is the position an endpoint occupies in the API archetype, and giving it a separate type is what lets either be tested without the other.
 
 ```csharp
+// One pass: a scope, a dispatch, and what the outcome means. Everything here is decided by the
+// result, so it can be exercised with no clock and no timer.
+internal sealed class ReconcileOrdersPass(IServiceScopeFactory scopes)
+{
+ public async Task RunAsync(CancellationToken ct)
+ {
+ await using var scope = scopes.CreateAsyncScope();
+ var handler = scope.ServiceProvider.GetRequiredService<IHandler<Request, Response>>();
+ var result = await handler.HandleAsync(new Request(), ct);
+ // map result category to retry / dead-letter / log — never throw to signal it
+ }
+}
+
+// The schedule, and one guarantee: a failed pass must not end the loop.
 internal sealed partial class ReconcileOrdersWorker(
-IServiceScopeFactory scopes,
+ReconcileOrdersPass pass,
  TimeProvider clock,
  ILogger<ReconcileOrdersWorker> logger)
  : BackgroundService
@@ -32,7 +46,7 @@ internal sealed partial class ReconcileOrdersWorker(
  {
  try
  {
- await RunOnceAsync(ct);
+ await pass.RunAsync(ct);
  }
  catch (Exception exception)
  when (exception is not OperationCanceledException || !ct.IsCancellationRequested)
@@ -42,15 +56,6 @@ internal sealed partial class ReconcileOrdersWorker(
  }
  }
 
- // ExecuteAsync schedules and keeps the loop alive; one pass lives here.
- internal async Task RunOnceAsync(CancellationToken ct)
- {
- await using var scope = scopes.CreateAsyncScope();
- var handler = scope.ServiceProvider.GetRequiredService<IHandler<Request, Response>>();
- var result = await handler.HandleAsync(new Request(), ct);
- // map result category to retry / dead-letter / log — never throw to signal it
- }
-
  [LoggerMessage(Level = LogLevel.Error, Message = "A pass threw and was swallowed to keep the worker alive.")]
  private static partial void Failed(ILogger logger, Exception exception);
 }
@@ -69,5 +74,5 @@ internal sealed partial class ReconcileOrdersWorker(
 ### Testing
 
 - **Handlers are tested directly**, against Testcontainers Postgres, with Respawn between tests. There is no transport to go through, so the handler *is* the entry point.
-- **Separate the pass from the schedule, and test the pass.** `RunOnceAsync` holds everything decided by a result — the scope, the dispatch, retry against dead-letter — so it can be exercised against a stub handler with no clock and no timer. Make the retry backoff a setting so a test can set it to zero.
+- **Separate the pass from the schedule, and test the pass.** The pass holds everything decided by a result — the scope, the dispatch, retry against dead-letter — so it can be exercised against a stub handler with no clock and no timer. Make the retry backoff a setting so a test can set it to zero.
 - **Test one guarded iteration, not the timer.** Extract the `try`/`catch` into an `internal` method — with `<InternalsVisibleTo Include="MyApp.Worker.Tests" />` on the host project — so a test can call it directly and assert which exceptions survive it. That a failing pass does not end the loop is your logic; that `PeriodicTimer` fires is the BCL's. Driving a real `BackgroundService` from a fake clock needs the scheduler to hand off between advancing the clock and the loop resuming — a test that does it is flaky unless it sleeps, and then it is a slow test of someone else's code.

src/Loom.Templates/templates/loom-api/src/MyApp.Api/Program.cs

@@ -42,7 +42,7 @@
 
 // includeInternalTypes matters: slice validators are internal, and without it none are registered.
 // The validating decorator treats a missing validator as nothing to validate, so the omission would
-// be silent — which is why ValidatorRegistrationTests asserts every validator is resolvable.
+// be silent — which is why RegistrationTests asserts every validator is resolvable.
 builder.Services.AddValidatorsFromAssemblyContaining<Program>(ServiceLifetime.Scoped, includeInternalTypes: true);
 
 builder.Services.AddProblemDetails();

src/Loom.Templates/templates/loom-worker/AGENTS.md

@@ -196,11 +196,25 @@ Applies to `src/MyApp.Worker/`.
 - **`BackgroundService` + `PeriodicTimer`.** No scheduling framework by default — most workers are "every N minutes" or "drain this," and the BCL does both with no dependencies.
 - **Escalate to Quartz.NET only for a stated need:** cron expressions, clustering, or persistent job state. Adding it speculatively buys a database table and a configuration surface you do not want.
 - **Hangfire is out.** `Hangfire.Core` is LGPL v3, which is a licence to adopt deliberately rather than inherit, and its Pro tier is paid. Its dashboard was compensating for missing observability, which Aspire already provides.
-- **`ExecuteAsync` contains no business logic.** It ticks, runs one pass, and refuses to let a failure end the loop. Resolving a scope and dispatching to a handler happens a level down in `RunOnceAsync` — that is the position an endpoint occupies in the API archetype, and keeping the two apart is what makes either testable without the other.
+- **`ExecuteAsync` contains no business logic.** It ticks, runs one pass, and refuses to let a failure end the loop. Resolving a scope and dispatching to a handler belongs to a **pass** of its own — that is the position an endpoint occupies in the API archetype, and giving it a separate type is what lets either be tested without the other.
 
 ```csharp
+// One pass: a scope, a dispatch, and what the outcome means. Everything here is decided by the
+// result, so it can be exercised with no clock and no timer.
+internal sealed class ReconcileOrdersPass(IServiceScopeFactory scopes)
+{
+ public async Task RunAsync(CancellationToken ct)
+ {
+ await using var scope = scopes.CreateAsyncScope();
+ var handler = scope.ServiceProvider.GetRequiredService<IHandler<Request, Response>>();
+ var result = await handler.HandleAsync(new Request(), ct);
+ // map result category to retry / dead-letter / log — never throw to signal it
+ }
+}
+
+// The schedule, and one guarantee: a failed pass must not end the loop.
 internal sealed partial class ReconcileOrdersWorker(
-IServiceScopeFactory scopes,
+ReconcileOrdersPass pass,
  TimeProvider clock,
  ILogger<ReconcileOrdersWorker> logger)
  : BackgroundService
@@ -220,7 +234,7 @@ internal sealed partial class ReconcileOrdersWorker(
  {
  try
  {
- await RunOnceAsync(ct);
+ await pass.RunAsync(ct);
  }
  catch (Exception exception)
  when (exception is not OperationCanceledException || !ct.IsCancellationRequested)
@@ -230,15 +244,6 @@ internal sealed partial class ReconcileOrdersWorker(
  }
  }
 
- // ExecuteAsync schedules and keeps the loop alive; one pass lives here.
- internal async Task RunOnceAsync(CancellationToken ct)
- {
- await using var scope = scopes.CreateAsyncScope();
- var handler = scope.ServiceProvider.GetRequiredService<IHandler<Request, Response>>();
- var result = await handler.HandleAsync(new Request(), ct);
- // map result category to retry / dead-letter / log — never throw to signal it
- }
-
  [LoggerMessage(Level = LogLevel.Error, Message = "A pass threw and was swallowed to keep the worker alive.")]
  private static partial void Failed(ILogger logger, Exception exception);
 }
@@ -257,5 +262,5 @@ internal sealed partial class ReconcileOrdersWorker(
 ### Testing
 
 - **Handlers are tested directly**, against Testcontainers Postgres, with Respawn between tests. There is no transport to go through, so the handler *is* the entry point.
-- **Separate the pass from the schedule, and test the pass.** `RunOnceAsync` holds everything decided by a result — the scope, the dispatch, retry against dead-letter — so it can be exercised against a stub handler with no clock and no timer. Make the retry backoff a setting so a test can set it to zero.
+- **Separate the pass from the schedule, and test the pass.** The pass holds everything decided by a result — the scope, the dispatch, retry against dead-letter — so it can be exercised against a stub handler with no clock and no timer. Make the retry backoff a setting so a test can set it to zero.
 - **Test one guarded iteration, not the timer.** Extract the `try`/`catch` into an `internal` method — with `<InternalsVisibleTo Include="MyApp.Worker.Tests" />` on the host project — so a test can call it directly and assert which exceptions survive it. That a failing pass does not end the loop is your logic; that `PeriodicTimer` fires is the BCL's. Driving a real `BackgroundService` from a fake clock needs the scheduler to hand off between advancing the clock and the loop resuming — a test that does it is flaky unless it sleeps, and then it is a slow test of someone else's code.

src/Loom.Templates/templates/loom-worker/tests/MyApp.Worker.Tests/RegistrationTests.cs

@@ -0,0 +1,69 @@
+using FluentValidation;
+using Loom.Handlers;
+using Microsoft.Extensions.DependencyInjection;
+
+namespace MyApp.Worker.Tests;
+
+/// <summary>
+/// Every handler and every validator resolves.
+/// </summary>
+/// <remarks>
+/// A validator that is not registered is silently ignored — the decorator treats a missing one as
+/// nothing to validate, which is right for a slice with no rules and disastrous for one with them.
+/// Assembly scanning excludes internal types unless asked, and slice validators are internal.
+/// <para>
+/// Both sets are discovered rather than listed. Naming one handler would only ever prove that handler
+/// is registered, so a new slice whose <c>AddHandler</c> call was forgotten would still pass — and in a
+/// worker the first sign of that is a tick failing in a deployment, with no request to fail instead.
+/// </para>
+/// </remarks>
+[NotInParallel]
+public sealed class RegistrationTests
+{
+ [Test]
+ public async Task Every_Validator_In_The_Application_Resolves()
+ {
+ using IServiceScope scope = WorkerFixture.Host.CreateScope();
+
+ Type[] requestTypes =
+ [
+ .. typeof(WorkerServices).Assembly.GetTypes()
+ .Where(type => type is { IsClass: true, IsAbstract: false }
+ && type.BaseType is { IsGenericType: true } baseType
+ && baseType.GetGenericTypeDefinition() == typeof(AbstractValidator<>))
+ .Select(type => type.BaseType!.GetGenericArguments()[0]),
+ ];
+
+ await Assert.That(requestTypes).IsNotEmpty();
+
+ foreach (Type requestType in requestTypes)
+ {
+ Type validatorType = typeof(IValidator<>).MakeGenericType(requestType);
+
+ await Assert.That(scope.ServiceProvider.GetService(validatorType)).IsNotNull();
+ }
+ }
+
+ [Test]
+ public async Task Every_Handler_Resolves_Through_Its_Decorator_Chain()
+ {
+ using IServiceScope scope = WorkerFixture.Host.CreateScope();
+
+ Type[] handlerInterfaces =
+ [
+ .. typeof(WorkerServices).Assembly.GetTypes()
+ .Where(type => type is { IsClass: true, IsAbstract: false })
+ .SelectMany(type => type.GetInterfaces())
+ .Where(contract => contract.IsGenericType
+ && contract.GetGenericTypeDefinition() == typeof(IHandler<,>))
+ .Distinct(),
+ ];
+
+ await Assert.That(handlerInterfaces).IsNotEmpty();
+
+ foreach (Type contract in handlerInterfaces)
+ {
+ await Assert.That(scope.ServiceProvider.GetService(contract)).IsNotNull();
+ }
+ }
+}