Skip to content

elegance: type LanceDBBackend.get_by_source() failure instead of swallowing it to []#224

Merged
Antawari merged 1 commit into
mainfrom
catrina/2026-06-13/w1-bonfire-public-get-by-source-typed-failure
Jun 14, 2026
Merged

elegance: type LanceDBBackend.get_by_source() failure instead of swallowing it to []#224
Antawari merged 1 commit into
mainfrom
catrina/2026-06-13/w1-bonfire-public-get-by-source-typed-failure

Conversation

@Antawari

Copy link
Copy Markdown
Contributor

DO NOT MERGE — fleet quality burn unit; opened for review only.

The unit

LanceDBBackend.get_by_source() caught except Exception as exc: and returned
[], making a genuine LanceDB lookup failure (corrupt table, unreachable store,
a vector-op error) indistinguishable from "no entries for this source path".
That is the swallowed-failure the Elegance Law forbids — and the exact masquerade
its structural sibling query() already had removed (it now raises a typed
RetrievalError). get_by_source() was the overlooked sibling: same
table.search(...).where(...).to_list() shape, same "list of entries" return,
same indistinguishable [].

It is the deliberate inverse of exists(), whose fail-open-to-False is a
documented, separately-test-pinned dedup contract (a false negative there only
causes a harmless duplicate store). get_by_source() has no such fail-open
caller — its list is the answer — so, like query(), it must raise rather
than degrade. That exists() contract is left untouched.

The falsifiable claim it satisfies

An oracle: inject a table whose .search() raises; get_by_source returns
[] with no exception — refuting any claim that this backend speaks failure
in the one typed vocabulary.

After this change the oracle is satisfied: a thrown lookup surfaces as a typed,
retryable RetrievalError (code == "retrieval", retryable is True) carrying
the originating exception as __cause__ and structured context (source_path).
A genuine empty result (zero matching entries) stays a legitimate success and
still returns [].

TDD

tests/unit/test_knowledge_backend_get_by_source_typed_failure.py (RED first):
4 tests — typed-raise on backend failure, __cause__ chaining, source_path
in context, and zero-hits-is-a-success. Uses a fake exploding table
(lancedb is not a test dependency), mirroring the sibling query() test.

Budget / anti-gaming notes

  • The implementation is net-zero in line/statement count
    (backend.py measure 244 → 244), so the src/bonfire file budget is
    unmoved — no budget was inflated.
  • The only baseline ratchet is the tests/unit package total re-frozen
    58858 → 59014 (+156, exactly the new test file, which is a new file under
    the 500-line ceiling), the documented re-anchor per
    configs/BASELINE-CONVENTIONS.md. No file row changed; no offender was
    laundered.

Gate

Reproduced locally against a clean export at the pinned kit SHA: CI lint
(ruff check + ruff format --check), full pytest (4421 passed), the
BubbleGum kit battery (cf-sticky-check, cf-file-budget: clean,
cf-mirror-check, cf-recursion-check, cf-exemptions, mypy ratchet =
0 new errors), and the smoke gate (wheel + sdist build/twine/smoke) — all green.

get_by_source() caught `except Exception` and returned [], making a genuine
LanceDB lookup failure (corrupt table, unreachable store, vector-op error)
indistinguishable from "no entries for this source path" — the swallowed
failure the Elegance Law forbids, and the exact masquerade its structural
sibling query() already had removed.

Now a thrown lookup surfaces as a typed, retryable RetrievalError (the one
Bonfire failure vocabulary) carrying the originating exception as __cause__
and structured context (source_path). A genuine empty result (zero matching
entries) stays a legitimate success and still returns []. exists() keeps its
deliberate, separately-tested fail-open dedup contract untouched.

The implementation is net-zero in line/statement count, so the src/bonfire
file budget is unmoved; the only baseline ratchet is the tests/unit package
total re-frozen for the new contract test (a new file under the 500-line
ceiling, re-anchored per BASELINE-CONVENTIONS.md).

RED: tests/unit/test_knowledge_backend_get_by_source_typed_failure.py pins
the typed-failure-vs-swallow contract using a fake exploding table (lancedb
is not a test dependency).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@Antawari Antawari changed the title DO-NOT-MERGE · elegance: type LanceDBBackend.get_by_source() failure instead of swallowing it to [] elegance: type LanceDBBackend.get_by_source() failure instead of swallowing it to [] Jun 14, 2026
@Antawari Antawari merged commit c929e68 into main Jun 14, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant