Engineering Notes
How Biloh is built and kept correct: each note is a pattern, the principle behind it and the test that locks it.
30 pages · last updated 2026-11-12
- A record from another business answers "not found"
How Biloh binds every request to one business before it reads or writes, so an id from another business answers 404 and changes nothing.
- A public promise is a test, not a sentence
How each thing Biloh says it will not do is backed by a test that fails the build the moment a new feature would make it untrue.
- Every outbound URL is checked before the server fetches it
Biloh's server only fetches a URL a business gave it after checking every resolved address is public, and it re-checks each redirect hop.
- OAuth codes are single-use and a replayed refresh token ends the grant
How Biloh's token endpoint makes each sign-in code redeemable once, binds refresh tokens to their app, and revokes a grant whose old token is replayed.
- The MCP endpoint checks the browser's Origin and never leaks internals
Biloh's MCP endpoint refuses browser calls from unlisted sites and turns every tool error into a plain message with a reference.
- Tool discoverability for agents
How an agent finds the right tool among hundreds — a categorised map, intent search, and the zero-result rate as the signal the catalogue works.
- Every record needs a visible bucket
Grouping a list into filters can leave records in no group at all — present in the data, invisible on screen. Make the buckets a partition and assert the union.
- When the money arrives but can't be recorded
When a provider confirms a payment your system can't record, alert a human and still acknowledge the provider — never fail silently.
- Put the yes where the thumb is
A field app's primary action belongs in the thumb zone, pinned and dominant — and the destructive options belong below the content, not above it.
- A failure ceiling that only goes down
A committed failure ceiling, calibrated only from CI, that refuses stale or partial evidence — and becomes the zero-failure gate when it reaches zero.
- Five ways a test suite lies to you
Silent-pass patterns found on the road to zero failing tests: vacuous scanners, swallowed errors, invisible todos, and a reporter that never ran.
- Freeze the baseline, then burn it down
Convert a never-green check into a frozen offender list that blocks new debt today and only shrinks, with invariants that keep the list honest.
- One question, one home: why parity beats correctness
A case where the UI and the agent tool answered the same question differently, and the correct half was not enough to prevent a false bug report.
- Quarantine as ratified contract, not hidden debt
When a failing test asserts ratified-but-unbuilt behaviour, preserve it verbatim in an integrity-locked quarantine its work package must turn green.
- One home, locked in both directions
A display rule and its compliance counterpart point opposite ways. Give each one home, then write the structural test that guards both boundaries.
- Shipping a feature beside an agent that also ships
When an autonomous worker merges to the same branch you are building on, version numbers collide and edits overlap. Merge, never overwrite.
- Making a multi-connector MCP setup safe to act on
How Biloh stops an agent holding several tenant connectors from acting on the wrong one: identity, a per-response stamp, a mismatch guard, confirm-gates.
- When an agent files a bug against working code
An agent reported a broken send. The send was fine — its own reporting tool was lying to it. How to triage a report written by a confident reader.
- Reading a tenant setting: unwrap the envelope
Governed settings writes wrap the value as {v:...}, so a raw read silently returns the default. The one unwrapper to use, and the lint that enforces it.
- Two places, one fact
A permission was stored in two places. The form wrote one, the gate read the other — so a user's saved choice was invisible to the system enforcing it.
- An orientation payload an agent can actually read
A read-me-first tool that returns 100KB is unreadable inside an agent's context budget. Make the default lean, put the full detail behind an explicit flag.
- Whose "today" is it? Timezones in a scheduling engine
A scheduling product that computes today in UTC shows the wrong day to most of the world. Resolve the day in the tenant's timezone and lock it with a test.
- Show the price you'll charge: one source of truth
Show prices from the same source that charges the customer. Copying a price into a second surface invites silent displayed-versus-charged drift.
- Drag is a desktop idiom; the phone wants a tap
Drag-and-drop dispatch boards are desktop tools. On touch a press-and-move is a scroll, so the field surface has to be tap-first, not drag-first.
- One write path, many callers
Why every mutation should funnel through one core that the UI and the agent both call — and the billing bug that appears when a caller skips it.
- Trust the signed account, not the webhook's metadata
A payment webhook must bind each charge to the provider's signed account, not to client-supplied metadata — the pattern that blocks cross-tenant spoofing.
- Verifying the tenant that isn't your default
A test harness that injects tenant context can't catch a tenant-resolution bug. Only live use on a non-default tenant exposed a 401 the suite couldn't see.
- A handler nothing subscribes to does nothing
An event handler can be unit-tested yet never run in production if nothing subscribes it to its event. Verify the wiring, not just the handler.
- The gap between a green build and a live deploy
Lessons from building a docs system into a deploy-on-every-push platform: a green local build and a working deployment are different claims.
- Lessons from shipping agent-facing MCP tools
Lessons from shipping a batch of MCP tools: test the consumer not just the logic, surface what agents need, and watch the build and version traps.