Class PreparedStatementCache

Tracks SQL statement usage (hit/miss counts, execution timings, last-used time) keyed by normalized SQL + params, with TTL-based expiry.

IMPORTANT — naming caveat: despite the name, this does not cache a real driver-level prepared-statement handle. None of the Dialect implementations in src/dialects/** expose a separate prepare/execute split - query(sql, options) always receives the full SQL text and applies options.replacements / options.bind per call (see e.g. sqlite/index.ts query(), which calls connection.prepare(sql) fresh on every invocation). So there is no reusable driver object for this class to hold onto; the compiled field on each entry is whatever metadata the caller passes to set() (by default just {}, or - see QueryOptimizer.executeQuery() - a lightweight { sql, paramCount } descriptor). In practice this class behaves as a query-usage/hit-count tracker with an optional metadata slot, not a real statement cache. It is kept under this name for backwards compatibility with existing callers/tests; treat getStats() / hitCount / topStatements as the reliable surface, and don't rely on compiled holding an executable handle.

Invalidation: entries expire via TTL (options.ttl, default 1 hour). Since that alone can serve stale-shaped results after schema changes made via raw DDL, invalidateTable() is provided to drop entries referencing a given table name on write (e.g. from a caller's insert/update/delete path); it is not auto-wired to every write in this codebase, but QueryOptimizer. invalidateTableCache() calls it alongside the query-result cache.