Capstone: an auditable scheme decision pipeline

The capstone assembles everything into one flow: a request arrives, registries are queried, a pure policy decides, and an audit record is written — with every step’s type stating what it can produce. The point to notice as you read is not any single abstraction; it is that the boundaries are now all typed.

The flow

The pipeline

1
public final class DecisionPipeline {
2

3
    private static final String RULE_VERSION = "farmer-support-2026.1";
4

5
    private final CitizenRegistry citizens;
6
    private final LandRegistry land;
7
    private final SchemeCode scheme;
8

9
    public Result<EligibilityOutcome, RegistryError> evaluate(String citizenId) {
10
        return citizens.loadCitizen(citizenId)
11
                .flatMap(facts -> land.loadLandRecord(citizenId)
12
                        .map(record -> FarmerSupportPolicy.evaluate(facts, scheme)));
13
    }
14

15
    public IO<Result<EligibilityOutcome, RegistryError>> evaluation(String citizenId) {
16
        return IO.delay(() -> evaluate(citizenId));
17
    }
18

19
    public IO<DecisionReport> auditedEvaluation(String citizenId, AuditStore audit, Clock clock) {
20
        return evaluation(citizenId)
21
                .map(result -> result.fold(
22
                        error -> new DecisionReport(
23
                                new ManualReview(scheme.value(), citizenId, "registry error"),
24
                                RULE_VERSION, clock.instant(), citizenId),
25
                        outcome -> new DecisionReport(outcome, RULE_VERSION, clock.instant(), citizenId)))
26
                .map(report -> {
27
                    audit.append(report);
28
                    return report;
29
                });
30
    }
31
}

Trace the types: evaluate is pure description — a Result that is either a decision or a named registry error. evaluation lifts it into IO, deferring the actual registry calls. auditedEvaluation composes three steps into one IO<DecisionReport>: run the lookups, convert any outcome (including Failure) into an auditable DecisionReport — a registry error routes to ManualReview rather than vanishing — then append it to the store. Nothing touches the network or the audit table until the controller calls unsafeRun().

The test that proves the boundary

1
@Test
2
void pipelineEvaluatesAndAudits() {
3
    DecisionPipeline pipeline = new DecisionPipeline(
4
            citizenId -> Result.success(new CitizenFacts(citizenId, true, 100_000, true)),
5
            citizenId -> Result.success(new LandRecord(citizenId, LandCategory.RAINFED, 1.5)),
6
            new SchemeCode("FARMER-SUPPORT"));
7

8
    List<DecisionReport> auditTrail = new ArrayList<>();
9
    Clock clock = Clock.fixed(Instant.parse("2026-09-24T10:00:00Z"), ZoneOffset.UTC);
10

11
    DecisionReport report = pipeline
12
            .auditedEvaluation("C-7", auditTrail::add, clock)
13
            .unsafeRun();
14

15
    assertThat(report.outcome()).isEqualTo(new Eligible("FARMER-SUPPORT", "C-7"));
16
    assertThat(report.ruleVersion()).isEqualTo("farmer-support-2026.1");
17
    assertThat(auditTrail).hasSize(1);
18
}

No mocks, no containers, no database — the “registries” are lambdas returning Result, the audit store is a List::add, the clock is fixed. That is what the whole series was building toward: a decision pipeline whose every effect is a value, so the entire flow is testable in a unit test that runs in milliseconds.

Where each piece landed

Concern	Type	Chapter
Absent evidence	`Option<T>`	5
Expected failures	`Result<T, RegistryError>`	6
Independent validation	`Validated` + `map2`	8
Dependent sequencing	`flatMap`	9
Effectful chains	`Results.andThenK`	11
Accumulation	`Monoid`, `Foldable.combineAll`	12–13
Expensive conditional facts	`Lazy<T>`	14
Deferred effects	`IO<T>`	15
Configuration	`Reader<PolicyEnvironment, T>`	16
Workflow transitions	`State<ApplicationStatus, A>`	17
Async lookups	`CompletableFuture` + virtual threads	18

What this series deliberately left out

Property-based law testing (jqwik), a Traversable over real collections, optics/lenses for nested updates, and a production effect runtime — each is a real tool and each would have doubled the series. The library at this point is ~700 lines; it is not a replacement for vavr or cats-effect, and was never meant to be. What it is: a working demonstration that Java 21’s records, sealed types, and pattern matching are enough to make functional architecture concrete — and a set of decision rules (which type for which failure, when to flatMap versus map2, where unsafeRun lives) that transfer directly to whichever effect library or framework you actually ship.

JavaFunctional Programming