Add invariant coverage to foundational samples

CONTRIBUTING.md

@@ -388,6 +388,7 @@ For code examples:
 - Use meaningful names.
 - Prefer examples that compile and can be tested.
 - Add tests when the lesson depends on behavioral correctness.
+- For executable samples, cover every documented outcome and stable reason code, prove negative side-effect invariants, and include relevant invalid-input and cancellation boundaries with descriptive test names.
 - Avoid embedding real credentials, secrets, tokens, connection strings, or personally identifiable information.
 - Use obviously fictional or placeholder values where examples require identifiers or sensitive-looking data.
 - When adding, renaming, or removing an executable sample, update both sample catalogs. Add or revise its repository-facing entry in `samples/README.md`, and update `docs/samples/index.md` with its learning objective, difficulty, key invariant, run command, and canonical README link so the published sample guide remains current.

samples/acknowledgment-and-audit-residue/README.md

@@ -64,7 +64,7 @@ From the repository root:
 dotnet test samples/acknowledgment-and-audit-residue/Tests/AcknowledgmentAndAuditResidue.Tests.csproj
 ```
 
-The focused xUnit tests make the boundary explicit: acknowledgment can satisfy one governance requirement, but it does not itself grant authorization or execution authority. Re-evaluation still controls the next step, and changed resource state can still block execution.
+The focused xUnit tests cover every policy outcome and acknowledgment binding failure, including the expiration boundary and stable reason codes. They also prove that acknowledgment does not grant execution authority, changed resource state can still block execution, and the executable scenarios preserve their correlated audit timelines.
 
 The sample uses deterministic local data and does not call external services.
 

samples/acknowledgment-and-audit-residue/Tests/AcknowledgmentBoundaryTests.cs

@@ -22,6 +22,9 @@ public void AcknowledgmentDoesNotGrantExecutionAuthority()
             GovernanceDecisionOutcome.AcknowledgmentRequired,
             initialDecision.Outcome);
         Assert.False(initialDecision.CanProceed);
+        Assert.Equal(
+            "account.disable.reason-required",
+            Assert.Single(initialDecision.Reasons).Code);
         Assert.Equal(0, executor.InvocationCount);
 
         AcknowledgmentChallenge challenge = CreateChallenge(
@@ -123,6 +126,215 @@ public void ExpiredAcknowledgmentDoesNotReachExecution()
         Assert.Equal(0, executor.InvocationCount);
     }
 
+    [Fact]
+    public void RejectedAcknowledgmentIsInvalid()
+    {
+        (AcknowledgmentChallenge challenge, AcknowledgmentResponse response) =
+            CreateValidExchange();
+
+        AcknowledgmentValidation validation = AcknowledgmentValidator.Validate(
+            challenge,
+            response with { Accepted = false },
+            response.OccurredUtc);
+
+        Assert.False(validation.IsValid);
+        Assert.Equal("acknowledgment.rejected", validation.ReasonCode);
+    }
+
+    [Fact]
+    public void WrongChallengeIdentifierIsInvalid()
+    {
+        (AcknowledgmentChallenge challenge, AcknowledgmentResponse response) =
+            CreateValidExchange();
+
+        AcknowledgmentValidation validation = AcknowledgmentValidator.Validate(
+            challenge,
+            response with { ChallengeId = "different-challenge" },
+            response.OccurredUtc);
+
+        Assert.False(validation.IsValid);
+        Assert.Equal("acknowledgment.challenge-mismatch", validation.ReasonCode);
+    }
+
+    [Fact]
+    public void WrongActorIsInvalid()
+    {
+        (AcknowledgmentChallenge challenge, AcknowledgmentResponse response) =
+            CreateValidExchange();
+
+        AcknowledgmentValidation validation = AcknowledgmentValidator.Validate(
+            challenge,
+            response with { ActorId = "operator-99" },
+            response.OccurredUtc);
+
+        Assert.False(validation.IsValid);
+        Assert.Equal("acknowledgment.actor-mismatch", validation.ReasonCode);
+    }
+
+    [Fact]
+    public void WrongAcknowledgmentCodeIsInvalid()
+    {
+        (AcknowledgmentChallenge challenge, AcknowledgmentResponse response) =
+            CreateValidExchange();
+
+        AcknowledgmentValidation validation = AcknowledgmentValidator.Validate(
+            challenge,
+            response with { AcknowledgmentCode = "account.disable.wrong-code" },
+            response.OccurredUtc);
+
+        Assert.False(validation.IsValid);
+        Assert.Equal("acknowledgment.code-mismatch", validation.ReasonCode);
+    }
+
+    [Fact]
+    public void WrongCorrelationIdentifierIsInvalid()
+    {
+        (AcknowledgmentChallenge challenge, AcknowledgmentResponse response) =
+            CreateValidExchange();
+
+        AcknowledgmentValidation validation = AcknowledgmentValidator.Validate(
+            challenge,
+            response with { CorrelationId = "different-correlation" },
+            response.OccurredUtc);
+
+        Assert.False(validation.IsValid);
+        Assert.Equal("acknowledgment.correlation-mismatch", validation.ReasonCode);
+    }
+
+    [Fact]
+    public void ResponseAtExpirationBoundaryIsValid()
+    {
+        (AcknowledgmentChallenge challenge, AcknowledgmentResponse response) =
+            CreateValidExchange();
+        AcknowledgmentResponse boundaryResponse = response with
+        {
+            OccurredUtc = challenge.ExpiresUtc
+        };
+
+        AcknowledgmentValidation validation = AcknowledgmentValidator.Validate(
+            challenge,
+            boundaryResponse,
+            boundaryResponse.OccurredUtc);
+
+        Assert.True(validation.IsValid);
+        Assert.Equal("acknowledgment.accepted", validation.ReasonCode);
+    }
+
+    [Fact]
+    public void NonAdministratorIsDeniedWithStableReasonCode()
+    {
+        DisableAccountPolicyContext original = CreateContext();
+        DisableAccountPolicyContext context = original with
+        {
+            Actor = original.Actor with { IsAdministrator = false }
+        };
+
+        GovernanceDecision decision = DisableAccountPolicy.Evaluate(context);
+
+        Assert.Equal(GovernanceDecisionOutcome.Denied, decision.Outcome);
+        Assert.Equal(
+            "account.disable.not-administrator",
+            Assert.Single(decision.Reasons).Code);
+    }
+
+    [Fact]
+    public void CrossTenantRequestIsDeniedWithStableReasonCode()
+    {
+        DisableAccountPolicyContext original = CreateContext();
+        DisableAccountPolicyContext context = original with
+        {
+            Account = original.Account with { TenantId = "tenant-b" }
+        };
+
+        GovernanceDecision decision = DisableAccountPolicy.Evaluate(context);
+
+        Assert.Equal(GovernanceDecisionOutcome.Denied, decision.Outcome);
+        Assert.Equal(
+            "account.disable.cross-tenant",
+            Assert.Single(decision.Reasons).Code);
+    }
+
+    [Fact]
+    public void ProtectedAccountRecommendsEscalationWithStableReasonCode()
+    {
+        DisableAccountPolicyContext original = CreateContext();
+        DisableAccountPolicyContext context = original with
+        {
+            Account = original.Account with { IsProtected = true }
+        };
+
+        GovernanceDecision decision = DisableAccountPolicy.Evaluate(context);
+
+        Assert.Equal(
+            GovernanceDecisionOutcome.EscalationRecommended,
+            decision.Outcome);
+        Assert.Equal(
+            "account.disable.protected-account",
+            Assert.Single(decision.Reasons).Code);
+    }
+
+    [Fact]
+    public void SuppliedReasonAllowsRequestWithoutReasonCodes()
+    {
+        DisableAccountPolicyContext original = CreateContext();
+        DisableAccountPolicyContext context = original with
+        {
+            Intent = original.Intent with { Reason = "Security investigation" }
+        };
+
+        GovernanceDecision decision = DisableAccountPolicy.Evaluate(context);
+
+        Assert.Equal(GovernanceDecisionOutcome.Allowed, decision.Outcome);
+        Assert.True(decision.CanProceed);
+        Assert.Empty(decision.Reasons);
+    }
+
+    [Fact]
+    public void AuditResidueKeepsLifecycleIdentityExplicit()
+    {
+        var residue = new AuditResidue(
+            Sequence: 2,
+            EventId: "test-user-100-event-02",
+            OccurredUtc: _nowUtc,
+            ActorId: "operator-7",
+            OperationName: "account.disable",
+            Outcome: "AcknowledgmentAccepted",
+            ReasonCodes: ["account.disable.reason-required", "acknowledgment.accepted"],
+            CorrelationId: "test-user-100",
+            PolicyVersion: "3.2",
+            Stage: "acknowledgment-accepted");
+
+        Assert.Equal("test-user-100", residue.CorrelationId);
+        Assert.Equal("3.2", residue.PolicyVersion);
+        Assert.Equal("acknowledgment-accepted", residue.Stage);
+        Assert.Equal(2, residue.ReasonCodes.Count);
+    }
+
+    [Fact]
+    public void ExecutableScenariosPreserveExpectedAuditTimelines()
+    {
+        System.Reflection.MethodInfo entryPoint =
+            Assert.IsAssignableFrom<System.Reflection.MethodInfo>(
+                typeof(DisableAccountPolicy).Assembly.EntryPoint);
+
+        entryPoint.Invoke(null, [Array.Empty<string>()]);
+    }
+
+    private static (AcknowledgmentChallenge Challenge, AcknowledgmentResponse Response)
+        CreateValidExchange()
+    {
+        DisableAccountPolicyContext context = CreateContext();
+        GovernanceDecision decision = DisableAccountPolicy.Evaluate(context);
+        AcknowledgmentChallenge challenge = CreateChallenge(
+            context,
+            decision,
+            _nowUtc);
+
+        return (
+            challenge,
+            CreateAcceptedResponse(challenge, _nowUtc.AddSeconds(1)));
+    }
+
     private static DisableAccountPolicyContext CreateContext()
     {
         return new DisableAccountPolicyContext(

samples/centralized-error-handling-and-problem-details/README.md

@@ -181,7 +181,7 @@ From the repository root:
 dotnet test samples/centralized-error-handling-and-problem-details/Tests/CentralizedErrorHandlingAndProblemDetails.Tests.csproj
 ```
 
-The focused tests prove these invariants:
+The focused tests cover every governance-to-HTTP outcome, invalid and unknown scenarios, safe known and unexpected exception responses, and trace correlation. They prove these invariants:
 
 ```text
 Denied governance decision

samples/centralized-error-handling-and-problem-details/Tests/ErrorHandlingIntegrationTests.cs

@@ -3,6 +3,7 @@
 using System.Net.Http.Json;
 using System.Text.Json;
 using Microsoft.AspNetCore.Builder;
+using Microsoft.AspNetCore.Http;
 using Microsoft.AspNetCore.Mvc;
 using Microsoft.AspNetCore.TestHost;
 using Microsoft.Extensions.Logging;
@@ -15,6 +16,23 @@ public sealed class ErrorHandlingIntegrationTests
     private static readonly JsonSerializerOptions _jsonOptions =
         new(JsonSerializerDefaults.Web);
 
+    [Fact]
+    public async Task Allowed_governance_decision_returns_no_content_without_exception_handler_log()
+    {
+        await using TestApplication application =
+            await TestApplication.StartAsync(TestContext.Current.CancellationToken);
+
+        HttpResponseMessage response = await application.Client.GetAsync(
+            "/governance/allowed",
+            TestContext.Current.CancellationToken);
+
+        Assert.Equal(HttpStatusCode.NoContent, response.StatusCode);
+        Assert.Empty(await response.Content.ReadAsByteArrayAsync(TestContext.Current.CancellationToken));
+        Assert.DoesNotContain(
+            application.LogProvider.Entries,
+            entry => entry.CategoryName == typeof(ApplicationExceptionHandler).FullName);
+    }
+
     [Fact]
     public async Task Denied_governance_decision_is_explicit_403_without_exception_handler_log()
     {
@@ -65,6 +83,88 @@ await client.GetAsync(
                 typeof(ApplicationExceptionHandler).FullName);
     }
 
+    [Fact]
+    public async Task Acknowledgment_required_decision_maps_to_explicit_409_problem()
+    {
+        await using TestApplication application =
+            await TestApplication.StartAsync(TestContext.Current.CancellationToken);
+
+        HttpResponseMessage response = await application.Client.GetAsync(
+            "/governance/acknowledgment-required",
+            TestContext.Current.CancellationToken);
+        ProblemDetails problem = await ReadProblemAsync(
+            response,
+            TestContext.Current.CancellationToken);
+
+        Assert.Equal(HttpStatusCode.Conflict, response.StatusCode);
+        Assert.Equal("Acknowledgment Required", problem.Title);
+        Assert.Equal("/problems/acknowledgment-required", problem.Type);
+        Assert.Equal("/governance/acknowledgment-required", problem.Instance);
+        Assert.Equal(
+            "governance.acknowledgment-required",
+            GetExtensionString(problem, "code"));
+    }
+
+    [Fact]
+    public async Task Escalation_recommended_decision_maps_to_distinct_409_problem()
+    {
+        await using TestApplication application =
+            await TestApplication.StartAsync(TestContext.Current.CancellationToken);
+
+        HttpResponseMessage response = await application.Client.GetAsync(
+            "/governance/escalation-recommended",
+            TestContext.Current.CancellationToken);
+        ProblemDetails problem = await ReadProblemAsync(
+            response,
+            TestContext.Current.CancellationToken);
+
+        Assert.Equal(HttpStatusCode.Conflict, response.StatusCode);
+        Assert.Equal("Escalation Recommended", problem.Title);
+        Assert.Equal("/problems/escalation-recommended", problem.Type);
+        Assert.Equal(
+            "governance.escalation-recommended",
+            GetExtensionString(problem, "code"));
+    }
+
+    [Fact]
+    public async Task Unknown_governance_scenario_remains_a_not_found_problem()
+    {
+        await using TestApplication application =
+            await TestApplication.StartAsync(TestContext.Current.CancellationToken);
+
+        HttpResponseMessage response = await application.Client.GetAsync(
+            "/governance/not-a-scenario",
+            TestContext.Current.CancellationToken);
+        ProblemDetails problem = await ReadProblemAsync(
+            response,
+            TestContext.Current.CancellationToken);
+
+        Assert.Equal(HttpStatusCode.NotFound, response.StatusCode);
+        Assert.Equal(StatusCodes.Status404NotFound, problem.Status);
+        Assert.DoesNotContain(
+            application.LogProvider.Entries,
+            entry => entry.CategoryName == typeof(ApplicationExceptionHandler).FullName);
+    }
+
+    [Fact]
+    public void Empty_governance_scenario_is_rejected_as_invalid_input()
+    {
+        Assert.Throws<ArgumentException>(
+            () => GovernanceDecision.TryFromScenario("   ", out _));
+    }
+
+    [Fact]
+    public void Governance_scenario_matching_is_case_insensitive()
+    {
+        bool found = GovernanceDecision.TryFromScenario(
+            "DeNiEd",
+            out GovernanceDecision decision);
+
+        Assert.True(found);
+        Assert.Equal(GovernanceDecisionOutcome.Denied, decision.Outcome);
+        Assert.Equal("governance.denied", decision.Code);
+    }
+
     [Fact]
     public async Task Unexpected_exception_becomes_safe_500_without_sensitive_detail()
     {

samples/decision-before-execution/README.md

@@ -50,7 +50,7 @@ From the repository root:
 dotnet test samples/decision-before-execution/Tests/DecisionBeforeExecution.Tests.csproj
 ```
 
-The focused xUnit tests assert that denied, deferred, and acknowledgment-required decisions never invoke the executor. A positive-control test confirms that an allowed decision crosses the execution boundary exactly once.
+The focused xUnit tests assert every outcome and stable reason code. Denied, deferred, acknowledgment-required, and escalation-recommended decisions never invoke the executor; an allowed decision crosses the boundary exactly once, and cancellation prevents that execution before its side effect is recorded.
 
 The sample evaluates five deterministic scenarios: