# Engineering notes

These are working notes, not essays. Each page names a method, gives the measurement it produced, and says where the measurement stops. They cover voice latency, isolation, query cost, counting bugs, tests that passed while proving nothing, and the defects a browser shows that a source file hides. None names a customer, and none reports a number nobody measured.

- **Status:** Available
- **Audience:** both, developer
- **Last verified:** 2026-09-10
- **Canonical:** https://connectbyjbrh.com/research/

## What counts as a note here

A note earns its page by having a method behind it. If the finding reduces to "it depends", there is nothing to publish: the useful version states what was driven, what came back, and which conclusion the evidence actually supports.

- **Method first.** What was run, against what, and how the result was read.
- **Numbers as measured.** Latency on the wire rather than from a transcript row; query cost in statements rather than in milliseconds on one machine.
- **Failures included.** Several of these notes exist because something shipped wrong, went unnoticed and was found by driving a live endpoint.
- **Limits stated.** Where a figure was never measured the page says UNKNOWN rather than offering a plausible one.

What you will not find: an author, an anecdote, a named customer, a benchmark against another product, or a claim about a capability Connect does not have. The [status vocabulary](/research/status-vocabulary/) that governs the rest of this manual governs these pages too.

## Voice and telephony

- [Measuring voice latency](/research/measuring-voice-latency/) — why the clock has to run on the wire, and what "8 ms" beside a multi-second wait was really measuring.
- [Prompt size and first token](/research/prompt-size-and-first-token/) — 7,500 characters against 9,600, and what each cost.
- [Barge-in without cutting the greeting](/research/barge-in-without-cutting-the-greeting/) — interruption handling that does not talk over its own opening.
- [Model-limited findings](/research/model-limited-findings/) — the problems no setting on the page can fix, listed and counted rather than hidden.
- [Silent failure](/research/silent-failure/) — five inbound calls recorded as "the caller hung up before speaking" that were nothing of the kind.
- [Callback promises](/research/callback-promises/) — refusing to record a time nobody said.
- [Idempotent telephony webhooks](/research/idempotent-telephony-webhooks/) — storing each provider event exactly once.
- [Provider-independent telephony](/research/provider-independent-telephony/) — capabilities asked for by name, never branched on by provider.
- [Deriving control state from the log](/research/derived-control-state/) — pause, take over, release, and the flags that cannot express them.

## Records, cost and counting

- [The query cost that grows with the business](/research/n-plus-one-that-grows/) — five thousand five hundred and seventy-four statements down to three, and three more measured examples.
- [Headline numbers that stop at the page size](/research/counting-past-the-limit/) — 500 reported for 530, and 0 reported for 40.
- [How a mail cursor loses messages](/research/cursor-loss/) — the refusal that must not advance a read position.
- [Why 'sent' requires provider evidence](/research/provider-evidence-for-sent/) — and the third state that is neither success nor failure.
- [Why 'connected' is not mailbox health](/research/mailbox-health-beyond-connected/) — the quiet mailbox that authenticates and returns nothing.
- [One person, many channels](/research/one-person-many-channels/) and [relationship memory](/research/relationship-memory/) — what a record has to hold for the second conversation to make sense.
- [Evidence-first prospecting](/research/evidence-first-prospecting/), [identity resolution](/research/prospect-identity-resolution/) and [research cost routing](/research/research-cost-routing/) — spending research where it changes a decision.
- [Evidence for a next action](/research/evidence-for-next-action/) and [safe refusals in sales](/research/safe-refusals-in-sales/) — the refusal that is correct behaviour.

## Architecture, boundaries and memory

- [Three layers of isolation](/research/three-layers-of-isolation/), [a facade that fails closed](/research/closed-by-default-facade/) and [one implementation for two audiences](/research/two-audiences-one-implementation/).
- [A row that is invisible, not missing](/research/invisible-not-missing/) and [the empty workspace stamp behind it](/research/workspace-stamp/).
- [Grounding without a vector database](/research/grounding-without-a-vector-database/), [structured business memory](/research/structured-business-memory/) and [corrections that stick](/research/memory-correction-that-sticks/).
- [Prompt injection in business mail](/research/prompt-injection-in-business-mail/), [authority separation](/research/authority-separation/) and [approval without blocking](/research/approval-without-blocking/).
- [Agent tools that call services](/research/agent-tools-call-services/), [undo for agents](/research/undo-for-agents/) and [uncertainty as an answer](/research/uncertainty-is-an-answer/).
- [One file service](/research/files-through-one-service/) and [a grid that is not a second database](/research/grid-over-services/).
- [One thinker](/research/single-thinker/), [background threads](/research/background-threads/) and [migrations that run at boot](/research/boot-time-migrations/).

## Proof, tooling and the manual itself

- [Five ways a suite passed while proving nothing](/research/false-passing-tests/) — and the change that made each one real.
- [A probe that fires on a correct release](/research/probes-that-cry-wolf/) — 235 files reported different for a release that changed no code.
- [Defects invisible in the source](/research/invisible-ui-defects/) and [focus rings that computed to none](/research/focus-rings-that-computed-to-none/).
- [A stale credential that read as a bad deploy](/research/stale-credentials/).
- [Documentation as a build](/research/documentation-as-a-build/), [writing for people and machines](/research/writing-for-people-and-machines/) and [measuring AI visibility](/research/measuring-ai-visibility/).

> **Note** Findings are dated and tied to a commit. Where one has been superseded the page says what changed rather than being quietly edited into agreement with the present.

## Everything in this section

49 pages, each with its own status and the date it was last checked against the running system.

| Page | What it covers |
|---|---|
| [A background thread that outlives its task](/research/background-threads/) | Cancelling the coroutine that awaits a worker thread does not stop the thread. What the orphan did at shutdown, and the cooperative stop that replaced it. |
| [A copy of a password somebody else rotates](/research/stale-credentials/) | A database password copied into an environment file kept working until somebody else rotated it, then failed at the next restart and read as a bad deploy. |
| [A focus ring that was defined, valid-looking and computed to nothing](/research/focus-rings-that-computed-to-none/) | A keyboard focus ring can be present in the source, valid to a linter, and still compute to nothing in the browser. What to measure instead of reading. |
| [A four-word vocabulary for capability status](/research/status-vocabulary/) | Four words describe every capability in this manual, one of them takes a qualifier, and nothing else is permitted. What each forbids, and what the discipline costs. |
| [A probe that fires on a correct release is worse than no probe](/research/probes-that-cry-wolf/) | A release probe reported 235 backend files changed for a release that changed no code. Why the comparison was wrong, and what a release check should compare. |
| [A row with no workspace stamp is invisible, not missing](/research/invisible-not-missing/) | Missing, deleted and invisible are three different incidents with three different repairs. The one-minute triage that tells them apart before anyone reaches for a backup. |
| [A spreadsheet view that is not a second database](/research/grid-over-services/) | A spreadsheet over 13 record sheets where every edit still goes through the service that owns the record. What the constraint costs, and what it prevents. |
| [A tenant facade that fails closed](/research/closed-by-default-facade/) | An unmapped API path is refused rather than guessed, in the browser and again on the server. What that costs per feature, and the enumerated test that keeps it honest. |
| [Barge-in without cutting the greeting in half](/research/barge-in-without-cutting-the-greeting/) | Letting a caller interrupt a voice agent without a cough killing the opening: the protected greeting, the sensitivity setting and the two-second rule. |
| [Data that is invisible rather than missing](/research/workspace-stamp/) | A row stamped with an empty workspace id is invisible to every list and openable by id. The asymmetry is the diagnosis, and the repair belongs at boot. |
| [Defects that are invisible in the source and obvious in a browser](/research/invisible-ui-defects/) | Three defects a source review could not have seen: an overlay covering a control, a remembered size hiding one, and a capability nothing on screen called. |
| [Deriving control state from the log instead of storing it](/research/derived-control-state/) | Pause, take over and release end in a state no single row describes. Why the live call's control state is folded from its guidance log instead of stored. |
| [Designing telephony that does not name its provider](/research/provider-independent-telephony/) | Three layers, one capability table, and the six production defects that came from putting code on the wrong side of the boundary. |
| [Designing undo for agent actions](/research/undo-for-agents/) | Reversible, compensable and irreversible: why an agent needs that taxonomy before it needs an undo button, and what Connect offers at each level. |
| [Evidence-first prospecting without guessed emails](/research/evidence-first-prospecting/) | Attaching a source to every claim and never generating an address: what the method costs in volume, what it buys, and where the honest gaps are. |
| [Findings a setting cannot fix](/research/model-limited-findings/) | Three voice behaviours prompting could not reach, the measurement that settled each one, and how a quality score should count a fault no control can fix. |
| [Five ways a test suite has passed while proving nothing](/research/false-passing-tests/) | Five suites that ran green while proving nothing: a rule asserted in prose, a policy never exercised, a clock on the wrong source, and a field that did not exist. |
| [Grounding an answer without pretending to have a vector database](/research/grounding-without-a-vector-database/) | How an answer is grounded in a workspace's own Knowledge and Facts without an embedding index, why selection by relation holds at this size, and where it stops. |
| [Headline numbers that stop at the page size](/research/counting-past-the-limit/) | When a list limit becomes a total, a workspace of 540 is told it has 500 and a category of 40 reads as 0. Two measured cases and the way to find more. |
| [How a mail cursor loses messages, and how to stop it](/research/cursor-loss/) | A read position advanced on a refusal skips mail permanently and silently. The rule that prevents it, the ordering it depends on, and how to check. |
| [Human approval without blocking low-risk work](/research/approval-without-blocking/) | Approval set as a rule per channel and scope rather than per message, a queue that drains itself, and the trade each of the four modes actually makes. |
| [Idempotency for retried telephony webhooks](/research/idempotent-telephony-webhooks/) | Why a carrier retries a webhook, what a duplicate delivery does to a live call, and the partial unique index that makes a replay harmless. |
| [Making a correction actually change behaviour](/research/memory-correction-that-sticks/) | A correction that is stored and never read looks exactly like one that worked. Where that happens, why, and what makes a correction change behaviour. |
| [Making a next-best-action defensible](/research/evidence-for-next-action/) | What a recommended next action has to carry before it is worth following: the record, the evidence, the rule behind it, and the act it enables. |
| [Measuring conversational latency correctly](/research/measuring-voice-latency/) | Why a transcript row is the wrong clock for a voice agent, what to time instead, and what moving the measurement did to the numbers. |
| [Measuring whether AI systems can actually read your site](/research/measuring-ai-visibility/) | Crawl, citation and referral are three different measurements with three different kinds of evidence. Only the first is visible in a server log. |
| [Migrations that run on every boot](/research/boot-time-migrations/) | Schema changes applied on every start, with no migration framework: what idempotent has to mean, and the properties a reflection API cannot see. |
| [One file service for two audiences](/research/files-through-one-service/) | A second file implementation for the second audience drifts within a release. The single-service shape used here, what it refuses at the door, and its limits. |
| [One implementation, two audiences](/research/two-audiences-one-implementation/) | One feature set over one body of code, the seam that keeps it that way, and what a reduced copy for the second audience costs before anybody notices. |
| [Preventing a voice agent from promising a call-back it cannot keep](/research/callback-promises/) | How a voice agent came to promise call-backs nothing had booked, the time-word rule that refuses the record, and the finding that measures the residue. |
| [Prompt injection arrives as ordinary business mail](/research/prompt-injection-in-business-mail/) | Received text is data, never instruction. The realistic attack on a mail-reading agent, the boundary that contains it, and the part that stays unproven. |
| [Relationship memory versus chat history](/research/relationship-memory/) | What a transcript cannot answer about a customer, what a tiered memory store answers instead, and what each of the two costs to keep and to read. |
| [Separating the agent's authority from the person's](/research/authority-separation/) | The agent's rights are a strict subset of the person's. What is deliberately absent from the tool set, the three places it matters, and where it thins out. |
| [Spending research budget where it changes a decision](/research/research-cost-routing/) | Running a deeper research pass only where it could change a decision, the same rule applied to model spend on live calls, and what is actually measured. |
| [Structured business memory instead of a longer prompt](/research/structured-business-memory/) | Why a bigger context window is not a memory, what a four-tier store gives that a longer prompt cannot, and the measured cost of choosing the prompt. |
| [Telling a new prospect from an existing customer](/research/prospect-identity-resolution/) | Deciding whether a discovered organisation or person is already somebody you know, and the two opposite ways that decision goes wrong. |
| [The query cost that grows with the business](/research/n-plus-one-that-grows/) | Query cost measured in statements rather than seconds, with four before-and-after figures: 5,574 to 3, 83 to 11, 89 to 17 and 133 to 15. |
| [Three independent layers of tenant isolation](/research/three-layers-of-isolation/) | An allowlist, an ORM kernel and PostgreSQL row-level security. What each catches that the other two miss, the gaps all three share, and the cost. |
| [Treating documentation as a build artefact](/research/documentation-as-a-build/) | Documentation compiled from one capability registry into HTML, manifests and machine descriptions, with a gate that fails closed on everything it can measure. |
| [What every character of a prompt costs on a live call](/research/prompt-size-and-first-token/) | The measured relationship between instruction size and time to first token on a live call, and the character budgets that came out of it. |
| [When a call is answered in silence](/research/silent-failure/) | Five inbound calls were answered in silence and filed as callers hanging up before speaking. The cause, and the event that now tells the two apart. |
| [Why 'connected' is not enough to prove mailbox health](/research/mailbox-health-beyond-connected/) | Authentication proves a credential, not a working mailbox. The signals that matter, the quiet mailbox that looks fine, and the setter that keeps a token alive. |
| [Why 'sent' must require provider evidence](/research/provider-evidence-for-sent/) | A message is sent when the provider says so and not before. The three states, why the uncertain one must stay uncertain, and how it is resolved. |
| [Why a sales agent should refuse to answer](/research/safe-refusals-in-sales/) | The commercial questions no agent should answer alone, why refusing is the correct outcome, and the escalation that keeps a deal moving anyway. |
| [Why an agent's tools should call domain services](/research/agent-tools-call-services/) | The shortcut where an agent tool writes rows directly, the rules that shortcut silently skips, and the shape that keeps one implementation for people and agents. |
| [Why only one loop may think](/research/single-thinker/) | One function turns an inbound message into a decision, and one caller reaches it. Why that boundary exists, what a second loop costs, and where it is enforced. |
| [Why the machine proposes a merge and a person disposes](/research/one-person-many-channels/) | One human reachable by phone, email and WhatsApp: the identity model, what a merge preserves, and why a machine proposes while a person disposes. |
| [Why uncertainty is a valid answer from a business agent](/research/uncertainty-is-an-answer/) | The cost of a confident wrong answer, the places Connect reports not-knowing instead, and what turns uncertainty from an evasion into something actionable. |
| [Writing documentation that both a person and a retrieval system can use](/research/writing-for-people-and-machines/) | One text has to serve a person reading and a retrieval system quoting. Answer-first structure, naming entities every time, and keeping facts out of pictures. |

## Questions

### Are these findings specific to Connect, or general?

Both, and each page tries to be honest about which. The measurements are from this system — this model, this carrier, this schema — so the numbers travel less well than the methods. Counting statements instead of milliseconds, or timing latency on the wire instead of from transcript rows, transfers to anything.

### Why is there no comparison against other products?

Because nothing here was measured against one. A comparison table would be an invention, and the corpus does not publish figures it did not produce — including search metrics, market share and competitor performance.

### How current is a note?

Each page carries the date its facts were verified and names the sources behind it. Where a figure is recorded against a specific call, release or commit, the page says so, because a latency measured on one model version is not a claim about the next one.

## Related

- [Connect by JBRH](https://connectbyjbrh.com/docs/product/)
- [Technology reference](https://connectbyjbrh.com/docs/technology/)
- [Developers and AI agents](https://connectbyjbrh.com/developers/)
- [Measuring conversational latency correctly](https://connectbyjbrh.com/research/measuring-voice-latency/)
- [The query cost that grows with the business](https://connectbyjbrh.com/research/n-plus-one-that-grows/)
- [Three independent layers of tenant isolation](https://connectbyjbrh.com/research/three-layers-of-isolation/)

## What this page is based on

- Connect capability registry (docs-source/facts.py) — the status vocabulary and the measured numbers these notes may quote
- `docs-source/sources/GENERAL.md` — the architecture the notes describe
- `docs-source/sources/PHONE.md` and `CHANNELS.md` — the measurements behind the voice, mail and record findings