[thekevinbot]

Layer 2 of 2 for #1034. Stacked on #1036 (base: claude/tackle-1034-cachesplit), which teaches the core to read and render the split; this layer teaches the embeddings plugin to produce it.

Fixes #1034

The problem

cachetta's wrap() returns a hit and a miss identically — same value, no signal — so Worker.embed had no way to say which it got. Without it, layer 1's parenthetical never appears for the one worker in this repo that actually caches.

The fix

The wrapped function is the signal. _compute runs on a miss and never on a hit, so it sets a sentinel; embed clears the sentinel, calls through the cache, and reads it back:

def embed(self, text, model_id):
    ...
    self._computed = False
    vector = self._compute_cached(digest, identifier)
    return vector, not self._computed

The response then carries the flag the core protocol defines:

{"ok": [0.12, ...], "meta": {"cached": true}}

handle gained an _embed_response extraction so it stays under the incoming 24-line one-function-per-file ratchet (21 lines now).

{"ok": null} for a NULL value is unchanged — nothing is computed, so there is no cache state to report.

Test changes beyond the new coverage

Several existing tests compared a whole response object (== {"ok": [1.0, 0.0]}) where the point was the vector. Those now compare response["ok"]; the meta key is asserted in its own describe_cache_reporting blocks rather than incidentally in every protocol test.

Red CI observed

Run 33922087464, dirsql-plugin-embeddings integration tests (3.12) and (3.13), on c86314a:

    assert response["meta"] == {"cached": False}
E   KeyError: 'meta'
FAILED tests/integration/cache_behavior_test.py::describe_cache_reporting::it_flags_a_recomputed_value_as_not_cached - KeyError: 'meta'
1 failed, 8 passed in 4.20s

(That run is against the pre-rebase sha c86314a; the branch was later rebased onto the restored base of #1036, making the same commit fc85500. The run and its logs remain reachable.)

Failing on the new assertion, for the asserted reason (-x stops there; locally the full run was 6 failed, 14 passed — the five other cache-reporting integration tests plus the e2e (2 cached) assertion).

Manual run

Worker directly, repeated value, real model2vec and real cachetta:

$ printf '{"call": ["hello there"]}\n{"call": ["hello there"]}\n{"call": ["a different string"]}\n' \
    | XDG_CACHE_HOME=/tmp/... uv run dirsql-plugin-embeddings worker
{'ok_len': 512, 'meta': {'cached': False}}
{'ok_len': 512, 'meta': {'cached': True}}
{'ok_len': 512, 'meta': {'cached': False}}

End to end through the real CLI over a four-file corpus, cold then warm against the same XDG_CACHE_HOME:

$ DIRSQL_PROGRESS=always dirsql --no-plugin query \
    "SELECT basename, vec_distance_cosine(embed(content), embed('quick fox')) AS d
     FROM '/tmp/dirsql-1034-plugin-manual/*.txt' ORDER BY d LIMIT 2" \
    --config src/dirsql_plugin_embeddings/dirsql.toml

# cold
dirsql: ran 5 worker calls in 3.3s
[{"basename":"beta.txt","d":0.2903204560279846},{"basename":"delta.txt","d":0.3246783912181854}]

# warm
dirsql: ran 5 worker calls in 0.3s (5 cached)
[{"basename":"beta.txt","d":0.2903204560279846},{"basename":"delta.txt","d":0.3246783912181854}]

Identical rows, 3.3s versus 0.3s, and the line now says why.

Parity

No change. The plugin exports no Python API (__init__.py is empty) and adds nothing to any SDK surface — PARITY.md is untouched, and layer 1 already recorded that the flag is worker-protocol rather than SDK surface. No drift.

Gates

just preflight → 0 failing pair(s), 3 skipped. plugins-embeddings [python] mutation → no surviving mutants — every mutation was caught (5 mutant(s) tested).

Changelog / Migrations

• Changelog fragment added under <root>/<pkg>/changelog.d/ for each changed package (or: skip-changelog trailer on a commit with reason)
• Migration fragment added under <root>/<pkg>/migrations.d/ (or: not required — additive/bugfix only)

plugins/dirsql-plugin-embeddings/migrations.d/2026-09-04-report-cache-hits.md. Nothing breaks and Required changes is _None._, but the trigger that fires is "changes runtime behavior without an API change": an ok line that read {"ok": [1.0, 0.0]} now reads {"ok": [1.0, 0.0], "meta": {"cached": false}}. dirsql ignores unknown keys, so this is additive for it — a third party doing exact-equality on the whole object is the one case that needs a line, and it gets one.

E2E Verification

• Ran e2e suites locally for every affected SDK
• Python SDK e2e: N/A — no packages/python change on this layer
• TypeScript SDK e2e: N/A — no packages/ts change on this layer
• Rust core e2e (if applicable): N/A — no packages/rust change on this layer
• packages/python/e2e-attestations/<branch>.json receipt written if packages/python changed (just e2e-attest-python) — not required, unchanged
• packages/ts/e2e-attestations/<branch>.json receipt written if packages/ts changed (just e2e-attest-ts) — not required, unchanged
• Command(s) run: uv run --with-editable ../../packages/python python -m pytest tests/e2e/ -x -q (plugin, via testing-conventions e2e attest); uv run --with-editable ../../packages/python python -m pytest tests/integration/ -q
• Result summary: e2e 17 passed, integration 49 passed. Receipt committed at plugins/dirsql-plugin-embeddings/e2e-attestations/claude-tackle-1034-plugin-flag.json.