The Timeout Stopped. The Pipeline Still Failed.
The previous episode made the graph backlog move further through the system. Schema enforcement and bounded concurrency let more work reach the database, where search timeouts became the next visible limit. Increasing a timeout changed how long the job could wait. It did not remove the unnecessary query that was consuming that time.
I wanted the ingestion path to avoid database work when it already knew there were no candidate edges to search. The first repair passed a test and a verifier but missed the callable the runtime used. The corrected repair then produced a result that needed two sentences: the timeout storm stopped in the reported smoke, and document ingestion still failed.

A repaired component can be a useful result while the larger job remains unfinished. Conceptual illustration.
This chapter covers the July 11–12, 2026 timeout investigation, centred on the July 12 v2 implementation and reported smoke. It is a curated reconstruction from the retained handover, implementation report, historical client and tests at 3d412cf0. I owned direction and review; agents assisted with implementation and verification. Historical test, deployment and smoke results remain attributed reports. Fresh isolated checks exercise the wrapper with fake callables and no database, model calls or live cluster changes.
An empty candidate set should change the plan
Graphiti’s edge search received a filter that could contain candidate edge identifiers. An explicitly empty list meant there were no candidate edges for that constrained search. The useful result could therefore be returned immediately, without asking the database to scan a broader relationship pattern and filter it down to nothing.
The July implementation report describes the expensive path as a full-text edge search that still performed a broad entity/relationship match before narrowing to the supplied candidates. It attributes substantial scan work to calls whose candidate list was empty. The original query profile and full call distribution are not retained here, so I am not turning its quoted scan sizes or prevalence estimate into an independently measured benchmark.
The source-level question is narrower and inspectable: when the caller explicitly supplies edge_uuids == [], can the wrapper return an empty result without calling the original search function? That is a useful fast path because the answer follows from the input contract rather than a heuristic prediction about query cost.
There are three different inputs to keep apart:
| Candidate filter | Meaning used by the repair | Wrapper behaviour |
|---|---|---|
[] | Explicitly empty candidate set | Return an empty list immediately |
| A non-empty identifier list | There are candidates to evaluate | Delegate to the original search |
None or an absent attribute | No explicit empty-set instruction | Delegate; do not silently treat unknown as empty |
The last row is especially important. A convenient truthiness check could collapse None and [] into one branch. That would change the behaviour of unconstrained or unspecified searches. The repair instead checks equality with an empty list, preserving the original path for other values.

An explicitly empty input can justify doing no work. An unspecified input cannot automatically justify the same decision. Conceptual illustration.
That is an engineering contract worth testing directly. It is much stronger than “the query usually returns nothing,” because it states which input permits the fast return and which inputs still require the original implementation.
The first patch repaired a disconnected path
The v1 approach introduced a candidate-bound search class and assigned it to a private driver attribute. The historical report says its test monkeypatched a class method. Both test and verifier passed. The live backfill nevertheless continued producing timeout errors.
The later diagnosis identified a call-path mismatch. Graphiti’s search used a module-level function and an imported alias, rather than the class method the v1 test exercised. Adding a helpful implementation to a driver attribute did not establish that the active caller would ever use it.
This resembles Episode 4’s retired-client problem, but the mechanism differs. There, the constructor selected a different client. Here, a module imported a function by name, creating another reference that the repair also had to account for. The common lesson is to follow the actual call boundary instead of inferring reachability from the presence of a tested class.
The implementation report records a 98-minute r5 run with 638 timeouts and substantial document failure. That is a reported observation for that attempt, not a fresh experiment or a universal timeout rate. Its importance is that the operational symptom remained after the supposed repair. A test pass and an unchanged failure signal required revisiting the test’s premise.
The report also distinguishes an earlier plan from what actually shipped. One proposed deployment sequence would have run a smoke before unsuspending the cron job. The final account says a parallel lane unsuspended it directly, based on the verifier and image checks, and the smoke happened afterward. This draft follows the amended report. It does not turn the safer-looking plan into an event that never occurred.
The corrected wrapper stayed deliberately small
The v2 implementation wraps the module function. When the supplied filter has an empty candidate list, it returns []. Otherwise it awaits the original callable with the same arguments. This exact excerpt is retained from the installer in graphiti_client.py:
client.py · empty-candidate wrapper · platform 3d412cf0
async def patched(driver, query, search_filter, group_ids=None, limit=10):
if getattr(search_filter, "edge_uuids", None) == []:
return []
return await original(driver, query, search_filter, group_ids, limit)
Explain this code line by line
- The wrapper preserves the caller-facing arguments and defaults.
- It reads edge_uuids with None as the default for an absent attribute.
- Only equality with an empty list triggers the immediate empty result.
- All other values, including None and a nonempty list, delegate to the saved original callable with the same arguments.
The code is small enough to look obvious after the investigation. What makes it useful is the boundary around it: which callable was saved as the original, which names were assigned the wrapper, and how repeated installation behaves. Those details determine whether the simple condition has any effect on the real path.
The wrapper does not catch arbitrary database failures or change the search algorithm for non-empty candidates. It preserves the original behaviour there. That narrowness makes the acceptance case precise, while keeping the remaining failure modes visible rather than hiding them behind a general empty-result fallback.
Here is a synthetic filter example, not an original request payload:
{
"query": "an illustrative relationship search",
"search_filter": {"edge_uuids": []},
"expected_wrapper_result": []
}
The expected result is justified by the explicitly empty candidate list, not by knowledge about the words in the query. Change the list to ["example-edge"] and the original search must receive the call. Change it to null and delegation must also remain possible. The fresh isolated checks exercise all three cases with a recording fake callable.
Follow the mechanism
The diagram shows the wrapper’s decision and the two reference sites. It is not a live trace or a complete Graphiti architecture map. The point is that an optimisation is only effective when the names the caller resolves reach the implementation being tested.
One function could have two relevant references
The inspected installer assigns the wrapper to both the search-utils module and Graphiti’s search module alias. Python’s import statement semantics explain why this can matter: importing a name binds a reference in the importing namespace. Later replacing the source module’s attribute does not automatically rewrite every already-bound alias.
client.py · _install_vw1235_edge_fulltext_search_patch, bindings · platform 3d412cf0
search_utils.edge_fulltext_search = patched
graphiti_search.edge_fulltext_search = patched
Explain this code line by line
- The first assignment changes the attribute on the source search-utils module.
- The second changes the already-bound alias used by the other search module.
- Both must be checked by the test; updating only the original namespace can leave an old reference reachable.
That does not mean every application should patch dependencies at import time. It describes the bounded compatibility repair retained in this episode. Such a patch needs version awareness, a clear ownership boundary and tests that check the actual references it intends to affect. A future upstream release can change those references or fix the behaviour itself.
The installer also marks the wrapper and stores the original callable on it. If invoked again on an already-patched function, it reuses that wrapper rather than nesting another wrapper around it. This idempotence matters in tests and repeated imports: repeated installation should not multiply layers or lose the original delegation target.
A test should therefore ask more than whether one direct call returns an empty list. It should confirm both aliases point to the expected wrapper, the empty case produces zero original calls, non-empty and unspecified filters delegate, and another installation preserves the intended identity. Those are separate assertions about reachability, behaviour and lifecycle.
A test repair created another kind of shared state
The first v2 test attempt used importlib.reload to get a spy onto the saved original function. Reloading a module re-executes its definitions. Objects created before and after that reload can therefore refer to different class objects even when their names look identical.
The historical report says two unrelated tests then failed because class identity had changed. A monkeypatch fixture could restore the attributes it had changed, but it could not undo all the new definitions created by the reload. The attempt solved one observation problem by mutating wider module state.
The corrected tests drove the already-installed wrapper directly. For the delegation case, they temporarily substituted a spy at both reference sites and reran the idempotent installer. The fixture then owned the specific substitutions and could restore them at teardown. This made the test’s effects closer to its stated scope.
patch-tests.py · empty-candidate acceptance assertions · platform 3d412cf0
assert result == []
# Zero DB work — the exact guarantee v1 could not prove.
driver.query.assert_not_awaited()
driver.execute_query.assert_not_awaited()
Explain this code line by line
- The result must be an empty list for the explicitly empty filter.
- The comment explains that the test is concerned with zero database awaits on this path.
- Both recording database methods must remain unawaited.
- This isolates the acceptance boundary; it is not a live database or complete ingestion test.
The zero-await assertions are the useful acceptance condition for the empty case. They do not prove that every real query avoids all database work. They show that this tested wrapper path did not await either recording database method for the supplied empty filter. The historical suite is reported as 128 passing tests; the new isolated checks validate the selected mechanism without claiming to rerun that whole environment.
This is where test count can be misleading. The first implementation could pass a test of a disconnected method. The second attempt could test the right function while damaging test isolation. The repair needed both path fidelity and controlled state, not simply a larger number printed at the end of a run.
A split smoke result was the honest outcome
The retained implementation report gives a longer smoke result: roughly an hour, zero edge-fulltext timeouts and zero of nine documents ingested. The shorter handover also describes a narrower r6 smoke window with zero timeouts. Those are different observation windows. This chapter does not merge their durations or treat one as an independently reproduced run.
The timeout deliverable and the ingestion objective therefore had different outcomes. The empty-candidate patch could be effective while the document pipeline remained blocked. The later failing stage was entity extraction from large documents, where local-model output exceeded its useful response boundary and arrived truncated or invalid as JSON.

Removing one failure does not establish that the final work is complete. Conceptual illustration of the split result, not a historical throughput measurement.
That is not a reason to discard the timeout fix. It is a reason to state what it fixed. Earlier failures can prevent execution from reaching later ones. Once the timeout storm stopped, the job could expose a different boundary that had been masked by earlier exits.
| Evidence | Component conclusion | End-to-end conclusion |
|---|---|---|
| Empty-list wrapper avoids original calls in isolated checks | The selected fast-return mechanism behaves as intended | No live ingestion result follows from that test |
| Historical smoke reports zero edge-fulltext timeouts | The targeted timeout signal disappeared in that window | Other stages may still fail |
| Historical longer smoke reports 0/9 documents ingested | The batch did not achieve its document goal | The pipeline was not recovered as a whole |
| Large-response JSON errors remained | Extraction required separate investigation | Raising a database timeout would not repair those responses |
The source also records database timeout persistence as a defensive backstop. Persisting a setting can prevent a restart from silently reverting it. It does not demonstrate that an inefficient query has become efficient, and it should not be credited as the empty-candidate fix itself.
The later record changed the outcome again
The zero-of-nine result belongs to the earlier smoke window, not the end of July 12. A later same-day handover reports that the extraction repair was deployed: truncated JSON was salvaged, entity and edge arrays received a sixty-item cap, and document chunks were reduced from six thousand to three thousand characters. Those were separate extraction changes; the empty-candidate wrapper had not supplied them.
That handover reports no JSON-decoding or unterminated-string errors in its smoke, with batches recording five processed documents and none failed. It also reports the graph reaching 284 nodes and 1,050 edges in that check. I have not independently replayed that deployment or inspected the raw smoke bundle, so these remain reported results. They do establish that the historical account moved beyond the earlier zero-document checkpoint.
Continuing the backfill then exposed another boundary. The same later handover reports full-text search timeouts on the non-empty candidate path as the graph grew. That is outside the explicit-empty fast return explained above: a real candidate set still delegates to the original search. The account ends with the backfill suspended pending a query-plan repair, rather than claiming a clean run to completion.
This is the more useful ending. One source revision repaired the empty path. A later extraction change allowed useful work through. Running at greater scale then revealed a different search problem. Keeping those stages separate avoids crediting one patch with every later improvement, or treating an earlier failed smoke as the final result of the day.
Lessons I would keep
I would specify the semantic difference between empty and unspecified inputs before writing a fast path. An optimisation that skips work needs a contract strong enough to justify the skipped work. A generic falsey check can weaken that contract without looking complicated.
I would make the acceptance test drive the name the runtime actually resolves. When aliases exist, that means inspecting the importing namespace as well as the original definition. A green test of a convenient class method is not useful proof if the caller never uses it.
I would isolate test state without reloading a module merely to create a spy seam. The test should own and restore the attributes it changes. If a broad reload is unavoidable, its effects on other captured references need explicit consideration rather than assuming ordinary monkeypatch cleanup can reverse it.
Finally, I would put the task-completion count beside the repaired error metric. “Zero timeouts” is a meaningful component result. “Zero documents ingested” is a meaningful operational result. Keeping both visible prevents a successful fix from being sold as a recovered pipeline, while still giving the fix the credit it earned.
Next in the sequence
The retained July 12 records start separating data preparation, enrichment and serving behind an explicit cutover plan. That is the next thread to reconstruct: what had to be ready before a new path could be selected, and how to distinguish code merged behind a flag from data actually prepared and served. This episode does not claim that the cutover had completed yet.
Glossary — plain-English definitions
Candidate set
The explicit records eligible for a constrained search. Episode evidence and limits (retained historical evidence).
Alias
Another namespace reference to an object such as a function. Primary concept reference.
Wrapper
A callable adding a narrow behaviour around another callable. Episode evidence and limits (retained historical evidence).
Delegation
Passing the request onward to the saved original implementation. Episode evidence and limits (retained historical evidence).
Idempotent installer
Repeated setup preserves the intended installed state without multiplying wrappers. Episode evidence and limits (retained historical evidence).
Module reload
Re-executing definitions, which can change class identity and shared state. Episode evidence and limits (retained historical evidence).
Smoke test
A bounded runtime check that establishes only what it actually exercised. Episode evidence and limits (retained historical evidence).
End-to-end result
The completed user objective across all required stages. Episode evidence and limits (retained historical evidence).
Sources and limits
The source and claim ledger (retained in review ledger) retains the amended implementation report, shorter handover, later cutover context, historical installer and tests. Raw database profiles, original smoke logs and a reproduced full Graphiti runtime are not included. Conflicting observation-window detail is labelled instead of flattened. This chapter is a July checkpoint, not the season finale or proof that the remaining extraction and serving work was finished.