fix: validate against duplicate collection aliases in subqueries (#719)

* docs: investigation of same collection alias bug in subqueries

Investigated Discord bug report where using the same collection with the
same alias in both a subquery and main query causes:
1. Empty results when subquery has joins
2. Aggregation cross-leaking (wrong aggregated values)

ROOT CAUSE:
- Parent and subquery share the same input streams from allInputs when
  they use the same alias
- IVM stream sharing causes interference between query contexts
- Caching compounds the issue by reusing compilations with wrong bindings

ATTEMPTED FIXES (all unsuccessful):
- Input filtering: Doesn't solve the core issue of shared streams
- Fresh caching: Breaks existing caching tests and doesn't fix the bug
- Both approaches together: Still fails

CONCLUSION:
This requires a fundamental architectural change to support independent
input streams per query context. Current workaround: wrap query in an
extra from() layer to avoid alias conflicts.

See INVESTIGATION_SAME_COLLECTION_BUG.md for full details.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* fix: validate against duplicate collection aliases in subqueries

Implements validation to prevent the Discord bug where using the same
alias for a collection in both parent query and subquery causes empty
results or incorrect aggregation values.

The issue occurs when both parent and subquery use the same alias to
reference a collection directly (e.g., both use `vote: votesCollection`).
This causes them to share the same input stream, leading to interference.

Solution: Add validation that throws a clear DuplicateAliasInSubqueryError
when this pattern is detected.

Implementation:
- New error: DuplicateAliasInSubqueryError with clear message
- collectDirectCollectionAliases(): Collects only direct CollectionRef aliases
- validateSubqueryAliases(): Checks for conflicts before compiling subqueries
- Only validates DIRECT collection references, not QueryRef (subquery outputs)

This allows legitimate patterns like:
  const sub = q.from({ issue: collection })
  q.from({ issue: sub })  // OK - different scopes

But prevents problematic patterns like:
  const sub = q.from({ x: coll }).join({ vote: voteColl }, ...)
  q.from({ vote: voteColl }).join({ x: sub }, ...)  // Error!

Users should rename the alias in either parent or subquery to fix.

Fixes Discord bug reported by JustTheSyme.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* docs: clean up investigation doc and add changeset

- Cleaned up INVESTIGATION_SAME_COLLECTION_BUG.md to focus on solution
- Added PR_UPDATE.md with suggested title and body for PR #719
- Added changeset for the alias validation fix

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* chore: clean up temporary documentation files

Removed investigation and PR update docs that were used during development.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* fix: run duplicate alias validation before query optimization

Moved the validation for duplicate collection aliases in subqueries to run
before query optimization rather than during compilation. This prevents false
positives from optimizer-generated subqueries while still catching user-written
duplicate aliases.

The optimizer can legitimately create internal subqueries that reuse aliases
(e.g., for predicate pushdown), but users should not be allowed to write
queries with conflicting aliases between parent and subquery.

Changes:
- Added validateQueryStructure() in compiler/index.ts that recursively validates
  the entire query tree before optimization
- Removed validation logic from processFrom() and processJoinSource() in joins.ts
- Fixed TypeScript type errors in discord-alias-bug.test.ts

All tests pass (1403 tests, 0 type errors).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* refactor: improve alias validation test naming and descriptions

Renamed test file from discord-alias-bug.test.ts to validate-aliases.test.ts
and updated test descriptions to focus on expected behavior rather than
referencing the Discord bug report.

Changes:
- Renamed: discord-alias-bug.test.ts → validate-aliases.test.ts
- Updated describe block: "Alias validation in subqueries"
- Updated test names to describe expected behavior:
  - "should throw DuplicateAliasInSubqueryError when subquery reuses a parent query collection alias"
  - "should allow subqueries when all collection aliases are unique"
- Improved inline comments to be more descriptive
- Simplified assertion comments

Addresses feedback from @samwillis

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

---------

Co-authored-by: Claude <[email protected]>

Author: KyleAMathews

.changeset/validate-duplicate-subquery-aliases.md

@@ -0,0 +1,5 @@
+---
+"@tanstack/db": patch
+---
+
+Validate against duplicate collection aliases in subqueries. Prevents a bug where using the same alias for a collection in both parent and subquery causes empty results or incorrect aggregation values. Now throws a clear `DuplicateAliasInSubqueryError` when this pattern is detected, guiding users to rename the conflicting alias.

packages/db/src/errors.ts

@@ -404,6 +404,22 @@ export class CollectionInputNotFoundError extends QueryCompilationError {
   }
 }
 
+/**
+ * Error thrown when a subquery uses the same alias as its parent query.
+ * This causes issues because parent and subquery would share the same input streams,
+ * leading to empty results or incorrect data (aggregation cross-leaking).
+ */
+export class DuplicateAliasInSubqueryError extends QueryCompilationError {
+  constructor(alias: string, parentAliases: Array<string>) {
+    super(
+      `Subquery uses alias "${alias}" which is already used in the parent query. ` +
+        `Each alias must be unique across parent and subquery contexts. ` +
+        `Parent query aliases: ${parentAliases.join(`, `)}. ` +
+        `Please rename "${alias}" in either the parent query or subquery to avoid conflicts.`
+    )
+  }
+}
+
 export class UnsupportedFromTypeError extends QueryCompilationError {
   constructor(type: string) {
     super(`Unsupported FROM type: ${type}`)

packages/db/src/query/compiler/index.ts

@@ -3,6 +3,7 @@ import { optimizeQuery } from "../optimizer.js"
 import {
   CollectionInputNotFoundError,
   DistinctRequiresSelectError,
+  DuplicateAliasInSubqueryError,
   HavingRequiresGroupByError,
   LimitOffsetRequireOrderByError,
   UnsupportedFromTypeError,
@@ -99,6 +100,11 @@ export function compileQuery(
     return cachedResult
   }
 
+  // Validate the raw query BEFORE optimization to check user's original structure.
+  // This must happen before optimization because the optimizer may create internal
+  // subqueries (e.g., for predicate pushdown) that reuse aliases, which is fine.
+  validateQueryStructure(rawQuery)
+
   // Optimize the query before compilation
   const { optimizedQuery: query, sourceWhereClauses } = optimizeQuery(rawQuery)
 
@@ -375,6 +381,74 @@ export function compileQuery(
   return compilationResult
 }
 
+/**
+ * Collects aliases used for DIRECT collection references (not subqueries).
+ * Used to validate that subqueries don't reuse parent query collection aliases.
+ * Only direct CollectionRef aliases matter - QueryRef aliases don't cause conflicts.
+ */
+function collectDirectCollectionAliases(query: QueryIR): Set<string> {
+  const aliases = new Set<string>()
+
+  // Collect FROM alias only if it's a direct collection reference
+  if (query.from.type === `collectionRef`) {
+    aliases.add(query.from.alias)
+  }
+
+  // Collect JOIN aliases only for direct collection references
+  if (query.join) {
+    for (const joinClause of query.join) {
+      if (joinClause.from.type === `collectionRef`) {
+        aliases.add(joinClause.from.alias)
+      }
+    }
+  }
+
+  return aliases
+}
+
+/**
+ * Validates the structure of a query and its subqueries.
+ * Checks that subqueries don't reuse collection aliases from parent queries.
+ * This must be called on the RAW query before optimization.
+ */
+function validateQueryStructure(
+  query: QueryIR,
+  parentCollectionAliases: Set<string> = new Set()
+): void {
+  // Collect direct collection aliases from this query level
+  const currentLevelAliases = collectDirectCollectionAliases(query)
+
+  // Check if any current alias conflicts with parent aliases
+  for (const alias of currentLevelAliases) {
+    if (parentCollectionAliases.has(alias)) {
+      throw new DuplicateAliasInSubqueryError(
+        alias,
+        Array.from(parentCollectionAliases)
+      )
+    }
+  }
+
+  // Combine parent and current aliases for checking nested subqueries
+  const combinedAliases = new Set([
+    ...parentCollectionAliases,
+    ...currentLevelAliases,
+  ])
+
+  // Recursively validate FROM subquery
+  if (query.from.type === `queryRef`) {
+    validateQueryStructure(query.from.query, combinedAliases)
+  }
+
+  // Recursively validate JOIN subqueries
+  if (query.join) {
+    for (const joinClause of query.join) {
+      if (joinClause.from.type === `queryRef`) {
+        validateQueryStructure(joinClause.from.query, combinedAliases)
+      }
+    }
+  }
+}
+
 /**
  * Processes the FROM clause, handling direct collection references and subqueries.
  * Populates `aliasToCollectionId` and `aliasRemapping` for per-alias subscription tracking.

packages/db/tests/query/validate-aliases.test.ts

@@ -0,0 +1,117 @@
+import { beforeEach, describe, expect, test } from "vitest"
+import { createLiveQueryCollection, eq } from "../../src/query/index.js"
+import { createCollection } from "../../src/collection/index.js"
+import { mockSyncCollectionOptions } from "../utils.js"
+
+type Lock = { _id: number; name: string }
+type Vote = { _id: number; lockId: number; percent: number }
+
+const locks: Array<Lock> = [
+  { _id: 1, name: `Lock A` },
+  { _id: 2, name: `Lock B` },
+]
+
+const votes: Array<Vote> = [
+  { _id: 1, lockId: 1, percent: 10 },
+  { _id: 2, lockId: 1, percent: 20 },
+  { _id: 3, lockId: 2, percent: 30 },
+]
+
+function createTestCollections() {
+  return {
+    locksCollection: createCollection(
+      mockSyncCollectionOptions<Lock>({
+        id: `locks`,
+        getKey: (lock) => lock._id,
+        initialData: locks,
+        autoIndex: `eager`,
+      })
+    ),
+    votesCollection: createCollection(
+      mockSyncCollectionOptions<Vote>({
+        id: `votes`,
+        getKey: (vote) => vote._id,
+        initialData: votes,
+        autoIndex: `eager`,
+      })
+    ),
+  }
+}
+
+describe(`Alias validation in subqueries`, () => {
+  let locksCollection: ReturnType<
+    typeof createTestCollections
+  >[`locksCollection`]
+  let votesCollection: ReturnType<
+    typeof createTestCollections
+  >[`votesCollection`]
+
+  beforeEach(() => {
+    const collections = createTestCollections()
+    locksCollection = collections.locksCollection
+    votesCollection = collections.votesCollection
+  })
+
+  test(`should throw DuplicateAliasInSubqueryError when subquery reuses a parent query collection alias`, () => {
+    expect(() => {
+      createLiveQueryCollection({
+        startSync: true,
+        query: (q) => {
+          const locksAgg = q
+            .from({ lock: locksCollection })
+            .join({ vote: votesCollection }, ({ lock, vote }) =>
+              eq(lock._id, vote.lockId)
+            )
+            .select(({ lock }) => ({
+              _id: lock._id,
+              lockName: lock.name,
+            }))
+
+          return q
+            .from({ vote: votesCollection }) // Reuses "vote" alias from subquery
+            .join({ lock: locksAgg }, ({ vote, lock }) =>
+              eq(lock._id, vote.lockId)
+            )
+            .select(({ vote, lock }) => ({
+              voteId: vote._id,
+              lockName: lock!.lockName,
+            }))
+        },
+      })
+    }).toThrow(/Subquery uses alias "vote"/)
+  })
+
+  test(`should allow subqueries when all collection aliases are unique`, () => {
+    const query = createLiveQueryCollection({
+      startSync: true,
+      query: (q) => {
+        const locksAgg = q
+          .from({ lock: locksCollection })
+          .join(
+            { v: votesCollection }, // Uses unique alias "v" instead of "vote"
+            ({ lock, v }) => eq(lock._id, v.lockId)
+          )
+          .select(({ lock }) => ({
+            _id: lock._id,
+            lockName: lock.name,
+          }))
+
+        return q
+          .from({ vote: votesCollection })
+          .join({ lock: locksAgg }, ({ vote, lock }) =>
+            eq(lock._id, vote.lockId)
+          )
+          .select(({ vote, lock }) => ({
+            voteId: vote._id,
+            lockName: lock!.lockName,
+          }))
+      },
+    })
+
+    const results = query.toArray
+
+    // Should successfully execute and return results
+    expect(results.length).toBeGreaterThan(0)
+    expect(results.every((r) => r.lockName)).toBe(true)
+  })
+})