# Revset semantics — notes for the §8 subset

Spec §8 requires a deliberately small revset subset (`author()`, `description()`,
`conflicted()`, `bookmarks()`, `open()`, plus `&`, `|`, `~`) parsed into SQL, and warns:

> Do not attempt to implement jj's full revset language against a Git-backed index; it will not
> be faithful, and a subtly wrong revset is worse than an honestly limited one.

These are behaviours verified against jj 0.43.0 that a naive SQL translation gets wrong.

## `description()` is an EXACT match, not a substring match

This is the trap. Verified directly:

```
$ jj log -r 'description("merge base")'          # commit described exactly "merge base"
(empty result)

$ jj log -r 'description(substring:"base")'
mmnulkozlxru  merge base

$ jj log -r 'subject("merge base")'
mmnulkozlxru  merge base
```

The obvious implementation — `WHERE description ILIKE '%' || $1 || '%'` — is **wrong**, and
wrong in the most damaging direction: it silently returns *more* than the CLI would, so a
reviewer filtering a change list sees results their terminal does not. That is precisely the
"subtly wrong revset" the spec says is worse than no revset.

Correct mapping for the v1 subset:

| revset | SQL |
|---|---|
| `description("x")` | `description = 'x'` — exact, including jj's trailing newline handling |
| `description(substring:"x")` | `description ILIKE '%x%'` |
| `subject("x")` | exact match against the **first line** of the description |

If only one form is implemented in v1, implement `description(substring:)`, because it is the
one users actually want — but then **do not accept the bare `description("x")` form at all**.
Reject it with the "unsupported expression" message rather than aliasing it to substring.
Accepting it with different semantics than the CLI is the failure mode to avoid.

Note also that jj descriptions carry a trailing newline. Normalise on ingest (store without
it) so exact matching does not depend on invisible whitespace.

## Prefix matching

Ambiguity handling matters. jj resolves the shortest unique prefix and errors on ambiguity;
spec §7 requires Dogfood render a disambiguation page rather than guess. The index has
`changes_prefix_idx (repo_id, change_id text_pattern_ops)` for this — use
`change_id LIKE $1 || '%'` and count results before choosing a page.

## Functions deliberately NOT in the v1 subset

`heads()`, `roots()`, `ancestors()`, `descendants()`, `::`, `..`, `latest()`, `merges()`,
`file()`, `diff_contains()` — all require graph traversal or content search that the SQL index
cannot answer faithfully. The parser must reject these by name with a clear message naming the
unsupported function, not fail to parse with a generic syntax error.

## `mine()` / `author()`

`author()` in jj matches against the author *email and name* as a substring. Dogfood stores
`revisions.author_email` and `author_name`; match against both, and be explicit in the UI that
this is a substring match so it is not confused with `description()`'s exact semantics.