dirsql 0.4.33__tar.gz → 0.4.35__tar.gz

{dirsql-0.4.33 → dirsql-0.4.35}/Cargo.lock

@@ -540,7 +540,7 @@ checksum = "6184e33543162437515c2e2b48714794e37845ec9851711914eec9d308f6ebe8"
 
 [[package]]
 name = "dirsql"
-version = "0.4.33"
+version = "0.4.35"
 dependencies = [
  "assert_cmd",
  "axum",
@@ -583,7 +583,7 @@ dependencies = [
 
 [[package]]
 name = "dirsql-py-ext"
-version = "0.4.33"
+version = "0.4.35"
 dependencies = [
  "dirsql",
  "pyo3",

{dirsql-0.4.33 → dirsql-0.4.35}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dirsql
-Version: 0.4.33
+Version: 0.4.35
 Requires-Dist: tomli>=2 ; python_full_version < '3.11'
 Requires-Dist: bin-shim>=0.1
 Summary: Ephemeral SQL index over a local directory

{dirsql-0.4.33 → dirsql-0.4.35}/docs/reference/cli.md

@@ -483,6 +483,42 @@ dirsql: indexed 41231 files in 3m12s
 
 stdout is untouched — it carries the query result and nothing else.
 
+A query gets the same treatment when it calls a
+[worker-backed function](./config.md#dirsql-function). Those cost one round
+trip per row, so a query that calls one over a whole corpus is the slowest
+thing dirsql does:
+
+```
+dirsql: running 9204 worker calls
+```
+
+and, when the query ends:
+
+```
+dirsql: ran 41231 worker calls in 2m41s
+```
+
+A worker that keeps a cache of its own can say so per response
+(`{"meta": {"cached": true}}` — see [Worker
+protocol](./config.md#worker-protocol)), and those round trips are then split
+out, because the number that answers *"will this be fast next time"* is not
+the total:
+
+```
+dirsql: running 9204 worker calls (8811 cached)
+dirsql: ran 41231 worker calls in 2m41s (38104 cached)
+```
+
+Both figures count **worker round trips, not rows**. A function declared
+`deterministic = true` lets SQLite reuse one answer for identical arguments
+within a query, so repeated content never reaches the worker at all and both
+numbers sit below the row count on a corpus with duplicates. The split covers
+only what the worker itself reports serving from cache. A worker that sends no
+`meta` gets the unsplit line above, not a `(0 cached)`.
+
+A query that calls no worker prints nothing, whatever the setting — the
+reporting only ever speaks when there is something to report.
+
 By default this is **terminal-only, and only for work slow enough to wonder
 about**: a phase that finishes in under half a second prints nothing at all,
 and a run whose stderr is a pipe or a file prints nothing regardless of how

{dirsql-0.4.33/packages/rust → dirsql-0.4.35}/docs/reference/config.md

@@ -133,6 +133,11 @@ process alive for the rest of the invocation, sending it every subsequent
 call — one process total, never one per row or per file. The worker is torn
 down when the invocation ends.
 
+A query paying per-row round trips reports them on stderr while it runs
+(`dirsql: running 9204 worker calls`), on the same terms as every other
+[progress line](./cli.md#progress-reporting): terminal-only by default, silent
+on a pipe, and gone before the result is printed.
+
 The `timeout` bounds each **round-trip call**, not the query: a query that
 calls the function on 10 000 rows is 10 000 individually timed calls. A call
 that times out, or a worker that crashes or closes its pipes, fails the query
@@ -156,6 +161,15 @@ request line in, one response line out, per call:
   JSON-text vectors) — or `{"err": "message"}`, which **fails the query**
   with that message. An `{"err": ...}` response leaves the healthy worker
   running; only transport failures (timeout, crash) recycle it.
+- **Optional `"meta"`**, alongside `"ok"`: a second top-level object carrying
+  facts about how the answer was produced rather than what it is. One key is
+  read today — `{"ok": [...], "meta": {"cached": true}}` says the worker
+  answered from a cache of its own, which dirsql reports as the `(N cached)`
+  split on its [worker-call progress line](./cli.md#progress-reporting). The
+  field is **optional and advisory**: a worker that omits it is a worker that
+  reports no cache hits, keys dirsql does not recognize are ignored (they
+  always have been), and a `meta` of an unexpected shape is ignored too rather
+  than failing a query over a progress counter.
 - **stderr passes through** to `dirsql`'s stderr, so a worker's progress
   bars and download logs reach the terminal.
 

{dirsql-0.4.33 → dirsql-0.4.35}/docs/reference/sdk.md

@@ -408,6 +408,10 @@ one summary of what each cost:
 dirsql: indexed 41231 files in 3m12s
 ```
 
+A `query` that calls a worker-backed function is reported the same way, as a
+running count of round trips (`dirsql: running 9204 worker calls`) — the shape
+`dirsql-plugin-embeddings` produces when it embeds a corpus one row at a time.
+
 This is terminal-only by default, and only for a phase that runs longer than
 half a second — a program whose stderr is a pipe, a file, or a log collector
 sees nothing, whatever the scan costs. Set `DIRSQL_PROGRESS=never` to

{dirsql-0.4.33 → dirsql-0.4.35}/packages/python/Cargo.toml

@@ -4,7 +4,7 @@ name = "dirsql-py-ext"
 # pypi/maturin handler can rewrite it via `write-version` before
 # `maturin build`. `pyproject.toml` declares `dynamic = ["version"]`
 # and maturin reads this field. Mirrors `packages/rust/Cargo.toml`.
-version = "0.4.33"
+version = "0.4.35"
 # abi3 note: the `abi3-py310` pyo3 feature (below) builds ONE stable-ABI
 # `cp310-abi3` wheel per platform that loads on every CPython >= 3.10
 # (matching `pyproject.toml`'s `requires-python = ">=3.10"`), instead of

{dirsql-0.4.33/packages/rust → dirsql-0.4.35/packages/python}/docs/reference/cli.md

@@ -483,6 +483,42 @@ dirsql: indexed 41231 files in 3m12s
 
 stdout is untouched — it carries the query result and nothing else.
 
+A query gets the same treatment when it calls a
+[worker-backed function](./config.md#dirsql-function). Those cost one round
+trip per row, so a query that calls one over a whole corpus is the slowest
+thing dirsql does:
+
+```
+dirsql: running 9204 worker calls
+```
+
+and, when the query ends:
+
+```
+dirsql: ran 41231 worker calls in 2m41s
+```
+
+A worker that keeps a cache of its own can say so per response
+(`{"meta": {"cached": true}}` — see [Worker
+protocol](./config.md#worker-protocol)), and those round trips are then split
+out, because the number that answers *"will this be fast next time"* is not
+the total:
+
+```
+dirsql: running 9204 worker calls (8811 cached)
+dirsql: ran 41231 worker calls in 2m41s (38104 cached)
+```
+
+Both figures count **worker round trips, not rows**. A function declared
+`deterministic = true` lets SQLite reuse one answer for identical arguments
+within a query, so repeated content never reaches the worker at all and both
+numbers sit below the row count on a corpus with duplicates. The split covers
+only what the worker itself reports serving from cache. A worker that sends no
+`meta` gets the unsplit line above, not a `(0 cached)`.
+
+A query that calls no worker prints nothing, whatever the setting — the
+reporting only ever speaks when there is something to report.
+
 By default this is **terminal-only, and only for work slow enough to wonder
 about**: a phase that finishes in under half a second prints nothing at all,
 and a run whose stderr is a pipe or a file prints nothing regardless of how

{dirsql-0.4.33 → dirsql-0.4.35/packages/python}/docs/reference/config.md

@@ -133,6 +133,11 @@ process alive for the rest of the invocation, sending it every subsequent
 call — one process total, never one per row or per file. The worker is torn
 down when the invocation ends.
 
+A query paying per-row round trips reports them on stderr while it runs
+(`dirsql: running 9204 worker calls`), on the same terms as every other
+[progress line](./cli.md#progress-reporting): terminal-only by default, silent
+on a pipe, and gone before the result is printed.
+
 The `timeout` bounds each **round-trip call**, not the query: a query that
 calls the function on 10 000 rows is 10 000 individually timed calls. A call
 that times out, or a worker that crashes or closes its pipes, fails the query
@@ -156,6 +161,15 @@ request line in, one response line out, per call:
   JSON-text vectors) — or `{"err": "message"}`, which **fails the query**
   with that message. An `{"err": ...}` response leaves the healthy worker
   running; only transport failures (timeout, crash) recycle it.
+- **Optional `"meta"`**, alongside `"ok"`: a second top-level object carrying
+  facts about how the answer was produced rather than what it is. One key is
+  read today — `{"ok": [...], "meta": {"cached": true}}` says the worker
+  answered from a cache of its own, which dirsql reports as the `(N cached)`
+  split on its [worker-call progress line](./cli.md#progress-reporting). The
+  field is **optional and advisory**: a worker that omits it is a worker that
+  reports no cache hits, keys dirsql does not recognize are ignored (they
+  always have been), and a `meta` of an unexpected shape is ignored too rather
+  than failing a query over a progress counter.
 - **stderr passes through** to `dirsql`'s stderr, so a worker's progress
   bars and download logs reach the terminal.
 

{dirsql-0.4.33/packages/rust → dirsql-0.4.35/packages/python}/docs/reference/sdk.md

@@ -408,6 +408,10 @@ one summary of what each cost:
 dirsql: indexed 41231 files in 3m12s
 ```
 
+A `query` that calls a worker-backed function is reported the same way, as a
+running count of round trips (`dirsql: running 9204 worker calls`) — the shape
+`dirsql-plugin-embeddings` produces when it embeds a corpus one row at a time.
+
 This is terminal-only by default, and only for a phase that runs longer than
 half a second — a program whose stderr is a pipe, a file, or a log collector
 sees nothing, whatever the scan costs. Set `DIRSQL_PROGRESS=never` to

dirsql-0.4.35/packages/python/e2e-attestations/claude-tackle-1034-cachesplit.json

@@ -0,0 +1,7 @@
+{
+  "command": "just test-e2e",
+  "ran_at": 1788557530,
+  "exit_code": 0,
+  "commit": "97fdc1dfbdf490f71bd2067d8be66a50dce22bcb",
+  "branch": "claude/tackle-1034-cachesplit"
+}

dirsql-0.4.35/packages/python/e2e-attestations/claude-tackle-957-lrm0z6-worker-calls.json

@@ -0,0 +1,7 @@
+{
+  "command": "uv run python -m pytest tests/e2e/ -x -q",
+  "ran_at": 1787263769,
+  "exit_code": 0,
+  "commit": "bced5b72c85b9c50073fd6326c1528326a1bd9d3",
+  "branch": "claude/tackle-957-lrm0z6-worker-calls"
+}

{dirsql-0.4.33 → dirsql-0.4.35}/packages/python/testing-conventions.toml

@@ -10,7 +10,7 @@
 extra_scope = ["packages/rust/src", "packages/python/src"]
 
 [python]
-one_function_per_file = { max_lines = 100 }
+one_function_per_file = { max_lines = 16 }
 
 # Same floor as the root file, which this lane no longer reads.
 [python.coverage]

{dirsql-0.4.33 → dirsql-0.4.35}/packages/rust/Cargo.toml

@@ -6,7 +6,7 @@ description = "Ephemeral SQL index over a local directory"
 # version stays for the binding crates (publish = false). The literal
 # intentionally lags the published version: putitoutthere rewrites it to
 # the planned release version at build time and never commits it back.
-version = "0.4.33"
+version = "0.4.35"
 edition.workspace = true
 # Literal `license` (not `license.workspace = true`) because
 # putitoutthere's preflight check reads `[package].license` directly

{dirsql-0.4.33/packages/python → dirsql-0.4.35/packages/rust}/docs/reference/cli.md

@@ -483,6 +483,42 @@ dirsql: indexed 41231 files in 3m12s
 
 stdout is untouched — it carries the query result and nothing else.
 
+A query gets the same treatment when it calls a
+[worker-backed function](./config.md#dirsql-function). Those cost one round
+trip per row, so a query that calls one over a whole corpus is the slowest
+thing dirsql does:
+
+```
+dirsql: running 9204 worker calls
+```
+
+and, when the query ends:
+
+```
+dirsql: ran 41231 worker calls in 2m41s
+```
+
+A worker that keeps a cache of its own can say so per response
+(`{"meta": {"cached": true}}` — see [Worker
+protocol](./config.md#worker-protocol)), and those round trips are then split
+out, because the number that answers *"will this be fast next time"* is not
+the total:
+
+```
+dirsql: running 9204 worker calls (8811 cached)
+dirsql: ran 41231 worker calls in 2m41s (38104 cached)
+```
+
+Both figures count **worker round trips, not rows**. A function declared
+`deterministic = true` lets SQLite reuse one answer for identical arguments
+within a query, so repeated content never reaches the worker at all and both
+numbers sit below the row count on a corpus with duplicates. The split covers
+only what the worker itself reports serving from cache. A worker that sends no
+`meta` gets the unsplit line above, not a `(0 cached)`.
+
+A query that calls no worker prints nothing, whatever the setting — the
+reporting only ever speaks when there is something to report.
+
 By default this is **terminal-only, and only for work slow enough to wonder
 about**: a phase that finishes in under half a second prints nothing at all,
 and a run whose stderr is a pipe or a file prints nothing regardless of how

{dirsql-0.4.33/packages/python → dirsql-0.4.35/packages/rust}/docs/reference/config.md

@@ -133,6 +133,11 @@ process alive for the rest of the invocation, sending it every subsequent
 call — one process total, never one per row or per file. The worker is torn
 down when the invocation ends.
 
+A query paying per-row round trips reports them on stderr while it runs
+(`dirsql: running 9204 worker calls`), on the same terms as every other
+[progress line](./cli.md#progress-reporting): terminal-only by default, silent
+on a pipe, and gone before the result is printed.
+
 The `timeout` bounds each **round-trip call**, not the query: a query that
 calls the function on 10 000 rows is 10 000 individually timed calls. A call
 that times out, or a worker that crashes or closes its pipes, fails the query
@@ -156,6 +161,15 @@ request line in, one response line out, per call:
   JSON-text vectors) — or `{"err": "message"}`, which **fails the query**
   with that message. An `{"err": ...}` response leaves the healthy worker
   running; only transport failures (timeout, crash) recycle it.
+- **Optional `"meta"`**, alongside `"ok"`: a second top-level object carrying
+  facts about how the answer was produced rather than what it is. One key is
+  read today — `{"ok": [...], "meta": {"cached": true}}` says the worker
+  answered from a cache of its own, which dirsql reports as the `(N cached)`
+  split on its [worker-call progress line](./cli.md#progress-reporting). The
+  field is **optional and advisory**: a worker that omits it is a worker that
+  reports no cache hits, keys dirsql does not recognize are ignored (they
+  always have been), and a `meta` of an unexpected shape is ignored too rather
+  than failing a query over a progress counter.
 - **stderr passes through** to `dirsql`'s stderr, so a worker's progress
   bars and download logs reach the terminal.
 

{dirsql-0.4.33/packages/python → dirsql-0.4.35/packages/rust}/docs/reference/sdk.md

@@ -408,6 +408,10 @@ one summary of what each cost:
 dirsql: indexed 41231 files in 3m12s
 ```
 
+A `query` that calls a worker-backed function is reported the same way, as a
+running count of round trips (`dirsql: running 9204 worker calls`) — the shape
+`dirsql-plugin-embeddings` produces when it embeds a corpus one row at a time.
+
 This is terminal-only by default, and only for a phase that runs longer than
 half a second — a program whose stderr is a pipe, a file, or a log collector
 sees nothing, whatever the scan costs. Set `DIRSQL_PROGRESS=never` to

{dirsql-0.4.33 → dirsql-0.4.35}/packages/rust/src/db.rs

@@ -1,8 +1,10 @@
 use rusqlite::Connection;
 use std::collections::{HashMap, HashSet};
 use std::path::{Path, PathBuf};
+use std::sync::Arc;
 use thiserror::Error;
 
+use crate::functions::CallReporter;
 use crate::parsed_vtab;
 use crate::path_table::{self, PathTable, Resolution};
 use crate::scanner;
@@ -264,6 +266,10 @@ pub struct Db {
     /// The persistent cache a parsed path-table reuses across runs. `None` for
     /// an ephemeral index, which has nowhere to cache to.
     path_table_cache: Option<PathBuf>,
+    /// Counts the worker round trips a query pays for. Shared with every
+    /// declared function registered on `conn`; inert until a function is both
+    /// declared and called.
+    calls: Arc<CallReporter>,
 }
 
 /// The skip rules a fresh `Db` starts with.
@@ -299,6 +305,7 @@ impl Db {
             path_table_gitignore: true,
             path_table_parser: None,
             path_table_cache: None,
+            calls: CallReporter::new(),
         })
     }
 
@@ -321,6 +328,7 @@ impl Db {
             path_table_gitignore: true,
             path_table_parser: None,
             path_table_cache: None,
+            calls: CallReporter::new(),
         })
     }
 
@@ -365,6 +373,12 @@ impl Db {
         self.path_table_cache = Some(path);
     }
 
+    /// The reporter every declared function increments. Handed to
+    /// `functions::register_all` at build time.
+    pub(crate) fn call_reporter(&self) -> &Arc<CallReporter> {
+        &self.calls
+    }
+
     /// Borrow the underlying SQLite connection. Internal use only — exposed
     /// to the `persist` module so it can manage the sidecar tables.
     #[doc(hidden)]
@@ -687,6 +701,12 @@ impl Db {
     /// internal writes (`insert_row`, delete-by-file, persist), which never go
     /// through `query()`, are unaffected.
     pub fn query(&self, sql: &str) -> Result<Vec<HashMap<String, Value>>> {
+        // Bracket the whole statement, prepare included: a worker-backed
+        // function called on every row makes this the slowest thing dirsql
+        // does, and the guard is what erases the counter before the caller
+        // prints the rows.
+        let _calls = self.calls.phase();
+
         // Each iteration must register a table no earlier iteration did; a
         // repeat means the fallback is not making progress, so the SQLite
         // error stands. That is what bounds the loop.