[thekevinbot]

Two independent changes, on one branch because the session was scoped to both issues.

Closes #1003
Closes #1004

---

1. Docs: the two semantic-search shapes, and two fixes to the vec0 template (#1003)

#1010 merged while this branch was open, landing #960's templates on a new page, docs/howto/search-indexes.md, which frames search-by-meaning.md as the no-config guide. Git merges the two cleanly — neither touched the other's file — but the result would have taught the same vec0 recipe twice with different details. So this follows the page that landed rather than competing with it: the index recipe lives once, on search-indexes.md, and search-by-meaning.md keeps the path-table shape and links out.

What #1003 asked for survives that split:

• The trade is stated explicitly, as a table up front — setup, freshness, per-query cost, top-k form — plus the caveat that an index only pays off when the table outlives the query (--persist, or dirsql server): a one-shot dirsql query against an ephemeral index rebuilds the table, and therefore re-embeds the corpus, before it answers, which is strictly more work than the subquery.
• The ::: tip Top-k is LIMIT k block is retired. It existed to explain why MATCH … AND k = did not apply; that is now a row in the trade table and one clause in the walk-through.
• The model-id / config-hash consequence (Docs: rewrite search-by-meaning around a vec0 index instead of per-row embed() #1003 item 5) is on search-indexes.md, where the ddl batch is, and linked from the trade section.

Two fixes to the template search-indexes.md ships

Both found by running it, not by reading it:

• distance_metric=cosine was missing. 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-by-meaning. The two agree only for vectors of equal length, so documents embedding to different magnitudes rank differently. Demonstrated against real sqlite-vec with three notes whose vectors are [1,1], [5,5], [2,1] and the query [1,1]:

  default (L2):            a.md 0.0     c.md 1.0     b.md 5.657
  distance_metric=cosine:  a.md 2.2e-16 b.md 2.2e-16 c.md 0.0513
  

  b and c swap. (My first pass claimed this with a unit-vector fixture, where the two metrics cannot diverge — that evidence didn't support the claim, so this is the run that does.)

• The insert trigger needed WHEN new.body IS NOT NULL. embed(NULL) is NULL, and vec0 rejects a NULL vector outright, so one row with missing text fails the whole table load rather than 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 the guard the row still lands in notes; only its vector is skipped. FTS5 needs no equivalent — it indexes a NULL happily.

Also worth noting for anyone reading #960: its sketch's embed(:q, '') would fail — the worker treats a two-arg call's second argument as a real model id (StaticModel.from_pretrained('')). The page that landed already spells the id out in both places, which is right.

Manual verification

HuggingFace is blocked by the sandbox proxy (CONNECT → 403), so the model itself could not be downloaded. Everything dirsql does was exercised for real against a locally built CLI (cargo build -p dirsql --features cli) and real sqlite-vec 0.1.9 from PyPI, with a stub embed() worker speaking the genuine [[dirsql.function]] worker protocol. Only model inference was substituted; function dispatch, trigger-time invocation, JSON-text vector binding, vec0 KNN, and the persist sweep are all the real code paths.

The corrected [[table]] block was extracted verbatim from search-indexes.md (only float[512] → float[2] for the stub's width) and run:

$ dirsql query "SELECT n.slug, v.distance FROM notes_vec AS v JOIN notes AS n ON n.rowid = v.rowid
                WHERE v.embedding MATCH embed('pasta cook', '…') AND k = 3 ORDER BY v.distance"
[{"distance":2.220446049250313e-16,"slug":"a"},{"distance":2.220446049250313e-16,"slug":"b"},{"distance":0.051316700875759125,"slug":"c"}]

$ dirsql query "SELECT (SELECT COUNT(*) FROM notes) AS notes, (SELECT COUNT(*) FROM notes_vec) AS vecs"
[{"notes":4,"vecs":3}]     # the empty file's NULL body is skipped, not fatal

Also confirmed earlier in the session: delete propagation across a --persist restart ([{"notes":2,"vecs":2}] after removing a file — the AFTER DELETE trigger fires through the incremental sweep), and that a wrong float[N] fails with Dimension mismatch … Expected 7 dimensions but received 8. pnpm build in docs/ exits clean (VitePress fails on broken links).

One thing I could not verify: the real vector width of minishlab/potion-retrieval-32M. HF is unreachable from the sandbox and neither the repo nor the model2vec README records it. search-indexes.md already handles this correctly — it makes the probe a required step and treats 512 as a placeholder — so nothing here depends on the number being right, but it is worth a maintainer eye.

---

2. Checks: enforce the platforms.py ↔ platforms.ts mirror (#1004)

#1004 is a discussion, not a work item, and asked which framing wins before anything is deleted. The maintainer chose the subset framing, enforced now — so exe goes and the mechanism behind it gets a gate, rather than tidying the symptom and leaving the drift possible.

Its claims check out: Platform.exe is read only by its own three test assertions, and git log --all -S'exe' -- packages/ts/src/platforms.ts is empty — the TypeScript side has never carried the field, so the comment justifying it has been false since it was written.

The check

dirsql-checks platforms-mirror reads both tables as source text — the Python one through ast, the TypeScript one stripped of comments and handed to json's own decoder. Neither is imported: internals/checks depends on neither internals/distcheck nor a node toolchain, and a check that executes the file it audits can be fooled by the file. A table it cannot parse fails rather than passing on an empty read, because a mirror check that silently stops comparing passes forever.

decide.py's SHARED is the invariant as data — every Python field and the TypeScript property it is sourced from (slug ← libName minus the @dirsql/lib- prefix, which is what librarySlug() returns). From that one table it derives four failures:

a Python field outside SHARED	drift by construction — the exe case
a published target with no Python row	a half-added target; the message prints the Platform(...) line to paste
a Python row that is not a published target	distcheck resolving a sub-package the release never publishes
a shared field whose values disagree	names the field and both values

triple and libc staying TypeScript-only is the subset working as intended — the framing the Python docstring already claimed and the PLATFORMS comment contradicted. That comment now states the subset and names the check enforcing it.

Wired as its own workflow (platforms-mirror-check.yml) rather than a job in internals-distcheck-ci.yml: that lane's path filter does not watch packages/ts, which is exactly where the half-added-target case starts.

Red/green

The removal of exe is exempt (AGENTS.md), but the gate is new behavior:

• RED — d617620 pushed the integration + e2e tests alone. Run 32441254650 failed on exactly one job, internals/checks integration tests, with ModuleNotFoundError: No module named 'checks.platforms_mirror'. Every other job passed.
• GREEN — c9a387f added the check and deleted exe.
• Mutation follow-up — 6a12c1e. See below.

The mutation round

CI found 33 surviving mutants that the local gate had not, because the gate scopes to the diff and the new modules were still untracked when it ran — it mutated nothing in them. (Lesson: run that gate after committing.)

Most were unkillable by any assertion rather than merely untested, so the fix was structural, not an exemption:

• Comparing a parsed identifier against a module-level string literal admits an == → is mutant that CPython's interning makes genuinely equivalent. Those name comparisons are now dict and set lookups: classes and module bindings are collected by name and looked up, and a row's callee is tested for membership in ROW_CALLS.
• _assigned_names drops the len(targets) == 1 guard and its targets[0], whose [-1] mutant was equivalent under that very guard — and it now reads A = PLATFORMS = (...) correctly as a side effect.
• The hand-rolled TypeScript scanner is gone, taking seventeen survivors in its index arithmetic and bounds checks with it. Comments and string literals are one regex alternation, and json's raw_decode finds the end of the array, so nothing counts brackets.
• typescript_value keys its per-field derivation off a DERIVE table instead of comparing the field name, and gate.run drops the keyword-only marker *, — cosmic-ray mutates it to the positional-only /, which the interpreter accepts and no caller can observe.

New assertions cover the rest: the positional-arity guard from both sides, a field whose value sorts above platforms.ts as well as below, a class and a table bound under names sorting either side of the real ones, and the string unwrapping pinned to an exact value. 224 mutants, no survivors locally with the files committed (versus 140 in the run that missed them). Zero exemptions — the repo's count stays at zero.

Manual verification

$ uv run --project internals/checks dirsql-checks platforms-mirror
ok platforms-mirror: internals/distcheck/…/platforms.py mirrors the shared fields of
packages/ts/src/platforms.ts across 5 published target(s).                    # exit 0

Re-adding exe: bool:

::error::Platform.exe has no counterpart in packages/ts/src/platforms.ts. platforms.py holds a
deliberate subset of the published target (node_platform, node_arch, slug, os, cpu), so a field
the mirror cannot source is drift: delete it, or add the property to the TypeScript `Platform`
interface and to SHARED here.                                                 # exit 1

Simulating a half-added win32-arm64 target in platforms.ts only:

::error::win32-arm64 is published by platforms.ts but has no row in platforms.py. Add
Platform('win32', 'arm64', 'win32-arm64-msvc', ['win32'], ['arm64']) to PLATFORMS in
internals/distcheck/src/distcheck/node_flow/platforms.py, or the node distcheck flow cannot
resolve the new target on that host.                                          # exit 1

Both scratch edits were reverted.

Gates run locally

dirsql-checks preflight --conventions internals-checks-ci.yml --conventions internals-distcheck-ci.yml — 0 failing pairs across both roots: declared-deps, colocated-test, unit-lint, integration-lint, unit-coverage (100%), e2e-verify; mutation re-run separately post-commit at 224 mutants, no survivors. Full suites: 461 passed (internals/checks), 65 passed / 2 skipped (internals/distcheck).

---

E2E Verification

• Ran e2e suites locally for every affected SDK
• Python SDK e2e: N/A — no packages/python change
• TypeScript SDK e2e: N/A — no packages/ts change
• Rust core e2e (if applicable): N/A — no packages/rust change
• packages/python/e2e-attestations/<branch>.json — N/A, packages/python untouched
• packages/ts/e2e-attestations/<branch>.json — N/A, packages/ts untouched
• Command(s) run: uvx testing-conventions e2e attest 'uv run python -m pytest tests/e2e -x -q' in internals/checks (its own e2e-verify gate is scoped to internals/checks/src, which this PR changes)
• Result summary: 23 passed; receipt committed at internals/checks/e2e-attestations/claude-issues-1003-1004-kfn8ug.json (abdcae0). The docs half is N/A - docs only.

Changelog / Migrations

• Changelog fragment — not required: nothing under packages/ or plugins/ changed. docs/, internals/checks/, internals/distcheck/ and .github/workflows/ are all outside changed_packages.
• Migration fragment — not required: Platform.exe is repo-only, never published, and nothing outside its own tests read it, so no public API or runtime behavior changes.

PARITY.md is untouched: no SDK public API changed, and no parity drift is introduced or restored.