DEV Community: Stephen Sookra

How I built Curtail: a governed agent fleet for water curtailment, where the human always signs

Stephen Sookra — Tue, 18 Aug 2026 03:42:55 +0000

In August 2022, a water association serving about 80 ranchers ran its pumps for eight days against a standing drought curtailment order on the Shasta River. The proposed penalty came to $4,000 in total, which is $500 per day. One rancher said, on the record: "We could have kept going for $500 a day."

The statute has since moved. Water Code 1846(b), as amended effective January 1, 2025, sets the rate at $10,000 per day. But the regulation a person actually reads, 23 CCR 875.9(b), still prints $500. The published rule understates the law by a factor of twenty, and nothing in the state's tooling notices.

That gap is the product. Curtail is my entry to the Google x Devpost All Things Agentic Hackathon: a governed multi-agent system that watches a river in real time, computes who must stop diverting under California prior-appropriation priority law, and drafts the curtailment order for a named human official to sign. Nothing self-executes. This post is about how it was built, and what building it taught me about putting language models anywhere near legal text.

The first decision: what may never be an LLM

The center of the system is not an agent. The Allocation Core, the thing that decides which priority groups a curtailment must reach, is deterministic Python with golden tests and property tests. Priority ordering, decree membership, gage reading against the operative minimum, computed shortfall: these are facts, and facts do not need a temperature parameter.

Just as deliberately, the Core produces a recommendation, never a determination. The regulation (23 CCR 875(b)) assigns the determination to a human official and expressly preserves their discretion to decline, narrow, or suspend. So the codebase uses the word "recommendation" throughout, and "determination" is reserved for the signature. The signed record shows what the official actually considered, including the judgment inputs the system surfaces but refuses to auto-resolve: weather, fisheries information, voluntary contributions, groundwater evidence.

Around that core sits a four-node fleet built on Google's Agent Development Kit, running on Cloud Run: a Gage Sentinel that classifies USGS readings against date-period-bounded minimums, an Order Scribe on gemini-3.5-flash via Vertex AI that drafts the legal document, a Herald that models the four legally distinct service methods under Water Code 1121 and never reports a notification as legal service, and a Season Ledger holding the statutory clocks (reconsideration windows, response deadlines) durably in Cloud Firestore. Durability was proven the only way I trust: a second, independently constructed client read the season back after the writer was gone.

Guards, because models fabricate exactly where it hurts

Before writing any code I had six external models review the concept. Two of them cited case law that does not exist in any database. Invented authorities, with confident citations, in a legal domain. That settled the security design: a system prompt forbidding invention is not a guardrail.

So the Scribe's output passes through a deterministic, server-side citation scrubber after the model call. Any authority not present in a verified allowlist is stripped and flagged before the draft can reach the document generator, and the fabricated citations from that review ship in the repository as a CI test fixture, so the guard can never quietly stop guarding. A second layer, ledger validation, rejects any draft that asserts a right, a priority date, or a tier the deterministic Core did not compute, with one retry and then escalation to the human queue marked UNVERIFIED. Model Armor screens untrusted order text on the way in, chunked to fit its documented prompt-injection window, and an unreachable screen reports UNAVAILABLE rather than clean.

The same discipline applies to my own prose. Every number in the demo video narration, the README, and the Devpost description draws from one generated fact sheet, docs/FACTS.md, computed from the shipped code. CI fails if the file drifts from the code that produces it. A gate reads the narration script and refuses any figure, digits or spelled out, that the fact sheet cannot source. That gate caught real errors before they reached a published, uncorrectable video.

Testing against the Board's own decisions

The credibility artifact is a backtest. I fetched the State Water Board's published curtailment orders and addenda for the Scott and Shasta rivers, 98 PDFs byte-verified, 95 scorable, and replayed the gage record against them. Curtail reproduces the direction of 6 of 6 scored historical curtailment decisions, with 5 documents excluded before scoring for stated reasons (a bound is not a reading; a named-diverter scope is not a basin threshold decision). The exclusions are reported next to the result, because a denominator you cleaned in private is not a metric.

The rights tables are the Board's own attachments, not synthetic data. The Scott table carries 384 rights, and here is the finding that justifies the whole architecture: the Board's attachment states each right's curtailment group in its own column, and inferring those groups from the rights' attributes instead agrees with the Board on 8 of 384. Group 1 is curtailed first and group 8 nearly last, so that gap is the difference between a ranch irrigating and a ranch shutting off. Read the record; never re-derive what the agency already stated.

My favorite fixture is July 2025. Fort Jones read 48.7 cfs on a Sunday night and curtailment was reinstated. Community members disputed the measurement, the watermaster district ran field flows, USGS revised the rating curve, and the same water read 78.4 cfs on Tuesday morning. Curtailment lifted. The river never rose; the measurement moved. An agent system that cannot be corrected by the person responsible for it is not governed, so that sequence, human evidence flowing back into the machine's recommendation, is the demo's centerpiece, and the near-threshold band that flags "field verification recommended" exists because of it.

There is also a scored axis for restraint: five cases where the right answer is not the obvious action, including a reading inside the near-threshold band and rights the Board published without a priority date. The system refuses or withholds rather than extrapolating. Scoring that axis immediately found a real bug: the Sentinel would classify a negative discharge, which on a sensor fault reads as far below minimum and points at curtailment. That is now unrepresentable at the domain object.

Data sovereignty, concretely

One more piece worth naming: document intake runs Gemma (gemma3:4b) locally through Ollama. It reads a published Board order and returns four filing fields, each verified verbatim against the source text before acceptance, and no document leaves the machine. An agency that cannot send landowner records to a third-party inference API can host these weights itself. The model files documents; it is not permitted to read law out of them.

What I learned

Most of my defects were false greens: checks that reported success without checking. A guard scoped to tracked files cannot see the file you are about to commit. A web application firewall serves its block page as HTTP 200, so a corpus fetcher that trusts status codes downloads error pages named as PDFs. A test can assert a figure that no primary document contains, and then defend the error against correction. The pattern underneath all of them: verify the artifact, never the action that claims to have produced it. That principle is also the product thesis, which is the kind of symmetry you only notice after the third incident.

The demo video's agent section is one continuous, uncut take of the production system, including the full length of the real Gemini call, because a rules requirement ("an unedited, live execution") is also just the honest way to show an agent working.

See it

Demo (3:41): https://youtu.be/Kz5tv6oe070
Live console, no account needed: https://curtail-console-api-672785135387.us-central1.run.app
Repository (Apache-2.0): https://github.com/StephenSook/curtail

I created this piece of content for the purposes of entering the All Things Agentic Hackathon. #AllThingsAgenticHackathon

Building strongly consistent parental consent across regions with Amazon Aurora DSQL

Stephen Sookra — Mon, 22 Jun 2026 01:56:08 +0000

Disclosure: I created this article for the purpose of entering the H0 Hackathon, Hack the Zero Stack with Vercel v0 and AWS Databases.
#H0Hackathon

🔗 Live app: https://custody-zeta.vercel.app

The gap I wanted to close

When a parent revokes consent or sets a spending cap for a child on a global platform, that decision may not take effect everywhere at once.

The platform writes the change in one region, replication catches up later, and during that window, the child may still be able to play or spend money somewhere else. There is also rarely verifiable proof of exactly when the parent acted.

I built Custody, a neutral system of record for parental consent and minor spending controls, to close that gap.

With Custody, a parent can:

Grant or revoke consent
Set a spending cap
Apply the decision consistently across regions once it commits
Verify every decision through a tamper-evident audit trail

Every action becomes a link in a hash chain that can be verified directly in the browser.

All data in the demonstration is synthetic. It contains no real minors, biometrics, or personal information.

Why I chose Amazon Aurora DSQL

Custody depends on one critical property:

When a write commits, every region must agree on the result.

Amazon Aurora DSQL is an active-active, multi-region database with strong consistency on commit. It provides the property Custody needs without requiring me to build and maintain a distributed consensus layer myself.

The deployment uses:

us-east-1 as one regional endpoint
us-east-2 as the second regional endpoint
us-west-2 as the quorum witness

The witness does not expose a database endpoint. Its purpose is to help maintain agreement between the two writable regions.

One framing rule I followed throughout the project was never calling the process “instant.”

A commit requires roughly two cross-region network round trips, and an optimistic-concurrency retry may add more time. The accurate claim is that the system is strongly consistent on commit, without a replication-lag window after the commit completes.

Precision matters more than a superlative.

The data model

Custody uses append-only event tables combined with per-entity projection rows.

Aurora DSQL is PostgreSQL-compatible, but it is not traditional PostgreSQL. The application architecture must respect its specific rules.

A few important examples:

Primary keys use random UUIDs instead of SERIAL, because sequences can create hot keys.
DSQL does not support foreign keys, triggers, or stored procedures, so referential integrity is handled in the application layer.
Indexes are created with CREATE INDEX ASYNC.
A unique asynchronous index does not enforce uniqueness until its build job finishes, so migrations wait for completion through sys.jobs.

Each consent action and spending action is stored as an append-only event.

The current consent status and running spending total are stored as projection rows. Each projection is updated in the same transaction as its related event append.

These projections exist per user or per minor. Custody never relies on a single global counter row because that row would become a hot key and create cascading conflicts under load.

Preventing the hash chain from forking

The part of the data model I am most proud of is how it handles concurrent writes.

Each event table uses a composite primary key:

(user_id, seq)

Imagine two requests attempting to append an event for the same user at the same time.

Both requests:

Read the same current chain tip.
Calculate the same next sequence number.
Attempt to insert the next event.
Collide on the composite primary key.

Aurora DSQL then raises a serialization conflict at commit using SQLSTATE 40001 with error code OC000.

One transaction succeeds. The other retries, reads the new chain tip, and appends after it.

This prevents the chain from forking.

I tested this with eight concurrent append requests. The stored events returned with sequence numbers 1 through 8, with:

No gaps
No duplicate sequence numbers
Every prev_hash matching the previous event’s entry_hash

The optimistic-concurrency wrapper

Every write passes through the same retry helper.

The helper:

Retries only serialization conflicts using 40001
Uses exponential backoff with full jitter
Limits the maximum number of attempts
Retries the entire transaction, never only part of it
Does not retry normal reads, because DSQL does not conflict-check plain reads

Writes are also idempotent.

The client provides a request UUID, which is stored under a unique asynchronous index. The application uses:

INSERT ... ON CONFLICT DO NOTHING

If the same request is replayed, it becomes a no-op rather than creating a duplicate event.

The tamper-evident audit trail

Custody’s audit trail is a separate SHA-256 hash chain for each user.

Each entry_hash is calculated from:

The canonical JSON representation of the event payload
The previous event’s hash

The first event uses a genesis previous hash containing 64 zeros.

Conceptually:

entry_hash = SHA256(canonical_payload + previous_hash)

Canonical JSON is important. Custody uses deterministic canonical JSON in the JCS style: object keys are recursively sorted and formatting is stable, so two logically identical payloads always serialize to the same bytes. It is not a full RFC 8785 implementation.

Without canonicalization, two logically identical JSON objects could produce different hashes because of differences in key ordering or number formatting. That would create false tampering warnings.

The verification function recalculates every event hash and reports the exact first index where the stored chain no longer matches.

Verification runs in the browser using the Web Crypto API. A judge can modify an event block in the interface and immediately see the chain turn red starting from the first broken link.

Credential-free authentication on Vercel

There is no database password stored anywhere in Custody.

The frontend uses Next.js 16 and runs on Vercel.

At runtime:

Vercel issues an OpenID Connect token.
The application exchanges it through AWS AssumeRoleWithWebIdentity.
AWS grants access to a restricted IAM role.
The Aurora DSQL connector creates a short-lived, region-scoped authentication token.

A token created for one region only authenticates against that region’s endpoint. Because of this, the application maintains a separate connection pool for each regional endpoint.

This architecture removes the need for permanent database credentials in Vercel environment variables.

Demonstrating cross-region consistency with SSE

The cross-region demonstration uses Server-Sent Events.

Vercel does not host persistent WebSocket servers, so each region has its own SSE route that streams the latest committed state.

When a parent revokes consent:

A Next.js Server Action submits the transaction.
The transaction commits to Aurora DSQL.
Both regional streams read the new committed state.
Both region panels update.

The us-east-2 panel reads from the second Aurora DSQL endpoint. It is not a duplicated client-side animation.

What appears in the interface reflects the state returned by the two regional database endpoints.

Hardening the public demonstration

The deployed application is open for judges and other users to test, so the public database role follows the principle of least privilege.

It can:

SELECT
INSERT
UPDATE

It cannot:

DELETE
Drop tables
Run DDL
Take ownership of tables

Aurora DSQL also does not support TRUNCATE.

This gives the public application exactly what it needs: read access, append access, and permission to update projection rows. It does not have permission to wipe the database.

Mutation routes are also rate-limited with Upstash Redis, and the event ledger is append-only by construction.

What is wired into the live app

The deployed version includes:

A multi-region Aurora DSQL ledger
Strongly consistent cross-region commits
Optimistic-concurrency retries
Idempotent writes
A per-user SHA-256 hash chain
Client-side tamper verification
Credential-free Vercel OIDC authentication
Region-scoped Aurora DSQL tokens
Live cross-region state streaming with SSE
SD-JWT age-bracket selective disclosure
A least-privilege public database role

The age proof uses selective disclosure under RFC 9901. It is not a complete zero-knowledge proof, and I do not claim that it is.

Testing

Custody currently has 88 tests:

83 unit tests
5 tests that run against the live Aurora DSQL cluster

The live-cluster tests include:

Cross-region read-after-commit verification
Eight-way concurrent append testing
Hash-chain integrity checks
Idempotency verification
Optimistic-concurrency retry behavior

Technology stack

Database: Amazon Aurora DSQL, multi-region and active-active
Frontend and server: Next.js 16 and React 19
Hosting: Vercel
Authentication: Vercel OIDC and AWS IAM
Rate limiting: Upstash Redis
Audit trail: SHA-256 hash chains
Selective disclosure: SD-JWT
Live regional updates: Server-Sent Events

Try Custody

Custody demonstrates how a globally distributed application can apply parental consent and spending-control decisions consistently across regions while maintaining a verifiable audit trail.

🔗 Live app: https://custody-zeta.vercel.app

Built with Amazon Aurora DSQL and Vercel for the H0 Hackathon.

#H0Hackathon