Prepare for the lab

Pre-read — Lab 2

10–15 minutes, before session day. Setup takes longer than reading this, so start with the setup step and read while Maven downloads.

1. Setup first

python3 scripts/verify_setup.py

This checks your toolchain, creates the two service repositories, warms the Maven cache and confirms the starting state. It must end with “Setup complete”. If it does not, bring the output to the facilitator before the session rather than during it.

A cold Maven cache is the single most common way a room loses fifteen minutes. Run this at your desk, on the machine you will use.

2. The situation, in plain terms

A merchant took a payment. Now they need to refund it.

The refund request arrives in a WSAPI-facing shape, is translated by TTA, and is sent to Payment Processor, which decides it and records it.

flowchart TB
  accTitle: The merchant refund journey
  accDescr: A merchant refund request passes through WSAPI to TTA, the translation boundary, then Payment Processor, the refund decision. The wider Meridian flow continues through CPC, Injection, LCS, and DCF; these downstream services are not implemented in this lab.
  R["Merchant refund request"] --> W["WSAPI"]
  W --> T["TTA · translation boundary"]:::focus
  T --> P["Payment Processor · refund decision"]:::focus
  P --> C
  subgraph downstream["Wider Meridian flow continues · not implemented in this lab"]
    C["CPC"] --> I["Injection"] --> L["LCS"] --> D["DCF"]
  end

You work on the TTA → Payment Processor portion only.

Your task: bring that portion into agreement — across contract, implementation, tests and technical requirements — without expanding into the rest of the flow.

3. The thing that makes it interesting

Both repositories build. Both have passing tests. Neither is obviously broken.

They still do not agree with each other.

That is the whole point of the exercise. Correctness across a service boundary lives in the relationship between two implementations, not inside either one, and no amount of testing one repository in isolation will show you a disagreement with the other.

Two examples of the shape of the problem, neither of which is a hint about where to look:

A service answers a duplicate refund with “this is a duplicate”. The service in front of it turns that into “the system failed”. The caller retries a request that was correctly refused.
Both sides implement retry protection. They protect against different retry identities. Each looks correct alone; together, the operation is not idempotent.

4. Lab versus real Meridian

The lab uses real Meridian terminology and real refund behaviour, simplified deliberately so the exercise fits in two hours.

Read SCENARIO_GROUNDING.md — it separates grounded Meridian behaviour from lab simplification from deliberately planted defect. The planted defects are teaching fixtures and do not imply anything about real Meridian systems.

The one rule worth carrying into the room: inventing lab code is fine; inventing Meridian platform behaviour is not.

5. Vocabulary

Skim TERM_CARD.md. Ten terms. You will use seam, context ledger and agent brief constantly.

6. What is graded

Read ESSENTIAL_OUTCOMES.md.

The short version: engineering outcomes and evidence, never whether your screen matches the facilitator’s.

7. Model output will vary — plan for it

Your agent will word things differently from the person next to you, find the same problem by a different route, and return findings in a different order. Running the same prompt twice will not give you the same text.

None of that means you are behind. If you find yourself trying to make your output look like the demonstration, stop and ask what the demonstration was showing you instead.

8. What this lab assumes you already have

From Lab 1: fresh-context review, sub-agents, human gates, deterministic checks, journey and hand-off. These are not re-taught. If any of them is hazy, say so early — Stage 0 is the moment for it, not Stage 4.

You do not need to know anything new about payments. You need to be willing to say “the source does not tell us that” and leave it unanswered.

Download the unchanged original source