Keys: the design in ten minutes
Keys is an operator for a residential property manager's daily work: rent, renewals, empty homes, repairs, vendors, statutory inspections and building alarms. It finds what goes wrong, fixes what a written rulebook allows, asks a person for the rest, writes down why, and grades itself against an answer key. The full design goes one level deeper; known gaps says what it does not do.
The running copy works on a synthetic world: an invented company, Corbelstone Residential, with 120 buildings and 8,000 homes in three invented cities. Every figure below comes from the seed 23 world and its replay (commands in the README).
1. One morning
Monday 2 November is the first working day of the month. 1 November was a Sunday, so the rent run lands on the 2nd: 5,955 rent payments post that day (4,915 of them direct debits), 5,503 before 08:00. The weekend's repair calls are waiting, and 96 new tickets arrive between 08:00 and 20:00. The lettings team sends its monthly renewal run, 622 offers, and a few of them are keyed outside the band. Vendors send their monthly invoices, some for jobs they were never sent to. A leak sensor in a plant room has been raising an alarm for twenty minutes and nobody has opened a ticket. The only working lift in an eight-floor block stops.
A good operations team catches each of these, eventually. Keys sees them as they happen, does the routine part at once, and puts the rest in front of the right person with the evidence attached.
2. The parts
world (DuckDB) ──► definitions ──► detectors ──► workers ──► controller ──► tools ──► world
▲ (YAML+SQL) (cadence) (rules or (policy.yaml) (snapshot,
│ model) │ undo)
│ ▼
└──────────── recal (answer key) ◄──────── ledger ◄──── queue (tier 2, people)
- Definitions (
keys/dictionary/definitions/*.yaml). Each sector term and each detector is written once, in SQL, with an owner, a version and tests: arrears, in SLA, vacant, renewal window, occupied, open ticket, band price, and the ten incident kinds. The detectors, the operator, the main screen and Ask all read the same files. - Detectors run those definitions on the schedule the policy sets: building problems (water alarms, lifts, duplicate tickets, SLA) at every step, offers and invoices hourly, rent, renewals, vacancies and inspections daily at 08:00.
- Workers propose one action per incident. When the runbook leaves one action, a fixed rule fills it in. The model is asked only where there is a real choice (dispatch, re-dispatch or replace a vendor; remind or go to legal; list a home or offer a concession).
- The controller checks every proposal against
keys/agent/policy.yaml. The action must exist and be allowed for this kind; its arguments must name only things in the evidence; a rent must sit inside the band the evidence names; a vendor must be one the evidence lists; cooldowns, dedupe windows and budgets must allow it. It is plain code, separate from the model, and a model answer cannot talk it round. - Tools make the change: a letter row, an offer, a dispatch, an invoice hold, a ticket from an alarm. Each records a before-snapshot so it can be undone.
- The ledger keeps every row, appended and never edited.
- The queue holds tier 2 proposals for a person. In the replay a scripted on-call shift answers it (a duty manager, a lettings lead, a credit control lead and a maintenance lead, each with written rules and delays).
- Recal scores the ledger against the answer key the world generator wrote.
3. Authority
Anything not listed in the policy is tier 3.
| Tier | Meaning | Examples |
|---|---|---|
| 0 | Just do it | arrears reminder on the schedule, renewal offer at the band price, dispatch a panel vendor inside the SLA, ticket from an alarm, merge a duplicate, hold an unmatched invoice, book an inspection, list an empty home |
| 1 | Do it and tell | reassign a vendor after a no-show, a notice to residents; the building manager is told |
| 2 | Ask first | legal notice, rent concession, take a vendor off the panel, re-issue an offer a tenant already holds |
| 3 | Never | eviction, a price outside the band, contacting a tenant about a legal matter, paying an invoice |
Budgets: six automatic actions per building per hour, thirty a minute across the portfolio, forty a minute for the back office (letters, offers, invoices). A building over its budget goes to a person with the reason; a portfolio over its rate waits a minute. The same problem on the same thing is handled once per fifteen minutes, and each action carries its own cooldown (one arrears reminder per lease every two days, at most).
4. A ledger row
Row #484 of the seed 23 replay, at 13:00 on the busy day:
- Incident: renewal offer outside the band, offer 717, home 3C at Kestrel Court.
- Evidence: the offer was sent at 1,660 a month; the band for a two-bedroom home there is 1,260 to 1,480, band price 1,330; 12.2% outside the band, 3,960 a year off the band price.
- Definition:
renewal_out_of_bandv2 (owner: Head of Lettings). - Decided by: rules. The runbook has one action for this kind.
- The call:
POST /offers/717/reissue rent=1330, tier 2 (withdrawing an offer the tenant already holds needs a person). - Approved fifteen minutes later by the scripted lettings lead, as row #485.
- Undo: withdraw the new offer and restore the old one.
Every row of every kind has the same parts. An approval, a rejection or an undo is a new row pointing at its parent.
5. The screens
- Buildings is the main screen: an elevation of every building, one cell per home, floors bottom up, grouped by city. A cell is coloured by the home's state at the clock's time, read from the dictionary: occupied, vacant on the market, not let (in works), in arrears, open ticket. Underneath, the ticket board puts every ticket alive that day into its stage: reported, vendor dispatched, on site, work done, closed, merged as a duplicate. On the right, the operator's receipts land as the clock reaches them.
- Play mode runs a sped-up clock over the busy window, 08:00 to 20:00 (×120, ×360 or ×720; at ×360 the day takes two minutes). As the clock passes a ledger row, its receipt drops into the rail, the home or building it touched gets an ink ring, and a ticket it moved changes column with an operator stamp on its card. Homes change colour as the dictionary's answers change: tickets open and close, arrears clear. The scrubber jumps to any minute.
- Ledger, Queue, Accuracy (with a day-by-day timeline), Definitions, Ask, this page and Known gaps complete the set. Every number on every screen is read from the database.
6. The busy day in numbers
Between 08:00 and 20:00 on seed 23 the ledger gains 72 rows (SELECT action, status, count(*) FROM ledger WHERE "at" >= '2026-11-02 08:00' GROUP BY ALL on out/keys-replayed.duckdb):
| Action | Rows | What happened |
|---|---|---|
| reissue_renewal_offer | 32 | 16 offers outside the band put to the lettings lead, 16 approvals |
| hold_invoice | 15 | invoices with no matching job held before the payment run, the vendor asked for the job number |
| open_ticket_from_alarm | 9 | four leak alarms and five lone-lift faults ticketed, a vendor dispatched |
| merge_duplicate_ticket | 6 | second reports of one fault merged into the original |
| notify_residents | 5 | residents of a building with no working lift told, the building manager informed |
| dispatch_vendor, reassign_vendor | 3 | tickets past half their SLA with no vendor, or a vendor who did not come |
| offer_rent_concession | 2 | a home empty 104 days: proposed, then approved by the duty manager |
7. Measuring it
The generator plants ten kinds of fault and writes each into incidents_truth: the kind, when it starts and ends, the home, lease, offer, ticket, invoice, alarm or building it is about, and the correct handling. The replay runs the operator over six days of history and the busy day on a copy of the world and scores it: precision and recall per kind, the share handled without a person, reverts, time to resolve, decided by rules versus the model, and the weakest detector.
On seed 23 the replayed week scores 98.6% precision and 99.4% recall on 319 planted faults; 85.1% of incidents are handled without a person; the weakest detector is duplicate ticket at 88.5% precision. Thresholds were tuned on seeds 7 and 11 only; seed 23 is the hold-out.
8. Plugging in
Read-only readers for the property management system, the rent ledger, the help desk, the purchase ledger and the building management system map onto the same tables (keys/world/schema.sql). Shadow mode (KEYS_SHADOW=1) writes "would do" rows and changes nothing. A few weeks of shadow rows, reviewed by the operations team, set the tiers before any action reaches a tenant or a vendor.