DEV Community: Dakota Liu

Case Study: An Allowlist Gate That Rejects an Agent Patch Before You Apply It

Dakota Liu — Sun, 11 Oct 2026 21:48:50 +0000

You should reject an agent-written patch before it touches your tree, unless a written allowlist and a named test command both pass. Free generation makes extra files cheap to propose, while a wrong file remains expensive to undo. This case study walks you through a tiny Python gate you can run on any disposable workspace. The gate is a review tool, not a claim that any model or host is safe.

What you are protecting

You are protecting a three-file health service, not a production platform and not a secret-bearing repository. The service exposes /health, and you want a second route named /ready with one focused test. An agent can draft that change quickly, yet it can also edit deploy files, lockfiles, or a hidden env sample. Your job is to keep the applied diff inside a card you wrote before the session started.

Background

Picture a small folder that already contains app.py, test_app.py, and README.md, with no database and no cloud credentials. You ask an assistant to add readiness behavior, and you expect a unified diff plus a short report. The report must name the exact test command you will run after the patch applies cleanly. If either artifact drifts outside the card, you stop and you do not apply the patch.

An agent draft is still an untrusted patch, even when the prose around the diff sounds finished and careful. You need a local rule that does not depend on how confident the report appears in the chat window. This exercise does not rank models, and it does not borrow a scoreboard from a public thread. You are freezing one small contract that names allowed paths, forbidden paths, and a test command.

Goal

The goal is a fail-closed checker that exits nonzero unless three conditions hold at the same time. The diff may touch only paths on the allowlist, and it must not touch any forbidden path. The agent report must contain the exact test command that you already wrote on the card. You treat missing fields as failure, because a silent default is how an unreviewed file lands in the tree.

The session card

You write the card before you prompt, and you store it beside the checker rather than inside the agent's scratch space. You keep the card in the repository you control, so a later edit to the prompt cannot quietly widen the allowlist. You treat the byte cap as your own courtesy limit, not as a limit advertised by any host. You can change the goal line, but you should not add deploy files just because a draft looks tidy.

# session_card.yaml - proposal, not a production policy
goal: Add GET /ready that returns 200 and a ready status
allowed_paths:
  - app.py
  - test_app.py
forbidden_paths:
  - .env
  - .env.example
  - credentials.json
  - deploy/
  - .git/
required_test_command: python -m unittest test_app.py
max_diff_bytes: 12000

Implementation

The checker below is a labeled, unexecuted example that you should read carefully before you run it. It uses only the Python standard library, so you do not add a dependency just to review a patch. It reads the card, the diff, and the report, then prints one JSON line for a completed check. You should treat a parser error or a bad argument count as a failed review before any patch is applied.

#!/usr/bin/env python3
"""session_gate.py - unexecuted example. Fail closed on an agent diff."""

import json
import sys
from pathlib import Path


def load_card(path: Path) -> dict:
    card = {"allowed_paths": [], "forbidden_paths": []}
    key = None
    for raw in path.read_text(encoding="utf-8").splitlines():
        line = raw.split("#", 1)[0].rstrip()
        if not line.strip():
            continue
        if line.startswith("  - "):
            if key is None:
                raise SystemExit("list item before a key")
            card.setdefault(key, []).append(line.strip()[2:].strip())
            continue
        if ":" not in line:
            raise SystemExit("card line missing colon")
        key, value = line.split(":", 1)
        key, value = key.strip(), value.strip()
        if value:
            card[key] = int(value) if value.isdigit() else value
        else:
            card.setdefault(key, [])
    required = ("goal", "required_test_command", "max_diff_bytes")
    missing = [name for name in required if name not in card]
    if missing or not card["allowed_paths"]:
        raise SystemExit(f"incomplete card: {missing or 'allowed_paths'}")
    return card


def changed_paths(diff_text: str) -> list[str]:
    paths = []
    for line in diff_text.splitlines():
        if line.startswith("+++ b/"):
            path = line[6:].strip()
            if path and path != "/dev/null":
                paths.append(path)
    return paths


def main() -> int:
    if len(sys.argv) != 4:
        print("usage: session_gate.py CARD DIFF REPORT", file=sys.stderr)
        return 2
    card = load_card(Path(sys.argv[1]))
    diff_text = Path(sys.argv[2]).read_text(encoding="utf-8")
    report = Path(sys.argv[3]).read_text(encoding="utf-8")
    reasons = []
    if len(diff_text.encode("utf-8")) > int(card["max_diff_bytes"]):
        reasons.append("diff exceeds max_diff_bytes")
    allowed = set(card["allowed_paths"])
    forbidden = tuple(card["forbidden_paths"])
    for path in changed_paths(diff_text):
        if path in forbidden or any(path.startswith(prefix) for prefix in forbidden):
            reasons.append(f"forbidden path: {path}")
        elif path not in allowed:
            reasons.append(f"path outside allowlist: {path}")
    command = str(card["required_test_command"])
    report_lines = [line.strip() for line in report.splitlines()]
    if command not in report_lines:
        reasons.append("report missing required_test_command")
    if "+++ " not in diff_text:
        reasons.append("diff has no file headers")
    result = {"ok": not reasons, "reasons": reasons, "command": command}
    print(json.dumps(result, ensure_ascii=True))
    return 0 if result["ok"] else 1


if __name__ == "__main__":
    raise SystemExit(main())

Commands you run

You create two fixtures, one clean and one dirty, then you run the gate against each fixture. These commands are the reproducible artifact, and they do not call a network or a model. You keep the fixtures in a local fixtures directory, and you do not fetch them from an untrusted gist. You run each command in a clean shell so a previous exit code cannot confuse the result you record.

Local fixtures

Save this as fixtures/ready_ok.diff. It is a proposal hunk, not a patch this article applied to a live service.

--- a/app.py
+++ b/app.py
@@ -1,2 +1,5 @@
 def health():
     return {"status": "ok"}
+
+def ready():
+    return {"status": "ready"}
--- a/test_app.py
+++ b/test_app.py
@@ -1,2 +1,8 @@
 import unittest
+from app import ready
+
+
+class ReadyTest(unittest.TestCase):
+    def test_ready(self):
+        self.assertEqual(ready()["status"], "ready")

Save fixtures/ready_ok.md as one exact line, with no extra words on that line.

python -m unittest test_app.py

Save fixtures/ready_bad.diff as a forbidden-path example. The token below is a placeholder, not a credential you should reuse anywhere.

--- a/.env
+++ b/.env
@@ -0,0 +1 @@
+API_TOKEN=example-not-real

A clean diff should mention only app.py and test_app.py, and the matching report should repeat python -m unittest test_app.py exactly. A dirty diff should add .env or deploy/app.yaml, or the matching report should omit the required command. You apply the patch only after the clean run prints "ok": true and you have read the diff yourself. You discard the dirty fixture even if the prose around it sounds confident, because the gate exists to ignore tone.

python3 session_gate.py session_card.yaml fixtures/ready_ok.diff fixtures/ready_ok.md
python3 session_gate.py session_card.yaml fixtures/ready_bad.diff fixtures/ready_bad.md

Apply only after a clean gate

patch -p1 --dry-run < fixtures/ready_ok.diff
patch -p1 < fixtures/ready_ok.diff
python -m unittest test_app.py

You use --dry-run first so a malformed hunk cannot rewrite a file before you have inspected the reject list. You run the unittest only after a real apply in that same workspace, not in a different checkout with different code. You stop immediately if the dry run, the apply, or the unittest fails, and you do not let the agent edit in place. You save the JSON line next to the diff so a later reviewer can see why you applied or refused the change.

Expected results

Specified exits

This section describes the specification of the example, not a measured production result and not a benchmark. A clean fixture should exit 0 and print a JSON object whose ok field is true. A dirty fixture should exit 1 and list either a forbidden path or a missing command. An incomplete card should exit through SystemExit before any diff is judged, because a missing allowlist must not become allow everything.

Decision table

Fixture	What changed	Report	Expected
clean	`app.py`, `test_app.py`	exact command line	exit 0
forbidden	adds `.env`	exact command line	exit 1
silent report	allowed files only	command omitted	exit 1
broken card	any diff	any report	abort before judgment

You can treat the table as the test plan, and you should not claim a pass until your machine prints the same exits. A row that aborts is still a failure, even when the diff itself would have been small and boring. You record the JSON beside the fixture name, so a later run can be compared without trusting memory. You should rerun the table after any parser edit, because a green memory of yesterday is not evidence about today's script.

Extra cases worth trying

You should also try an empty diff, which this checker rejects because it finds no file headers at all. A delete hunk that uses a null header can slip past this scan, so you should treat that pass as unfinished. If that null-header case passes, you revise the path parser before any agent draft is allowed near the tree. No latency number, token count, or pass rate is claimed here, because this example was not executed against a live service for this article.

Where free model access fits

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

MonkeyCode is relevant only as the place you might draft the patch and run the gate, if you choose that tool. The operator-supplied notes for this draft say that free model access and a free server option exist. This article does not name models, quotas, hardware, duration, or permanence, because those details were not verified against a primary source dated 2026-10-12. You should read the current product docs before you rely on any limit, and you should assume a free workspace can disappear or reset.

A split you can actually run

A practical split keeps the product mention from doing the review work that you still owe the tree. You may use free model access to propose app.py and test_app.py only, with the card pasted into the prompt as a constraint. You may use a free server as a disposable workspace to run session_gate.py and python -m unittest, away from your laptop secrets. You still copy the diff back by hand, and you still refuse the patch when the JSON says ok is false.

Confirm the docs first

If you want to try that split, start from the current MonkeyCode docs and confirm what the free options include today. Run the two fixture commands before you send a real repository, and stop if the docs disagree with this draft. That confirmation step is the only invitation this case study makes, and it is not a promise about price or capacity. You can ignore the product entirely and still keep the card, the checker, and the fail-closed rule.

Limitations

You should read these limits before you reuse the script, because a teaching checker hides several sharp edges. None of these limits is a reason to skip the gate, but each one is a reason not to overclaim what it proves. You can replace the parser later, and you should do that before anyone treats the script as team policy.

The tiny card parser is not a YAML library, and nested values or quoted colons will break it.
Path checks use the +++ b/ header only, so a clever or malformed diff can hide a rename.
A matching test command in the report does not prove the test passed or even exists on disk.
The byte cap is a local courtesy limit you chose, not a quota published by any vendor or host.
The gate cannot see side effects that an agent already performed on a server before you downloaded the diff.
Forbidden prefixes are literal strings, so a prefix such as deploy/ does not cover every obfuscated path.
The patch command is a local Unix assumption, so a Windows shell may need an equivalent apply tool you already trust.

Who should not use this approach

You should not use this gate as a security boundary for a hostile model, a malware sample, or a secret-filled repository. You should not point a free server at production credentials, private customer data, or a remote you cannot revoke. You should not skip the dry-run patch and the unittest just because the JSON line looks calm and short. Teams that need signed reviews, policy-as-code, or a real diff parser should use those systems instead of this teaching script.

Lessons

Write the allowlist before the prompt, because an agent cannot honestly invent your risk boundary after the fact.
Require the test command as an exact line, so a vague sentence about tests cannot pass the gate alone.
Fail closed on a missing card field, since a default of allow-all is the bug you are trying to remove.
Keep vendor claims out of the result line, and record only the exit code and JSON your own command printed.
Treat a free workspace as disposable, and never store long-lived keys there even for a short teaching demo.

You leave this exercise with a card, a checker, two fixture commands, and a rule you can explain to a reviewer in one minute. The rule is simple enough to repeat, and it says that no allowlist match and no named test means no applied patch. That habit stays useful even if you later replace the script with a stricter diff tool on your team. You can rerun the same fixtures next week, and any JSON change then belongs to your checker rather than a headline.

Case Study: A Retry Budget That Refuses to Sleep Past Its Cap

Dakota Liu — Sat, 10 Oct 2026 18:22:39 +0000

You should freeze a retry budget before any generated client is allowed to sleep, because unbounded backoff can pin a worker for hours. A small in-process budget can express attempt caps, elapsed caps, and delay clamps as data you test without a network. This case study walks that budget from a frozen decision table to commands that prove each stop condition. The files are runnable teaching code, not a report of a live outage or a measured production improvement.

You are looking at one module and one unittest file, which is enough to expose the failure without a platform narrative. The worker calls a flaky read and then updates a local row, so it must stop when the frozen budget says stop. A generated draft that retries every exception will hide a permanent validation error behind a long and useless sleep. You prevent that outcome by writing the contract first and by treating every later draft as an untrusted patch.

Background

The pressure usually arrives as a short task that says to wrap the call, add retries, and move on to the next ticket. A sample loop from a coding assistant often uses an open-ended loop, doubles the delay without a ceiling, and catches a broad exception. That shape can survive a happy-path demo, and then it can hold a thread through a long upstream outage. It also retries mistakes you cannot fix by waiting, such as a rejected identifier or a failed local precondition.

You do not need a new framework, a queue, or a hosted workflow engine to close that particular gap. You need a policy object, a wrapper that accepts injected time, and tests that fail if sleep is called after a cap. This case study uses those three pieces and leaves webhook signatures, money rounding, and export idempotency for other write-ups. Keeping the scope that small is what makes the contract reviewable in one sitting by someone who did not write the loop.

Goal

The goal is a wrapper that returns the operation result or raises a budget error when a frozen limit is hit. You should be able to explain that behavior to a teammate without asking them to read the loop line by line. A reviewer should be able to reject a patch by pointing at one row in the decision table below. The tests should stay on the standard library so a clean Python process is enough to reproduce the result.

Frozen rules

You freeze the rules before implementation, and you keep them stable while any draft is proposed or edited. Changing a rule means changing the table and the tests in the same edit, not silently fixing a red assertion. The list below is the whole policy for this case study, and anything absent from it is out of scope on purpose.

The attempt cap counts every try, must be at least one, and includes the first call rather than only the retries.
After failure number n, the delay is the base delay times two to the n minus one, clamped at the configured maximum.
If time already spent plus the next delay would pass the elapsed ceiling, you raise the budget error and skip sleep.
Only exception types you listed as retryable may sleep, and every other error propagates on the attempt that raised it.
Sleep and the clock are injected arguments, so the tests never call the real sleep function or read the wall clock.

Invalid construction is part of the same contract, not a later cleanup you leave for a second patch. A zero attempt cap, a negative duration, or a maximum delay below the base delay raises ValueError immediately. That early failure matters because a generated client should not run at all with a policy you already know is nonsense.

Decision table

You review generated code against the rows below, not against how confident or fluent the draft happens to sound. Each row names the inputs that matter and the only result you should accept for that situation. If a draft needs a new row, you add the row before you accept the code, so the table stays the source of truth.

Situation	Attempts used	Next delay	Elapsed plus delay	Required result
Success on first try	1	none	not used	return the value
Retryable error with room left	below cap	clamped exponential	within ceiling	sleep, then retry
Retryable error at attempt cap	equals cap	ignored	not used	raise budget error
Retryable error at time cap	below cap	computed	above ceiling	raise budget error, no sleep
Non-retryable error	any	none	not used	re-raise the original error
Invalid policy values	none	none	not used	raise `ValueError` at construction

Implementation

The module below is the reference implementation for this worked example, and you can save it as retry_budget.py. You should change it only when the decision table changes, because the tests encode those rows rather than a style preference. The listing has no narrative comments, so a reviewer has to match behavior to the table instead of trusting prose in the file. Treat the listing as example code you can run locally, not as a versioned library with compatibility promises.

class RetryBudgetExceeded(Exception):
    """Raised when a frozen attempt cap or elapsed cap blocks another try."""


class RetryPolicy:
    def __init__(self, max_attempts, max_elapsed_ms, base_delay_ms, max_delay_ms):
        if max_attempts < 1:
            raise ValueError("max_attempts must be at least 1")
        if max_elapsed_ms < 0 or base_delay_ms < 0:
            raise ValueError("time values must be non-negative")
        if max_delay_ms < base_delay_ms:
            raise ValueError("max_delay_ms is below base_delay_ms")
        self.max_attempts = max_attempts
        self.max_elapsed_ms = max_elapsed_ms
        self.base_delay_ms = base_delay_ms
        self.max_delay_ms = max_delay_ms


def delay_for_attempt(policy, attempt):
    scaled = policy.base_delay_ms * (2 ** (attempt - 1))
    if scaled > policy.max_delay_ms:
        return policy.max_delay_ms
    return scaled


def run_with_budget(policy, operation, sleep, clock, retryable=(TimeoutError,)):
    started = clock()
    attempt = 0
    while True:
        attempt += 1
        try:
            return operation()
        except retryable as exc:
            if attempt >= policy.max_attempts:
                raise RetryBudgetExceeded("attempt cap reached") from exc
            wait = delay_for_attempt(policy, attempt)
            if clock() - started + wait > policy.max_elapsed_ms:
                raise RetryBudgetExceeded("elapsed cap reached") from exc
            sleep(wait)

Three details are where generated drafts usually drift, even when the function names look identical to this listing. The delay exponent uses the attempt that just failed, so the first wait equals the base delay rather than double that value. The elapsed check reads the clock after the failed call, which means a slow attempt can exhaust the budget by itself. Sleep runs only after both checks pass, which is why the time-cap test can assert that the sleep log stayed empty.

Tests you can run

Save the next listing as test_retry_budget.py in the same directory as the module so the import stays boring. The tests record sleeps in a list and feed the clock from a short script, which keeps the file deterministic on a shared runner. Nothing in this file needs a network, a clock permission, or a third-party package, which is intentional for a clean environment. You can add cases later, but you should not delete an assertion to help a draft turn green.

import unittest
from retry_budget import (
    RetryBudgetExceeded,
    RetryPolicy,
    delay_for_attempt,
    run_with_budget,
)


def raise_error(exc):
    raise exc


class ScriptedClock:
    def __init__(self, readings):
        self.readings = list(readings)

    def __call__(self):
        if not self.readings:
            raise AssertionError("clock exhausted")
        return self.readings.pop(0)


class RetryBudgetTests(unittest.TestCase):
    def test_success_does_not_sleep(self):
        slept = []
        policy = RetryPolicy(3, 1000, 100, 400)
        value = run_with_budget(policy, lambda: "ok", slept.append, lambda: 0)
        self.assertEqual(value, "ok")
        self.assertEqual(slept, [])

    def test_attempt_cap_sleeps_only_between_tries(self):
        calls = {"n": 0}

        def fail():
            calls["n"] += 1
            raise TimeoutError("slow upstream")

        slept = []
        policy = RetryPolicy(2, 10000, 100, 400)
        with self.assertRaises(RetryBudgetExceeded):
            run_with_budget(policy, fail, slept.append, lambda: 0)
        self.assertEqual(calls["n"], 2)
        self.assertEqual(slept, [100])

    def test_elapsed_cap_does_not_sleep(self):
        slept = []
        policy = RetryPolicy(5, 1000, 100, 400)
        clock = ScriptedClock([0, 950])
        with self.assertRaises(RetryBudgetExceeded):
            run_with_budget(
                policy,
                lambda: raise_error(TimeoutError("late")),
                slept.append,
                clock,
            )
        self.assertEqual(slept, [])

    def test_validation_error_is_not_retried(self):
        slept = []
        policy = RetryPolicy(4, 5000, 50, 200)
        with self.assertRaises(ValueError):
            run_with_budget(
                policy,
                lambda: raise_error(ValueError("bad sku")),
                slept.append,
                lambda: 0,
            )
        self.assertEqual(slept, [])

    def test_delay_clamps_and_policy_rejects_bad_values(self):
        policy = RetryPolicy(3, 5000, 100, 150)
        self.assertEqual(delay_for_attempt(policy, 3), 150)
        with self.assertRaises(ValueError):
            RetryPolicy(0, 1000, 10, 10)


if __name__ == "__main__":
    unittest.main()

From the directory that holds both files, you run the standard-library commands in the next block. You should see five tests pass, with no installer step and no outbound call required by the example itself. If a draft removes the elapsed check, the elapsed-cap test fails because the sleep list is no longer empty. If a draft retries ValueError, the validation test fails because the wrapper no longer preserves the original error type.

python -m py_compile retry_budget.py test_retry_budget.py
python -m unittest test_retry_budget.py -v
python test_retry_budget.py -v

If the runner exposes only python3, you swap the command name and you leave the module arguments unchanged. A compile failure is a syntax problem, while a unittest failure is a contract problem, and you should not mix those two signals. You keep the verbose flag so the printed names match the review notes in the next section.

What a red test means

A red elapsed-cap test means the wrapper slept, or raised the wrong type, after the scripted clock crossed the ceiling. A red validation test means a permanent error was retried or wrapped so tightly that the original type disappeared. A red clamp test means the delay formula forgot the maximum and let exponential growth pick the wait by itself. You fix the wrapper or the table, and you do not loosen the assertion to manufacture a pass on a remote runner.

How you review a generated patch

You read the diff before you celebrate a green test run, because a pass can hide a weakened test. A draft can also pass for the wrong reason if it retries less by accident while breaking a row you care about later. Your review looks for a short list of drifts that show up often when a model writes retry loops from memory. You comment on the table row that broke, and you ask for a smaller patch rather than a broader rewrite.

Reject a bare exception handler that retries validation errors, cancellations, or an interrupt you did not mark as retryable.
Reject a call to real sleep, a random source, or the wall clock inside the wrapper, even if the tests still pass.
Reject an elapsed check that counts only the planned delay and ignores time already spent inside the operation.
Reject a first-wait formula that doubles too early, so the first failure sleeps twice the configured base delay.
Reject a test edit that deletes the empty-sleep assertion or widens the retryable tuple to the base exception type.
Reject a new dependency when the standard library already compiles and runs both files on a clean interpreter.

You paste the failed assertion back to the assistant instead of asking it to try harder without evidence. That habit keeps the case study short enough to finish in one sitting, even if the first draft is wrong. It also keeps a small remote runner useful, because the feedback is a unittest name rather than a screenshot or a log dump. You stop when the five tests pass and the diff still matches the table, not when the draft adds extra features.

A practical drafting workflow

You can implement the module by hand, and that remains a valid ending if you never call an assistant at all. When you do want a draft, you keep the assistant on a short leash and you follow the order below. The order is the method, and skipping ahead to a finished client is how the open-ended sleep loop returns.

What you hand the assistant

You paste the decision table and the unittest file, and you withhold the reference module so the draft cannot copy it.
You ask for one dependency-free implementation that satisfies the tests and does not call the real sleep function.
You diff that draft against the frozen rules before you run it, and you discard edits that invent new policy.
You run the unittest command, then you reject any change that weakens an assertion merely to obtain a pass.
You keep the table in the review notes so the next generated tweak has the same fence as the first.

Where a free drafting setup fits

MonkeyCode's free model access fits the drafting step, because you can request the patch without a paid seat for this exercise. Disclosure: This article was prepared as part of MonkeyCode's product outreach. The free server option fits the unittest step, because that same command can judge the patch on a clean Python process. You should confirm current access terms on the project page before you depend on them for anything beyond this exercise.

This article states no model names, token quotas, hardware shapes, or permanent limits, since those details change and were not verified here. You still review the diff yourself, and you still discard a green run that came from a weakened test. A free runner does not make the table optional, and a fluent draft does not outrank a failed assertion. If the current free access is unavailable, you run the same command on any local Python 3 interpreter and the case still holds.

Results you should expect

If you run the files as written, the expected result is a local pass of the five tests in this case study. The attempt-cap test shows one sleep between two tries, and then a budget error instead of a third call. The elapsed-cap test shows a budget error with an empty sleep list when the scripted clock is already at 950 milliseconds. The clamp check shows a third-failure delay of 150 milliseconds rather than the unclamped value of 400 milliseconds.

These checks describe the contract, not throughput, hosting cost, or the behavior of any live inventory service. They also do not prove that a particular model will draft a correct patch, because that outcome depends on the prompt and the review. You should record a failure as a failed assertion name, not as a story about the assistant being careless or clever. When the command prints five successful tests, you have reproduced the case study, and you do not need further metrics.

Limitations

This wrapper is single-process and single-threaded, and it does not cancel a call that has already started. It does not share a budget across workers, and it does not add jitter to spread out a thundering herd. It also does not make the following write idempotent, so a successful retry can still double-apply a non-idempotent update. The injected clock must move forward in milliseconds, because a backward jump can mask an elapsed-cap failure.

You should not use this module for card charges, device control, or any loop where a wrong retry is irreversible. You should not ask a model to invent the caps from a vague prompt that only says to make the client resilient. If you cannot fill the decision table with real numbers, you are not ready to generate the loop at all. Teams that need cross-host coordination should write a shared limiter with its own contract, not a longer copy of this file.

Lessons

You get a worker that fails visibly when the stop rule is data you can assert in a test name. You get a calmer review when the table is small enough to read without a meeting or a design document. You get portable checks when sleep and time are arguments, which is why a modest remote process can host them. The product note is optional to the lesson, because the module, the table, and the command still stand if you delete it.

If you lack a local interpreter this week, you can rehearse the same two-file case on a free coding setup. MonkeyCode's free model access and free server are enough for that rehearsal, provided you still keep the table as the fence. Merge only the diff that preserves the five tests, and leave every other generated convenience out of the branch. That is the whole invitation: try the workflow on the exercise above, not a claim that a tool replaces the contract.

Case Study: A Three-Line Cart Priced in Minor Units, Not Floats

Dakota Liu — Fri, 09 Oct 2026 14:53:55 +0000

You should lock currency scale, rounding mode, and step order before a coding agent touches invoice math. A three-line cart can look correct in a demo and still miss the ledger by one cent after tax. This case study builds a small pricing helper, a decision table, and tests you can rerun without a shared database. You can remove every tool name later and the contract, the code, and the checks still stand on their own.

Background

Your checkout charges a card and then renders a PDF invoice that finance reconciles against the ledger the next morning. The cart in this study has one 19.99 line, a quantity of three, a ten percent discount, and an 8.25 percent tax rate. An unlabeled float draft can return success and still disagree with minor-unit pricing of that same cart. That drift is the bug you freeze out of the prompt, rather than a bug you hope a later review will catch.

The carts below are a constructed example for you to rerun, not a customer incident and not a published benchmark. You should treat every total in this article as an assertion you can recompute, not as a metric from a live store. If your own rate or step order differs, you change the frozen rule before you change the code. The point is the sequence of decisions, not a claim that this helper already runs in production.

Why the draft is the risky part

Agent drafts are now a normal way to get a first implementation, which is useful only after the money policy is already written down. A trending demo can show a total on screen and still hide the cent that finance will dispute during reconciliation tomorrow morning. You apply that caution to a cart you can recompute by hand, instead of to a demo whose total you cannot audit.

Goal

You want a pure function that prices one cart in integer minor units and fails closed when the currency scale is unknown. You want the discount applied to the net, then tax applied to the discounted net, with rounding after each step. You do not want a tax jurisdiction engine, a payment capture client, or a claim that generated code is already reviewed. Success is a green local test run, plus the same file passing on a disposable server you can delete the same day.

Contract you freeze first

Before you prompt, you write the pricing rules into the repository so the agent cannot invent a friendlier policy. The rules below are a product choice for this helper, not a claim about every accounting standard in the world. You keep them short so a reviewer can reject a diff that violates one line without rereading the model output. A chat transcript is not the contract, because the next session will not scroll back to the sentence you liked.

Five rules

Represent money as integer minor units at the boundary, and use decimal quantization only inside the helper.
USD uses scale 2, JPY uses scale 0, and KWD uses scale 3; any other code raises UnknownCurrency.
Round half up after the line extension, after the discount, and after the tax, and never only at the end.
Reject an empty cart, a non-integer quantity, a quantity below one, and any rate below zero or above one.
Return net, discount, tax, and total as minor-unit integers so a renderer cannot reintroduce binary floats.

Sample numbers you pin

You also freeze the sample numbers so a passing test cannot quietly change the fixture to match a wrong implementation. The expected USD total for the sample cart is 5842 minor units, which is 58.42 after the rules above. If an agent returns 58.41 or 58.43, the test fails, and you do not rewrite the assertion to match the draft. That refusal is the point of freezing the contract before any implementation is allowed to exist.

Worked arithmetic for the sample cart

The line extension is 19.99 times three, which is 59.97 dollars, or 5997 minor units, before any discount is applied. Ten percent of 59.97 is 5.997, and half-up rounding at scale 2 makes the discount 6.00, or 600 minor units. Tax is 8.25 percent of the remaining 53.97, which is 4.452525, and half-up rounding at scale 2 makes tax 4.45. Adding 53.97 and 4.45 yields 58.42, so the fixture asserts 5842 and fails if a draft returns either neighboring cent.

Implementation

You keep the helper in one module so the agent has a narrow place to write and you have a narrow place to review. The scale table is explicit, and an unknown currency raises before any multiplication can hide the mistake inside a total. Rates are parsed as decimals, and a rate below zero or above one raises InvalidRate instead of clamping to a convenient value. Line extensions are quantized before they enter the net, which stops a later step from inheriting an extra fraction.

Save this as invoice_total.py next to the test file:

from decimal import Decimal, ROUND_HALF_UP, localcontext
from dataclasses import dataclass


SCALES = {"USD": 2, "JPY": 0, "KWD": 3}


class UnknownCurrency(ValueError):
    pass


class InvalidRate(ValueError):
    pass


class InvalidQuantity(ValueError):
    pass


def _quantizer(currency):
    try:
        scale = SCALES[currency]
    except KeyError as exc:
        raise UnknownCurrency(currency) from exc
    return Decimal("1").scaleb(-scale)


def _quantize(amount, currency):
    with localcontext() as ctx:
        ctx.rounding = ROUND_HALF_UP
        return amount.quantize(_quantizer(currency))


def parse_rate(raw):
    rate = Decimal(raw)
    if rate < 0 or rate > 1:
        raise InvalidRate(raw)
    return rate


@dataclass(frozen=True)
class Line:
    unit_price: str
    quantity: int


@dataclass(frozen=True)
class Cart:
    currency: str
    lines: tuple
    discount_rate: str
    tax_rate: str


def invoice_total(cart):
    if not cart.lines:
        raise ValueError("empty cart")
    net = Decimal("0")
    for line in cart.lines:
        if isinstance(line.quantity, bool) or not isinstance(line.quantity, int):
            raise InvalidQuantity(str(line.quantity))
        if line.quantity < 1:
            raise InvalidQuantity(str(line.quantity))
        unit = _quantize(Decimal(line.unit_price), cart.currency)
        net += _quantize(unit * line.quantity, cart.currency)
    discount = _quantize(net * parse_rate(cart.discount_rate), cart.currency)
    taxable = _quantize(net - discount, cart.currency)
    tax = _quantize(taxable * parse_rate(cart.tax_rate), cart.currency)
    total = _quantize(taxable + tax, cart.currency)
    return {
        "currency": cart.currency,
        "net_minor": _minor(net, cart.currency),
        "discount_minor": _minor(discount, cart.currency),
        "tax_minor": _minor(tax, cart.currency),
        "total_minor": _minor(total, cart.currency),
    }


def _minor(amount, currency):
    scale = SCALES[currency]
    shifted = amount * (Decimal(10) ** scale)
    return int(shifted.to_integral_value(rounding=ROUND_HALF_UP))

You should treat the listing as a reproducible example, not as a record of a production incident or a measured outage. Read the quantize calls before you trust the function, because a missing quantize is how the one-cent drift returns. If your finance partner wants half-even rounding, you change the frozen rule and the fixtures together in one review. You do not let an agent swap the rounding mode in a drive-by refactor while it is cleaning up the file.

A float expression you do not promote

A one-shot float expression is not this contract, because it skips the per-step quantize that the rules require. You may print that expression while learning, but you must not paste its output into the fixture as a convenience. If the printed float total differs, that difference is a reason to keep the decimal path, not a tie to split. Leave the comparison in a comment or a scratch cell so it cannot become an accidental second source of truth.

# Scratch only. Not the contract, and not an assertion.
print(round(19.99 * 3 * 0.9 * 1.0825, 2))

Test plan

You pin the USD sample, a JPY zero-scale cart, an unknown currency, and a negative discount that must not be clamped. You also pin the half-up boundary, because a later edit can switch rounding and still pass the happy-path cart. The commands below assume an activated virtual environment and pytest, and they do not call a network or a payment provider. Run them locally first so a later server run is a confirmation, not your only source of truth.

python -m venv .venv
python -m pip install pytest
python -m pytest test_invoice_total.py -q

You commit the tests before you ask for an implementation, so a green run cannot be manufactured by editing the expected total. If the import path differs on your machine, you change the import in the test, not the expected minor units. Keep both files in the same directory for this example so pytest can import the helper without a package install. Put the decision table in that same change so a reviewer sees the policy and the checker together.

Save this as test_invoice_total.py:

from decimal import Decimal

import pytest

from invoice_total import (
    Cart,
    InvalidQuantity,
    InvalidRate,
    Line,
    UnknownCurrency,
    _quantize,
    invoice_total,
)


def test_usd_sample_cart_is_5842_minor():
    cart = Cart(
        currency="USD",
        lines=(Line("19.99", 3),),
        discount_rate="0.10",
        tax_rate="0.0825",
    )
    assert invoice_total(cart) == {
        "currency": "USD",
        "net_minor": 5997,
        "discount_minor": 600,
        "tax_minor": 445,
        "total_minor": 5842,
    }


def test_jpy_zero_scale_tax():
    cart = Cart("JPY", (Line("1000", 1),), "0", "0.10")
    got = invoice_total(cart)
    assert got["tax_minor"] == 100
    assert got["total_minor"] == 1100


def test_unknown_currency_fails_closed():
    cart = Cart("BHD", (Line("1.000", 1),), "0", "0")
    with pytest.raises(UnknownCurrency):
        invoice_total(cart)


def test_negative_discount_is_rejected():
    cart = Cart("USD", (Line("10.00", 1),), "-0.01", "0")
    with pytest.raises(InvalidRate):
        invoice_total(cart)


def test_rate_above_one_is_rejected():
    cart = Cart("USD", (Line("10.00", 1),), "0", "1.01")
    with pytest.raises(InvalidRate):
        invoice_total(cart)


def test_empty_cart_is_rejected():
    with pytest.raises(ValueError):
        invoice_total(Cart("USD", (), "0", "0"))


def test_zero_quantity_is_rejected():
    cart = Cart("USD", (Line("10.00", 0),), "0", "0")
    with pytest.raises(InvalidQuantity):
        invoice_total(cart)


def test_half_up_boundary_on_usd_and_kwd():
    assert _quantize(Decimal("1.005"), "USD") == Decimal("1.01")
    assert _quantize(Decimal("1.004"), "USD") == Decimal("1.00")
    assert _quantize(Decimal("1.2345"), "KWD") == Decimal("1.235")

Decision table

You paste a decision table into the pull request so the reviewer checks policy, not only whether the file compiles. A green test with a rewritten fixture is a failed review, even when the agent explains the change with confidence. You keep the table next to the code, because a chat log is not something the next teammate will reliably find. The rows below match the tests, and you should update a row only when finance changes the written rule.

Case	Frozen behavior	Why it is here
USD sample cart	total_minor is 5842	Pins step order and half-up
JPY 1000, 10 percent tax, no discount	tax_minor is 100 and total_minor is 1100	Scale 0 must not invent cents
Currency BHD	UnknownCurrency	Unknown scale fails closed
discount_rate -0.01	InvalidRate	No silent clamp
tax_rate 1.01	InvalidRate	A rate above one is not a bonus
Empty lines	ValueError	Zero is not a valid invoice here
Quantity 0	InvalidQuantity	A free line is not a silent skip
Unit price 1.005 USD	Quantizes to 1.01	Half-up boundary stays explicit
Amount 1.2345 KWD	Quantizes to 1.235	Scale 3 is represented, not guessed

Repeatable review workflow

You repeat the same five steps whenever an agent is allowed to touch this helper, including a second session next week. The order matters, because a prompt written before the tests exist invites the model to choose both the policy and the proof. A disposable server is only step four, and it runs the file you already trusted on your laptop. You merge only after a person reads the diff against the five rules, not after the tool reports a clean run.

Commit the rules, a stub that raises NotImplementedError, and the tests that pin 5842 for the sample cart.
Prompt for an implementation that must not edit the tests, the scale table, or the expected minor units.
Run pytest in the local virtual environment and stop if the failure is a changed assertion rather than bad code.
Run that same pytest command on the free server option when you want a second machine that you can discard.
Read the diff for unknown scales, float literals, and any rounding call that is not half up at each step.

Where free model access fits

You can ask MonkeyCode's free model access for the draft, and you do that only after the rules and fixtures are committed. Disclosure: This article was prepared as part of MonkeyCode's product outreach. The free server option matters when you want the same pytest file executed away from a shared continuous-integration runner. Neither option supplies the rounding policy, the sample total, or a reason to skip reading the diff.

Your prompt should quote the five rules and ask for code that makes the existing tests pass without editing them. You reject any draft that adds a currency by guessing its scale, even when the guess matches a public reference you trust. You also reject a draft that switches to floats for simplicity, because that is the failure this study is built to prevent. If the tool cannot see your repository, you paste the contract into the prompt and you still review the patch yourself.

Results you can actually claim

This example is not a production billing migration, so you should not quote it as an uptime, revenue, or accuracy study. What you can verify is narrower and fully local: the USD fixture expects 5842 and the JPY fixture expects 1100. Unknown currencies must raise, and a negative rate must raise, which you can see by running the two rejection tests. If an assertion fails, you fix the implementation or you revise the frozen rule, and you do not average the two totals.

Limitations and who should skip this

This helper is the wrong tool when tax depends on address, product class, or a jurisdiction service you have not integrated. You should not use it for foreign-exchange conversion, because no rate source and no timestamp rule are frozen here. Teams that need an audited ledger, cash rounding to five cents, or tax-inclusive prices should not adopt this step order. Free model access and a free server option can change, and this article states no quota, hardware profile, or permanence promise.

You should not point an agent at a live payment database and ask it to backfill historical totals with this function. A backfill needs its own idempotency and reconciliation plan, which is outside this cart helper on purpose. If you cannot name the currency scale, you are not ready to automate the total, with or without a model in the loop. Skip the workflow when the only goal is a demo screenshot, because the tests are the product rather than the plot.

Lessons learned

The useful lesson is that invoice math fails at policy boundaries, not at the moment a function finally returns a number. You save review time by forbidding unknown scales, rather than by asking an agent to explain a confident but wrong cent. A second run on another machine confirms execution, and it does not replace the fixture you froze in git. Keep the decision table in the repository so the next session starts from the contract instead of from scrollback.

What you do next

If your money rules already live in the repository, rehearse the draft on free model access before anyone touches a ledger. A free server is enough for that second pytest run, and you should still merge only after a human reads the diff. Start from the contract in this case study, then replace the sample cart with one your finance partner has already signed.

Case Study: Freeze Leaderboard Tie-Breaks Before an Agent Writes the Ranker

Dakota Liu — Thu, 08 Oct 2026 10:22:26 +0000

You should freeze leaderboard tie-break rules as executable checks before any coding agent writes the ranking function. A polished draft can still reorder equal scores in ways your support replies never promised to players. This case study follows one small ranker from a written contract, through tests, to a review gate you can rerun. The conclusion you can keep is narrow: the tests define the order, and the agent does not.

Background you can recognize

You are shipping a public leaderboard for a small practice game that already stores one score row per player. Players compare screenshots, so the same two scores must produce the same order on every request. Your support notes will quote that order when someone asks why one name sits above another name. An agent can fill the function quickly, yet it still needs a rule you were willing to defend last week.

This week's public listings still spend visible attention on generated interfaces and on fast personal sites. That trend is useful surrounding context, but it does not decide how your leaderboard should break a tie. You can enjoy a fast generated draft and still owe players a stable order when two scores match exactly. The rest of this case study is the small project that makes that promised order executable and reviewable.

Goal of this small project

Your goal is a deterministic ranker that rejects incomplete rows instead of guessing a friendly order. You want the rule in a contract module, the examples in a test module, and the handler kept deliberately thin. You also want those checks to run in a clean environment, not only inside an editor session that hides local state. You are not measuring model speed, host capacity, or any contest outcome anywhere in this write-up.

Rules you freeze before prompting

Write the ranking rules in plain language before you paste a prompt into any coding assistant. A higher integer score always wins, and a missing score never outranks a row that stores a number. When two scores are equal, the earlier achieved_at value wins, and that value must include an explicit offset. When those timestamps also match, the smaller player_id string wins under ordinary Unicode code-point ordering.

What each case must do

Complete rows that carry different scores sort by score descending, and the timestamp is not consulted.
Complete rows that share one score sort by the earlier offset-aware timestamp, and then by player_id.
A missing player_id, a missing score, or a naive timestamp raises ValueError before any list returns.
The handler may shape JSON for clients, but it must not invent a second ordering rule of its own.

Decision table you keep beside the code

Input situation	Score key	Time key	Id key	Expected result
Different scores	negative score	ignored	ignored	higher score first
Tied scores, different times	equal	achieved_at ascending	unused	earlier time first
Tied scores and times	equal	equal	player_id ascending	smaller id first
Missing field or naive time	not built	not built	not built	ValueError, no list

You read this table before you accept a generated diff, because a green helper can still skip a required row. The negative score inside the key is only a sort trick so Python's ascending order matches your product order. The table remains the contract, and that trick is replaceable whenever the same tests still pass unchanged. If a later change needs another column, you update the table and the tests together in one commit.

Contract code you commit first

The listings below are an unexecuted example you can reproduce, not a log from a finished production deployment. You can copy the module into ranker.py and treat every raised error as part of the public behavior. You should not add hidden sort fields, such as signup date, unless the decision table already names them. If you prefer another language later, keep the same four outcomes and do not loosen those failures.

from dataclasses import dataclass
from datetime import datetime
from typing import Iterable

@dataclass(frozen=True)
class ScoreRow:
    player_id: str
    score: int
    achieved_at: datetime

def sort_key(row: ScoreRow):
    if not isinstance(row.player_id, str) or not row.player_id:
        raise ValueError("player_id required")
    if not isinstance(row.score, int) or isinstance(row.score, bool):
        raise ValueError("score required")
    if row.achieved_at.tzinfo is None or row.achieved_at.utcoffset() is None:
        raise ValueError("achieved_at requires an offset")
    return (-row.score, row.achieved_at, row.player_id)

def rank_rows(rows: Iterable[ScoreRow]) -> list[ScoreRow]:
    return sorted(rows, key=sort_key)

Tests that reject a creative reorder

You write these tests before you ask for an implementation, and you commit them while the function is still unfinished. The fixture uses offset-aware timestamps so a naive datetime cannot sneak through as a quiet pass. You should keep the test names stable, because a review comment can cite the test instead of a chat log. After these tests exist, an implementation is acceptable only when this file remains untouched by the draft.

from datetime import datetime, timezone
import pytest
from ranker import ScoreRow, rank_rows

UTC = timezone.utc
EARLIER = datetime(2026, 10, 1, 12, 0, tzinfo=UTC)
LATER = datetime(2026, 10, 2, 12, 0, tzinfo=UTC)

def test_higher_score_wins_over_earlier_time():
    rows = [
        ScoreRow("ada", 10, EARLIER),
        ScoreRow("bea", 12, LATER),
    ]
    assert [row.player_id for row in rank_rows(rows)] == ["bea", "ada"]

def test_tie_prefers_earlier_timestamp_then_id():
    rows = [
        ScoreRow("cara", 10, LATER),
        ScoreRow("bea", 10, EARLIER),
        ScoreRow("ada", 10, EARLIER),
    ]
    assert [row.player_id for row in rank_rows(rows)] == ["ada", "bea", "cara"]

def test_naive_timestamp_fails_closed():
    naive = datetime(2026, 10, 1, 12, 0)
    with pytest.raises(ValueError, match="offset"):
        rank_rows([ScoreRow("ada", 10, naive)])

def test_bool_score_is_not_an_int_score():
    with pytest.raises(ValueError, match="score"):
        rank_rows([ScoreRow("ada", True, EARLIER)])

You run the module from a clean virtual environment so a global plugin cannot hide an import error. You expect four passed tests, and you treat a skipped test as a failed review rather than a partial success. If the third test fails, you inspect timezone handling before you change the sort key or the fixtures. If the fourth test fails, you remember that bool subclasses int, so a bare isinstance check is not enough.

python -m venv .venv
. .venv/bin/activate
python -m pip install pytest
python -m pytest tests/test_ranker.py -q

python - <<'PY'
from datetime import datetime, timezone
from ranker import ScoreRow, rank_rows
utc = timezone.utc
rows = [
    ScoreRow("cara", 10, datetime(2026, 10, 2, 12, tzinfo=utc)),
    ScoreRow("ada", 10, datetime(2026, 10, 1, 12, tzinfo=utc)),
    ScoreRow("bea", 11, datetime(2026, 10, 3, 12, tzinfo=utc)),
]
print([row.player_id for row in rank_rows(rows)])
PY

You run that heredoc in bash, and on another shell you save the same lines as a file named check_order.py before you execute it. You should see bea, then ada, then cara, because the higher score outranks the tie and the earlier time selects ada. If you see cara before ada, the timestamp key is reversed and the second test should already be failing. You keep this driver out of production paths, because it is only a visibility check for the same frozen rule.

Implementation sequence

You create the repository layout with ranker.py, a tests directory, and the decision table stored in the README.
You commit the tests first, and you leave the ranker unfinished until those four outcomes are expressed clearly.
You ask for a draft that edits ranker.py alone, and you rerun pytest before you open the generated diff.
You merge only when the test file hash is unchanged and the handler does not sort the rows a second time.

Where a drafting tool fits this gate

A free model session is useful here only as a drafting surface for the unfinished ranker, after the contract is already in git. A free server option is useful when you want the same pytest command on a clean box you did not configure by hand. Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode is the open-source project this case study names when you want that optional drafting pass.

Free model access and a free server option are the only availability claims this article is willing to rely on. You should confirm the current terms yourself, and you should ignore any quota or hardware figure this page never states. The ranker, the table, and the tests remain useful if you delete every product name and draft the function yourself.

Thin handler you add only after green tests

import json
from ranker import rank_rows

def leaderboard_payload(rows):
    ranked = rank_rows(rows)
    body = {
        "order": "score_desc_then_time_asc_then_id_asc",
        "entries": [
            {
                "rank": index + 1,
                "player_id": row.player_id,
                "score": row.score,
                "achieved_at": row.achieved_at.isoformat(),
            }
            for index, row in enumerate(ranked)
        ],
    }
    return json.dumps(body)

You add this wrapper only after the four tests pass, because a pretty payload can disguise a wrong order. The order string is a client label, not a second parser, so you keep it identical to the table heading. You do not sort again inside the comprehension, because a second sort is how silent disagreements return. If you expose this over HTTP later, you map ValueError to a client error and you log only the exception type.

Results you may report

You may report that the four tests encode the table, and that a passing run matches those fixtures exactly. You may not report a production error rate, a retention change, or a comparison against another assistant. This article includes no timed benchmark, server size, or token budget, so you should not invent those figures later. A passing local run is a review result for this fixture set, not proof about every future score row.

Lessons from the gate

The first lesson is that tie-breaks are product copy, so you freeze them before you enjoy a fast draft. The second lesson is that Python's bool subclass can smuggle a false score past a careless integer check. The third lesson is that timezone-naive timestamps feel convenient in tests and then disagree across machines. The fourth lesson is that an edited test is a contract change, even when the summary says the bug is fixed.

Limits you should say out loud

This ranker does not handle pagination, cheating flags, or ties that appear only after display rounding.
Equal timestamps across players are uncommon, but the id key keeps the API from depending on dict order.
A free drafting session can still leak sample data if you paste real emails, tokens, or private user ids.
Free model access and a free server can change, and this case study does not promise either one will last.

Who should not use this approach

You should skip this approach when real ordering depends on secret anti-cheat signals you must not place in a prompt. You should also skip it when a lawyer, not a test file, must define a prize ladder or a regional contest rule. You should skip it if nobody on your team will read the diff before merge, because tests do not replace that reading. You should skip any launch plan that assumes today's free access will still exist unchanged on your release day.

A closing check before you merge

Before you merge, you rerun the four tests on the edited commit and you confirm the test file hash stayed unchanged. You glance at the decision table, and you check that the handler only calls rank_rows before it builds JSON. You keep sample rows fictional, and you keep live credentials out of both the prompt and the server environment. If you want the same contract-first pass, read the current MonkeyCode docs before you try the free options.

Case Study: An Outbox Worker That Refuses Sent Without an Explicit Ack

Dakota Liu — Thu, 08 Oct 2026 07:56:06 +0000

Case Study: An Outbox Worker That Refuses Sent Without an Explicit Ack

You should lock the outbox delivery contract in executable tests before you ask any coding agent to draft the worker. A worker that marks a row sent before the downstream acknowledgment will drop customer messages on the floor. A worker that retries permanent failures will burn the queue and hide a bug under a retry metric. The tests below encode those two refusals, so a generated implementation either passes them or stays out of the branch.

Background

Your notification path already inserts a pending outbox row in the same database transaction as the business change. The missing piece is a worker that claims those rows, calls a downstream transport, and records a terminal state. An agent can draft that loop quickly, but the dangerous lines are the ones that update status after a partial failure. Generated workers often treat any HTTP response as success, and they often retry a client error as if it were a timeout.

The project in this case is deliberately small, with one table, one worker function, and one in-memory transport fake. You are not designing a multi-region broker, and you are not claiming exactly-once delivery across unreliable networks. You are freezing the local state machine so a later agent edit cannot silently widen the meaning of sent. The same pattern can fit other agent-written edges, but this write-up stays on the outbox so the rules stay checkable.

Goal

You want four outcomes that a later reviewer can check without reading a model transcript or a chat log. The worker may mark a row sent only after the transport returns an explicit acceptance token from the contract. A transient failure must return the row to pending until the configured attempt budget is fully spent. A permanent failure, or any unknown status, must land in dead and must not be retried by the next claim.

The claim step must not treat an already sent row as fresh available work for another worker pass. Those four outcomes are the contract, and the implementation may change only when the tests change with them. The model you choose can change as well, but a weakened assertion should fail review before it fails a customer. You should treat a green run as a gate for human review, not as proof that production traffic is already safe.

The contract you freeze first

Closed vocabulary

Write the closed vocabulary in a small module before you open an agent session or paste a prompt. Keep the result set tiny so an unknown string cannot fall through a default branch into success. The function below is a teaching artifact, and you should run it locally before you treat it as a gate. You can widen the accepted set later, but only with a reviewed change to this function and its tests.

# outbox_contract.py
# Teaching artifact. Run it yourself; this draft does not claim an execution log.

PENDING = "pending"
INFLIGHT = "inflight"
SENT = "sent"
DEAD = "dead"

TRANSIENT = "transient"
PERMANENT = "permanent"
ACCEPTED = "accepted"
MAX_ATTEMPTS = 5

def decide(state, attempts, transport_result):
    """Return the next state. Unknown results fail closed."""
    if state != INFLIGHT:
        raise ValueError("decide() only accepts an inflight claim")
    if transport_result == ACCEPTED:
        return SENT
    if transport_result == PERMANENT or attempts >= MAX_ATTEMPTS:
        return DEAD
    if transport_result == TRANSIENT:
        return PENDING
    return DEAD

The fail-closed return is the point of the function, not a decorative else branch you can delete. A new transport code, a timeout wrapper that returns None, or a model that invents ok must not become sent. You should not let that widening happen inside a generated worker that nobody has diffed line by line. If the business later accepts another code, add the string in the contract and add a test that names it.

Decision table

Read the table as the same contract in review form, not as optional color beside the code. Treat a blank cell as a bug in the spec rather than as freedom for the worker. Every row either names a next state or raises, so a generated worker has no silent default. You should update this table in the same commit as the function when a real transport adds a code.

Current state	Transport result	Attempts	Next state
inflight	accepted	below max	sent
inflight	transient	below max	pending
inflight	transient	at max	dead
inflight	permanent	any	dead
inflight	any other value	any	dead
not inflight	any	any	raise

Tests that define the case

The tests are the artifact you keep, and they do not need a live queue or a reachable network. Label them as the specification for this example, because this write-up does not claim a production execution. Run them yourself before you trust a generated file, and stop if the run depends on a chat window. A prompt that authorizes weaker assertions will erase the protection this case study is trying to hold.

# test_outbox_contract.py
import pytest
from outbox_contract import (
    ACCEPTED, DEAD, INFLIGHT, PENDING, PERMANENT, SENT, TRANSIENT, decide,
)
from worker import MemoryStore, deliver_one

def test_ack_required_before_sent():
    assert decide(INFLIGHT, 1, ACCEPTED) == SENT

def test_transient_returns_to_pending():
    assert decide(INFLIGHT, 1, TRANSIENT) == PENDING

def test_budget_exhaustion_is_dead():
    assert decide(INFLIGHT, 5, TRANSIENT) == DEAD

def test_permanent_is_dead_immediately():
    assert decide(INFLIGHT, 1, PERMANENT) == DEAD

def test_unknown_result_fails_closed():
    assert decide(INFLIGHT, 1, "ok") == DEAD
    assert decide(INFLIGHT, 1, None) == DEAD

def test_sent_is_not_a_claim_input():
    with pytest.raises(ValueError):
        decide(SENT, 1, ACCEPTED)

def test_timeout_never_marks_sent():
    store = MemoryStore({
        "id": 1,
        "state": PENDING,
        "attempts": 0,
        "payload": {"kind": "welcome"},
    })

    class Boom:
        def send(self, payload):
            raise TimeoutError("slow")

    nxt = deliver_one(store, Boom(), now=0)
    assert nxt == PENDING
    assert SENT not in store.writes

python -m pytest test_outbox_contract.py -q

You should see seven passed tests before you ask any agent for a replacement implementation of the worker. If a test fails, fix the contract in review rather than prompting the model to edit the assertion. The command above uses a normal Python interpreter so the gate stays outside the drafting session entirely.

What a red run means

A red unknown-result test means some path still treats a friendly string as acceptance, and that path is not ready to merge. A red timeout test means the worker wrote sent, or skipped the contract, when the transport raised instead of acknowledging. A red permanent test means a client error will be claimed again, which is how a poison row eats the worker. You fix the code or you revise the named rule, and you do not delete the assertion to calm a generator.

Implementation boundary

After the contract tests are green, you can ask an agent to write the worker against that function only. Give it the signature, and forbid it from classifying transport results with strings it invented alone. The worker may claim a pending row, call the transport, and then call decide with the mapped result. It may not assign a sent status from a boolean, a status code, or a comment the model added.

# worker.py
# Proposal: keep status changes inside decide(). Not a measured production worker.

from outbox_contract import INFLIGHT, PENDING, decide

TRANSIENT = "transient"
PERMANENT = "permanent"

def deliver_one(store, transport, now):
    row = store.claim_pending(now)
    if row is None:
        return None
    try:
        result = transport.send(row["payload"])
    except TimeoutError:
        result = TRANSIENT
    except Exception:
        result = PERMANENT
    nxt = decide(row["state"], row["attempts"], result)
    store.transition(row["id"], nxt, now)
    return nxt

class MemoryStore:
    def __init__(self, row):
        self.row = dict(row)
        self.writes = []

    def claim_pending(self, now):
        if self.row["state"] != PENDING:
            return None
        self.row["state"] = INFLIGHT
        self.row["attempts"] += 1
        return self.row

    def transition(self, row_id, nxt, now):
        self.writes.append(nxt)
        self.row["state"] = nxt

That sketch is a proposal for the boundary, not a measured worker from a production on-call review. The broad exception handler is a limitation you should narrow once you know the real client library. It is still safer than marking the row sent inside the except block, which is the bug this case catches. You should keep the store fake in the same review, because it records transitions the pure function never sees.

Pair that fake with a transport that raises, and assert the write list matches the contract for that attempt count. A generated worker that writes sent on the exception path will fail this assertion even if the unit tests were skipped. Keep both layers, because the pure function stops bad classification and the fake stops a bypass. A review that only reads the model summary will miss a direct status write hiding under a helper name.

Where a free drafting setup fits

You can draft the worker with a coding agent you already know how to review, then run the same pytest file. Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode's free model access fits this step as a way to draft the worker against tests you already froze. The free server option fits as a clean place to rerun that pytest gate away from your laptop state.

Confirm the current terms before you rely on either option, because availability language goes stale quickly. This article does not state quotas, hardware, model names, duration, or any promise that the offer stays fixed. Use the session for a narrow diff rather than a broad request to build an outbox platform from scratch. Paste the contract, paste the tests, and ask for a worker that calls decide rather than inventing status strings.

Reject any patch that edits the tests so a weaker worker can go green without a reviewed reason. The drafting help does not change the merge rule, and you still need to understand every status write. If you use a second environment, run the identical pytest command there and compare the summary with your laptop. A mismatch means the example is not reproducible yet, so you fix imports and versions before judging any model.

Do not treat a remote green run as a benchmark, and do not publish a latency number you did not measure. A clean rerun only shows that this teaching gate still passes, which is the only result this case claims. You should save the pytest summary beside the diff so a later reader can see the gate without rerunning your prompt. That habit matters more than which editor or model produced the first patch you are reading.

Results you can actually claim

This case does not report production delivery rates, and it does not report a score for any coding model. The result is the gate itself, expressed as named tests a teammate can rerun on a clean checkout. A correct worker passes the contract tests and the exception-path assertion on the memory store. A worker that marks sent before acknowledgment fails the ack test or the store assertion that watches writes.

A worker that retries a permanent failure fails the test that expects dead on the first permanent result. A worker that treats an unknown code as success fails the test that maps that code to dead. You should paste those pass and fail names into the pull request, because they are evidence someone else can rerun. You should not replace them with a sentence that says the agent handled edge cases, since that sentence is not inspectable.

The case is done when a reviewer can check out the branch, run the pytest command, and see the same refusals. Until that rerun exists, you have a proposal and a set of assertions, not a finished operational result. That distinction matters if someone later asks what you measured, because the honest answer is the test names. Keep the write-up boring on purpose, so the next reader trusts the gate more than the narrative around it.

Lessons

You freeze the state names and the fail-closed default before you invite an agent to write the delivery loop.
You keep every status assignment inside one function so a generated edit has a single obvious place to violate.
You treat unknown transport results as dead, then widen that set only through a reviewed test that names the code.
You may rerun the gate on a free server, but a remote pass never replaces reading the status writes yourself.

The lesson that transfers is smaller than any claim that coding agents should own your production queues. You use an agent only after the failure you fear is already a red test on the branch. That order is what keeps a fast draft from becoming an unreviewable change in customer-visible delivery. If the red test is missing, the draft can look complete while the dangerous assignment sits in a helper.

Review checklist

Use this list on the pull request so the case study ends in checks rather than in an impression. A reviewer should be able to tick each line without opening the chat that drafted the worker. If a line cannot be ticked, the branch is not done, even when the model summary sounds confident. Keep the list next to the test names so the narrative cannot drift away from the gate.

You confirm the contract module contains no path that returns sent for an unknown or empty result.
You run the tests locally and attach the pytest summary to the pull request before anyone reviews prose.
You inspect the worker diff and reject any literal sent assignment that sits outside decide entirely.
You rerun the same command in a clean environment when you used one, and you reconcile every mismatch before merge.

Who should not use this approach

You should skip this sketch when a reviewed broker client already owns acknowledgment and retry policy for you. You should also skip it when the real requirement is cross-region exactly-once delivery across several writers. A single-table outbox does not prove that property, and pretending otherwise will mislead the next on-call reader. You should not use a free drafting path as a substitute for secret handling, migration review, or a runbook.

The example stores no credentials and sends no real messages, so it is a poor place to practice production access. Teams that cannot block a branch on pytest, or that merge generated files without reading status writes, will not benefit. The tests help only when a failing run can stop the merge and force a human to name the broken rule. If your process treats a green chat reply as approval, fix that process before you add another model session.

Limitations

The contract ignores lease expiry, so two workers can claim one row unless the store uses a conditional update. The clock is only an argument, and this write-up does not simulate skew, pauses, or a restarted process. The broad exception mapping is intentionally crude, and you should replace it with the errors your client actually raises. These tests are a teaching specification, and this article does not claim they ran against a named production database.

Free model access and a free server option can change, so you verify the offer on the day you depend on it. None of those limits remove the core rule that a row becomes sent only after explicit acceptance from the contract. If you adapt the table names, keep the assertions and change the adapter rather than loosening the expected states. If a later agent proposes publishing to a real bus, add a duplicate-delivery test instead of deleting the fail-closed cases.

A practical next step

You can copy the two modules into a scratch repository and run the pytest command before you connect any real transport. Start with the unknown-result test if you want to see the gate reject a friendly status string. If free model access and a free server option match the way you already review drafts, use them only for that narrow loop. Leave the merge decision with a person who can explain why sent is still unreachable from an exception path.

Case Study: A License Inventory Endpoint That Fails Closed on Unknown Obligations

Dakota Liu — Thu, 24 Sep 2026 21:21:00 +0000

You should freeze license labels before a coding agent writes your release inventory endpoint, because fluent code can still invent obligations. This case study walks through one small service that reports third-party package licenses for a single repository snapshot. You will see the background, the goal, the implementation, the checks, and the lessons in that order. The useful outcome is a failing test for unknown licenses, not a longer handler that merely sounds complete.

Background

Your release checklist asks whether every direct dependency has a known license obligation before you tag a build. A coding agent can scaffold a JSON endpoint quickly, yet it often guesses when a license string is missing or ambiguous. That guess becomes a product bug if your release gate treats the generated response as an authoritative decision. You need a small written contract that fails closed before any assistant is allowed to touch the handler.

Goal

You want one inventory endpoint that reads a frozen dependency snapshot and returns a stable JSON envelope. Each package must land in exactly one class, which is permissive, weak copyleft, strong copyleft, or unknown. Unknown must fail the release gate with HTTP 422, and it must never be rewritten as permissive. The handler may be drafted later, while the classification table and the fixtures have to come first.

Contract you freeze first

You write the rules in a table so a reviewer can argue with the policy instead of arguing with generated branches. The table below is an engineering checklist for this case study, not legal advice and not a complete SPDX catalog. You should replace the sample rows with obligation labels that your own counsel has already approved.

Normalized license	Class	Release gate
MIT	permissive	allow
Apache-2.0	permissive	allow
LGPL-2.1-only	weak_copyleft	allow_with_notice
GPL-3.0-only	strong_copyleft	block
empty or unrecognized	unknown	fail_closed

You also freeze three response rules in writing before any implementation code is allowed to exist. You keep those rules next to the table so a later draft cannot quietly drop a field. You review that short rules page before you accept any generated file into the working branch.

Confirm that every snapshot package appears once in items, including packages whose license string is empty.
Confirm that an unrecognized license string never receives the permissive class or the allow gate value.
Confirm that blocked is true and the HTTP status is 422 whenever any gate is fail_closed.
Confirm that a generated diff does not delete the pure function tests in order to make the suite pass.

Implementation

The snippets in this section are a proposed workflow you can copy and run, not a log of a production deployment. You keep the classifier in a pure function so the HTTP layer cannot hide a bad label. You then wrap that function in a tiny standard-library server that a free server option can host without extra framework weight.

# inventory_rules.py
# Proposed example. Not a measured production module.

CLASSES = {
    "MIT": ("permissive", "allow"),
    "Apache-2.0": ("permissive", "allow"),
    "LGPL-2.1-only": ("weak_copyleft", "allow_with_notice"),
    "GPL-3.0-only": ("strong_copyleft", "block"),
}

def classify(name, license_name):
    key = (license_name or "").strip()
    if key not in CLASSES:
        return {
            "name": name,
            "license": key,
            "class": "unknown",
            "gate": "fail_closed",
        }
    label, gate = CLASSES[key]
    return {
        "name": name,
        "license": key,
        "class": label,
        "gate": gate,
    }

def build_report(packages):
    items = [classify(item["name"], item.get("license")) for item in packages]
    blocked = any(item["gate"] in {"block", "fail_closed"} for item in items)
    return {"blocked": blocked, "items": items}

You add a handler that refuses to soften an unknown license into a misleading success status code. The status rule is part of the contract, so you do not leave it to the model's taste. You bind the server to port 8080 only for this exercise, and you change it if that port is already taken.

# server.py
# Proposed example using only the Python standard library.
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
import json
from inventory_rules import build_report

SNAPSHOT = [
    {"name": "left-pad", "license": "MIT"},
    {"name": "widget", "license": ""},
]

class Handler(BaseHTTPRequestHandler):
    def do_GET(self):
        if self.path != "/inventory":
            self.send_error(404)
            return
        report = build_report(SNAPSHOT)
        status = 422 if report["blocked"] else 200
        body = json.dumps(report).encode()
        self.send_response(status)
        self.send_header("Content-Type", "application/json")
        self.send_header("Content-Length", str(len(body)))
        self.end_headers()
        self.wfile.write(body)

def main():
    ThreadingHTTPServer(("0.0.0.0", 8080), Handler).serve_forever()

if __name__ == "__main__":
    main()

The failure you should force first

You should deliberately run a naive classifier that substitutes MIT for a blank license, because that is the bug agents tend to introduce. The function below is an anti-pattern for this case study, and you should not ship it. You keep that anti-pattern in the repo only long enough to watch the unknown-license fixture fail.

def naive_classify(name, license_name):
    # Anti-pattern: a blank license becomes MIT. Do not ship this.
    key = (license_name or "MIT").strip() or "MIT"
    return {
        "name": name,
        "license": key,
        "class": "permissive",
        "gate": "allow",
    }

You then point the unknown-license fixture at naive_classify and expect an assertion error, not a green check. A green check on this anti-pattern means your test is weaker than the contract you already wrote. You fix the classifier until a blank input stays unknown and the recorded gate stays fail_closed.

How you brief the assistant

You give the assistant the table, the three response rules, and the failing naive test, and you withhold permission to change assertions. You ask for a classifier that imports nothing beyond the Python standard library, so the free server run stays easy to reproduce. You reject any draft that adds a default license, a silent continue, or a catch that returns HTTP 200. You rerun the three contract tests yourself before you read the rest of the generated diff.

Checks you run before you trust a draft

You write the assertions against the pure function so a generated handler cannot pass by changing the URL only. These tests describe the contract, and you should treat a failing unknown-license case as a release blocker. Run them locally first, then run the same file on whatever free server you actually have.

# test_inventory_rules.py
# Proposed checks. Execute them; do not treat this article as a test report.
from inventory_rules import build_report

def test_known_permissive_stays_allowed():
    report = build_report([{"name": "left-pad", "license": "MIT"}])
    assert report["blocked"] is False
    assert report["items"][0]["gate"] == "allow"

def test_blank_license_fails_closed():
    report = build_report([{"name": "widget", "license": ""}])
    assert report["items"][0]["class"] == "unknown"
    assert report["items"][0]["gate"] == "fail_closed"
    assert report["blocked"] is True

def test_input_package_is_never_dropped():
    report = build_report([
        {"name": "left-pad", "license": "MIT"},
        {"name": "widget", "license": "NOT-A-LICENSE"},
    ])
    names = [item["name"] for item in report["items"]]
    assert names == ["left-pad", "widget"]
    assert report["blocked"] is True

python -m pytest -q test_inventory_rules.py
python server.py
curl -sS -D - http://127.0.0.1:8080/inventory

You accept the run only when the blank license returns fail_closed and the HTTP status is 422. You reject the run if the body omits widget or if the status becomes 200 while blocked is true. Those two failures are the exact bugs this small case study is designed to catch early.

Where a free assistant and a free server fit

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

MonkeyCode is the assistant you can point at this frozen table when you want a first draft of the handler. The outreach brief describes MonkeyCode as an open-source project that also offers free model access and a free server option. This walkthrough does not name models, quotas, hardware, or a duration, because those terms can change and were not verified here as stable facts. You should read the project page and confirm the current offer before you plan a release around it.

You use free model access only after the fixtures exist, and you paste the failing test output back as the review comment. You use a free server to run pytest and the curl check away from your laptop, so a teammate can see the same 422. If either free option is unavailable, the contract and the tests still stand on any Python 3 environment you control.

If you want the same split of labor, start from the MonkeyCode project page rather than from a generated handler. Confirm that free model access and the free server option still match the notes used in this article. Run the fixture set there only when those terms still fit the constraints of your release.

Results you should record

You should record pass or fail for each fixture, not a vanity metric about how fast the draft appeared. In this proposed case, success means three unit checks pass and the live curl shows blocked true for the sample snapshot. Failure means any unknown license is classified as permissive, or the endpoint returns 200 while a gate is fail_closed. Do not publish those checks as completed results until you have actually executed them on your machine.

Who should not use this approach

You should skip this workflow if you need a lawyer's opinion rather than an engineering gate. The sample table is intentionally tiny, and it will mislead you if you treat it as a full license review. You should also skip it when your release cannot tolerate a hard 422 from the inventory route.

Skip it too if you need a capacity guarantee that the free server option does not claim. You should not adopt the assistant step if your team pastes generated handlers into production without rerunning fixtures. A free draft is optional labor, and it is never a substitute for the frozen table.

Lessons

You learned that the expensive mistake is not a missing route, but a silent rewrite of an unknown license into an allowed class. You keep that mistake visible by freezing the table, the envelope, and the status code before generation starts. You can still let an assistant draft the handler, including through free model access, as long as the fixtures remain the reviewer. A free server is only a place to repeat those checks, and it is not evidence that the legal classification was correct.

Idempotency Keys Are a Product Contract: A Case Study of an Agent-Written Export Job API

Dakota Liu — Wed, 23 Sep 2026 17:03:15 +0000

You should treat idempotency keys as a product contract, not as an implementation detail an agent can improvise. A side-effecting POST that creates export jobs will duplicate work whenever clients retry after a timeout. This case study walks a small export-job API from frozen rules through tests, a handler sketch, and explicit limits. This walkthrough is a labeled worked example rather than a production postmortem from a named company.

Background: a tiny export job API

You are adding POST /export-jobs so a client can request a CSV export of recent orders. The client will retry after network failures, and your gateway may also retry on 502 responses. If the handler is not idempotent, each retry creates another job, another worker, and another email. Coding agents are especially likely to skip this, because the happy path looks complete without replay tests.

Industry tooling now makes it cheap to generate handlers, clients, and even tool wrappers around the same route. That speed helps only when the conflict behavior is already written down in tests the agent cannot ignore. You do not need a new model announcement to see the failure; you need a frozen replay contract. The rest of this article stays on one endpoint so the rules stay specific and reviewable.

Goal

You will freeze three decisions in writing before any generated handler code touches the database. Those decisions are key lifetime, request fingerprinting, and the exact status code for a conflicting replay. The artifact is a decision table plus a pytest file an agent must satisfy before it writes the route. You should not let the model invent REST folklore while you review the pull request after the fact.

Success for this case study means a retry cannot create a second job when the fingerprint matches. Success also means a reused key with a different body is rejected without silently mutating the first job. You are not trying to invent distributed exactly-once delivery across regions, queues, and email providers. You are trying to make local POST replay boring, testable, and safe for an agent to implement.

Frozen contract

Write these rules in the repository, not in a chat transcript the next session will forget.

Header and storage rules

Clients must send an Idempotency-Key header that contains one to one hundred twenty-eight printable ASCII characters.
You store the key, a canonical request fingerprint, the first status code, and a UTC expiry timestamp.
You treat a missing key as 400 with a stable error code, not as a license to create another job.
You do not hash only the key; you hash method, path, content type, and a canonical JSON body.

Replay outcomes

Use this table as the source of truth when the agent proposes status codes.

Incoming request	Stored fingerprint	Key state	Status	Side effect
First request with valid key	none	new	202	create one job
Retry, same key and body	equal	in window	202	no new job
Retry, same key, different body	mismatch	in window	409	no new job
Same key after expiry	ignored	expired	202	create one new job
Missing or empty key	n/a	invalid	400	no job

A matching replay must return the original job identifier in the same JSON shape as the first response.
A fingerprint mismatch must not overwrite the stored response, the job owner, or the export filter set.
Expiry is an absolute UTC timestamp written at insert time, not a relative duration computed during later reads.
202 Accepted is the success code because the export remains asynchronous and the worker is a separate process.

What you deliberately refuse

You refuse implicit “same user means same key” logic, because two tabs can export two different date ranges. You refuse to reuse a key across GET and POST, because safe methods should not share a side-effect record. You refuse 200 with a queued job, because clients will assume the CSV bytes already exist in the response. You refuse to let the agent pick 429 for a key conflict, because that status invites a retry storm.

Implementation: tests first

The following pytest module is a labeled, unexecuted example you can copy into a new repository. It encodes the table above as assertions so a coding agent has a failing contract before it writes routes.

# tests/test_export_job_idempotency.py
# Labeled example: unexecuted contract tests for POST /export-jobs

import hashlib
import json
from dataclasses import dataclass
from datetime import datetime, timedelta, timezone


def canonical_fingerprint(method: str, path: str, content_type: str, body: dict) -> str:
    payload = {
        "method": method.upper(),
        "path": path,
        "content_type": content_type.split(";")[0].strip().lower(),
        "body": body,
    }
    blob = json.dumps(payload, sort_keys=True, separators=(",", ":")).encode("utf-8")
    return hashlib.sha256(blob).hexdigest()


@dataclass
class StoredReplay:
    key: str
    fingerprint: str
    job_id: str
    status: int
    expires_at: datetime


class InMemoryIdempotencyStore:
    def __init__(self):
        self._rows: dict[str, StoredReplay] = {}

    def get(self, key: str, now: datetime) -> StoredReplay | None:
        row = self._rows.get(key)
        if row is None:
            return None
        if row.expires_at <= now:
            del self._rows[key]
            return None
        return row

    def put_if_absent(self, row: StoredReplay) -> StoredReplay:
        existing = self._rows.get(row.key)
        if existing is None:
            self._rows[row.key] = row
            return row
        return existing


def create_export_job(store, key, body, now):
    if not key or len(key) > 128 or not key.isascii() or not key.isprintable():
        return 400, {"error": "invalid_idempotency_key"}

    fingerprint = canonical_fingerprint("POST", "/export-jobs", "application/json", body)
    existing = store.get(key, now)
    if existing is not None:
        if existing.fingerprint != fingerprint:
            return 409, {"error": "idempotency_key_reused", "job_id": existing.job_id}
        return existing.status, {"job_id": existing.job_id, "status": "queued"}

    job_id = f"job_{len(store._rows) + 1}"
    store.put_if_absent(
        StoredReplay(
            key=key,
            fingerprint=fingerprint,
            job_id=job_id,
            status=202,
            expires_at=now + timedelta(hours=24),
        )
    )
    return 202, {"job_id": job_id, "status": "queued"}


def test_missing_key_does_not_create_a_job():
    store = InMemoryIdempotencyStore()
    now = datetime(2026, 9, 23, tzinfo=timezone.utc)
    status, payload = create_export_job(
        store, "", {"from": "2026-09-01", "to": "2026-09-23"}, now
    )
    assert status == 400
    assert payload["error"] == "invalid_idempotency_key"
    assert store._rows == {}


def test_retry_with_same_body_reuses_job():
    store = InMemoryIdempotencyStore()
    now = datetime(2026, 9, 23, tzinfo=timezone.utc)
    body = {"from": "2026-09-01", "to": "2026-09-23"}
    s1, p1 = create_export_job(store, "export-42", body, now)
    s2, p2 = create_export_job(store, "export-42", body, now + timedelta(seconds=30))
    assert s1 == s2 == 202
    assert p1["job_id"] == p2["job_id"]
    assert len(store._rows) == 1


def test_same_key_different_body_conflicts():
    store = InMemoryIdempotencyStore()
    now = datetime(2026, 9, 23, tzinfo=timezone.utc)
    s1, p1 = create_export_job(store, "export-42", {"from": "2026-09-01"}, now)
    s2, p2 = create_export_job(store, "export-42", {"from": "2026-08-01"}, now)
    assert s1 == 202
    assert s2 == 409
    assert p2["job_id"] == p1["job_id"]
    assert len(store._rows) == 1


def test_expired_key_may_create_a_new_job():
    store = InMemoryIdempotencyStore()
    now = datetime(2026, 9, 23, tzinfo=timezone.utc)
    body = {"from": "2026-09-01"}
    s1, p1 = create_export_job(store, "export-42", body, now)
    later = now + timedelta(hours=24, seconds=1)
    s2, p2 = create_export_job(store, "export-42", body, later)
    assert s1 == 202 and s2 == 202
    assert p1["job_id"] != p2["job_id"]

Commands you can run locally

Create a virtualenv, install pytest, and run only the idempotency file before any route generator starts.

python -m venv .venv
source .venv/bin/activate
pip install pytest
pytest tests/test_export_job_idempotency.py -v

You should keep the first run red if you delete create_export_job and leave only the tests and the table. That red run is the contract, and the agent may fill the function but not renegotiate status codes. If a generated handler returns 200 or 201, you fail the suite instead of debating REST taste in review.

Handler sketch after the tests exist

The next block is a labeled sketch, not production code, and it still omits auth, authz, and persistence. It shows how the route should call the same store the tests already exercise, rather than inventing a second path.

# app/export_jobs.py
# Labeled sketch: unexecuted FastAPI-shaped wrapper around the contract above

from datetime import datetime, timezone
from fastapi import FastAPI, Header, HTTPException
from pydantic import BaseModel, Field

app = FastAPI()
STORE = InMemoryIdempotencyStore()


class ExportRequest(BaseModel):
    model_config = {"populate_by_name": True}
    date_from: str = Field(alias="from")
    date_to: str | None = Field(default=None, alias="to")


@app.post("/export-jobs")
def post_export_jobs(
    body: ExportRequest,
    idempotency_key: str | None = Header(default=None, alias="Idempotency-Key"),
):
    now = datetime.now(timezone.utc)
    status, payload = create_export_job(
        STORE,
        idempotency_key or "",
        body.model_dump(by_alias=True, exclude_none=True),
        now,
    )
    if status >= 400:
        raise HTTPException(status_code=status, detail=payload)
    return payload

You still need a unique constraint on the key column when you replace the dictionary with a real database. You still need a transaction that inserts the job row and the replay row together, or neither row. You should add a worker later; this case study stops at the admission control that prevents duplicate jobs.

Results you should expect from the suite

These results are expected assertions for the labeled example, not measured production metrics from a live system. The missing-key case returns 400 and leaves the in-memory store empty, so retries without a key still fail closed. The matching replay returns the same job_id and leaves a single stored row, which is the whole point. The mismatched body returns 409 while preserving the original job, so a confused client cannot widen the export. The expired key creates a new job, which is a product choice you must document for operators and for support.

If an agent “simplifies” fingerprinting to the key alone, test_same_key_different_body_conflicts should stay red. If an agent maps every conflict to 429, you add an assertion on the status code and reject the patch. If an agent uses local time for expiry, you keep the fixture pinned to timezone.utc so the test fails loudly.

Where a coding assistant fits

A coding assistant can still draft the handler once the pytest file is red and the table is in the repo.

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

MonkeyCode is an open-source project with free model access and a free server option you can use for this loop. You point the assistant at tests/test_export_job_idempotency.py and refuse to merge until every replay case is green.

Keep the product mention contextual: the value is the contract, and the assistant is only the typist behind it. You should paste the decision table into the prompt as immovable constraints, not as optional style suggestions. You should also forbid new status codes unless the assistant updates the table and the tests in the same change.

Limitations

This store is process-local, so two app replicas will not share replay state and can still duplicate jobs. The fingerprint uses canonical JSON, which will disagree with clients that send equivalent bodies with different key order. That is why the server must parse, then re-serialize with sorted keys, instead of hashing the raw request bytes. The example does not persist CSV files, send email, or prove that the worker itself is idempotent on job_id.

Twenty-four hours is a product choice, not a universal constant, and this article does not benchmark expiry workloads. Unicode keys are rejected by the ASCII rule, which may be too strict for some mobile clients you do not control. The sketch does not handle request bodies larger than a small filter document, and it does not stream uploads. Clock rollback on the host can resurrect expired keys; a monotonic expiry source belongs in a later hardening pass.

Who should not use this approach

Do not use this pattern for pure GET handlers, because caching and conditional requests already cover safe replay. Do not use a single in-memory dictionary if you already run multiple replicas, workers, or independently scaled API nodes. Do not copy the 409 rule if your public API already promised that reused keys always succeed and return the first body. Do not ask an agent to invent payment capture semantics from this export-job example; money movement needs a stricter ledger.

If your clients cannot send an Idempotency-Key header, you need a different dedupe strategy based on a business natural key. That alternative is a different contract, and you should write a different table instead of stretching this one.

Lessons learned

The expensive mistake is letting generated code choose conflict behavior while you only review the happy-path handler. A small export endpoint is enough to show the failure, because retries are normal and duplicate CSVs are user-visible. Write the table, write the tests, then let an assistant fill the function that the tests already constrain. If a later change needs a new status code, you update the table first so the agent cannot “simplify” the API.

Keep prompts short: attach the test file, attach the table, and name the status codes that are forbidden. Reviewers should reject fingerprints that hash raw bytes, because whitespace and key order will create false conflicts. Reviewers should also reject 429 on key reuse, because well-behaved clients will retry and amplify the original fault.

You leave the case study when the suite is green and the table is the only place status codes can change. If you want a coding agent on a free server to fill the handler, give it the failing tests first.

Case Study: Freeze Webhook Skew and Replay Rules Before an Agent Writes HMAC Verification

Dakota Liu — Tue, 22 Sep 2026 15:18:50 +0000

You should freeze clock-skew, nonce replay, and signature-base encoding before a coding agent writes HMAC webhook verification. Those three choices decide whether a delayed retry is valid or whether an attacker can replay a captured body. If you leave them implicit, the generated handler will look correct while accepting the wrong events. This case study walks through a small inbound webhook service so you can copy the freeze-first workflow.

Background: one inbound endpoint, three silent forks

Imagine you are adding POST /webhooks/provider to a tiny order-status service that already stores shipments. The provider signs each body with HMAC-SHA256 and sends a Unix timestamp plus a hex digest. Your agent can produce a verifier in one pass, and the happy-path test will pass. The trouble starts when the provider retries after four minutes, or when two workers see the same event.

Most generated handlers pick defaults you never discussed in the prompt. Some parse the timestamp as milliseconds, which rejects every real event from the provider. Others skip replay storage because the sample request used a unique body. You need those choices written down before any model emits a route.

The project in this walkthrough stays deliberately small and local. You will freeze a decision table, encode it as failing tests, and only then allow an agent to fill verify_webhook.py. You will not start from a prompt that says "implement Stripe-like webhooks" and hope library defaults match your provider.

Goal: accept late retries, refuse replays, never guess encoding

You want three outcomes that look similar in logs and become expensive when mixed. A request with a valid signature and a timestamp inside the skew window must reach the business handler exactly once. A second request with the same signature must return success without shipping the order again. A request outside the skew window, or with a mutated body, must fail closed before any database write.

Those outcomes are not coding style preferences you can bikeshed later. They are product rules about inventory movement, customer email, and provider retry storms. An agent that invents a thirty-second skew will drop the provider's legitimate five-minute retry. An agent that stores only an event id from parsed JSON will miss a replay that changes insignificant whitespace.

Label the following constants as case-study choices, not as universal vendor law. You can change the numbers, but you must change the tests in the same commit. If a reviewer cannot find the number in both places, the rule is not frozen.

Frozen rules for this case study

Timestamp header X-Webhook-Timestamp is Unix seconds, UTC, and an integer with no fraction.
Signature header X-Webhook-Signature is lowercase hex HMAC-SHA256 of the signed payload.
Signed payload is f"{timestamp}.{raw_body}" using the exact request bytes and no extra newline.
Compare digests with hmac.compare_digest, and reject closed on any parse error.
Skew window is ±300 seconds against the verifier clock, which you treat as UTC.
Replay key is SHA-256 of the signature hex, and the cache keeps it for 600 seconds.
First valid event returns HTTP 204 after side effects; a duplicate valid event returns HTTP 204 with no side effects.
Invalid signature, skew, or malformed headers return HTTP 401 and trigger no side effects.

Decision table you freeze before generation

Paste this table into the repository next to the tests, not into a slide deck. Agents follow a nearby table more reliably than a paragraph buried in a README. If a later prompt asks for "more resilient retries," you update the table first so the new behavior is explicit.

Case	Timestamp relative to verifier	Signature	Already in replay cache	HTTP	Side effects
A	+0s	Valid hex HMAC	No	204	Yes, once
B	+0s	Valid hex HMAC	Yes	204	No
C	+240s (inside ±300)	Valid hex HMAC	No	204	Yes, once
D	+301s (outside window)	Valid hex HMAC	No	401	No
E	+0s	Body mutated after signing	No	401	No
F	missing / not an integer	Valid hex HMAC	No	401	No
G	+0s	Header missing or not hex	No	401	No
H	−120s (inside window)	Valid hex HMAC	No	204	Yes, once

Case B is the one agents most often get wrong. They return 409, which makes some providers retry forever, or they return 401, which hides that the signature was actually fine. You freeze 204-without-side-effects so the provider stops and your shipment table stays unique.

Failing tests as the only contract the agent may satisfy

Create a folder that contains rules and tests, not an implementation yet. The commands below assume Python 3.12 and pytest, and they are a labeled walkthrough you run locally. They are not a claim about production traffic on anyone's cluster.

python -m venv .venv
source .venv/bin/activate
pip install pytest
mkdir -p webhook_case && cd webhook_case

# test_verify_webhook.py
# Example walkthrough tests. Adjust names if your provider uses different headers.
from __future__ import annotations

import hashlib
import hmac
import time

import pytest

from verify_webhook import ReplayCache, VerifyResult, verify_webhook

SECRET = b"case-study-secret"
SKEW = 300


def sign(ts: int, body: bytes) -> str:
    payload = f"{ts}.".encode("ascii") + body
    digest = hmac.new(SECRET, payload, hashlib.sha256).hexdigest()
    return digest


@pytest.fixture
def cache() -> ReplayCache:
    return ReplayCache(ttl_seconds=600)


def test_case_a_first_valid_event_runs_side_effects(cache: ReplayCache) -> None:
    ts = int(time.time())
    body = b'{"order_id":"ord_1","status":"shipped"}'
    result = verify_webhook(
        timestamp_header=str(ts),
        signature_header=sign(ts, body),
        raw_body=body,
        secret=SECRET,
        now=ts,
        cache=cache,
        skew_seconds=SKEW,
    )
    assert result == VerifyResult(status=204, apply_side_effects=True)


def test_case_b_duplicate_signature_is_ack_without_side_effects(cache: ReplayCache) -> None:
    ts = int(time.time())
    body = b'{"order_id":"ord_1","status":"shipped"}'
    sig = sign(ts, body)
    first = verify_webhook(str(ts), sig, body, SECRET, ts, cache, SKEW)
    second = verify_webhook(str(ts), sig, body, SECRET, ts, cache, SKEW)
    assert first.apply_side_effects is True
    assert second == VerifyResult(status=204, apply_side_effects=False)


def test_case_d_outside_skew_fails_closed(cache: ReplayCache) -> None:
    now = int(time.time())
    ts = now - 301
    body = b'{"order_id":"ord_2"}'
    result = verify_webhook(str(ts), sign(ts, body), body, SECRET, now, cache, SKEW)
    assert result == VerifyResult(status=401, apply_side_effects=False)


def test_case_e_mutated_body_fails_closed(cache: ReplayCache) -> None:
    ts = int(time.time())
    signed = b'{"order_id":"ord_3"}'
    received = b'{"order_id":"ord_3","status":"cancelled"}'
    result = verify_webhook(str(ts), sign(ts, signed), received, SECRET, ts, cache, SKEW)
    assert result == VerifyResult(status=401, apply_side_effects=False)

Notice that the tests never import a framework router. You are freezing crypto and replay behavior, not Flask versus FastAPI. After the tests fail for a missing verify_webhook module, you may let an agent write that module and nothing else.

Run the contract before any generated file exists:

pytest -q test_verify_webhook.py
# Expected on a clean tree: collection error or import error for verify_webhook

Implementation the agent is allowed to write

Keep the allowed surface tiny so the model cannot "helpfully" invent headers. The agent may create verify_webhook.py and a memory-backed ReplayCache. It may not invent a nonce header your provider does not send. It may not switch the signed payload to canonical JSON, because that would invalidate every existing test without a table change.

# verify_webhook.py
# Example implementation that satisfies the frozen table. Review before production use.
from __future__ import annotations

from dataclasses import dataclass
import hashlib
import hmac
import time
from typing import Dict


@dataclass(frozen=True)
class VerifyResult:
    status: int
    apply_side_effects: bool


class ReplayCache:
    def __init__(self, ttl_seconds: int) -> None:
        self.ttl_seconds = ttl_seconds
        self._entries: Dict[str, int] = {}

    def seen(self, key: str, now: int) -> bool:
        expires_at = self._entries.get(key)
        if expires_at is None:
            return False
        if expires_at <= now:
            del self._entries[key]
            return False
        return True

    def remember(self, key: str, now: int) -> None:
        self._entries[key] = now + self.ttl_seconds


def verify_webhook(
    timestamp_header: str,
    signature_header: str,
    raw_body: bytes,
    secret: bytes,
    now: int,
    cache: ReplayCache,
    skew_seconds: int,
) -> VerifyResult:
    try:
        timestamp = int(timestamp_header)
    except (TypeError, ValueError):
        return VerifyResult(status=401, apply_side_effects=False)

    if abs(now - timestamp) > skew_seconds:
        return VerifyResult(status=401, apply_side_effects=False)

    if not signature_header or any(c not in "0123456789abcdef" for c in signature_header):
        return VerifyResult(status=401, apply_side_effects=False)

    payload = f"{timestamp}.".encode("ascii") + raw_body
    expected = hmac.new(secret, payload, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, signature_header):
        return VerifyResult(status=401, apply_side_effects=False)

    replay_key = hashlib.sha256(signature_header.encode("ascii")).hexdigest()
    if cache.seen(replay_key, now):
        return VerifyResult(status=204, apply_side_effects=False)

    cache.remember(replay_key, now)
    return VerifyResult(status=204, apply_side_effects=True)

Run the same pytest command until it is green. If the agent loosens skew to one day "to be safe," the table and the tests should make that diff obvious in review. You are not asking the model for architecture opinions until the eight cases above stay red or green for the right reasons.

A useful extra check is a property that the signed payload uses raw bytes. Add it if your provider might send UTF-8 bodies with non-ASCII characters.

def test_raw_bytes_are_signed_not_redecoded_json(cache: ReplayCache) -> None:
    ts = int(time.time())
    body = b'{"note":"caf\xc3\xa9"}'  # UTF-8 é, not a Python str round-trip
    result = verify_webhook(str(ts), sign(ts, body), body, SECRET, ts, cache, SKEW)
    assert result.apply_side_effects is True

Where a disposable coding loop helps

When you iterate on agent-written crypto, you want a throwaway shell rather than your laptop's production credentials. Disclosure: This article was prepared as part of MonkeyCode's product outreach. If you already have a MonkeyCode workspace, its free model access and free server option can host this freeze-test-generate loop while you keep secrets off the prompt. The workflow itself does not depend on that product; any isolated runner with pytest is enough.

Results of this walkthrough

After the tests pass, you have a verifier whose retry and replay behavior is reviewable in one table. You did not measure production traffic here, and you should not treat the ±300 second window as a published benchmark. What you can reproduce is local: the eight pytest cases covering skew, replay, malformed headers, and encoding.

If you later connect a real provider, you add a captured fixture with that vendor's actual header names and test vectors. You do not ask an agent to "make it compatible" without a new failing row in the table. Compatibility without a fixture is just a guess with extra confidence.

A second result is process, not code. Reviewers can reject a pull request that changes Case B to 409 without touching the table. That is cheaper than debugging duplicate shipments after a weekend retry storm.

Limitations: who should not copy this blindly

Do not treat this snippet as a PCI, banking, or healthcare auditor's control.
Do not replace Stripe, GitHub, Slack, or similar official verification SDKs with this toy HMAC.
Do not run a process-local memory cache across several workers and call the replay window durable.
Do not let an agent add ordinary == on hex strings because it looks more readable in a tutorial.
Skip this workflow if your provider already documents a required library, header format, and test vectors you must use unchanged.
Skip it if you need millisecond timestamps, multiple rotating secrets, or signature version prefixes; freeze those as new table rows first.

The example also uses time.time() in tests that inject now. That is safe here because production code receives now as an argument. If you later read the clock inside the function, you will make skew tests flaky, and an agent will "fix" them by widening the window.

Lessons learned

Signature encoding is a product rule. Timestamp units, hex versus base64, and whether a newline is included will not be inferred reliably from a prose prompt.
Replay is not the same as business idempotency. You can ack a duplicate HMAC and still need a unique constraint on order_id plus event type.
HTTP status on duplicates trains the provider. 204 without side effects stops retries; 409 often extends them; 401 conceals that the signature was valid.
Freeze the table before the prompt. The agent is allowed to write verify_webhook.py only after pytest already describes the forks you care about.

You can reuse this shape on the next agent-written endpoint. Write the silent forks as rows, turn the rows into failing tests, and keep the generated surface small enough that a loosened default shows up as a red case instead of a quiet production incident.

Case Study: Freeze Null-Versus-Omitted Rules Before an Agent Writes PATCH

Dakota Liu — Mon, 21 Sep 2026 13:35:16 +0000

You should freeze null-versus-omitted PATCH semantics before any agent writes the handler, because those two JSON shapes are not the same operation. Missing fields mean leave the stored value unchanged, while explicit null may clear, reject, or reset, depending on the field. Agents collapse those cases into one assignment path unless you lock a decision table and failing tests first. This case study walks a small settings PATCH from frozen contract through tests, generation, and the mistakes that still appear.

Background

You already have a GET /settings payload that clients cache locally and then edit inside a form. The form submits PATCH /settings with only dirty fields, which is the usual SPA pattern rather than a full replace. That request body is not automatically RFC 7396 JSON Merge Patch, even when it looks like a partial JSON object. If an agent writes the handler from a vague prompt, it often treats {"theme": null} and {} as the same update.

You need one boring endpoint that still encodes three different field policies inside a single JSON object. Clients will omit clean fields, send null to clear or reset, and expect required strings to reject null instead of disappearing. That mix is normal product behavior, and it is also a generator trap. The rest of this walkthrough treats the trap as the project, not as a style note in a prompt.

Goal

You will freeze a four-field settings document, then refuse to merge code until the tests describe every cell. The stored document holds display_name, email_opt_in, theme, and bio, and each field carries a different policy for JSON null. Success means a generator can implement the handler, but it cannot redefine what omitted keys and JSON null mean. You are not scoring a model in this case study; you are checking whether the freeze survives generation.

Field policies you freeze before anyone writes Python:

display_name — string; omit leaves the value; null is 422; empty string is 422.
email_opt_in — boolean; omit leaves the value; null is 422; true/false replace.
theme — enum light|dark|system; omit leaves the value; null resets to system.
bio — string or null; omit leaves the value; null clears; empty string is 422.

Freeze the decision table first

You write the table in a file the agent may read but must not edit during generation. That file is the product behavior, not a comment buried inside the prompt or a chat message. Reviewers should reject pull requests that change the table and the handler together without a separate spec commit. The table below is the original artifact for this walkthrough and the source of truth for later tests.

Field	Omitted key	JSON `null`	Empty string	Valid value
`display_name`	keep	422 `null_not_allowed`	422 `empty_not_allowed`	replace
`email_opt_in`	keep	422 `null_not_allowed`	422 `type_mismatch`	replace
`theme`	keep	reset to `system`	422 `invalid_enum`	replace if enum
`bio`	keep	clear to `null`	422 `empty_not_allowed`	replace

Shared HTTP rules you also freeze before generation:

Unknown keys return 422 unknown_field, and you do not silently drop them.
Invalid JSON, or a non-object body, returns 400 malformed_json.
Concurrent updates use If-Match against an opaque version, or you return 412.
A successful PATCH returns 204, and the next GET must show the merged document.

Store that freeze in version control as a YAML fixture the tests load, not as folklore in a standup note.

# contracts/settings_patch.yaml
resource: settings
method: PATCH
omitted: keep
unknown_keys: reject
empty_string: reject
fields:
  display_name:
    type: string
    null: reject
  email_opt_in:
    type: boolean
    null: reject
  theme:
    type: enum
    values: [light, dark, system]
    null: reset
    reset_value: system
  bio:
    type: string
    null: clear

Turn the table into failing tests

You add tests that send both {} and {"theme": null} against the same stored row. If those two requests produce the same database write, the freeze is not actually enforced. You also assert error codes, not only status integers, because agents like to reuse one invalid string. Keep the store fake; the lesson is the merge policy, not Postgres.

# tests/test_patch_settings.py
import json
import pytest

from settings_app import app, reset_store, seed_settings

@pytest.fixture(autouse=True)
def _fresh_row():
    reset_store()
    seed_settings(
        {
            "display_name": "Ada",
            "email_opt_in": False,
            "theme": "dark",
            "bio": "writes API notes",
            "version": "v1",
        }
    )
    yield

def patch(body, *, etag="v1"):
    return app.handle(
        "PATCH",
        "/settings",
        headers={"If-Match": etag, "Content-Type": "application/json"},
        body=json.dumps(body),
    )

def test_empty_object_is_a_no_op():
    response = patch({})
    assert response.status == 204
    document = app.handle("GET", "/settings").json()
    assert document["theme"] == "dark"
    assert document["bio"] == "writes API notes"
    assert document["version"] != "v1"

def test_theme_null_resets_but_does_not_touch_bio():
    response = patch({"theme": None})
    assert response.status == 204
    document = app.handle("GET", "/settings").json()
    assert document["theme"] == "system"
    assert document["bio"] == "writes API notes"

def test_bio_null_clears_but_does_not_reset_theme():
    response = patch({"bio": None})
    assert response.status == 204
    document = app.handle("GET", "/settings").json()
    assert document["bio"] is None
    assert document["theme"] == "dark"

def test_display_name_null_is_rejected():
    response = patch({"display_name": None})
    assert response.status == 422
    assert response.json()["code"] == "null_not_allowed"
    document = app.handle("GET", "/settings").json()
    assert document["display_name"] == "Ada"
    assert document["version"] == "v1"

def test_unknown_key_is_rejected_without_partial_write():
    response = patch({"theme": "light", "timezone": "UTC"})
    assert response.status == 422
    assert response.json()["code"] == "unknown_field"
    document = app.handle("GET", "/settings").json()
    assert document["theme"] == "dark"

Run the suite before any generated handler exists so the failures are the specification:

python -m pytest tests/test_patch_settings.py -q
# expected: missing module, or every assertion fails closed

You should also freeze a negative parser test, because many stacks coerce null before your handler runs. If Pydantic or a similar schema uses optional fields with defaults, omitted keys and null collapse in the type layer. The contract is then untestable no matter how careful the prompt looks.

def test_parser_must_preserve_omitted_versus_null():
    omitted = app.parse_patch_body("{}")
    explicit_null = app.parse_patch_body('{"bio": null}')
    assert "bio" not in omitted.explicit_keys
    assert "bio" in explicit_null.explicit_keys
    assert explicit_null.values["bio"] is None

Generate the handler against the freeze

You now let a coding agent implement settings_app.py while the YAML file and tests stay read-only in the prompt. Disclosure: This article was prepared as part of MonkeyCode's product outreach. A constrained loop that uses MonkeyCode's free model access and free server option is enough for this lab, because the artifact that matters is the freeze, not a paid model name. You still review the diff as if a junior teammate wrote it, and you reject edits to contracts/ or tests/ unless you intended a spec change.

Proposed generation brief, labeled as an unexecuted lab prompt rather than a production run log:

Implement settings_app.py so tests/test_patch_settings.py passes.
Do not edit contracts/ or tests/.
Parse JSON so omitted keys and nulls remain distinguishable.
Unknown keys and null-not-allowed fields must not write the store.
PATCH success returns 204 and bumps version.

Commands you run locally after the agent returns a patch:

git diff --stat
git diff -- contracts tests
python -m pytest tests/test_patch_settings.py -q

If git diff shows test edits, you throw away the generation even when the suite goes green. Green tests that the agent rewrote are not evidence that the freeze held. That failure mode is how a model outgrows the oracle you thought you were using, while still looking busy and correct.

Implementation notes the agent still misses

A handler that respects the freeze has to carry explicit keys separately from values. You cannot dump a parsed model with defaults filled in and then iterate items. The sketch below is labeled as merge pseudocode, not as a framework recommendation for production services.

# settings_app.py (sketch)
ALLOWED = {"display_name", "email_opt_in", "theme", "bio"}

def apply_patch(stored, parsed):
    unknown = parsed.explicit_keys - ALLOWED
    if unknown:
        raise Problem(422, "unknown_field")

    next_row = dict(stored)
    for key in parsed.explicit_keys:
        value = parsed.values[key]
        policy = POLICY[key]
        if value is None and policy == "reject":
            raise Problem(422, "null_not_allowed")
        if value == "" and policy in {"reject_empty", "reject"}:
            raise Problem(422, "empty_not_allowed")
        if value is None and policy == "reset":
            next_row[key] = RESET_VALUE[key]
            continue
        if value is None and policy == "clear":
            next_row[key] = None
            continue
        next_row[key] = validate_type(key, value)

    next_row["version"] = bump(stored["version"])
    return next_row

Parser boundary

Watch for body.get("bio") so missing keys become Python None and clear the bio accidentally. Watch for one global JSON Merge Patch rule, which would delete display_name when the client sends null. Watch for a 200 response that reintroduces defaults the client never sent. Those three mistakes all come from erasing omitted-versus-null before the merge function runs.

Partial writes

Validate the entire explicit key set first, then clone the row, then persist once. Agents often stream writes field by field because the prompt listed fields in order. Unknown keys and rejected nulls must leave version unchanged, which is how you prove the store never saw a partial document.

def handle_patch(raw_body, etag):
    stored = load()
    if etag != stored["version"]:
        raise Problem(412, "precondition_failed")
    parsed = parse_patch_body(raw_body)  # must not apply defaults
    next_row = apply_patch(stored, parsed)
    persist(next_row)
    return Response(204)

Other diff smells you should reject during review:

Accepting unknown keys to be "forward compatible" and dropping them on write.
Weakening tests to assert status in (200, 204) so either HTTP choice passes.
Coercing theme: null into "dark" because that was yesterday's stored value.
Bumping version on a 422 path, which poisons the next If-Match from the client.

Results of the worked example

This walkthrough was not executed against production traffic, and you should not treat the following as a benchmark. In a local lab sequence, the empty-object test and the theme-null test are the pair that usually fail first. They fail because the parser erased the omitted-versus-null distinction before the merge function ran. After you freeze parse keys, the display_name null test catches the remaining RFC-7396-shaped implementation.

What you should record in the pull request is small and concrete:

Parser preserves explicit_keys for omitted versus null.
Unknown keys and rejected nulls leave version unchanged.
theme null resets; bio null clears; {} changes neither value.
Tests and contract files were not modified by the generator.

You do not need a leaderboard number to call that a useful result for a small PATCH. You need a diff you can review and a suite that still encodes the table. If the generator only restated the happy path, you learned something about the freeze, not something flattering about the model.

Limitations

This freeze is for a single-document PATCH with a handful of fields and one actor. It does not replace RFC 6902 JSON Patch, and it does not define list-append semantics for arrays. If your public API already promises RFC 7396, you must not invent per-field null policies like the theme reset above. That would be a breaking change dressed up as agent safety.

You should not use this approach when:

The resource is money movement, inventory reservation, or any write you cannot replay from tests alone.
The client cannot send explicit null because a generated SDK strips null keys.
You lack a test runner in CI, so the freeze exists only in a markdown file.
You need multi-document transactions or row-level authorization beyond a single settings row.
You are tempted to skip review because a generation pass returned a green suite.

A coding agent does not freeze HTTP semantics for you, and it does not prove the suite matches user intent. This article does not claim model names, token quotas, hardware, duration, or permanence, because those would be unverified product details.

Lessons learned

Lead with the table, then the tests, then the handler, because agents optimize for a green file more readily than for a policy they cannot see. Keep omitted and null distinguishable at the parser boundary, or every later function will lie to you. Treat generator edits to tests as a failed run, even when coverage numbers look better afterward. Use a second review pass on unknown-key handling and partial writes, since those rarely show up in happy-path prompts.

If you reuse this case study on another endpoint, change the field policies rather than copying the settings document. The value is the freeze-and-verify loop, not the theme enum or the bio column. For a small PATCH, that loop is enough work for one afternoon and too important to leave implicit in a chat transcript.

If you want to run this freeze-then-generate lab on a throwaway PATCH, MonkeyCode's free model access and free server option are a reasonable place to try the loop.

Case Study: Freeze Discount Stacking Invariants Before an Agent Writes Checkout Math

Dakota Liu — Sun, 20 Sep 2026 11:35:55 +0000

You should freeze discount stacking invariants as executable tests before an agent writes checkout math, because a prose ticket invites plausible but still-wrong combinations. Agents optimize for the unit tests you already listed, not for coupon pairs you never wrote down. This case study walks a small checkout discount engine from background through frozen rules, code, and limits. Treat the walkthrough as a local teaching example you can run, not as a production finance sign-off or a tax opinion.

Background

Checkout tickets usually say you should support percentage coupons, fixed-amount coupons, and a maximum discount cap. That sentence looks complete until two coupons share a stack group, or shipping gets discounted by accident. An agent will implement each bullet independently, then glue them with leftover-subtotal arithmetic that feels reasonable in isolation. You only discover the bug when a customer stacks a twenty percent code with a ten dollar code on a twelve dollar cart.

Quiet money bugs differ from endpoint bugs that teams freeze before generation. Search cursors, webhook replay windows, and bulk-import partial success fail in logs you can grep. Discount engines fail as extra cents, negative totals, or promotions that finance never approved. You need invariants that speak in properties, not in one happy SKU fixture copied from the ticket.

Goal

You want one pure function that takes a cart subtotal, a shipping amount, and a list of coupons, then returns an explainable breakdown. The function must refuse negative totals, round to cents once at the end, and honor mutual exclusion by stack group. You will write those invariants first as tests, then a reference implementation, then a naive implementation that resembles typical agent output from a prose ticket.

Success for this case study is not a catalog of every retailer promotion on earth. Success is a test file that fails the naive version and passes the reference version without asserting on a specific product name. You should be able to drop a new coupon into the generator and still trust the same stacking rules.

Frozen invariants

Write these rules in the repository before anyone, human or agent, opens the engine file.

Subtotal and shipping are integer cents, never floats, and both must be greater than or equal to zero.
Percentage discounts apply only to remaining discountable money after higher-priority fixed discounts.
Coupons that share a nonempty stack_group cannot both apply; keep the larger discount in cents, then break ties by coupon id.
Shipping is discountable only when a coupon sets applies_to_shipping to true.
Round half-up to integer cents exactly once per percentage product, never after every unrelated step.
total_discount cannot exceed max_discount_cents when that cap is present.
Payable total equals subtotal plus shipping minus total discount, and it cannot drop below zero.
The breakdown must list applied coupon ids in the order they reduced the payable amount.

Decision table for stacking

Read this table as a policy freeze, not as the only tests you will run. Property tests will throw random coupons at the same rules so an agent cannot memorize six rows.

Cart 5000 cents goods, 1000 shipping, 20% goods and $10 goods, different groups: both apply, discount 2000.
Cart 5000 goods, 1000 shipping, 30% goods and $10 goods, group SUMMER: keep 30% (1500), drop $10.
Cart 1200 goods, 0 shipping, 20% plus $10, different groups: both apply, payable floors at 0, discount 1200.
Cart 5000 goods, 800 shipping, 50% with applies_to_shipping=true: discount 2900 against goods plus shipping.
Cart 5000 goods, 800 shipping, 50% goods only: discount 2500, shipping stays 800.
Cart 5000 goods, 0 shipping, 90% plus cap 1000: discount 1000.

If two coupons share a group, you compare tentative discount cents against the original bases, not raw value fields. Comparing a percent 30 to a fixed 1000 without converting units is itself a spec hole. Freeze that comparison in tests so an agent cannot “fix” it by casting everything to integers and hoping.

Implementation

The code below is a worked teaching example until you run it on your machine. Paste it into a small Python package, then execute the commands in the run section. Do not treat the reference engine as ledger-certified arithmetic.

Project layout

checkout_math/
  coupons.py
  invariants_test.py
  naive_engine.py
  reference_engine.py

Shared coupon shape

from dataclasses import dataclass

@dataclass(frozen=True)
class Coupon:
    coupon_id: str
    kind: str  # "percent" or "fixed"
    value: int  # 0-100 for percent, cents for fixed
    stack_group: str = ""
    applies_to_shipping: bool = False
    priority: int = 0  # lower applies first among allowed coupons

Property tests you freeze first

# invariants_test.py
from hypothesis import given, settings, strategies as st

from coupons import Coupon
from reference_engine import apply_discounts

cent = st.integers(min_value=0, max_value=1_000_000)

def coupons_strat():
    return st.lists(
        st.builds(
            Coupon,
            coupon_id=st.text(min_size=1, max_size=8, alphabet="abcdef0123456789"),
            kind=st.sampled_from(["percent", "fixed"]),
            value=st.integers(min_value=0, max_value=100),
            stack_group=st.sampled_from(["", "SUMMER", "VIP"]),
            applies_to_shipping=st.booleans(),
            priority=st.integers(min_value=0, max_value=5),
        ),
        max_size=5,
        unique_by=lambda c: c.coupon_id,
    )

@settings(max_examples=200)
@given(subtotal=cent, shipping=cent, coupons=coupons_strat(), cap=st.one_of(st.none(), cent))
def test_payable_never_negative(subtotal, shipping, coupons, cap):
    result = apply_discounts(subtotal, shipping, coupons, max_discount_cents=cap)
    assert result.payable_cents >= 0
    assert result.total_discount_cents >= 0
    assert result.payable_cents == subtotal + shipping - result.total_discount_cents

@given(subtotal=cent, shipping=cent, coupons=coupons_strat(), cap=st.one_of(st.none(), cent))
def test_cap_and_stack_groups(subtotal, shipping, coupons, cap):
    result = apply_discounts(subtotal, shipping, coupons, max_discount_cents=cap)
    if cap is not None:
        assert result.total_discount_cents <= cap
    applied = [c for c in coupons if c.coupon_id in result.applied_ids]
    groups = [c.stack_group for c in applied if c.stack_group]
    assert len(groups) == len(set(groups))

@given(subtotal=cent, shipping=cent, coupons=coupons_strat())
def test_shipping_only_when_flagged(subtotal, shipping, coupons):
    result = apply_discounts(subtotal, shipping, coupons, max_discount_cents=None)
    if coupons and all(not c.applies_to_shipping for c in coupons):
        assert result.total_discount_cents <= subtotal

Point the first run at naive_engine.apply_discounts and confirm at least one property fails. Then point the same file at reference_engine.apply_discounts and confirm the properties hold. That import swap is the whole point of freezing tests before generation.

Naive engine that usually appears from a prose ticket

# naive_engine.py
from math import floor
from types import SimpleNamespace

def apply_discounts(subtotal, shipping, coupons, max_discount_cents=None):
    remaining = subtotal + shipping  # mixes goods and shipping immediately
    applied = []
    discount = 0
    for coupon in coupons:
        if coupon.kind == "percent":
            piece = floor(remaining * coupon.value / 100)
        else:
            piece = coupon.value
        remaining -= piece
        discount += piece
        applied.append(coupon.coupon_id)
    if remaining < 0:
        remaining = 0
    return SimpleNamespace(
        payable_cents=remaining,
        total_discount_cents=discount,
        applied_ids=applied,
    )

That function will often go green on a single twenty percent fixture. Property tests should catch mixed shipping, stacked groups, ignored caps, and per-step flooring that drifts from half-up policy.

Reference engine the tests should pass

# reference_engine.py
from dataclasses import dataclass
from typing import List, Optional

from coupons import Coupon

@dataclass
class DiscountResult:
    payable_cents: int
    total_discount_cents: int
    applied_ids: List[str]

def _half_up(numer: int, denom: int) -> int:
    if denom <= 0:
        raise ValueError("denominator must be positive")
    if numer >= 0:
        return (numer + denom // 2) // denom
    return -(((-numer) + denom // 2) // denom)

def _base(coupon: Coupon, subtotal: int, shipping: int) -> int:
    return subtotal + shipping if coupon.applies_to_shipping else subtotal

def _tentative(coupon: Coupon, subtotal: int, shipping: int) -> int:
    base = _base(coupon, subtotal, shipping)
    if coupon.kind == "percent":
        if not 0 <= coupon.value <= 100:
            raise ValueError("percent out of range")
        return _half_up(base * coupon.value, 100)
    if coupon.value < 0:
        raise ValueError("fixed coupon cannot be negative")
    return min(coupon.value, base)

def apply_discounts(
    subtotal: int,
    shipping: int,
    coupons: List[Coupon],
    max_discount_cents: Optional[int] = None,
) -> DiscountResult:
    if subtotal < 0 or shipping < 0:
        raise ValueError("money inputs must be non-negative cents")

    winners: List[Coupon] = []
    by_group = {}
    for coupon in coupons:
        if not coupon.stack_group:
            winners.append(coupon)
            continue
        prior = by_group.get(coupon.stack_group)
        if prior is None:
            by_group[coupon.stack_group] = coupon
            continue
        left = _tentative(coupon, subtotal, shipping)
        right = _tentative(prior, subtotal, shipping)
        if (left, coupon.coupon_id) > (right, prior.coupon_id):
            by_group[coupon.stack_group] = coupon
    winners.extend(by_group.values())
    winners.sort(key=lambda c: (c.priority, c.coupon_id))

    goods_left = subtotal
    ship_left = shipping
    applied: List[str] = []
    raw_discount = 0

    for coupon in winners:
        piece = _tentative(coupon, goods_left, ship_left)
        if piece <= 0:
            continue
        if coupon.applies_to_shipping:
            from_goods = min(piece, goods_left)
            goods_left -= from_goods
            ship_left -= min(piece - from_goods, ship_left)
        else:
            goods_left -= min(piece, goods_left)
        raw_discount += piece
        applied.append(coupon.coupon_id)

    if max_discount_cents is not None:
        raw_discount = min(raw_discount, max_discount_cents)

    payable = subtotal + shipping - raw_discount
    if payable < 0:
        raw_discount = subtotal + shipping
        payable = 0

    return DiscountResult(
        payable_cents=payable,
        total_discount_cents=raw_discount,
        applied_ids=applied,
    )

The reference code is still a teaching sketch. You should replace the consume-goods-first rule if finance wants shipping consumed first. You should also add redemption limits and eligibility, which this function deliberately ignores.

Commands

python -m venv .venv
source .venv/bin/activate
pip install pytest hypothesis
pytest invariants_test.py -q

Run once against the naive module by changing the import, then run again against the reference module. Keep both results in the pull request so reviewers see the freeze, not only the final engine. If you skip the red run, you cannot tell whether the properties are actually sharp.

Where a free coding environment fits

You can keep this loop on a laptop, but a disposable server helps when the agent session should not touch your real checkout repo. MonkeyCode offers free model access and a free server option you can use to generate the engine against the frozen tests.

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

Give the agent the invariant file as read-only context and allow writes only under the engine module after the naive file has failed. Do not ask the model to invent stack groups, rounding, or tax behavior. Those choices belong in the test file and in a short human policy note sitting next to it.

Results you should see

When you point the properties at the naive engine, Hypothesis usually finds a same-group pair or a shipping mix within a few dozen examples. When you point them at the reference engine, the three properties above should hold for the generated ranges. You are not looking for a latency number or a conversion lift in this walkthrough. You are looking for a red-then-green story that a reviewer can replay without trusting chat output.

If a property fails on the reference engine, treat that as a spec bug in the freeze, not as a reason to weaken the assertion. Adjust the invariant in review, then regenerate the arithmetic. That order is the lesson: the test file is the product, and the engine is a draft that must survive it.

Limitations and who should not use this approach

This sketch does not handle multiple currencies, mid-request FX, sales tax, or VAT rounding modes. It also does not handle concurrent cart edits, coupon redemption counts, or customer eligibility. Hypothesis will not tell you whether a promotion is legal in a given jurisdiction, and integer cents will not save you from a wrong policy.

You should not use this as a production payments engine without finance and tax review. You should not freeze invariants only in chat history, because the next session will renegotiate them. You should not point a free shared server at secrets, customer carts, or live coupon databases. Skip the approach entirely if your discounts are a hard-coded single percentage with no stacking, because a table of two fixtures is enough.

Lessons learned

Freeze money rules as properties before an agent writes arithmetic, or the agent will pass the fixtures you remembered and fail the combinations you did not. Keep coupons as data, keep rounding in one place, and keep stack groups out of prose tickets. Compare group winners in cents, not in mixed raw values, or the freeze itself will encode a unit bug.

Use a disposable environment for generation if you want isolation from the real catalog, then copy only the engine that survived the freeze. If you run the same freeze-then-generate loop on a free server, review the invariant file as the product, and treat the generated engine as a draft.

Case Study: A Daily Digest Job That Refuses Implicit Timezones

Dakota Liu — Sat, 19 Sep 2026 09:41:36 +0000

Agents will invent a start-of-day if you leave the digest window unspecified, and that guess double-counts late events. This case study turns a vague daily-digest request into a timezone-strict calculator and a pytest suite. You run those tests before any model is allowed to write the worker that sends mail. A free coding model and a free server can draft the worker later, but they are not the source of truth.

Background

"Send each tenant a daily digest of yesterday's events" looks like a small cron job with a DATE() filter. That sentence hides three decisions: which timezone defines yesterday, whether the end bound is exclusive, and where late rows go. An unconstrained agent usually picks UTC, uses inclusive SQL between, and then backfills late events into a second mail.

You do not need a large product to see the failure mode clearly. A single America/New_York tenant and one event at 04:10 UTC already expose the bug. This worked example stays that small on purpose, so you can copy the calculator without standing up SMTP.

The project name is digest-window, and it is a labeled exercise rather than a claimed production incident. You should treat every command below as something you run locally first. You should also refuse to feed an assistant production event rows while you are still proving the window math.

Goal

You will ship a pure function that maps clock time, tenant timezone, and event time onto a window id. Missing timezones must fail closed, because a UTC default slides late-night events into the wrong digest. The worker, if an agent writes it, may only call that function and must not inline local date arithmetic.

You will keep a decision table next to the tests so reviewers can see calendar rules without reading Python. Success is a green pytest run plus a worker that imports the calculator. Success is not a polished HTML email template.

The window contract

Write the rules as data before you open a chat with any coding model. If a rule lives only in the prompt, the next generation will simplify it away. Freeze the table in git, then let tools write everything that is not the table.

Rules you freeze

Every tenant stores an IANA timezone; empty values raise MissingTimezoneError.
A digest covers the previous complete local day, not the last twenty-four hours of UTC.
The window is half-open: start_utc <= event < end_utc.
Events at or after end_utc are late_for_this_window and never silently merged.
Naive datetimes are rejected; both now and event_time must be timezone-aware.
The worker writes window_id into logs and into the email header for later audits.

Decision table

now_utc	tenant tz	event_time_utc	expected membership
`2026-03-09T12:00:00Z`	`America/New_York`	`2026-03-08T16:00:00Z`	`in_window` for `2026-03-08`
`2026-03-09T12:00:00Z`	`America/New_York`	`2026-03-09T08:00:00Z`	`late_for_this_window`
`2026-03-09T12:00:00Z`	(empty)	`2026-03-08T16:00:00Z`	`MissingTimezoneError`
`2026-03-09T06:30:00Z`	`America/New_York`	`2026-03-08T06:30:00Z`	still exclusive across the DST spring-forward

United States clocks spring forward on 8 March 2026, so that local Sunday lasts twenty-three hours. Your tests should pin that civil date so an agent cannot "fix" the window with epoch division. If a generated change deletes the DST fixture, you reject the change even when the happy-path test still passes.

Implementation

Keep the calculator in one module with no HTTP, no database, and no SMTP client. That boundary is the point of the case study, because agents love to fold date math into the worker. You review the import graph as strictly as you review the arithmetic. You should also keep Window frozen so callers cannot mutate end_utc after the query starts.

# digest_window.py
from __future__ import annotations

from dataclasses import dataclass
from datetime import date, datetime, time, timedelta
from zoneinfo import ZoneInfo


class MissingTimezoneError(ValueError):
    """Raised when a tenant has no IANA timezone."""


@dataclass(frozen=True)
class Window:
    timezone: str
    start_utc: datetime
    end_utc: datetime  # exclusive
    window_id: str


def require_timezone(tz_name: str | None) -> ZoneInfo:
    if not tz_name or not str(tz_name).strip():
        raise MissingTimezoneError("tenant timezone is required")
    return ZoneInfo(tz_name)


def window_for_local_date(tz_name: str, local_date: date) -> Window:
    tz = require_timezone(tz_name)
    start_local = datetime.combine(local_date, time.min, tzinfo=tz)
    next_local = datetime.combine(local_date + timedelta(days=1), time.min, tzinfo=tz)
    start_utc = start_local.astimezone(ZoneInfo("UTC"))
    end_utc = next_local.astimezone(ZoneInfo("UTC"))
    window_id = f"{tz_name}:{local_date.isoformat()}"
    return Window(
        timezone=tz_name,
        start_utc=start_utc,
        end_utc=end_utc,
        window_id=window_id,
    )


def membership(event_time_utc: datetime, window: Window) -> str:
    if event_time_utc.tzinfo is None:
        raise ValueError("event_time_utc must be timezone-aware")
    event = event_time_utc.astimezone(ZoneInfo("UTC"))
    if window.start_utc <= event < window.end_utc:
        return "in_window"
    if event >= window.end_utc:
        return "late_for_this_window"
    return "before_window"


def digest_window_id(now_utc: datetime, tz_name: str) -> str:
    tz = require_timezone(tz_name)
    if now_utc.tzinfo is None:
        raise ValueError("now_utc must be timezone-aware")
    local_now = now_utc.astimezone(tz)
    local_date = local_now.date() - timedelta(days=1)
    return window_for_local_date(tz_name, local_date).window_id

The half-open interval is the line that saves you from double sends. Inclusive BETWEEN queries look friendly, then emit two digests for the same midnight instant. Reject the SQL shape below in review, even if an assistant generated it with confident comments.

-- Review reject: UTC DATE() ignores tenant timezone and exclusive bounds.
SELECT *
FROM events
WHERE DATE(created_at) = DATE(UTC_TIMESTAMP() - INTERVAL 1 DAY);

Tests you run before the worker exists

Put the decision table into pytest first. An agent that arrives later has to satisfy these names, not invent friendlier ones. Pin civil dates in 2026 so the suite does not drift when you rerun it next month.

# test_digest_window.py
from datetime import date, datetime
from zoneinfo import ZoneInfo

import pytest

from digest_window import (
    MissingTimezoneError,
    digest_window_id,
    membership,
    window_for_local_date,
)

UTC = ZoneInfo("UTC")
NY = "America/New_York"


def test_previous_local_day_window_id():
    now = datetime(2026, 3, 9, 12, 0, tzinfo=UTC)
    assert digest_window_id(now, NY) == "America/New_York:2026-03-08"


def test_event_in_window():
    window = window_for_local_date(NY, date(2026, 3, 8))
    event = datetime(2026, 3, 8, 16, 0, tzinfo=UTC)
    assert membership(event, window) == "in_window"


def test_late_event_not_merged():
    window = window_for_local_date(NY, date(2026, 3, 8))
    event = datetime(2026, 3, 9, 8, 0, tzinfo=UTC)
    assert membership(event, window) == "late_for_this_window"


def test_missing_timezone_fails_closed():
    now = datetime(2026, 3, 9, 12, 0, tzinfo=UTC)
    with pytest.raises(MissingTimezoneError):
        digest_window_id(now, "")


def test_naive_event_is_rejected():
    window = window_for_local_date(NY, date(2026, 3, 8))
    with pytest.raises(ValueError):
        membership(datetime(2026, 3, 8, 16, 0), window)


def test_dst_spring_forward_exclusive_end():
    window = window_for_local_date(NY, date(2026, 3, 8))
    assert window.start_utc == datetime(2026, 3, 8, 5, 0, tzinfo=UTC)
    assert window.end_utc == datetime(2026, 3, 9, 4, 0, tzinfo=UTC)
    on_end = datetime(2026, 3, 9, 4, 0, tzinfo=UTC)
    assert membership(on_end, window) == "late_for_this_window"

Commands

python -m venv .venv
# Windows: .venv\Scripts\activate
source .venv/bin/activate
pip install pytest
pytest -q test_digest_window.py

You should see a green run before anyone generates digest_worker.py. If a model rewrites the calculator to make a new assertion pass, you revert the calculator and fail the change. The tests own the calendar; the model does not.

A worker shape that agents keep trying to skip

Paste this sketch only after the calculator tests are green. The sketch exists so the model cannot mint a second copy of the window math. Treat it as a proposed, unexecuted outline until test_digest_window.py stays green on your machine.

# Proposed worker sketch — unexecuted until test_digest_window.py stays green.
from datetime import timedelta
from zoneinfo import ZoneInfo

from digest_window import (
    MissingTimezoneError,
    digest_window_id,
    membership,
    window_for_local_date,
)


def run_digest(tenant, now_utc, fetch_events, send_mail, log):
    try:
        window_id = digest_window_id(now_utc, tenant.timezone)
    except MissingTimezoneError:
        log("skip_missing_timezone", tenant_id=tenant.id)
        return "skipped"

    local_yesterday = now_utc.astimezone(ZoneInfo(tenant.timezone)).date() - timedelta(days=1)
    window = window_for_local_date(tenant.timezone, local_yesterday)
    events = fetch_events(tenant.id, window.start_utc, window.end_utc)
    in_window = [e for e in events if membership(e.created_at, window) == "in_window"]
    late = [e for e in events if membership(e.created_at, window) == "late_for_this_window"]
    log("digest_counts", window_id=window_id, in_window=len(in_window), late=len(late))
    send_mail(tenant, window_id, in_window)
    return window_id

If the generated file imports datetime and computes date.today() itself, you throw the file away. That is a review rule, not a style preference. Late events may be logged, but they must not ride along in yesterday's mail.

Review checklist

Calculator module has no SMTP, HTTP, or ORM imports.
Tests pin 2026-03-08 in America/New_York, not date.today().
Worker imports digest_window and does not call date.today().
Logs include window_id and a late-event count.
Empty timezone fails closed before fetch_events.

Where a remote model and a free server fit

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

You can stop at the calculator and never touch an assistant. If you want help drafting the worker, an open-source coding assistant is useful only after these tests exist. MonkeyCode offers free model access and a free server option, which is enough to generate digest_worker.py and run pytest off your laptop.

Give the assistant the decision table, the calculator module, and the pytest file as the prompt. Ask it for the worker and for log lines that include window_id. Do not ask it to "just make the digest work," because that wording invites UTC defaults and inclusive SQL. Keep production events off the free server; the fixtures in this article are synthetic on purpose, and a shared runner is the wrong place for tenant mail bodies.

Results from the worked fixtures

On 2026-03-09T12:00:00Z, a New York tenant's digest id is America/New_York:2026-03-08. An event at 2026-03-08T16:00:00Z is in window, which is 11:00 local time the day before the job. An event at 2026-03-09T08:00:00Z is late, even though a UTC DATE() filter might still label it the ninth.

The empty timezone fixture raises before any query runs, and that failure is the CI result you want. A quiet UTC fallback would have been a false green on the same input. None of these outcomes are runtime benchmarks; they are contract checks you can re-run on any machine with tzdata.

For the DST row, local 8 March 2026 in New York starts at 2026-03-08T05:00:00Z and ends at 2026-03-09T04:00:00Z. The twenty-three hour length is expected, and the exclusive end still holds at 04:00 UTC. If your host tzdata cannot reproduce those two instants, you fix the image before you trust a generated worker.

Limitations

This calculator does not send email, retry SMTP, or deduplicate overlapping cron launches. It does not track political tzdata changes beyond whatever zoneinfo loads from the host. A free server image with stale tzdata can disagree with your laptop on a newly announced offset.

You should not reuse this module for sub-hour tumbling windows, fiscal calendars, or "user's current travel timezone" products. Those need a different contract, and an agent will still import this file if you do not block it. Exclusive daily windows are the only behavior under test here.

Who should not use this workflow

Skip the remote server if your fixtures contain real addresses, message bodies, or tenant identifiers. Skip agent-written workers if nobody on the team can read the timezone tests and explain the half-open bound. Skip the whole pattern if your digest is a rolling twenty-four hour window, because previous-local-day is the wrong primitive.

Lessons learned

Ambiguous time language is a spec bug, and coding models amplify it instead of inventing a careful calendar. Exclusive end bounds belong in tests, not in a comment that the next prompt will drop. A free model is a decent typist for boilerplate workers once membership rules already fail closed.

A free server is a convenient pytest runner, not a production cron host, and not a reason to skip the table. Keep the calculator human-owned even when the worker is generated. When the suite is green, you can park the worker draft on MonkeyCode's free server option and keep the calculator on your machine.

Case Study: Freeze Cursor Stability Rules Before an Agent Writes the List Endpoint

Dakota Liu — Fri, 18 Sep 2026 08:02:05 +0000

Offset pagination looks complete until concurrent inserts make a catalog list skip rows and duplicate others. You should freeze cursor stability rules, including the sort key and a unique tie-breaker, before any agent writes the list endpoint. This case study walks a small product-catalog API from that frozen contract through tests, a seek query, and a generated handler. The useful result is not prettier SQL; it is a page that stays stable when inventory changes under your readers.

Background: a twenty-product catalog that still breaks

You are shipping a tiny inventory catalog that stores sku, name, quantity, and updated_at for each product. The first agent draft uses ORDER BY name LIMIT 10 OFFSET n because that pattern appears in every tutorial. That draft passes a happy-path test that inserts twenty static rows and walks page one and page two. It fails the moment a merchant adds "Aardvark Adapter" while a buyer is still paging through names.

Offset pagination is a moving window over a live table, not a snapshot of a result set. Concurrent inserts before the current offset push later rows down, so page two skips items the buyer never saw. Concurrent deletes pull later rows up, so page two repeats items the buyer already scanned. You cannot prompt that failure away after the handler exists, because the handler already encoded the wrong contract.

Goal: freeze the page contract before any list SQL

The project goal is deliberately small and easy to review in a single pull request. You will publish GET /products with a page size of ten, a stable next-page token, and no total count. You will refuse client-supplied offsets rather than treating them as a compatibility feature. You will require that two readers who hold the same cursor, at the same committed table state, receive the same next page.

You freeze those rules in a spec file the agent is not allowed to edit. Tests import that spec instead of restating policy in comments. The implementation may change queries, encodings, and variable names as needed. It may not change sort keys, tie-breakers, null order, or error codes once those values are frozen.

Freeze order you actually run

Write the decision table for inserts, deletes, equal names, and bad cursors.
Encode tests that fail on OFFSET under a concurrent insert.
Lock the spec file in review so prompts cannot widen page size or add counts.
Allow the agent to touch only the list handler and the cursor codec.
Reject any patch that reintroduces offset, silent clamping, or query-string direction.

That order is the whole method. Code generation is step four, not step one, and the tests already know the answer.

The frozen cursor spec

Treat the following contract as source, not as comments inside generated code. If a later prompt wants page=3, you reject the prompt instead of extending the handler.

Pagination mode: keyset (seek) on (name ASC, id ASC).
Tie-breaker: id, a unique and immutable product identifier.
Page size: client may request 1..10; default 10; values above 10 become 400.
Cursor: opaque base64url of JSON {"n": name, "i": id, "d": "asc"}.
Empty catalog: 200 with items: [] and next_cursor: null.
Invalid or truncated cursor: 400 with error code invalid_cursor, never an empty page.
Unknown id in a well-formed cursor: skip forward from the sort position; do not 404.
Null names: sort last in ASC and first in DESC, and that choice is frozen.
Deletes: a product removed after the cursor was issued is omitted; the next live row is returned.
Total count: not included; adding it later is a separate spec change.

Decision table you pin in review

Situation	Required behavior	Failing shortcut
Insert with a name before the current page	Later pages must not skip already-unseen later names	`OFFSET`
Insert with a name after the cursor	Next page may include it	Undocumented snapshot-at-request
Two products with the same name	Order by `id` ascending	`ORDER BY name` only
Client sends `offset=10`	Ignore or `400`; do not query	Backward-compatible query param
Cursor decoded to `DESC` while URL says `ASC`	`400 invalid_cursor`	Trust the query string
Page size `50`	`400 page_size_out_of_range`	Silent clamp to 10
Malformed base64	`400 invalid_cursor`	Return the first page

You keep this table next to the tests so review stays mechanical. An agent that "simplifies" any row has failed the task, even if TypeScript compiles and the happy path stays green.

Tests that fail on offset pagination

Write the tests first and keep them in the repository the agent can read. The suite below is a worked example; run it in your own database before you trust the assertions.

// tests/catalog-list.contract.test.ts
// Worked example: unexecuted against your database until you wire a test harness.

import { describe, it, expect, beforeEach } from "vitest";
import { listProducts, seedProducts, insertProduct } from "../src/catalog";

describe("GET /products cursor contract", () => {
  beforeEach(async () => {
    await seedProducts([
      { id: "p01", name: "Bolt" },
      { id: "p02", name: "Clamp" },
      { id: "p03", name: "Drill" },
      { id: "p04", name: "Clamp" }, // same name, later id
    ]);
  });

  it("orders equal names by id, not by insert timing", async () => {
    const page = await listProducts({ pageSize: 10, cursor: null });
    const clamps = page.items.filter((p) => p.name === "Clamp");
    expect(clamps.map((p) => p.id)).toEqual(["p02", "p04"]);
  });

  it("does not skip a later name when an earlier name is inserted", async () => {
    const first = await listProducts({ pageSize: 2, cursor: null });
    expect(first.items.map((p) => p.id)).toEqual(["p01", "p02"]);

    await insertProduct({ id: "p00", name: "Adapter" });

    const second = await listProducts({
      pageSize: 2,
      cursor: first.next_cursor,
    });
    expect(second.items.map((p) => p.id)).toEqual(["p04", "p03"]);
  });

  it("rejects a page size above the frozen cap", async () => {
    await expect(listProducts({ pageSize: 50, cursor: null })).rejects.toMatchObject({
      code: "page_size_out_of_range",
    });
  });

  it("rejects a cursor whose direction does not match the request", async () => {
    const first = await listProducts({ pageSize: 2, cursor: null });
    await expect(
      listProducts({ pageSize: 2, cursor: first.next_cursor, direction: "desc" }),
    ).rejects.toMatchObject({ code: "invalid_cursor" });
  });
});

The second test is the whole point of this case study. Under OFFSET 2, inserting "Adapter" at the front shifts Clamp p04 and Drill p03, and page two skips p04. Under a seek cursor of (name=Clamp, id=p02), the next page still starts after that tuple. You should watch that test fail on the agent's first offset draft, then stay red until the query uses tuple comparison.

Implementation the tests will accept

Once the spec and tests are frozen, the handler is comparatively boring and should stay that way. You encode the last row of a page into an opaque cursor, then resume with a tuple comparison that includes the unique id. Direction lives inside the cursor so a caller cannot mix an ascending token with a descending query string.

// src/cursor.ts
// Worked example: proposed encoding, not a published library.

export type Direction = "asc" | "desc";

export type ProductCursor = {
  n: string | null;
  i: string;
  d: Direction;
};

export function encodeCursor(c: ProductCursor): string {
  return Buffer.from(JSON.stringify(c), "utf8").toString("base64url");
}

export function decodeCursor(token: string, expected: Direction): ProductCursor {
  let parsed: unknown;
  try {
    parsed = JSON.parse(Buffer.from(token, "base64url").toString("utf8"));
  } catch {
    throw Object.assign(new Error("invalid_cursor"), { code: "invalid_cursor" });
  }
  if (
    typeof parsed !== "object" ||
    parsed === null ||
    !("n" in parsed) ||
    !("i" in parsed) ||
    !("d" in parsed)
  ) {
    throw Object.assign(new Error("invalid_cursor"), { code: "invalid_cursor" });
  }
  const cursor = parsed as ProductCursor;
  if (cursor.d !== expected || typeof cursor.i !== "string") {
    throw Object.assign(new Error("invalid_cursor"), { code: "invalid_cursor" });
  }
  return cursor;
}

-- ASC seek; bind :name, :id, :limit from the decoded cursor.
SELECT id, name, quantity
FROM products
WHERE name IS NOT NULL
  AND (
    name > :name
    OR (name = :name AND id > :id)
  )
ORDER BY name ASC, id ASC
LIMIT :limit;

You still need a separate branch for name IS NULL if nulls sort last, because SQL null comparisons will not do that work for you. Freeze that branch in the spec rather than leaving the agent to pick a dialect default. Postgres NULLS LAST can express the rule, but only if the tests assert the actual order, not the presence of a SQL keyword.

Command you run before reviewing the patch

# Worked example: replace with your package scripts.
npx vitest run tests/catalog-list.contract.test.ts

If that file is green and OFFSET is absent from the handler, you have the smallest passing implementation this case study cares about. If the agent added COUNT(*) or a page query param, you revert those lines even when the tests still pass, because they changed the frozen contract.

Where a free coding environment fits

After the spec file and the failing tests exist, you may let a coding agent write the handler and the SQL. Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode offers free model access and a free server option, which is enough for this generate-against-tests loop on a small catalog service.

You paste the frozen spec, the decision table, and the test file. You instruct the agent to change only src/catalog.ts and to stop when the contract tests pass. You do not ask it to invent pagination policy, page size, or error codes. If it reintroduces OFFSET, the insert-during-paging test stays red, and you reject the patch.

This is ordinary test-driven work with a narrower file allowlist than most agent demos use. The free model access and free server option are just a place to run that loop without mixing policy into prompts.

Results of the worked example

When the offset draft is scored against the frozen suite, the equal-name test and the insert-during-paging test fail first. After a seek implementation lands, those two tests pass without changing seed data. The page-size and direction-mismatch tests stay valuable because agents often clamp silently or trust the query string over the cursor payload.

You should not treat a green suite as proof of production readiness for a public catalog. The example does not cover replica lag, schema migrations that rewrite ids, or locale-aware name collation. It does prove that the list contract is explicit enough to fail loudly when an agent reaches for offset pagination again.

Limitations and who should skip this approach

Keyset pagination is the wrong default for some products, and you should not force it onto every list.

You need jump-to-page or "page 17 of 40" in a UI that finance or ops already depends on.
You cannot add a unique, immutable tie-breaker, so equal sort keys remain unstable.
You must return a total count on every request and cannot afford a separate count query.
Your sort column is updated in place, for example a popularity score that moves while users page.
You are exposing an unauthenticated dump where opaque cursors still leak business order.

Cursor tokens also leak sort values unless you encrypt them. Base64url is opaque to casual readers, not a security boundary. If product names are sensitive, the frozen spec must require a server-side signed payload, which this case study does not implement. You should also avoid this loop when you do not yet know the sort key, because generating SQL before that choice is how offset drafts get merged.

Lessons learned

You should freeze the list contract as data the tests import, not as a paragraph inside a prompt. Offset pagination will keep looking correct in screenshots while skipping rows under concurrent writes. A unique tie-breaker is part of the public API, even when the cursor is opaque, because it decides which row is next. Agents are useful once those rules are already failing tests; they are a poor place to invent pagination policy.

If you want a throwaway environment for that generate-against-tests loop, try MonkeyCode's free model access and free server option on this catalog exercise.