[thekevinbot]

Refs #1575 (Rust core + Python SDK; the TypeScript binding follows in a second PR from fresh main once this merges).

query(sql, params) hands params to SQLite's own parameter binding; values never enter the SQL text. A sequence fills ? placeholders in order; a mapping fills :name (also @name / $name) placeholders, keyed without the prefix. Works for path-tables and declared tables.

• Python: await db.query(sql, params=None). Accepts None, int, bool, float, str, bytes, bytearray. Any other value type raises TypeError (unsupported parameter type: <type>), and an out-of-range int raises OverflowError. A params that is neither a sequence nor a mapping (a str included) raises TypeError.
• Rust: Params::{Positional(Vec<Value>), Named(HashMap<String, Value>)}. New methods: DirSQL::query_with, query_ordered_with, query_each_with and AsyncDirSQL::query_with. The existing methods bind Params::default() (empty).
• Strict fit (DbError::Params, which Python raises as RuntimeError): a wrong count, a missing name, an unused mapping key, or a sequence/mapping that does not match the placeholder style each fail with a message naming the problem.
• Every core query path binds: run_statement (both runs of a batched function) and query_each_ref (the streaming path, including its batched fallback).
• No CLI flag.

Parity: this introduces drift, because TypeScript lacks params until the follow-up PR. That PR is tracked by #1575, which stays open. PARITY.md is updated.

Manual run: built with maturin develop --release and wrote three JSON files whose advice holds it's "quoted" — ok, ünïcødé ✓ 日本語 and x'; DROP TABLE t; --. Then ran await db.query("SELECT path FROM './*.json' WHERE content ->> 'advice' = :advice", {"advice": text}) for each. Each returned exactly its own file (a.json, b.json, c.json), and a non-matching value returned []. The error cases printed RuntimeError the query has 1 parameter(s), but 2 value(s) were given, RuntimeError the named parameter :a has no value and TypeError unsupported parameter type: object.

E2E Verification

• Ran e2e suites locally for every affected SDK
• Python SDK e2e: pass (impacted query tests)
• TypeScript SDK e2e: pass (impacted query tests)
• Rust core e2e (if applicable): pass
• 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 -p dirsql --features cli
  • cd packages/python && testing-conventions e2e attest 'uv run python -m pytest tests/e2e/query_contract_test.py tests/e2e/on_file_query_test.py tests/e2e/declared_table_name_test.py tests/e2e/use_case_join_test.py tests/e2e/stat_speed_test.py -x -q'
  • cd packages/ts && testing-conventions e2e attest 'pnpm exec vitest run --dir tests/e2e query-contract declared-table-name'
• Result summary: Rust 2195 passed; Python e2e 17 passed; TypeScript e2e 12 passed.

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 with the same slug added under <root>/<pkg>/migrations.d/ for each changed package (every subsection but Summary _None._ when nothing breaks)