dirsql 0.4.30__tar.gz → 0.4.32__tar.gz

{dirsql-0.4.30 → dirsql-0.4.32}/Cargo.lock

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

{dirsql-0.4.30 → dirsql-0.4.32}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dirsql
-Version: 0.4.30
+Version: 0.4.32
 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.30/packages/rust → dirsql-0.4.32}/docs/howto/search-by-meaning.md

@@ -3,10 +3,10 @@
 Ask a question in plain language and get the closest documents back — even
 when they share no keywords with it. Install
 [`dirsql-plugin-embeddings`](../plugins.md#dirsql-plugin-embeddings) and
-semantic search becomes plain SQL: the plugin's `embed()` function turns
-text into vectors, [`sqlite-vec`](https://github.com/asg017/sqlite-vec)'s
-`vec_distance_cosine()` measures distance, and `ORDER BY … LIMIT` does the
-ranking. No config, no API keys, no services — the model runs locally.
+semantic search becomes plain SQL: the plugin's `embed()` function turns text
+into vectors and loads [`sqlite-vec`](https://github.com/asg017/sqlite-vec),
+which does the distance math. No API keys, no services — the model runs
+locally.
 
 Suppose short notes live in `notes/*.md`:
 
@@ -40,7 +40,32 @@ The first-ever run downloads the model (on the order of a hundred megabytes,
 with progress on stderr); after that it loads from the local cache. Results
 print one `path<TAB>distance` line per match, closest first.
 
-## The SQL behind it
+## Which shape
+
+The one-liner embeds every matched file on every run. That is the right trade
+for a question you ask once, and the wrong one for a corpus you search
+repeatedly — where a stored [`vec0` index](./search-indexes.md#vector-search-vec0)
+embeds each file once, at ingest, and a query embeds only the question:
+
+| | This page: path-table | [Vector index](./search-indexes.md#vector-search-vec0) |
+|---|---|---|
+| Setup | none | a `[[table]]` with a `ddl` batch |
+| Freshness | always current — the walk is the read | watcher-maintained; survives restarts under [`--persist`](./persist.md) |
+| Per query | one `embed()` round trip **per matched file**, plus a walk that reads every file's content | one `embed()` round trip **total**, plus an in-process KNN scan |
+| Top-k | `ORDER BY … LIMIT k` | `MATCH … AND k = …` |
+| Good for | a one-off question, a small corpus, an ad-hoc glob | a corpus you query repeatedly |
+
+The index only pays off when the table outlives the query — under `--persist`,
+or inside a long-running [`dirsql server`](../reference/cli.md). A one-shot
+`dirsql query` against an ephemeral index rebuilds the table, and therefore
+re-embeds the corpus, before it answers; that is strictly more work than the
+subquery below. The full recipe — the width probe, the `ddl` batch, both
+triggers, and what a model-id edit costs — is
+[Add a search index to a table](./search-indexes.md#vector-search-vec0).
+
+The rest of this page is the zero-setup shape.
+
+## The SQL behind the one-liner
 
 The one-liner generates and runs ordinary `dirsql` SQL, and you can write it
 yourself when you want more than ranked paths — a different projection, a
@@ -79,7 +104,9 @@ Reading the query inside-out:
    and its distance are NULL too — and SQLite sorts NULLs *first* ascending,
    so without this line the unrankable files take the top-k slots.
 4. `vec_distance_cosine(...)` computes cosine distance between the two
-   vectors; `ORDER BY distance LIMIT 3` keeps the three nearest.
+   vectors; `ORDER BY distance LIMIT 3` keeps the three nearest. There is no
+   `vec0` table here, so `sqlite-vec`'s `MATCH … AND k = …` does not apply —
+   for a plain expression, `ORDER BY … LIMIT k` *is* its documented top-k.
 
 Structured files compose with SQL's JSON operators — embed one field instead
 of the whole file:
@@ -93,24 +120,19 @@ ORDER BY vec_distance_cosine(emb, embed('local private models'))
 LIMIT 10
 ```
 
-::: tip Top-k is `LIMIT k`
-If you know `sqlite-vec` you may reach for its `MATCH … AND k = 10` idiom.
-That syntax belongs to `sqlite-vec`'s `vec0` virtual table, which the table
-above does not use: a `[[table]]`'s own `name` is always a per-file row table.
-For plain expressions, `sqlite-vec`'s own documented pattern is exactly what
-this guide uses: `ORDER BY vec_distance_cosine(...) LIMIT k`. To get the `vec0`
-idiom instead, declare the `vec0` table alongside the row table in the same
-[`ddl` batch](../reference/config.md#batch-ddl) and fill it from a trigger.
-:::
+The same projection works as an `on-file` hook feeding the indexed shape:
+parse the field in the hook, store it as a column, and the trigger embeds it
+once instead of on every query.
 
 ## Repeat runs are cheap
 
 Computed vectors are cached on disk, keyed on content and model
 ([vector cache](../plugins.md#vector-cache)) — re-running a search over
-unchanged files skips the model entirely and re-embeds only what changed.
-And the plugin costs nothing when idle: a query that never calls `embed()`
-spawns no worker and loads no model
-([zero cost when unused](../plugins.md#zero-cost-when-unused)).
+unchanged files skips the model entirely and re-embeds only what changed. That
+takes the *inference* out of the shape above, but not the walk or the per-file
+round trip; only a stored index removes those. And the plugin costs nothing
+when idle: a query that never calls `embed()` spawns no worker and loads no
+model ([zero cost when unused](../plugins.md#zero-cost-when-unused)).
 
 ## How `embed()` gets into SQL
 

{dirsql-0.4.30/packages/rust → dirsql-0.4.32}/docs/howto/search-indexes.md

@@ -155,8 +155,10 @@ ddl     = '''
 CREATE TABLE notes (slug TEXT, title TEXT, body TEXT);
 
 -- Width must equal what the probe printed for the model id named below.
-CREATE VIRTUAL TABLE notes_vec USING vec0(embedding float[512]);
-CREATE TRIGGER notes_vi AFTER INSERT ON notes BEGIN
+CREATE VIRTUAL TABLE notes_vec
+  USING vec0(embedding float[512] distance_metric=cosine);
+CREATE TRIGGER notes_vi AFTER INSERT ON notes
+WHEN new.body IS NOT NULL BEGIN
   INSERT INTO notes_vec(rowid, embedding)
     VALUES (new.rowid, embed(new.body, 'minishlab/potion-retrieval-32M'));
 END;
@@ -169,6 +171,29 @@ END;
 The delete side is an ordinary `DELETE`, not FTS5's `'delete'` command row —
 `vec0` is a normal-looking table that way.
 
+Two clauses in there are load-bearing:
+
+- **`distance_metric=cosine`.** `vec0` defaults to L2, which is not the metric
+  the rest of dirsql's semantic search uses — `vec_distance_cosine()` backs
+  both the plugin's one-liner and
+  [Search documents by meaning](./search-by-meaning.md). The two agree only for
+  vectors of equal length, so as soon as documents embed to vectors of
+  different magnitude they rank differently: against three notes, L2 returned
+  `a, c, b` where cosine returned `a, b, c`. Declaring the metric makes
+  `distance` the number `vec_distance_cosine()` would compute.
+- **`WHEN new.body IS NOT NULL`.** `embed(NULL)` is `NULL`, and `vec0` rejects
+  a NULL vector outright — so without the guard a single row whose text is
+  missing fails the **whole** table load, not just its own insert:
+
+  ```
+  dirsql query: failed to load config: SQLite error: Inserted vector for the
+  "embedding" column is invalid: Input must have type BLOB (compact format) or
+  TEXT (JSON), found NULL
+  ```
+
+  With it, that row still lands in `notes`; only its vector is skipped. FTS5
+  needs no such guard — it indexes a NULL happily.
+
 Query it with `sqlite-vec`'s KNN form, joined back on `rowid`:
 
 ```bash

{dirsql-0.4.30 → dirsql-0.4.32}/docs/reference/cli.md

@@ -460,3 +460,47 @@ Turn discovery off with either:
 
 A plugin that declares itself but is missing its module or its `dirsql.toml`
 fragment is a launcher error naming the package — never a silent skip.
+
+## Progress reporting
+
+Building the index over a large tree is not instant: the walk visits every
+file, then each matched file costs one `on-file` round trip plus whatever the
+table's `ddl` fires on insert. On a big corpus that is minutes. dirsql reports
+the two phases on **stderr** while they run:
+
+```
+dirsql: scanning 128413 files
+dirsql: indexing 9204/41231 files (22%)
+```
+
+Each line is rewritten in place. When a phase ends its line is erased and
+replaced by one summary of what it cost:
+
+```
+dirsql: scanned 128413 files in 4.2s
+dirsql: indexed 41231 files in 3m12s
+```
+
+stdout is untouched — it carries the query result and nothing else.
+
+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
+long it takes. `dirsql "…" 2>run.log` and `dirsql "…" | jq` are byte-for-byte
+what they were before.
+
+Override with `DIRSQL_PROGRESS`:
+
+| Value | Effect |
+|---|---|
+| unset, or `auto` | Report only on a terminal, and only once a phase has run for half a second. The default. |
+| `always`, `1`, `true` | Report from the first update, terminal or not. Use it to watch a scan whose stderr is redirected. |
+| `never`, `0`, `false` | Report nothing, ever. |
+
+Values are case-insensitive and surrounding whitespace is ignored; anything
+unrecognized reads as `auto`, so a typo cannot stop a scan from running.
+
+The setting is read by the **core**, not the CLI, so it governs an index built
+from any SDK as well — a Python or TypeScript program that builds a `DirSQL`
+with a terminal attached gets the same two phases on stderr, and the same
+silence when piped.

{dirsql-0.4.30 → dirsql-0.4.32}/docs/reference/sdk.md

@@ -396,3 +396,22 @@ not fit that range is a hard error, not a lossy conversion: Python raises
 A TypeScript `bigint` **within** `i64` range maps to `INTEGER`. Only a real
 `bytes`/`bytearray` (Python) or `Buffer`/`Uint8Array` (TypeScript) maps to
 `BLOB` — a list/array of integers does not.
+
+## Progress on construction
+
+Constructing a `DirSQL` walks the tree and ingests every matched file, which
+on a large corpus is the slowest thing your program does. The core reports
+both phases on **stderr** while they run, then erases the live line and leaves
+one summary of what each cost:
+
+```
+dirsql: indexed 41231 files in 3m12s
+```
+
+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
+guarantee silence even on a terminal, or `DIRSQL_PROGRESS=always` to report
+regardless. The full table is in the
+[CLI reference](cli.md#progress-reporting); the setting lives in the shared
+core, so it behaves identically from all three SDKs.

{dirsql-0.4.30 → dirsql-0.4.32}/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.30"
+version = "0.4.32"
 # 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.30 → dirsql-0.4.32/packages/python}/docs/howto/search-by-meaning.md

@@ -3,10 +3,10 @@
 Ask a question in plain language and get the closest documents back — even
 when they share no keywords with it. Install
 [`dirsql-plugin-embeddings`](../plugins.md#dirsql-plugin-embeddings) and
-semantic search becomes plain SQL: the plugin's `embed()` function turns
-text into vectors, [`sqlite-vec`](https://github.com/asg017/sqlite-vec)'s
-`vec_distance_cosine()` measures distance, and `ORDER BY … LIMIT` does the
-ranking. No config, no API keys, no services — the model runs locally.
+semantic search becomes plain SQL: the plugin's `embed()` function turns text
+into vectors and loads [`sqlite-vec`](https://github.com/asg017/sqlite-vec),
+which does the distance math. No API keys, no services — the model runs
+locally.
 
 Suppose short notes live in `notes/*.md`:
 
@@ -40,7 +40,32 @@ The first-ever run downloads the model (on the order of a hundred megabytes,
 with progress on stderr); after that it loads from the local cache. Results
 print one `path<TAB>distance` line per match, closest first.
 
-## The SQL behind it
+## Which shape
+
+The one-liner embeds every matched file on every run. That is the right trade
+for a question you ask once, and the wrong one for a corpus you search
+repeatedly — where a stored [`vec0` index](./search-indexes.md#vector-search-vec0)
+embeds each file once, at ingest, and a query embeds only the question:
+
+| | This page: path-table | [Vector index](./search-indexes.md#vector-search-vec0) |
+|---|---|---|
+| Setup | none | a `[[table]]` with a `ddl` batch |
+| Freshness | always current — the walk is the read | watcher-maintained; survives restarts under [`--persist`](./persist.md) |
+| Per query | one `embed()` round trip **per matched file**, plus a walk that reads every file's content | one `embed()` round trip **total**, plus an in-process KNN scan |
+| Top-k | `ORDER BY … LIMIT k` | `MATCH … AND k = …` |
+| Good for | a one-off question, a small corpus, an ad-hoc glob | a corpus you query repeatedly |
+
+The index only pays off when the table outlives the query — under `--persist`,
+or inside a long-running [`dirsql server`](../reference/cli.md). A one-shot
+`dirsql query` against an ephemeral index rebuilds the table, and therefore
+re-embeds the corpus, before it answers; that is strictly more work than the
+subquery below. The full recipe — the width probe, the `ddl` batch, both
+triggers, and what a model-id edit costs — is
+[Add a search index to a table](./search-indexes.md#vector-search-vec0).
+
+The rest of this page is the zero-setup shape.
+
+## The SQL behind the one-liner
 
 The one-liner generates and runs ordinary `dirsql` SQL, and you can write it
 yourself when you want more than ranked paths — a different projection, a
@@ -79,7 +104,9 @@ Reading the query inside-out:
    and its distance are NULL too — and SQLite sorts NULLs *first* ascending,
    so without this line the unrankable files take the top-k slots.
 4. `vec_distance_cosine(...)` computes cosine distance between the two
-   vectors; `ORDER BY distance LIMIT 3` keeps the three nearest.
+   vectors; `ORDER BY distance LIMIT 3` keeps the three nearest. There is no
+   `vec0` table here, so `sqlite-vec`'s `MATCH … AND k = …` does not apply —
+   for a plain expression, `ORDER BY … LIMIT k` *is* its documented top-k.
 
 Structured files compose with SQL's JSON operators — embed one field instead
 of the whole file:
@@ -93,24 +120,19 @@ ORDER BY vec_distance_cosine(emb, embed('local private models'))
 LIMIT 10
 ```
 
-::: tip Top-k is `LIMIT k`
-If you know `sqlite-vec` you may reach for its `MATCH … AND k = 10` idiom.
-That syntax belongs to `sqlite-vec`'s `vec0` virtual table, which the table
-above does not use: a `[[table]]`'s own `name` is always a per-file row table.
-For plain expressions, `sqlite-vec`'s own documented pattern is exactly what
-this guide uses: `ORDER BY vec_distance_cosine(...) LIMIT k`. To get the `vec0`
-idiom instead, declare the `vec0` table alongside the row table in the same
-[`ddl` batch](../reference/config.md#batch-ddl) and fill it from a trigger.
-:::
+The same projection works as an `on-file` hook feeding the indexed shape:
+parse the field in the hook, store it as a column, and the trigger embeds it
+once instead of on every query.
 
 ## Repeat runs are cheap
 
 Computed vectors are cached on disk, keyed on content and model
 ([vector cache](../plugins.md#vector-cache)) — re-running a search over
-unchanged files skips the model entirely and re-embeds only what changed.
-And the plugin costs nothing when idle: a query that never calls `embed()`
-spawns no worker and loads no model
-([zero cost when unused](../plugins.md#zero-cost-when-unused)).
+unchanged files skips the model entirely and re-embeds only what changed. That
+takes the *inference* out of the shape above, but not the walk or the per-file
+round trip; only a stored index removes those. And the plugin costs nothing
+when idle: a query that never calls `embed()` spawns no worker and loads no
+model ([zero cost when unused](../plugins.md#zero-cost-when-unused)).
 
 ## How `embed()` gets into SQL
 

{dirsql-0.4.30 → dirsql-0.4.32/packages/python}/docs/howto/search-indexes.md

@@ -155,8 +155,10 @@ ddl     = '''
 CREATE TABLE notes (slug TEXT, title TEXT, body TEXT);
 
 -- Width must equal what the probe printed for the model id named below.
-CREATE VIRTUAL TABLE notes_vec USING vec0(embedding float[512]);
-CREATE TRIGGER notes_vi AFTER INSERT ON notes BEGIN
+CREATE VIRTUAL TABLE notes_vec
+  USING vec0(embedding float[512] distance_metric=cosine);
+CREATE TRIGGER notes_vi AFTER INSERT ON notes
+WHEN new.body IS NOT NULL BEGIN
   INSERT INTO notes_vec(rowid, embedding)
     VALUES (new.rowid, embed(new.body, 'minishlab/potion-retrieval-32M'));
 END;
@@ -169,6 +171,29 @@ END;
 The delete side is an ordinary `DELETE`, not FTS5's `'delete'` command row —
 `vec0` is a normal-looking table that way.
 
+Two clauses in there are load-bearing:
+
+- **`distance_metric=cosine`.** `vec0` defaults to L2, which is not the metric
+  the rest of dirsql's semantic search uses — `vec_distance_cosine()` backs
+  both the plugin's one-liner and
+  [Search documents by meaning](./search-by-meaning.md). The two agree only for
+  vectors of equal length, so as soon as documents embed to vectors of
+  different magnitude they rank differently: against three notes, L2 returned
+  `a, c, b` where cosine returned `a, b, c`. Declaring the metric makes
+  `distance` the number `vec_distance_cosine()` would compute.
+- **`WHEN new.body IS NOT NULL`.** `embed(NULL)` is `NULL`, and `vec0` rejects
+  a NULL vector outright — so without the guard a single row whose text is
+  missing fails the **whole** table load, not just its own insert:
+
+  ```
+  dirsql query: failed to load config: SQLite error: Inserted vector for the
+  "embedding" column is invalid: Input must have type BLOB (compact format) or
+  TEXT (JSON), found NULL
+  ```
+
+  With it, that row still lands in `notes`; only its vector is skipped. FTS5
+  needs no such guard — it indexes a NULL happily.
+
 Query it with `sqlite-vec`'s KNN form, joined back on `rowid`:
 
 ```bash

{dirsql-0.4.30/packages/rust → dirsql-0.4.32/packages/python}/docs/reference/cli.md

@@ -460,3 +460,47 @@ Turn discovery off with either:
 
 A plugin that declares itself but is missing its module or its `dirsql.toml`
 fragment is a launcher error naming the package — never a silent skip.
+
+## Progress reporting
+
+Building the index over a large tree is not instant: the walk visits every
+file, then each matched file costs one `on-file` round trip plus whatever the
+table's `ddl` fires on insert. On a big corpus that is minutes. dirsql reports
+the two phases on **stderr** while they run:
+
+```
+dirsql: scanning 128413 files
+dirsql: indexing 9204/41231 files (22%)
+```
+
+Each line is rewritten in place. When a phase ends its line is erased and
+replaced by one summary of what it cost:
+
+```
+dirsql: scanned 128413 files in 4.2s
+dirsql: indexed 41231 files in 3m12s
+```
+
+stdout is untouched — it carries the query result and nothing else.
+
+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
+long it takes. `dirsql "…" 2>run.log` and `dirsql "…" | jq` are byte-for-byte
+what they were before.
+
+Override with `DIRSQL_PROGRESS`:
+
+| Value | Effect |
+|---|---|
+| unset, or `auto` | Report only on a terminal, and only once a phase has run for half a second. The default. |
+| `always`, `1`, `true` | Report from the first update, terminal or not. Use it to watch a scan whose stderr is redirected. |
+| `never`, `0`, `false` | Report nothing, ever. |
+
+Values are case-insensitive and surrounding whitespace is ignored; anything
+unrecognized reads as `auto`, so a typo cannot stop a scan from running.
+
+The setting is read by the **core**, not the CLI, so it governs an index built
+from any SDK as well — a Python or TypeScript program that builds a `DirSQL`
+with a terminal attached gets the same two phases on stderr, and the same
+silence when piped.

{dirsql-0.4.30/packages/rust → dirsql-0.4.32/packages/python}/docs/reference/sdk.md

@@ -396,3 +396,22 @@ not fit that range is a hard error, not a lossy conversion: Python raises
 A TypeScript `bigint` **within** `i64` range maps to `INTEGER`. Only a real
 `bytes`/`bytearray` (Python) or `Buffer`/`Uint8Array` (TypeScript) maps to
 `BLOB` — a list/array of integers does not.
+
+## Progress on construction
+
+Constructing a `DirSQL` walks the tree and ingests every matched file, which
+on a large corpus is the slowest thing your program does. The core reports
+both phases on **stderr** while they run, then erases the live line and leaves
+one summary of what each cost:
+
+```
+dirsql: indexed 41231 files in 3m12s
+```
+
+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
+guarantee silence even on a terminal, or `DIRSQL_PROGRESS=always` to report
+regardless. The full table is in the
+[CLI reference](cli.md#progress-reporting); the setting lives in the shared
+core, so it behaves identically from all three SDKs.

dirsql-0.4.32/packages/python/e2e-attestations/claude-tackle-957-lrm0z6.json

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

dirsql-0.4.32/packages/python/e2e-attestations/claude-tackle-975-n8mc2h.json

@@ -0,0 +1,7 @@
+{
+  "command": "uv run python -m pytest tests/e2e/ -x -q",
+  "ran_at": 1787287690,
+  "exit_code": 0,
+  "commit": "8e3939201856c8bcaf2b7c2c951371711c753dbb",
+  "branch": "claude/tackle-975-n8mc2h"
+}

dirsql-0.4.32/packages/python/testing-conventions.toml

@@ -0,0 +1,34 @@
+# Per-package config so `[e2e]` can be per-package: it is one global table
+# applied to every caller reading a given config, so "the core plus MY binding"
+# has nowhere else to live. Folded back into the root file, a napi change would
+# start staling this package.
+#
+# The PyO3 glue is in scope because the console script runs the CLI in-process
+# through it (#721), so every e2e case crosses it. packages/ts/napi is not: it
+# cannot reach this suite.
+[e2e]
+extra_scope = ["packages/rust/src", "packages/python/src"]
+
+[python]
+one_function_per_file = { max_lines = 100 }
+
+# Same floor as the root file, which this lane no longer reads.
+[python.coverage]
+fail_under = 100
+branch = true
+
+# The hermetic integration tier is defined by patching the first-party core
+# boundary: `dirsql._async._RustDirSQL` is the PyO3 class, and replacing it is
+# what lets these tests run SQLite-free and native-build-free. There is no
+# third-party target to re-root onto, so `no-first-party-patch` has nothing to
+# say about this seam. Every other patch in both files targets stdlib and stays
+# gated.
+[[python.exempt]]
+path = "tests/integration/hermetic/dirsql_test.py"
+rules = ["no-first-party-patch"]
+reason = "the hermetic tier IS the _RustDirSQL core-boundary patch; no third-party target exists to move it to"
+
+[[python.exempt]]
+path = "tests/integration/hermetic/extensions_test.py"
+rules = ["no-first-party-patch"]
+reason = "the hermetic tier IS the _RustDirSQL core-boundary patch; no third-party target exists to move it to"

{dirsql-0.4.30 → dirsql-0.4.32}/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.30"
+version = "0.4.32"
 edition.workspace = true
 # Literal `license` (not `license.workspace = true`) because
 # putitoutthere's preflight check reads `[package].license` directly

{dirsql-0.4.30/packages/python → dirsql-0.4.32/packages/rust}/docs/howto/search-by-meaning.md

@@ -3,10 +3,10 @@
 Ask a question in plain language and get the closest documents back — even
 when they share no keywords with it. Install
 [`dirsql-plugin-embeddings`](../plugins.md#dirsql-plugin-embeddings) and
-semantic search becomes plain SQL: the plugin's `embed()` function turns
-text into vectors, [`sqlite-vec`](https://github.com/asg017/sqlite-vec)'s
-`vec_distance_cosine()` measures distance, and `ORDER BY … LIMIT` does the
-ranking. No config, no API keys, no services — the model runs locally.
+semantic search becomes plain SQL: the plugin's `embed()` function turns text
+into vectors and loads [`sqlite-vec`](https://github.com/asg017/sqlite-vec),
+which does the distance math. No API keys, no services — the model runs
+locally.
 
 Suppose short notes live in `notes/*.md`:
 
@@ -40,7 +40,32 @@ The first-ever run downloads the model (on the order of a hundred megabytes,
 with progress on stderr); after that it loads from the local cache. Results
 print one `path<TAB>distance` line per match, closest first.
 
-## The SQL behind it
+## Which shape
+
+The one-liner embeds every matched file on every run. That is the right trade
+for a question you ask once, and the wrong one for a corpus you search
+repeatedly — where a stored [`vec0` index](./search-indexes.md#vector-search-vec0)
+embeds each file once, at ingest, and a query embeds only the question:
+
+| | This page: path-table | [Vector index](./search-indexes.md#vector-search-vec0) |
+|---|---|---|
+| Setup | none | a `[[table]]` with a `ddl` batch |
+| Freshness | always current — the walk is the read | watcher-maintained; survives restarts under [`--persist`](./persist.md) |
+| Per query | one `embed()` round trip **per matched file**, plus a walk that reads every file's content | one `embed()` round trip **total**, plus an in-process KNN scan |
+| Top-k | `ORDER BY … LIMIT k` | `MATCH … AND k = …` |
+| Good for | a one-off question, a small corpus, an ad-hoc glob | a corpus you query repeatedly |
+
+The index only pays off when the table outlives the query — under `--persist`,
+or inside a long-running [`dirsql server`](../reference/cli.md). A one-shot
+`dirsql query` against an ephemeral index rebuilds the table, and therefore
+re-embeds the corpus, before it answers; that is strictly more work than the
+subquery below. The full recipe — the width probe, the `ddl` batch, both
+triggers, and what a model-id edit costs — is
+[Add a search index to a table](./search-indexes.md#vector-search-vec0).
+
+The rest of this page is the zero-setup shape.
+
+## The SQL behind the one-liner
 
 The one-liner generates and runs ordinary `dirsql` SQL, and you can write it
 yourself when you want more than ranked paths — a different projection, a
@@ -79,7 +104,9 @@ Reading the query inside-out:
    and its distance are NULL too — and SQLite sorts NULLs *first* ascending,
    so without this line the unrankable files take the top-k slots.
 4. `vec_distance_cosine(...)` computes cosine distance between the two
-   vectors; `ORDER BY distance LIMIT 3` keeps the three nearest.
+   vectors; `ORDER BY distance LIMIT 3` keeps the three nearest. There is no
+   `vec0` table here, so `sqlite-vec`'s `MATCH … AND k = …` does not apply —
+   for a plain expression, `ORDER BY … LIMIT k` *is* its documented top-k.
 
 Structured files compose with SQL's JSON operators — embed one field instead
 of the whole file:
@@ -93,24 +120,19 @@ ORDER BY vec_distance_cosine(emb, embed('local private models'))
 LIMIT 10
 ```
 
-::: tip Top-k is `LIMIT k`
-If you know `sqlite-vec` you may reach for its `MATCH … AND k = 10` idiom.
-That syntax belongs to `sqlite-vec`'s `vec0` virtual table, which the table
-above does not use: a `[[table]]`'s own `name` is always a per-file row table.
-For plain expressions, `sqlite-vec`'s own documented pattern is exactly what
-this guide uses: `ORDER BY vec_distance_cosine(...) LIMIT k`. To get the `vec0`
-idiom instead, declare the `vec0` table alongside the row table in the same
-[`ddl` batch](../reference/config.md#batch-ddl) and fill it from a trigger.
-:::
+The same projection works as an `on-file` hook feeding the indexed shape:
+parse the field in the hook, store it as a column, and the trigger embeds it
+once instead of on every query.
 
 ## Repeat runs are cheap
 
 Computed vectors are cached on disk, keyed on content and model
 ([vector cache](../plugins.md#vector-cache)) — re-running a search over
-unchanged files skips the model entirely and re-embeds only what changed.
-And the plugin costs nothing when idle: a query that never calls `embed()`
-spawns no worker and loads no model
-([zero cost when unused](../plugins.md#zero-cost-when-unused)).
+unchanged files skips the model entirely and re-embeds only what changed. That
+takes the *inference* out of the shape above, but not the walk or the per-file
+round trip; only a stored index removes those. And the plugin costs nothing
+when idle: a query that never calls `embed()` spawns no worker and loads no
+model ([zero cost when unused](../plugins.md#zero-cost-when-unused)).
 
 ## How `embed()` gets into SQL