feat: verified query optimization via altimate_core_rewrite verify_equivalence mode

Merged
AN
5mo ago
+465-16

What does this PR do?

Adds verified query optimization as a mode of the existing altimate_core_rewrite tool (rather than a separate, overlapping tool).

altimate_core_rewrite gains a verify_equivalence option. When true, each proposed rewrite is checked against the original via altimate_core.equivalence, and only rewrites that return strict equivalent === true are labeled verified-safe to apply — the rest are returned but labeled "review before applying." The gate is conservative: it never promises "safe" unless equivalence proves it, so a verified rewrite can be applied without changing results.

Design note (review feedback): the first cut was a standalone altimate_verified_optimize tool, but that overlapped with sql_optimize and altimate_core_rewrite — three near-identical "optimize a query" tools would confuse the agent's tool selection (a documented failure mode). Folding verification into altimate_core_rewrite as a mode keeps the tool surface clean: verification is an option, not a competing tool.

Also wires the query-optimize skill to call altimate_core_rewrite with verify_equivalence: true, folding its old manual rewrite→equivalence steps into one verified call.

Current altimate_core.equivalence coverage is limited (tracked in altimate-core-internal #137); this is sound today (won't ship a wrong rewrite) and surfaces more verified wins as that engine coverage improves.

Type of change

  • New feature (non-breaking change which adds functionality)

Issue for this PR

Closes #917

How did you verify your code works?

  • 18 tests (test/altimate/altimate-core-rewrite-verify.test.ts) exercising verify mode:
    • gate logic (verified vs unverified partitioning, no-op/dedup filtering, mixed, no-schema, engine-error)
    • adversarial block: the gate trusts only strict equivalent === true — rejects "true", 1, {}, undefined, null, with specific reasons (missing-field / non-boolean / not-equivalent); fails safe when the equivalence handler throws (partial-failure resilience)
    • real-engine integration test against the altimate-core native binary (auto-skips if absent)
  • verify_equivalence defaults to false → existing altimate_core_rewrite behavior is unchanged (regression-checked against tool-formatters + tool-error-propagation-complete).
  • tsgo typecheck clean; marker guard clean.

Checklist

  • My code follows the style guidelines of this project
  • I have performed a self-review of my code
  • I have added tests that prove my feature works
  • New and existing unit tests pass locally with my changes

Summary by CodeRabbit

Release Notes

  • New Features

    • Query optimization now verifies rewrite equivalence, classifying results as verified (safe to apply) or unverified (requires manual review).
    • Schema inspection enhances rewrite safety when available.
  • Bug Fixes

    • Improved error handling for rewrite operations.
  • Documentation

    • Updated query optimization workflow documentation.