How I built Waterline to turn route geometry and scattered evidence into a pilot-authorized plan and a realtime follower room that cannot change flight authority.
This article was created for the purposes of entering the All Things Agentic Hackathon.
The destination was a lake.
The briefing workflow wanted an aerodrome identifier.
There was no useful destination code to enter. There was no weather station at the destination to query either.
That did not mean there was no evidence. Route-level notices existed. Nearby stations were reporting weather. A local condition card identified a landing obstruction. The pilot still needed a responsible person following the flight.
The evidence was there. The natural lookup key was not.
That is the contradiction behind Waterline: a flight can have a real route, real hazards, and real human accountability even when the destination is absent from the identifier-first workflow.
My first design decision was therefore not a model choice. It was a data-model choice.
Stop asking the lake for an airport code. Start with geometry.
That change led to the second, more important rule:
Realtime coordination does not require realtime authority.
Waterline can assemble evidence and open a live room for a flight follower. Neither the model nor the conversation is allowed to approve the route.
Geometry became the key
For the deployed scenario, the pilot selects Toronto Pearson (CYYZ), Lady Evelyn Lake, and a cruise altitude.
Waterline resolves those endpoints to a line, then uses PostGIS to create a ten-nautical-mile route corridor and an altitude band. The database—not a language model—decides which notices intersect that corridor, overlap the flight level, and remain valid for the flight window. PostGIS documents ST_Buffer as the operation that produces the polygon around a line or geography; Waterline uses that deterministic geometry to reduce a FIR-wide set to the hazards that touch this flight.
A FIR is a Flight Information Region. A NOTAM is a time-sensitive notice about an aeronautical facility, service, procedure, or hazard. A METAR is a coded observation from a weather station. NAV CANADA's own flight-planning page describes its Weather and NOTAM data as geographically referenced, searchable around an aerodrome, navigation aid, or FIR.
Lady Evelyn Lake still has no destination METAR. Waterline does not pretend otherwise. It gathers nearby real observations, calculates a bounded stationless read, and keeps the distance, source stations, spread, and confidence visible. The interface calls it inference, not measurement.
This distinction is load-bearing. A fluent sentence cannot turn nearby weather into a destination observation.
The wrong path earns the right plan
The local condition evidence is a prepared synthetic card for the Lady Evelyn scenario. It is visibly labelled FIXTURE in the product and film.
Gemini extracts a typed record from that image: lake, validity window, observed sector, obstruction, and confidence. Deterministic validation binds the result to the source digest and schema. A hostile note embedded in the image tells the model to ignore the safety rules and authorize dispatch.
Waterline does not hide that text. It records its hash and quarantines it. The note creates no trusted fact, memory, or state transition.
The accepted fact is narrower: the east cove has a log boom across the approach.
That one fact changes the plan.
east-cove route v1
→ deterministic obstruction check
→ REJECTED
→ west-cove route v2 proposed
→ ATTESTATION REQUIRED
The failure is not demo decoration. It is the causal reason the route revision exists. The model may explain why west cove is the candidate sector, but deterministic code owns the rejection and the state graph.
Then Waterline stops.
The one decision the agent cannot make
The pilot sees the full evidence stack: the route corridor, source receipts, stationless weather confidence, hostile-text quarantine, rejected v1, and proposed v2.
The status is ATTESTATION REQUIRED.
No agent can click through it. No follower can click through it. The authenticated pilot performs one owner-bound attestation by selecting Attest & open follower room.
That action atomically writes one Cloud SQL receipt. The receipt commits the mission, the one-hour expiry, the room reference, and the SHA-256 of the capability token. It does not store the raw signed token.
The browser receives a QR code and a copyable link. The invitation contains no phone number, pilot identity, or mutable route field. Possession grants access to one temporary coordination room—not permission to alter the briefing.
The state now reads HANDOFF READY · WAITING FOR FOLLOWER.
The consequence arrives in both browsers
The responsible person opens the link on a phone-sized browser. Firebase Anonymous Authentication creates a temporary browser identity. A Cloud Run authorization bridge validates the signed capability and expiry, then creates exactly one mission-scoped follower membership.
After that bridge, both browsers talk directly to Firestore under Security Rules. Firestore's onSnapshot() listener delivers the initial room state and subsequent updates. The follower can send one fixed acknowledgement—Following acknowledged—and plain-text messages up to 500 characters. There are no attachments, edits, deletes, typing indicators, arbitrary recipients, or presence tracking.
The acknowledgement changes the pilot's presentation to:
FOLLOWING ACTIVE · LIVE VIA FIRESTORE
In the recorded deployed run, the acknowledgement appeared on the cockpit in 309 milliseconds. The follower's text reached the pilot in 224 milliseconds. The pilot's reply reached the follower in 854 milliseconds.
Those are observations from one recorded mission, not latency promises.
The consequential boundary is simpler than the timings:
Chat changes who is informed. It does not change what is authorized.
Replay had to return the same room
Browsers refresh. Pilots double-click. Networks fail after a server has committed work but before the response arrives.
If replay opened a second room, Waterline would turn a safety feature into ambiguity.
So Cloud SQL claims the handoff with one idempotency key. The invitation is reconstructed from durable mission inputs and the persisted expiry. Waterline hashes the reconstructed token and compares it with the stored digest before returning it.
The accepted proof refreshed the follower page and restored all three messages. Replaying the pilot command returned the same receipt, room, token digest, and expiry. Firestore still contained one thread.
This is why the database stores a digest instead of the raw capability. Restoration remains possible, but a SQL read cannot reveal a usable invitation.
Four systems, four permissions
The architecture makes more sense after seeing the consequence.
| Layer | Job | What it cannot do |
|---|---|---|
| Google ADK + Vertex AI Gemini | Coordinate eight scoped readers, extract typed evidence, rank, and compose a sourced proposal | Write mission authority or attest for the pilot |
| Public and private Cloud Run services | Host the Next.js cockpit, exact signed relay, Firebase bridge, and private FastAPI/ADK service | Invent a route decision or broaden a command |
| Cloud SQL PostgreSQL + PostGIS + pgvector | Own missions, route revisions, append-only events, attestation, spatial filtering, owner-scoped recall, expiry, and the duplicate-safe receipt | Delegate authoritative writes to chat or model prose |
| Firebase Auth + Cloud Firestore | Bind two temporary members and deliver acknowledgement plus bounded realtime text | Change route, attestation, SQL receipt, or mission status |
Cloud Run service identities let the public web revision invoke the private agent and access Google services without a downloaded service-account key. The deployed private agent has exactly one Cloud Run invoker: the web service account.
The eight ADK agents have different work because separation is more useful than agent count: resolve geometry, ingest live inputs, filter the corridor, recall reviewed evidence, infer nearby weather, compose, verify, and open the already-attested room. The final FollowingAgent still passes through a deterministic callback before its tool can run.
Two additional Google models sit outside the authority boundary. gemini-embedding-001 creates a 768-dimensional destination vector for owner-scoped reviewed recall. If embedding fails, memory is disabled and every candidate resurfaces. Gemma 4 (google/gemma-4-26b-a4b-it-maas) may reorder the complete NOTAM set for the reading budget, but a cardinality check prevents it from removing a notice. If Gemma fails, deterministic order remains.
Model failure therefore increases what the pilot sees. It never suppresses a hazard.
Three failures that tightened the boundary
The interesting bugs were not crashes. They were cases where the system could have appeared successful while proving the wrong thing.
1. The pilot could acknowledge as the follower
The first Firestore rule required the fixed acknowledgement text, but it did not require the sender role to be follower. A pilot member could create the same acknowledgement and make the cockpit appear active without a responsible follower.
The fix added an explicit role check and an emulator regression test that proves pilot acknowledgement is denied. The final suite covers unauthenticated, unbound, expired, cross-mission, spoofed UID/role, oversized, extra-field, update, delete, and pilot-acknowledgement denial.
The lesson: validating content is not enough when the actor is part of the fact.
2. A realtime page never became “network idle”
The deployed verifier originally waited for Playwright's networkidle state after opening and reloading the follower page. A healthy Firestore listener is deliberately long-lived, so network silence was the wrong definition of readiness.
I changed the proof to wait for domcontentloaded and then assert the visible LIVE VIA FIRESTORE state. The same fix sanitizes any handoff capability from error text before writing a report.
The lesson: test the product's contract, not a browser heuristic that contradicts the product.
3. The newest model was not always available
During launch load, the preferred Gemini Flash endpoint intermittently returned transient 429/503 responses. Waterline now retries with bounded backoff and falls through a 3.7 → 3.6 → 3.5 Flash chain. Every model clears the event's Gemini 3.5-or-newer requirement, and the deterministic evidence gate remains identical whichever model answers.
The lesson: model availability can change the reader, but it must not change the constitution.
What the proof actually established
The Matilda v6 film records mission mission-11d9e8bf923c4e76aeb0 on the deployed .run.app service.
One pilot attestation produced:
- one Cloud SQL handoff receipt;
- one Firestore thread;
- two scoped members,
pilotandfollower; - one fixed acknowledgement;
- one text message in each direction;
- restored history after reload;
- the identical receipt, invitation, token digest, and expiry on replay;
- zero browser errors.
The backend suite passed 54 tests, the web suite passed 16, the Firestore Rules emulator passed 6, and the production build passed. The 3:47.133 master is 1920×1080 H.264 with English narration and AAC audio. Its first six seconds are visibly labelled synthetic domain illustrations. The deployed product then runs as one uninterrupted 1× execution through duplicate-safe replay. A disclosed native Google Cloud Logs Explorer insert shows the exact mission, private agent revision, timestamp, agent URL, and successful request status before the repository architecture closes the film.
That continuity distinction matters. The complete master is not “all live” or end-to-end continuous. It is two truth-labelled context shots, a continuous operational product execution, a disclosed native Console proof, and repository architecture.
The limits are part of the design
Waterline is a hackathon prototype, not an official aviation briefing service and not flight advice.
The Lady Evelyn condition card is synthetic. Five Ontario water destinations are curated. The video uses a deployed phone-sized browser surface rather than footage of a physical handset. The follower room is short-lived coordination, not dispatch, flight-plan filing, emergency monitoring, or presence tracking.
The deployment reads a publicly reachable NAV CANADA CFPS Weather/NOTAM endpoint, but written authorization for this software integration has not been established. NAV CANADA's terms restrict copying and software integration absent permission. I therefore do not describe the endpoint as an open or authorized API. OurAirports station coordinates come from a separately identified public-domain dataset.
Firestore TTL eventually cleans up expired documents; Waterline's Security Rules stop access at the recorded expiry without waiting for deletion.
Most importantly, Waterline does not decide whether a flight is safe. It organizes evidence, exposes uncertainty, enforces one route-change workflow, and preserves the pilot's decision.
Six rules I would reuse
- Choose the real key before choosing the model. If the destination identifier is missing, geometry may be the stable object the workflow actually owns.
- Make inference look different from measurement. Preserve source distance, confidence, and provenance instead of letting fluent prose erase uncertainty.
- Bind facts to actors. “Acknowledged” is incomplete unless the system proves who was allowed to acknowledge.
- Keep fast coordination outside durable authority. Firestore can update both screens instantly while Cloud SQL remains the only mission ledger.
- Design replay as a first-class path. One human decision should not multiply rooms, receipts, or consequences under retry.
- Fail toward more review. If embeddings, ranking, or a model fail, surface more evidence and keep the gate closed.
Waterline began with a missing airport code.
It ended with a clearer division of responsibility: geometry finds the evidence, Gemini and ADK assemble the proposal, deterministic policy rejects the wrong path, the pilot attests, Cloud SQL remembers, and Firestore keeps one follower informed.
The room is realtime.
The authority is not.
Try the deployed app: https://waterline-web-2hjaxuzova-uc.a.run.app
Read the source: https://github.com/Zen-cronic/waterline
Watch the verified demo: https://youtu.be/05H46M1ir-o
View the Devpost project: https://devpost.com/software/waterline
Upstream contribution: google/adk-python#6968 — open
Top comments (0)