Replace query internals with canonical backend-agnostic IR AST

[flyon]

Summary

Replaces the internal query representation with a canonical backend-agnostic IR AST. The public Shape DSL (Shape.select(), .create(), .update(), .delete()) is unchanged — what changed is what IQuadStore implementations receive.

Why

Stores previously received ad-hoc nested arrays and objects (query.select[0][0].property.label). This made downstream store implementations brittle, hard to reason about, and tightly coupled to internal DSL structure. A normalized IR with typed discriminated unions gives store implementers a stable, well-documented contract to build against.

What

• SelectQuery, CreateQuery, UpdateQuery, DeleteQuery ARE the IR types. No separate "IR" vs "query" type hierarchy — factories emit IR directly via build().
• Full IR AST for selects: root (shape scan pattern), projection (expression-based), where (expression tree), orderBy, limit, subjectId, singleResult, resultMap.
• Typed mutations: Same kind discriminators (create, update, delete) with IRFieldUpdate[], IRNodeDescription, and set modification support (add/remove).
• Compact references: IR carries shapeId and propertyShapeId strings only — no embedded shape/property objects.
• Early normalization: some() → exists(), every() → not exists(not ...) during canonicalization. Boolean trees flattened.
• Explicit aliasing: Deterministic alias generation (a0, a1, ...) with lexical scope validation.

How

A multi-stage pipeline converts DSL traces to IR:

SelectQueryFactory.build()
  → toRawInput()             (extract factory state)
  → desugarSelectQuery()     (IRDesugar — flatten DSL tree)
  → canonicalize()           (IRCanonicalize — normalize booleans, rewrite quantifiers)
  → lowerSelectQuery()       (IRLower — produce full AST with aliases, patterns, expressions)
  → SelectQuery

Mutations convert directly via buildCanonical*MutationIR() in IRMutation.ts.

New modules: IRDesugar.ts, IRCanonicalize.ts, IRLower.ts, IRPipeline.ts, IRProjection.ts, IRAliasScope.ts, IRMutation.ts. All exported functions have JSDoc documentation.

Breaking changes for downstream stores

IQuadStore method signatures are unchanged, but the objects they receive are structurally different. Select queries are completely new (query.root, query.projection, query.where). Mutation queries are structurally similar but properly typed. Store result types are now exported: ResultRow, SelectResult, CreateResult, UpdateResult, SetOverwriteResult, SetModificationResult.

Full IR reference: documentation/intermediate-representation.md.

Other improvements

• QueryParser simplified: Deleted IQueryParser interface. Shape calls QueryParser directly — no swappable indirection.
• Dead code removed: ~50 lines of commented-out type variants cleaned up.
• Test coverage: 147 tests across 9 suites. Every select pattern (56) and mutation pattern (18) from the original query.test.ts has IR assertions. Old legacy test file deleted.
• Docs consolidated: Four plan docs merged into docs/003-ir-refactoring.md.

Test plan

• All 147 tests pass (npx jest --config jest.config.js)
• TypeScript compiles cleanly (npx tsc --noEmit)
• No stale references to deleted APIs (IQueryParser, getLegacyQueryObject, getCanonicalIR, etc.)
• IR golden fixtures cover all select/mutation patterns
• Compile-time type inference assertions green (query.types.test.ts)

🤖 Generated with Claude Code