DEV Community: Kateryna Ivashchenko

Clockwrit — every hour has a citation (an agent that knows what time it is, legally)

Kateryna Ivashchenko — Sun, 04 Oct 2026 22:07:23 +0000

This is a submission for the Sanity Challenge, Path One: Ship an Agent That Queries Real Content

What I Built

On 1 November 2026, Canada stops changing its clocks — one province at a time. British Columbia, Alberta and the Northwest Territories already went permanent this year; Manitoba follows on 31 October. IANA shipped five tzdata releases in 2026 to keep up, and for several of these changes it deliberately models the switch on 1 November at 02:00 instead of the legal date (a documented "temporary hack"). Morocco quietly went back to GMT on 20 September.

Meanwhile, the Node.js you're running ships whatever tz data it was built with. On my machine that's 2025b: 11 of 597 zones are wrong in 2026–27. Even the Vercel runtime this project is deployed on (tzdata 2026c) still puts Winnipeg an hour off. Ask a search engine whether Ukraine abolished daylight saving time and you'll get "yes" — the bill passed in 2024 and was never signed.

So I built an agent that answers what the clock and the calendar legally say at a place and moment — and on whose authority.

Clockwrit reads the law, the IANA time zone database and your runtime's own clock, and tells you which one is right — with the decree, the date and the source quote.

Ask. "A weekly call is set for Mondays 10:00 in New York. What time is it in Winnipeg on 2 November 2026, and why?" The answer comes back as cards, not prose: the local time, and four clocks side by side — the law, IANA 2026e, this server, and your browser, read live — plus every instrument the answer rests on, with its authority tier (§ primary law, † reference data, ‡ community) and its legal status.
Pending laws as Content Releases. The US Sunshine Protection Act, Ukraine's bill 4201, Florida's conditional permanent-DST law, the EU proposal and three more are modelled as Sanity Content Releases. Pick one and the agent answers as if it had passed — the same tools, reading the dataset through the release perspective.
A ruling desk. When the Knowledge Base finds two sources that disagree, the agent drafts a ruling, a person signs it, and the decision becomes a standing instruction for every future rebuild. (More below — this is the part I'm proudest of.)
A schedule auditor, a drift report, an eval page, an MCP server, a CLI and a Sanity Dashboard app.

Demo

Live: https://clockwrit.vercel.app — no login needed.

A five-minute path, if you're reviewing:

Home — the page reads your browser's tz data for 2 November and grades it against the law (landing).
Ask — try a suggested question, then switch "Answer under" to Ukraine bill 4201 and ask about Kyiv next July.
Ruling desk — draft and approve a ruling. Reviewer passcode: every-hour-has-a-citation.
Audit — a weekly meeting across five cities, every occurrence checked.
Eval — every question, every answer, every verdict.

Code

RaYYeR220 / clockwrit

What time is it, legally? An agent on Sanity Context that reads the law, IANA tzdata and your runtime's clock, and tells you which one is right.

Clockwrit

What time is it — legally? An agent that reads the law, IANA tzdata and your runtime’s clock, and tells you which one is right, with the decree, the date and the source quote. Built on Sanity Context: a typed dataset for the facts, a Knowledge Base for what the sources say, and a ruling loop for when they disagree.

Live: https://clockwrit.vercel.app · Video (3 min): https://youtu.be/pSU875tMuzw · Ask: /ask · Ruling desk: /desk · Eval: /eval · MCP: https://clockwrit.vercel.app/api/mcp · Reviewing? Start with JUDGES.md.

Why this exists

In 2026 Canada stopped changing its clocks one province at a time: British Columbia, Alberta, the Northwest Territories, then Manitoba from 31 October. IANA shipped five tzdata releases (2026a–e) to keep up, and for some of them deliberately models the change on 1 November at 02:00 — a documented “temporary hack” — while the law takes effect on another…

View on GitHub

A pnpm monorepo: a deterministic legal-time engine (packages/core, 30 tests), the Next.js app and agent (web), the Studio and schema (studio), the App SDK Dashboard app (desk), the dataset and the 90-source corpus (knowledge), the evaluation (eval) and the CLI (packages/cli). MIT.

How I Used Sanity

1. A typed dataset where every fact points at its law

The schema is the product. A ruleSegment is one zone's clock regime over one span of time — the standard offset, the DST rule written the way the law (and zic) writes it (Sun>=8 2:00 wall), validFrom/validTo as UTC instants — and a required basis[] that references the instrument it rests on. An instrument is anything that makes a claim: a statute, a decree, a bill, an IANA release, a Microsoft notice, a news article, a holiday library. Each has an authority tier (primary / secondary / community), a legal status (in force, enacted-not-effective, conditional, pending bill, proposed, vetoed…), dates, and verbatim quotes in their original language with translations.

The calendar side has holiday (with dateCertainty: fixed by law, announced, or merely calculated — Eid moves on a moon sighting), weekendRegime (the UAE moved its weekend in 2022), workdayOverride (China's adjusted working Saturdays) and holidaySuspension (Ukraine's martial law suspends holiday days off). Each jurisdiction records which years have a complete holiday list, so the agent knows when it's allowed to say "working day".

845 documents, 179 instruments (83 of them primary law), 47 zones, 58 jurisdictions. Every one of the 114 clock regimes is checked against IANA tzdata 2026e — daily and hourly around every transition, 2020–2028 — before it's loaded.

2. Content Releases as pending legislation

A release is a set of document versions that publish together. That's exactly what a bill is. Seven releases hold the clock regimes as they would read if each law took effect, and the agent's tools read the dataset with perspective: [releaseId]. Asking "what if Ukraine's bill is signed?" isn't a prompt trick — it's the same deterministic computation over a different perspective.

3. Two Sanity Context MCP endpoints

clockwrit-catalog — GROQ mode over the dataset. The agent uses groq_query and schema_explorer to find instruments, statuses and dates. The endpoint's instructions explain what authority and status mean.
clockwrit-sources — Knowledge Base mode. The agent uses knowledge_base_search / knowledge_base_read for what the sources actually say.

Both endpoints' /initial-context is inlined into the system prompt so the agent doesn't spend a tool call on orientation. Every Ask answer shows an evidence trail of the Context tool calls it made. Conversations are saved to Context Insights through @sanity/context's AI SDK integration.

The agent never states an offset or a working day from memory. Three deterministic tools — legal_time, working_day, audit_schedule — read the typed records and compute. Code decides; the model explains.

4. A Knowledge Base built from 90 real sources — in two passes

I imported the corpus in two phases, each source with a header naming its authority tier:

Phase A, the law first: statutes, proclamations, gazettes, government announcements, IANA NEWS entries.
Phase B, then the internet: the news headline that overstated a bill, the Microsoft notice with a different date, the Wikipedia line its own citation doesn't support, the holiday library that's a day off for Pakistan's Eid.

5. The ruling loop: Knowledge Base issues → instructions

When the build finds a fact the sources disagree on, it files a conflict issue with both sides and the exact quoted lines. The one that matters most: Manitoba's proclamation says 31 October; IANA 2026e says 1 November 02:00.

On the ruling desk the agent drafts a ruling — which side, why (authority, status, dates), and a cross-check against the typed records — through a forced tool call. It cannot apply it. Applying is a code path behind a gate: the reviewer passcode, or — from the Dashboard app — the reviewer's own Sanity token, accepted only if a dry-run edit of that ruling succeeds with their permissions and they administer the organisation that owns the Knowledge Base. Approval resolves the issue through the Knowledge Base API, which mints an instruction that every later build follows, and writes the ruling back to the dataset.

6. The App SDK desk

A Dashboard app lists rulings live (useDocuments, useDocumentProjection), lets an editor approve with their own identity (useAuthToken), and shows the pending laws (useActiveReleases).

Why this only works because the content is structured

I wrote 40 questions from the verified research before the agent existed, each with an answer key and a trap reason. Ten were used while building; the 30 held-out ones were run once against three arms, graded by a model from a different family:

	Correct	Traps correct
Clockwrit	30 / 30	14 / 14
Same model, no tools	22 / 30	8 / 14
Keyword search (BM25) over the same 90 sources + same model	16 / 30	6 / 14

The model alone is confidently wrong exactly where the world changed this year: it says Casablanca is UTC+1 (it isn't, since 20 September), that 01:30 on 20 September happened once there (twice), that Pakistan's Eid al-Adha was the 28th. Keyword search made it worse than no retrieval at all — 8 abstentions — because the passages that match the words rarely carry the effective date, the legal status or the instant that decides the answer. Every answer and verdict is on the eval page.

What surprised me (and what I'm not claiming)

The Knowledge Base is smarter than I planned for. My first test fed it a news headline ("Rada abolished the clock change") and the bill card ("never signed"). It didn't raise a conflict — it wrote "adopted but not in force", which is correct. Conflicts only appear when claims truly can't both be true. That's why the second import pass matters.
It doesn't rate authority on its own. Conflict sides came back with no authority tier, and in one test it rated a community source as primary. Clockwrit takes authority from the typed records instead.
A full rebuild restructures every entry. Decisions survive (issues keep a stable fingerprint, instructions persist) — the entry paths don't.
The legal date and tzdata disagree on purpose. For Manitoba and the NWT the dataset records the legal effective instant; the UTC offset is identical either way, only the DST flag and abbreviation differ.
Not claimed: global coverage (47 zones and 58 jurisdictions where something changed or is contested; elsewhere it says so), discovery of unknown facts (the eval measures whether structure gets the agent to the right answer), legal advice. The full ledger is docs/CLAIMS.md.

Sanity Project Details

Project ID: c9x90tjo — dataset production (public)
Public dataset query: every instrument with its authority and status
Studio: https://clockwrit.sanity.studio
Context MCP endpoints: clockwrit-catalog (dataset, GROQ mode), clockwrit-sources (Knowledge Base mode)

Use it from your own agent:

claude mcp add --transport http clockwrit https://clockwrit.vercel.app/api/mcp

Agent Session

No session transcript is attached to this entry.

I built an agent that reads 200-year-old handwriting — the interesting part is what it refuses to do

Kateryna Ivashchenko — Mon, 31 Aug 2026 23:48:38 +0000

The National Archives Catalog holds 34,309,409 records. Most of the handwritten material in it has never been transcribed, which means it is not full-text searchable, which means it is effectively invisible: you can only find a document if you already know it exists. The people who fix that are volunteers in the Citizen Archivist programme, typing one page at a time.

I spent a build cycle on a partner for that volunteer. Along the way I hit four things that cost me real time and that I have not seen written down anywhere, so here they are.

1. The catalog answers HTTP 200 with an HTML page when you are wrong

catalog.archives.gov exposes a full JSON API behind /proxy/*. It is unauthenticated, it works from outside the US, and it is genuinely good. But it has a failure mode that will eat an afternoon: when your request is invalid, or when you have been going too fast, it returns 200 OK with the single-page app's HTML shell. Not a 400. Not a 429. A 200, with a text/html body, 5,454 bytes every time.

So the only reliable success signal is the content type:

resp = await client.get(path, params=params)
if "application/json" not in resp.headers.get("content-type", ""):
    raise ShellResponse(...)   # retryable

Worse, limit is not a range — it is an allowlist: {1, 10, 20, 50, 75, 100, 1000, 10000}. limit=3 and limit=5 both silently return that same shell. I lost about an hour to limit=5 before I checked the content type instead of the status code.

Two more from the same afternoon: pagination is page, not offset; and transcriptions_exist=true is accepted and then ignored — it returns identical counts for true, false and a nonsense value. Scope by series with ancestorNaId instead.

2. The Gemini free tier is 20 requests per day, and retrying makes it worse

I assumed a 429 meant "slow down". It can also mean "come back tomorrow":

GenerateRequestsPerDayPerProjectPerModel-FreeTier   value: 20

Twenty requests per day, per model, per project. My evaluation harness had a perfectly sensible retry policy — six attempts, exponential backoff — and it turned a spent budget into a very spent budget, because every retry against a daily cap is another request from a bucket that is already empty.

The fix is to tell the two apart before deciding to retry:

_DAILY_MARKERS = ("perday", "per_day", "requestsperday", "free_tier", "freetier")

def _is_daily_quota(exc) -> bool:
    text = str(exc).lower().replace(" ", "").replace("-", "")
    return "429" in text and any(m in text for m in _DAILY_MARKERS)

A per-minute limit clears if you wait. A per-day limit does not, and retrying it is pure waste.

The way out, incidentally, is not a bigger free tier — it is Vertex AI, which bills through Cloud and has no daily cap of this kind. Which leads to:

3. Vertex and AI Studio are not the same API, and one model lives on only one of them

google-genai gives you one Client for both, which makes it easy to assume they are interchangeable. They are not:

Interactions API (client.interactions.create) is the current AI Studio surface and it supersedes generate_content. On Vertex it answers 400 Unsupported model interaction: gemini-3.7-flash.
So on Vertex you use generate_content with response_mime_type + response_schema — the pair that is marked deprecated on the AI Studio path in favour of response_format. Both are correct; which one is correct depends on the endpoint.
Gemma is not a Vertex publisher model. gemma-4-31b-it is a plain 404 there — on Vertex it only exists behind a Model Garden deployment you provision and pay for. The AI Studio endpoint serves it directly.

I run Gemini on Vertex and Gemma on AI Studio in the same process, which needs one more thing that is easy to miss: GOOGLE_GENAI_USE_VERTEXAI is read process-wide, so a client you construct with api_key= still routes to Vertex unless you say vertexai=False explicitly.

def client_for(model: str) -> Client:
    if model.startswith("gemma") and on_vertex():
        return Client(api_key=key, vertexai=False)   # explicit, or the env var wins
    return get_client()

4. ADK 2.8: the workflow agents are deprecated, and tool confirmation does not work in a graph

Two things changed under the tutorials.

SequentialAgent, ParallelAgent and LoopAgent are all @deprecated in 2.8, superseded by google.adk.workflow.Workflow — a real graph runtime. BaseAgent now subclasses workflow.BaseNode, so agents are nodes and inherit retry_config, timeout, rerun_on_resume and state_schema. Retries and timeouts stop being wrapper code and become properties of the topology, which is a much nicer place for them.

Two runtime behaviours you only find by running it: ctx.run_node() raises unless the calling node has rerun_on_resume=True, and a JoinNode placed behind a conditional fan-out never completes, because it waits for all predecessors and one of them never runs.

And the one that actually cost me a design: FunctionTool(fn, require_confirmation=True) — the human-in-the-loop gate — is implemented in the LlmAgent flow, in flows/llm_flows/request_confirmation.py. A Workflow's tool node builds a fresh ToolContext, calls tool.run_async and yields the result. It never emits adk_request_confirmation and never resumes. Drop a confirmation-gated tool into a graph and it will run straight through, silently, exactly as if you had not asked for a gate.

What works: raise a workflow-native RequestInput carrying the pending call, and on resume re-validate the arguments against a digest you recorded when approval was requested — then hand it to the confirmation-gated tool. You keep the property that matters, which is that an approver cannot alter the call they approved.

The part I did not want to write

The whole product is built on one idea: the agent should learn the volunteer's editorial conventions from their corrections, so the hundredth page costs less attention than the first.

So I tested it properly. Mine conventions from corrections on 60 training pages, apply them to 60 pages the miner never saw, grade the same model reading twice — once raw, once styled — so the comparison is paired and sampling noise cannot move it.

1 page improved. 57 unchanged. 2 worsened. Mean CER change: −0.0001.

Six conventions were mined, each at 100% precision on training data. They simply do not fire often enough on unseen pages to move a median. My best guess is the shape of the material: abbreviations in Revolutionary War pension files are long-tailed, so a clerk's contraction learned from one veteran's file rarely shows up in another. The experiment that would settle it learns within a single file unit, where one hand repeats across dozens of leaves. I have not run it.

An earlier version was worse. I had seeded plausible conventions by hand — Recd → Received — and it scored worse than doing nothing, because archival practice is to transcribe verbatim. Expanding the abbreviation moves the text away from what the volunteer actually typed. Guessing at someone's editorial style is exactly the mistake the product exists to prevent, which is a funny way to learn a lesson.

The transcription itself is fine — median CER 6.8% against transcriptions written by people, best page 0.29%. It is the learning claim that is unproven, and a result that only reports its wins is not a result.

Code: https://github.com/RaYYeR220/longhand · Live: https://longhand-494617981995.us-central1.run.app