Keysproperty operations Corbelstone Residential
Architecture in ten minutesIn fullKnown gapsdocs/architecture-full.md

Keys: the full design

This page goes one level deeper than the ten-minute version. The world it runs on is described in docs/world.md; what it does not handle is in known gaps.

Data plane

Source systemTablesFreshness
Property management systembuildings, units, unit_vacancies, rent_bands, tenants, leases, renewal_offersrealtime
Rent ledgerrent_ledger, tenant_noticesrealtime
Maintenance help desktickets, ticket_events, vendorsrealtime
Building management systemassets, alarmsstreaming
Access controlaccess_eventsstreaming
Purchase ledgervendor_invoiceshourly
Compliance registerinspectionsdaily

The operator owns four more tables: messages (the outbox: drafts a person sends), process_gaps (kinds with no runbook), detector_runs (when each scheduled check last ran) and replay_events (markers for the timeline), plus the ledger's ledger, approvals and ledger_repeats.

Incident taxonomy

KindDefinitionCadenceRunbook (in order)
rent_arrearsoldest unpaid charge 10+ days, next stage not takendaily 08:00send_arrears_reminder (0), serve_legal_notice (2)
renewal_not_sentlease ends within 60 days, no offer, no noticedaily 08:00send_renewal_offer (0)
renewal_out_of_bandpending offer outside its sending date's bandhourlyreissue_renewal_offer (2)
long_vacancyempty 45+ days, not renovationdaily 08:00list_unit (0), offer_rent_concession (2)
ticket_sla_breachno vendor at half the SLA, or no attendance by its endevery stepdispatch_vendor (0), reassign_vendor (1), replace_vendor (2)
duplicate_ticketsame fault, same home or hallway, while the first is openevery stepmerge_duplicate_ticket (0)
invoice_without_ticketjob invoice matching no job of that vendorhourlyhold_invoice (0)
inspection_overduestatutory check past due, nothing bookeddaily 08:00book_inspection (0)
water_alarm_no_ticketlive leak alarm, no ticket after 10 minutesevery stepopen_ticket_from_alarm (0)
lift_outage_singlelift fault 5+ minutes, no other lift workingevery stepopen_ticket_from_alarm (0), then notify_residents (1)

Decision model

For each incident a worker proposes one action. If the runbook leaves one action at tier 0 or 1, a fixed rule fills it in (keys/agent/rules.py). Where there is a choice, or a person may have to approve, the model is asked with the incident, the definition used and the allowed actions with their arguments; its JSON answer is validated against the policy and falls back to the rule if it is unusable. The controller then decides: execute, queue, wait or decline, each with a plain-English reason.

The ledger row

Incident id (kind, subject, start), kind, subject, evidence (with the money at stake), definition term and version, proposal (rules or model, rationale, confidence), decision (tier, reason, checks, policy version), the call, the result with before and after snapshots, who approved, and the undo. Rows are appended and never edited; an approval, rejection or undo is a new row pointing at its parent. A decline repeated for the same incident is folded into the first row's repeats.

Failure modes

Measurement

Recal matches detections to the answer key by kind, by the thing they are about, and by time (20 minutes of slack): precision per detection, recall per planted fault, the share of incidents resolved without a person, reverts, time to resolve and age at detection. The per-day timeline scores only faults that began that day.

Policy in one file

keys/agent/policy.yaml (version 2) holds, for each of the 14 actions: the call it stands for, its tier, the incident kinds it may answer, its arguments and where each must come from (the evidence, the band, the panel), its cooldown, and its undo in words. Around them: the never list (eviction, a rent outside the band, contacting a tenant about a legal matter, waiving arrears, paying an invoice, ending a lease, deleting a record, and anything not listed), budgets per building (six automatic actions an hour), per portfolio (thirty a minute) and for the back office (forty a minute), the dedupe window (fifteen minutes), the cadence of each detector (every step, hourly, daily at 08:00), what happens when a budget is used up (a person decides) or a cooldown is active (declined, with the reason), and when the model is asked (only where the runbook offers more than one action or a tier 2 step is possible; water alarms, duplicates, inspections and invoices are always decided by rules). The controller (keys/agent/controller.py) loads it at start and stamps its version on every decision.

The interface

A FastAPI application (app/) with server-rendered pages and one script for the main screen. It reads the database through app/data.py, the only module that touches DuckDB; one short connection per call, never shared across threads. The visitor's site arm (?v=&p=) is carried on every same-site link, form and redirect by app/arm.py. Responses over 2 KB are compressed.

PathScreenRead from
/Buildings: the elevation, the ticket board, the receipts, play mode/api/stack (below)
/ledger, /ledger/{id}every row; one row with evidence, definition, the call, the controller's checks, before and after, undoledger, ledger_repeats
/queuetier 2 items with approve and reject; the people's latest decisionsledger, approvals
/accuracyheadline scores, the weakest detector, day by day, per incident kindrecal over the ledger and incidents_truth
/definitions, /definitions/{term}every term; one term evaluated at the window's end, each meaning side by sidethe dictionary
/ask?q=a question answered through the definitions, both meanings where there are two, nothing where none fitsthe dictionary
/architecture, /architecture/full, /known-gapsthese documentsdocs/

The building stack payload

GET /api/stack (app/stack.py) returns everything the main screen draws, built once and cached until the ledger changes (an approval or undo on another screen rebuilds it on the next read):

Play mode

The clock runs in the browser at ×120, ×360 or ×720 over 08:00 to 20:00. On every new minute it applies the frames up to that minute, recomputes each ticket's stage, and lands the receipts the clock has passed: an ink ring pulses on the home or above the building, the cell keeps an ink outline for the rest of the day, and a ticket the operator moved carries a stamp linking to its ledger row. Scrubbing backwards rebuilds the state from the first frame. Play replays the recorded run: the operator's decisions as it made them on this world during the replay, at the times it made them. It does not run the operator again in the browser (see known gaps).

Tests

.venv/bin/pytest -q runs the suite on a seed 7 world generated once per session and a short replay on a copy of it: world determinism and incident counts, every definition's tests, the policy file's shape, the controller refusing tier 3 and over-budget actions, the ledger's undo, a replay smoke test, recal, every screen answering 200 with the site arm kept and the synthetic-data label shown once, and the stack payload's counters equal to the dictionary's at the same moment.

Screenshots

scripts/screenshot_all.py starts the app on port 8165 against out/keys-replayed.duckdb, visits every screen at 1440x900 with Playwright (including the main screen while playing and with a home under the pointer), writes the PNGs to out/screens/, fails on any HTTP or browser console error, and stops the server by its port. It presses no approve, reject or undo button, so the database is not changed.