[thekevinbot]

Both layers of #1034. This PR opened as layer 1 of a two-PR stack (core only), and the stack collapsed into it: layer 2 (#1038, the embeddings plugin) was merged into this branch, not into main. So the diff below carries the core change and the plugin change, and this PR alone closes the issue.

Fixes #1034

Layer 1 — core (this branch's own commits)

What

A worker may now flag a response it served from a cache of its own:

{"ok": [0.1, 0.2], "meta": {"cached": true}}

and dirsql splits those out of the worker-call progress line:

dirsql: running 9204 worker calls (8811 cached)
dirsql: ran 41231 worker calls in 2m41s (38104 cached)

Why the field is on the worker, and why it is generic

Core counts round trips, and a cache hit is a round trip — the worker is asked and answers from disk. Core cannot see the difference, so the worker has to say. The flag is deliberately not embedding-shaped: any [[dirsql.function]] may set it, which keeps #1002's property that core knows nothing about what its workers do.

meta is advisory. It feeds a progress counter and nothing else, so an absent field, a non-object meta, or a non-boolean cached all read as "not cached" rather than failing a query. A worker that flags nothing gets exactly the line it got before — there is no (0 cached).

Wire compatibility

parse_response has always read err, else ok, and ignored every other key, so an existing worker is unaffected byte-for-byte. The break is in the documented contract, which enumerated the response shape exhaustively in two places that moved together here: docs/reference/config.md's "Worker protocol" and the ## Protocol block in packages/rust/src/functions.rs.

Precision note (documented)

docs/reference/cli.md now says in one sentence that both figures count worker round trips, not rows: a deterministic = true function lets SQLite reuse an answer for identical arguments within a query, so repeated content never reaches the worker and both numbers sit below the row count on a corpus with duplicates.

Design note: where the count is taken

record() still fires before the call, so a slow worker's first round trip still puts a line on screen while it is in flight — that is the whole point of #1002's counter. Cachedness is only knowable once the response is in hand, so it is a second, separate mark_cached() after the call returns. The total count is therefore unchanged, including for calls that fail.

Red/green

• RED commit 93e7870, Rust CI run 33920999219 — the Integration tests job, tests/worker_call_progress_e2e.rs: the_summary_splits_out_the_calls_the_worker_served_from_cache and the_summary_counts_only_the_flagged_calls_as_cached both FAILED, on the asserted strings (and names how many of them cost nothing: "…dirsql: ran 4 worker calls in 0.0s\n"). 7 passed, 2 failed — nothing else in the workspace broke, no compile error.
• GREEN commit 97fdc1d carries the implementation, the unit tests, the docs and the fragments.

The red is at the e2e tier by necessity: the new behavior is a line on the CLI's stderr, which the Rust SDK integration tier cannot observe. The integration tier (packages/rust/tests/functions.rs) carries the two guards it can assert — that a meta-carrying response binds only its ok value, and that an unrecognized meta shape does not fail the query.

Manual verification

A worker that caches by value, called twice per row over three files (the function is not deterministic, so SQLite makes all six calls):

$ cd /tmp/dirsql-1034-manual
$ DIRSQL_PROGRESS=always dirsql query \
    "SELECT shout(basename) AS a, shout(basename) AS b FROM './*.txt' ORDER BY a" \
    -c .dirsql.toml
dirsql: running 1 worker calls                              dirsql: ran 6 worker calls in 0.0s (3 cached)
[{"a":"A.TXT","b":"A.TXT"},{"a":"B.TXT","b":"B.TXT"},{"a":"C.TXT","b":"C.TXT"}]

Six round trips, three of them the worker's second sighting of a value, reported as (3 cached). stdout is untouched JSON.

Layer 2 — embeddings plugin (merged in from #1038)

#1038 was reviewed and merged on 2026-09-04 with base: claude/tackle-1034-cachesplit, so its three commits (fc85500, f4ee741, 6da2c8f) are ancestors of this branch's head and appear in this PR's diff against main. Its own description is preserved on #1038; the essentials:

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 layer 1's protocol defines: {"ok": [0.12, ...], "meta": {"cached": true}}. handle gained an _embed_response extraction so it stays under the 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.

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/green

RED on the plugin layer: run 33922087464, dirsql-plugin-embeddings integration tests (3.12) and (3.13) — assert response["meta"] == {"cached": False} → KeyError: 'meta', 1 failed, 8 passed. GREEN in f4ee741.

Manual verification

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:

# cold
dirsql: ran 5 worker calls in 3.3s
# warm
dirsql: ran 5 worker calls in 0.3s (5 cached)

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

E2E Verification

Covers both layers. Layer 1's suites were run on this branch; layer 2's on claude/tackle-1034-plugin-flag before it merged in.

• Ran e2e suites locally for every affected SDK
• Python SDK e2e: pass (37 passed)
• TypeScript SDK e2e: pass (16 passed across 5 files)
• Rust core e2e (if applicable): pass (cargo test --features cli --tests, whole workspace green; worker_call_progress_e2e 9 passed)
• Plugin (plugins/dirsql-plugin-embeddings) e2e: pass (17 passed; integration 49 passed)
• packages/python/e2e-attestations/<branch>.json receipt written if packages/python changed (just e2e-attest-python)
• packages/ts/e2e-attestations/<branch>.json receipt written if packages/ts changed (just e2e-attest-ts)
• Command(s) run: cargo test --manifest-path packages/rust/Cargo.toml --features cli --lib, … --tests, just e2e-attest-python, just e2e-attest-ts, just preflight; plugin: uv run --with-editable ../../packages/python python -m pytest tests/e2e/ -x -q via testing-conventions e2e attest
• Result summary: 823 unit / all integration + e2e green; just preflight reports 0 failing pairs, 3 skipped; unit mutation on rust tested 27 mutants with no survivors, on the plugin 5 with no survivors.

Three receipts ride in the diff, one per package whose scoped source the combined change touches — a packages/rust/src change puts both bindings in scope via [e2e].extra_scope, and the plugin change puts the plugin in scope:

added  packages/python/e2e-attestations/claude-tackle-1034-cachesplit.json
added  packages/ts/e2e-attestations/claude-tackle-1034-cachesplit.json
added  plugins/dirsql-plugin-embeddings/e2e-attestations/claude-tackle-1034-plugin-flag.json

Changelog / Migrations

• Changelog fragment added under <root>/<pkg>/changelog.d/ for each changed package — packages/rust/changelog.d/2026-09-04-worker-call-cache-split.md and plugins/dirsql-plugin-embeddings/changelog.d/2026-09-04-report-cache-hits.md
• Migration fragment added under <root>/<pkg>/migrations.d/ — packages/rust/migrations.d/2026-09-04-worker-call-cache-split.md and plugins/dirsql-plugin-embeddings/migrations.d/2026-09-04-report-cache-hits.md

Migration-fragment decision: yes, written, for both packages. Nothing here is breaking, and both "Required changes" sections say so explicitly (_None._). They are written anyway because two of AGENTS.md's triggers fire: the worker response shape is documented public contract, and the summary line's format changes at runtime with no API change. #1002 set the precedent by shipping one for a purely additive progress line. The core fragment's value is its "Behavior changes without code changes" section — a worker that already emitted a top-level meta for its own reasons now has meta.cached read by dirsql. The plugin fragment covers the mirror case: an ok line that read {"ok": [1.0, 0.0]} now reads {"ok": [1.0, 0.0], "meta": {"cached": false}}, which matters only to a third party doing exact-equality on the whole object.

Parity

PARITY.md updated. No drift. The flag is part of the worker protocol, not any SDK's API surface — no SDK gained or lost a symbol, and both the parsing and the line live in the shared core, so all three SDKs change in this commit. The plugin exports no Python API (__init__.py is empty) and adds nothing to any SDK surface.