docs: plan filtrify conditions as a runtime translator

[roderm]

Design only — nothing implemented. Carried over from the pre-move repository, where it was never pushed.

The main finding

The third plugin does not need a writer. Load<Msg> already takes conds ...query.Cond, so a filter is just another condition:

cond, err := filter.Build(crmv1.PersonTable, expr)
people, err := crmv1.LoadPerson(ctx, conn, mask, cond)

The generated files stay exactly as they are. The work is metadata plus one translation function.

What is missing is metadata

Three small additions to what the schema writer already emits — proto_name on SchemaColumn (filters name proto fields, never columns), entity on SchemaTable, and a per-file Tables registry so HasChildren can find a child table. The registry also closes the gap where migration.Create makes callers hand-list every table.

The blocking decision

filtrify speaks message fields and entities and never learns table or column names, so the translation has to happen on this side, where the metadata and the SQL assembly already live. That needs the AST types here, which the two-dependency rule forbids — and importing filtrify/ast/v1 today also links grpc, since the generated gRPC service shares that package.

Recommended: relax the rule for the AST once those messages move to a package without the service. Alternative is a bridge module. Both are laid out in the doc, along with why walking the AST through protoreflect to dodge the dependency was rejected.

Also recorded

• Whether to replace the hand-rolled builder with a library. Measured rather than assumed: one would own about a quarter of pkg/query and none of the subtle parts (Mask, Key), which are the two that have actually had bugs. bob/dialect/psql and goqu are the only candidates with a real upsert API — relevant since conflict handling is on the roadmap.
• filtrify's parser defaults an unrecognised operator to equality rather than failing, so a ~ b becomes a = b before the AST exists. Any operator a SQL whitelist would reject is already lost upstream.

Open questions

1. HasChildren.entity — entity name or relation field name? They differ as soon as a parent has two relations to the same entity, and an entity name cannot disambiguate.
2. contains semantics: %/_ escaping and case sensitivity both differ per dialect.
3. IsNullExpr is declared but not in Expr's oneof — wire it in or drop it.

🤖 Generated with Claude Code