Capstone: Prove This Postgres Database Is a System of Record
You have done migrations, journal, idempotency, claims, outbox, events, RLS, MCP boundary, and forensics. Now you sit at the desk where the Reconciler is about to be promoted from a one-user prototype to a multi-tenant production Worker. The boss asks the question every release deserves: "is the database actually ready to be the system of record for this Worker?" Your job is to produce the evidence bundle that answers yes or no, with reasons.
Capstone Rules
- Run all nine drills, in order.
- For each drill, capture a one-line evidence string.
- Assemble the evidence bundle as a JSON object in the exact shape below.
- Write a one-paragraph release decision: PERMITTED or BLOCKED with reasons.
- If any drill is BLOCKED, identify which prior lesson's habit is missing.
No skipping drills. The evidence bundle is the artifact, and the release decision is the call.
The Nine Drills
Drill 1: Migration Review (callback Lesson 1)
What you do: The agent proposes a migration that adds a notes column to expenses (nullable, text). You read the DDL without running it. You confirm the migration carries an upgrade() and a downgrade(), that the drop guard is in place (no DROP TABLE without explicit override), and that no unrelated changes ride along. You apply the migration on a Neon branch and roll it back to confirm both directions work.
What evidence to capture: "Migration adds notes column, downgrade drops it cleanly, applied and rolled back on Neon branch cap-migration-1. No scope creep."
Drill 2: Run Journal Resume Drill (callback Lesson 2)
What you do: Start a Reconciler run. Mid-turn, kill the process. Restart the Worker. Watch what happens: it should read runs, turns, and tool_calls, recognise the crash signature (status = 'running', finished_at IS NULL), and resume from the last incomplete turn without re-doing the completed ones.
What evidence to capture: "Run resumed from turn 3 of 5. Turns 1 and 2 were not re-executed. Journal shows continuous timeline with one gap closed."
Drill 3: Idempotency Retry Test (callback Lesson 3)
What you do: Run the same Worker write twice with the same input. Confirm exactly one row lands in expenses. The ON CONFLICT DO NOTHING (or DO UPDATE) clause must keep the second write from duplicating the row.
What evidence to capture: "Two invocations with the same idempotency key produced one expenses row. Second insert was a no-op. Row count delta: +1."
Drill 4: Concurrency Claim Test (callback Lesson 4)
What you do: Spin two Worker sessions at the same time. Both race for the same pending transaction. The SELECT ... FOR UPDATE SKIP LOCKED claim must give the row to exactly one Worker. The loser must silently move on to the next claimable row.
What evidence to capture: "Worker A claimed pending_transaction T-101. Worker B skipped T-101 and claimed T-102. No duplicate processing. No lock errors raised."
Drill 5: Outbox Relay Retry Test (callback Lesson 5)
What you do: Force the relay to fail once on a deliberate transient error (network blip simulated). Confirm the outbox row stays in pending with retry metadata. On the next relay attempt, the row dispatches successfully exactly once. The dedup_key prevents a double-send if the relay accidentally retries after success.
What evidence to capture: "Relay failed once, retried once, dispatched once. Outbox row O-405 ended in dispatched. Email service received exactly one delivery for this dedup_key."
Drill 6: Append-Only Event Test (callback Lesson 6)
What you do: Try to UPDATE one row in agent_events. The database must refuse, either via the role grants (UPDATE/DELETE revoked from worker_write) or via a trigger that raises an exception. Then reconstruct one full Reconciler run by reading agent_events alone, ordered by id, and narrate the run in plain English.
What evidence to capture: "UPDATE on agent_events raised permission error (or trigger exception). Replayed run R-44 from six event rows. Narrative reconstructed without consulting the snapshot."
Drill 7: RLS Identity Flip Test (callback Lesson 7)
What you do: Set the tenant context to Alice. Run SELECT * FROM expenses;. Confirm only Alice's rows are visible. Flip the context to Bob. Run the same SELECT. Confirm only Bob's rows are visible. Flip to unset (no tenant context). Confirm zero rows are visible. The policy must enforce isolation in all three states.
What evidence to capture: "Alice context returned 47 rows (all Alice). Bob context returned 31 rows (all Bob). Unset context returned 0 rows. No cross-tenant leakage in any flip."
Drill 8: MCP Boundary Test (callback Lesson 8)
What you do: Confirm the Worker process has no DATABASE_URL in its environment. The tool surface should be a minimal allow-list of MCP tools (claim, write, queue, read). Attempt one disallowed action through the MCP layer (for example, an arbitrary DROP TABLE call). The tool layer must refuse before the database is touched.
What evidence to capture: "Worker env has no DATABASE_URL. Tool surface lists four allowed operations. Disallowed drop_table call refused at MCP layer with tool-not-found error. Database connection logs show no rogue queries."
Drill 9: Forensics Drill (callback Lesson 9)
What you do: Take a deliberately failed run from any of the prior drills (or simulate one). Produce the four-query forensic report scoped to that run_id: the runs row, the tool_calls joined to turns and runs, the outbox state grouped by status, and the agent_events ordered by id. Fill the six-line forensic report template.
What evidence to capture: "Forensic report assembled for run_id 8a3f.... Six lines populated. Root cause named in one sentence. Recommended next action: retry with same idempotency keys."
The Evidence Bundle
Fill in the bundle exactly in this shape. Each value is either "pass" or a one-line reason for "fail". The release_decision is one paragraph.
{
"migration_review": "pass",
"run_journal_resume_drill": "pass",
"idempotency_retry_test": "pass",
"concurrency_claim_test": "pass",
"outbox_relay_retry_test": "pass",
"append_only_event_test": "pass",
"rls_identity_flip_test": "pass",
"mcp_boundary_test": "pass",
"forensics_drill": "pass",
"release_decision": "permitted_or_blocked_with_reason"
}
The bundle is the artifact. The release_decision paragraph belongs in the same file as the JSON, immediately below. Together they answer the boss's question with rows behind every claim.
Mastery Gate
You pass this capstone when:
- All nine drills ran with an explicit pass or fail.
- The evidence bundle is assembled exactly in the JSON shape above.
- The release decision paragraph states the call AND the reason.
- At least one rejected drill (intentional or otherwise) blocks the release with named reasons. If every drill passed on the first try, repeat one drill with a deliberate break (for example, remove the idempotency key) and capture the failure honestly.
A passing capstone is not a capstone where everything worked. It is a capstone where you can honestly say what worked, what did not, and why.
Reflection
You built the minimum SoR discipline: migrations, journal, idempotency, claims, outbox, append-only events, RLS, MCP boundary, and forensics.
This is the foundation. A Worker pointed at this database can crash, retry, race another Worker, lose its network for thirty seconds, and still leave behind a clean answer to "what happened?" That is what Invariant 5 demanded back in Lesson 0. Today you can prove the database delivers on it.
Try With AI
Prompt 1: Evidence Bundle Drill
I have run the nine drills against the Reconciler database. For each
drill, I will paste my one-line evidence string. After I paste all
nine, assemble the JSON bundle exactly in the shape from the lesson.
Do not interpret. Do not improve my evidence strings. If any line
reads like a fail, mark it fail; otherwise mark it pass.
What you're learning: Treating the agent as a bundler, not as a grader. You did the drills. You wrote the evidence. The agent just shapes the JSON.
Prompt 2: Blocked-Release Rationale Drill
My idempotency drill failed: two invocations produced two rows in
expenses instead of one. The other eight drills passed. Write the
release decision paragraph for me. Name the failure, name the
lesson whose habit is missing (idempotency keys, Lesson 3), and
recommend the smallest change that would unblock the release.
What you're learning: A blocked release is not a defeat. It is the SoR doing its job: refusing to ship a Worker that cannot retry safely. The agent can draft the rationale; you decide whether the recommendation is the right fix.
Prompt 3: 100-Worker Fleet Thought Experiment
Today the Reconciler runs as one Worker against one Neon database.
Tomorrow we are running 100 Workers in parallel against the same
database. Do not write code. Tell me in five bullets which of the
nine drills would change, which would stay the same, and which
would need a new drill added that is not in the current chapter.
What you're learning: Scaling reveals which SoR habits are pre-paid (idempotency, claims with SKIP LOCKED, RLS) and which need new investment (connection pooling, outbox sharding, event table partitioning). The chapter taught the floor; this prompt sketches the next floor up.
Checkpoint
- I ran all nine drills, in order, and captured one-line evidence for each.
- I assembled the evidence bundle exactly in the JSON shape from this lesson.
- I wrote the release decision paragraph naming PERMITTED or BLOCKED with reasons.
- At least one drill was blocked honestly (intentionally or otherwise) and the blocking reason names a Chapter 21B lesson.
- I can map each drill back to the lesson that taught the underlying habit (Lessons 1 through 9).
- I can name two SoR topics this chapter did not teach and where they belong.