RAG Scope Filters

The bug this exists to prevent

Scoped retrieval queries are built by appending conditions to a base query that already binds some parameters:

  WHERE embedding <=> $1 ... AND organization_id = $2 LIMIT $3

Add a document-kind filter and it must be $4. Add a year filter too and that one is $5 — unless the kind filter was skipped, in which case the year filter is $4. Every optional dimension shifts the numbering of every dimension after it.

Get it wrong and the query does not fail. Postgres binds whatever value is in that position, so a filter intended to select documentKind = 'lease' compares against the limit, or against the organisation id. It returns rows — the wrong rows — and the shape of the result is exactly what the caller expects.

**On a retrieval path that is the tenant-isolation boundary, "wrong rows" means one customer's documents answering another customer's question.** Nothing logs an error, because nothing went wrong as far as the database is concerned.

Rule 1 — the caller declares what is already bound

buildScopeFilters() takes baseParamCount — how many $N the query binds before these — and numbers from there. The count is stated once, at the call site that owns the base query, rather than recomputed in your head at each append.

Rule 2 — no dimensions set means byte-for-byte unchanged

With nothing to scope by, it returns an empty fragment and an empty param list, so an unscoped query is identical to what it was before this existed. That matters for adoption: dropping this into a working query must not change its plan, its results, or its cost when no filter applies.

Rule 3 — principal scoping is a dimension, not an afterthought

Per-principal access is built in alongside tenant and kind, because the alternative — filtering retrieved rows in application code after the query returns — leaks through LIMIT. Ten rows come back, three are filtered out, and the user gets seven results with no indication that the ranking was computed over documents they cannot read.

What this does NOT do

No query execution, no connection, no ORM. It builds a fragment and a parameter list for you to splice into your own SQL. It does not know your schema — column names are the ones this was extracted with, and adapting them is a deliberate edit rather than configuration.

It does not authorise. It scopes a query to values you supply; deciding what a principal may see is upstream.

Verified

11 tests covering each dimension alone and in combination, the numbering shift when optional dimensions are absent, baseParamCount offsets, and the empty case producing an unchanged query.

Not covered: the fragment is never executed against a real database in the test suite. The numbering is asserted structurally.