From face9c2b6cf237bfe99f03abb5a1523e72ffb796 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 24 Oct 2025 18:15:31 +0000
Subject: [PATCH 1/6] docs: investigation of same collection alias bug in
 subqueries
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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 <noreply@anthropic.com>
---
 INVESTIGATION_SAME_COLLECTION_BUG.md | 141 +++++++++++++++++++++++++++
 1 file changed, 141 insertions(+)
 create mode 100644 INVESTIGATION_SAME_COLLECTION_BUG.md

diff --git a/INVESTIGATION_SAME_COLLECTION_BUG.md b/INVESTIGATION_SAME_COLLECTION_BUG.md
new file mode 100644
index 000000000..b4b94975f
--- /dev/null
+++ b/INVESTIGATION_SAME_COLLECTION_BUG.md
@@ -0,0 +1,141 @@
+# Investigation: Same Collection in Subquery and Main Query Bug
+
+## Bug Report Summary (from Discord)
+
+When using the same collection with the same alias in both a subquery and the main query, two issues occur:
+
+1. **Empty Results**: When a subquery has a join with a collection, and the main query also uses that collection, the query returns empty results.
+
+2. **Aggregation Cross-Leaking**: Aggregated values from subqueries show incorrect values (individual row values instead of aggregates).
+
+Example:
+```typescript
+const locksAgg = q
+  .from({ lock: c.locksCollection })
+  .join({ vote: c.votesCollection }, ...) // Uses "vote" alias
+  .groupBy(...)
+  .select({ overallPercent: sum(vote.percent) })
+
+return q
+  .from({ vote: c.votesCollection })  // ALSO uses "vote" alias
+  .join({ lockAgg }, ...)
+  .select({ percent: vote.percent, overallPercent: lockAgg?.overallPercent })
+```
+
+Expected: `overallPercent` should be the sum (e.g., 45)
+Actual: `overallPercent` equals individual `percent` values (e.g., 30)
+
+## Root Cause Analysis
+
+###  1. Shared Input Streams
+
+The core issue is in the query compiler architecture:
+
+- All queries (parent and subqueries) receive the same `allInputs` map containing keyed streams for each collection alias
+- When a parent query and subquery both use the same alias (e.g., "vote"), they share the SAME input stream
+- IVM streams are stateful, and sharing them between different query contexts causes interference
+
+### 2. Caching Issues
+
+The query compiler caches compiled queries using `QueryIR` as the key. When a subquery is compiled multiple times in different contexts, it returns the cached result from the first compilation, which has the wrong input bindings.
+
+## Attempted Fix
+
+I implemented a partial fix in `packages/db/src/query/compiler/index.ts` and `packages/db/src/query/compiler/joins.ts`:
+
+1. **Input Filtering**: Created `collectQueryAliases()` to identify which collection aliases each query needs
+2. **Fresh Cache**: Each subquery compilation uses a fresh `WeakMap` cache to prevent incorrect caching
+
+### Code Changes
+
+```typescript
+// In processFrom() for QueryRef case:
+const subqueryAliases = collectQueryAliases(originalQuery)
+const filteredInputs: Record<string, KeyedStream> = {}
+for (const alias of subqueryAliases) {
+  if (allInputs[alias]) {
+    filteredInputs[alias] = allInputs[alias]
+  }
+}
+
+const subqueryCache = new WeakMap()
+const subqueryMapping = new WeakMap()
+
+const subQueryResult = compileQuery(
+  originalQuery,
+  filteredInputs,  // Filtered inputs
+  collections,
+  subscriptions,
+  callbacks,
+  lazySources,
+  optimizableOrderByCollections,
+  setWindowFn,
+  subqueryCache,  // Fresh cache
+  subqueryMapping
+)
+```
+
+## Current Status
+
+- ✅ Existing tests continue to pass (including nested subquery tests)
+- ❌ The specific bug is NOT fixed - tests still show empty results and cross-leaking
+
+## Why the Fix Doesn't Work
+
+Even with filtering and fresh caching, the fundamental issue remains: **parent and subquery still share the same input streams** when they use the same alias. The filtering only determines WHICH streams to pass, but if both need "vote", they get the same stream instance.
+
+## Proper Solution Required
+
+This bug requires a more substantial architectural change:
+
+### Option 1: Separate Streams Per Context
+- Create independent input streams for each query compilation context
+- Subqueries would get their own streams, not share the parent's
+- Requires changes to how inputs are created and managed
+
+### Option 2: Stream Isolation
+- Implement a mechanism to "fork" or isolate streams when they're used in multiple contexts
+- May require changes to the IVM layer
+
+### Option 3: Alias Namespacing
+- Internally rename aliases in subqueries to avoid conflicts
+- E.g., parent uses "vote", subquery internally uses "vote_subquery_1"
+- Requires careful tracking and remapping of aliases
+
+## Recommendation
+
+This issue requires deeper architectural discussion and likely a larger refactor. The current fix provides:
+- Better cache isolation (prevents some edge cases)
+- Foundation for future improvements
+
+But does not solve the core bug. I recommend:
+
+1. Creating an issue to track this as a known limitation
+2. Documenting the workaround (wrapping in an extra `from()` layer)
+3. Planning a larger refactor to properly support this use case
+
+## Workaround for Users
+
+As mentioned in the Discord thread, wrapping the query in another layer works:
+
+```typescript
+const problematicQuery = q
+  .from({ vote: c.votesCollection })
+  .join({ lockAgg }, ...)
+  .where(...)
+
+// Workaround: wrap in another from()
+return q.from({ votesQ: problematicQuery })
+  .where(({ votesQ }) => eq(votesQ.poolAddress, poolAddress))
+```
+
+This works because the wrapped query no longer directly uses "vote" at the top level, avoiding the alias conflict.
+
+---
+
+**Files Modified:**
+- `packages/db/src/query/compiler/index.ts` (added collectQueryAliases, fresh cache for subqueries)
+- `packages/db/src/query/compiler/joins.ts` (same changes for join processing)
+
+**Investigation Date:** 2025-10-24
+**Investigated By:** Claude Code

From 331e9831a924db95b42f5fcf8a10d118c3858ef3 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 24 Oct 2025 18:46:49 +0000
Subject: [PATCH 2/6] fix: validate against duplicate collection aliases in
 subqueries
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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 <noreply@anthropic.com>
---
 INVESTIGATION_SAME_COLLECTION_BUG.md          |  68 +++++++---
 packages/db/src/errors.ts                     |  16 +++
 packages/db/src/query/compiler/index.ts       |  59 ++++++++-
 packages/db/src/query/compiler/joins.ts       |  59 ++++++++-
 .../db/tests/query/discord-alias-bug.test.ts  | 121 ++++++++++++++++++
 5 files changed, 298 insertions(+), 25 deletions(-)
 create mode 100644 packages/db/tests/query/discord-alias-bug.test.ts

diff --git a/INVESTIGATION_SAME_COLLECTION_BUG.md b/INVESTIGATION_SAME_COLLECTION_BUG.md
index b4b94975f..502d24962 100644
--- a/INVESTIGATION_SAME_COLLECTION_BUG.md
+++ b/INVESTIGATION_SAME_COLLECTION_BUG.md
@@ -102,40 +102,66 @@ This bug requires a more substantial architectural change:
 - E.g., parent uses "vote", subquery internally uses "vote_subquery_1"
 - Requires careful tracking and remapping of aliases
 
-## Recommendation
+## Solution Implemented
 
-This issue requires deeper architectural discussion and likely a larger refactor. The current fix provides:
-- Better cache isolation (prevents some edge cases)
-- Foundation for future improvements
+After Sam's insight, the fix is to **validate and prevent** alias reuse, not to make it work:
 
-But does not solve the core bug. I recommend:
+### Implementation
 
-1. Creating an issue to track this as a known limitation
-2. Documenting the workaround (wrapping in an extra `from()` layer)
-3. Planning a larger refactor to properly support this use case
+Added validation that throws a clear error when a subquery uses the same alias as its parent query for DIRECT collection references:
 
-## Workaround for Users
+1. **New Error Type** (`DuplicateAliasInSubqueryError`):
+   - Clear message explaining the conflict
+   - Lists all parent aliases for context
+   - Suggests renaming the alias
 
-As mentioned in the Discord thread, wrapping the query in another layer works:
+2. **Validation Logic**:
+   - `collectDirectCollectionAliases()`: Collects only CollectionRef aliases, not QueryRef
+   - `validateSubqueryAliases()`: Checks for conflicts before compiling subqueries
+   - Only validates direct collection references to allow legitimate subquery wrapping
+
+### Key Insight
+
+The validation only checks **direct** collection references (CollectionRef), not subquery references (QueryRef). This allows:
 
 ```typescript
-const problematicQuery = q
-  .from({ vote: c.votesCollection })
-  .join({ lockAgg }, ...)
-  .where(...)
+// ✅ ALLOWED: Different alias scopes
+const subquery = q.from({ issue: issuesCollection })
+return q.from({ issue: subquery })  // OK - "issue" refers to subquery output
+```
 
-// Workaround: wrap in another from()
-return q.from({ votesQ: problematicQuery })
-  .where(({ votesQ }) => eq(votesQ.poolAddress, poolAddress))
+```typescript
+// ❌ PREVENTED: Same collection, same alias
+const subquery = q.from({ lock: ... }).join({ vote: votesCollection }, ...)
+return q.from({ vote: votesCollection }).join({ lock: subquery }, ...)
+// Error: Both use "vote" for votesCollection directly
 ```
 
-This works because the wrapped query no longer directly uses "vote" at the top level, avoiding the alias conflict.
+### Workaround for Users
+
+Rename the alias in either the parent or subquery:
+
+```typescript
+// Discord bug - renamed "vote" to "v" in subquery
+const locksAgg = q
+  .from({ lock: c.locksCollection })
+  .join({ v: c.votesCollection }, ({ lock, v }) =>  // Renamed!
+    eq(lock._id, v.lockId)
+  )
+
+return q
+  .from({ vote: c.votesCollection })  // No conflict now
+  .join({ lock: locksAgg }, ...)
+```
 
 ---
 
 **Files Modified:**
-- `packages/db/src/query/compiler/index.ts` (added collectQueryAliases, fresh cache for subqueries)
-- `packages/db/src/query/compiler/joins.ts` (same changes for join processing)
+- `packages/db/src/errors.ts` - Added `DuplicateAliasInSubqueryError`
+- `packages/db/src/query/compiler/index.ts` - Added validation logic
+- `packages/db/src/query/compiler/joins.ts` - Added validation logic
+- `packages/db/tests/query/discord-alias-bug.test.ts` - Test for the Discord bug
 
 **Investigation Date:** 2025-10-24
-**Investigated By:** Claude Code
+**Solution Date:** 2025-10-24
+**Investigated & Fixed By:** Claude Code
diff --git a/packages/db/src/errors.ts b/packages/db/src/errors.ts
index 7ec6dd478..64180f521 100644
--- a/packages/db/src/errors.ts
+++ b/packages/db/src/errors.ts
@@ -369,6 +369,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}`)
diff --git a/packages/db/src/query/compiler/index.ts b/packages/db/src/query/compiler/index.ts
index 1cd033453..167e3fab9 100644
--- a/packages/db/src/query/compiler/index.ts
+++ b/packages/db/src/query/compiler/index.ts
@@ -3,6 +3,7 @@ import { optimizeQuery } from "../optimizer.js"
 import {
   CollectionInputNotFoundError,
   DistinctRequiresSelectError,
+  DuplicateAliasInSubqueryError,
   HavingRequiresGroupByError,
   LimitOffsetRequireOrderByError,
   UnsupportedFromTypeError,
@@ -124,6 +125,9 @@ export function compileQuery(
   // of the same collection (e.g., self-joins) maintain independent filtered streams.
   const sources: Record<string, KeyedStream> = {}
 
+  // Collect direct collection aliases used in this query (for validation when processing subqueries)
+  const parentCollectionAliases = collectDirectCollectionAliases(query)
+
   // Process the FROM clause to get the main source
   const {
     alias: mainSource,
@@ -141,7 +145,8 @@ export function compileQuery(
     cache,
     queryMapping,
     aliasToCollectionId,
-    aliasRemapping
+    aliasRemapping,
+    parentCollectionAliases
   )
   sources[mainSource] = mainInput
 
@@ -375,6 +380,52 @@ 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 that a subquery doesn't reuse any collection aliases from its parent query.
+ * Only checks aliases for direct collection references, not subquery references.
+ * Throws DuplicateAliasInSubqueryError if conflicts are found.
+ */
+function validateSubqueryAliases(
+  subquery: QueryIR,
+  parentCollectionAliases: Set<string>
+): void {
+  const subqueryCollectionAliases = collectDirectCollectionAliases(subquery)
+
+  for (const alias of subqueryCollectionAliases) {
+    if (parentCollectionAliases.has(alias)) {
+      throw new DuplicateAliasInSubqueryError(
+        alias,
+        Array.from(parentCollectionAliases)
+      )
+    }
+  }
+}
+
 /**
  * Processes the FROM clause, handling direct collection references and subqueries.
  * Populates `aliasToCollectionId` and `aliasRemapping` for per-alias subscription tracking.
@@ -391,7 +442,8 @@ function processFrom(
   cache: QueryCache,
   queryMapping: QueryMapping,
   aliasToCollectionId: Record<string, string>,
-  aliasRemapping: Record<string, string>
+  aliasRemapping: Record<string, string>,
+  parentCollectionAliases: Set<string>
 ): { alias: string; input: KeyedStream; collectionId: string } {
   switch (from.type) {
     case `collectionRef`: {
@@ -410,6 +462,9 @@ function processFrom(
       // Find the original query for caching purposes
       const originalQuery = queryMapping.get(from.query) || from.query
 
+      // Validate that subquery doesn't reuse parent query collection aliases
+      validateSubqueryAliases(originalQuery, parentCollectionAliases)
+
       // Recursively compile the sub-query with cache
       const subQueryResult = compileQuery(
         originalQuery,
diff --git a/packages/db/src/query/compiler/joins.ts b/packages/db/src/query/compiler/joins.ts
index 505f90bf3..8805b6f5b 100644
--- a/packages/db/src/query/compiler/joins.ts
+++ b/packages/db/src/query/compiler/joins.ts
@@ -1,6 +1,7 @@
 import { filter, join as joinOperator, map, tap } from "@tanstack/db-ivm"
 import {
   CollectionInputNotFoundError,
+  DuplicateAliasInSubqueryError,
   InvalidJoinCondition,
   InvalidJoinConditionLeftSourceError,
   InvalidJoinConditionRightSourceError,
@@ -121,6 +122,9 @@ function processJoin(
 ): NamespacedAndKeyedStream {
   const isCollectionRef = joinClause.from.type === `collectionRef`
 
+  // Collect parent direct collection aliases for subquery validation
+  const parentCollectionAliases = collectDirectCollectionAliases(rawQuery)
+
   // Get the joined source alias and input stream
   const {
     alias: joinedSource,
@@ -139,7 +143,8 @@ function processJoin(
     queryMapping,
     onCompileSubquery,
     aliasToCollectionId,
-    aliasRemapping
+    aliasRemapping,
+    parentCollectionAliases
   )
 
   // Add the joined source to the sources map
@@ -414,6 +419,52 @@ function getSourceAliasFromExpression(expr: BasicExpression): string | null {
   }
 }
 
+/**
+ * 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 that a subquery doesn't reuse any collection aliases from its parent query.
+ * Only checks aliases for direct collection references, not subquery references.
+ * Throws DuplicateAliasInSubqueryError if conflicts are found.
+ */
+function validateSubqueryAliases(
+  subquery: QueryIR,
+  parentCollectionAliases: Set<string>
+): void {
+  const subqueryCollectionAliases = collectDirectCollectionAliases(subquery)
+
+  for (const alias of subqueryCollectionAliases) {
+    if (parentCollectionAliases.has(alias)) {
+      throw new DuplicateAliasInSubqueryError(
+        alias,
+        Array.from(parentCollectionAliases)
+      )
+    }
+  }
+}
+
 /**
  * Processes the join source (collection or sub-query)
  */
@@ -430,7 +481,8 @@ function processJoinSource(
   queryMapping: QueryMapping,
   onCompileSubquery: CompileQueryFn,
   aliasToCollectionId: Record<string, string>,
-  aliasRemapping: Record<string, string>
+  aliasRemapping: Record<string, string>,
+  parentCollectionAliases: Set<string>
 ): { alias: string; input: KeyedStream; collectionId: string } {
   switch (from.type) {
     case `collectionRef`: {
@@ -449,6 +501,9 @@ function processJoinSource(
       // Find the original query for caching purposes
       const originalQuery = queryMapping.get(from.query) || from.query
 
+      // Validate that subquery doesn't reuse parent query collection aliases
+      validateSubqueryAliases(originalQuery, parentCollectionAliases)
+
       // Recursively compile the sub-query with cache
       const subQueryResult = onCompileSubquery(
         originalQuery,
diff --git a/packages/db/tests/query/discord-alias-bug.test.ts b/packages/db/tests/query/discord-alias-bug.test.ts
new file mode 100644
index 000000000..7f547d4ef
--- /dev/null
+++ b/packages/db/tests/query/discord-alias-bug.test.ts
@@ -0,0 +1,121 @@
+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(`Discord Bug: Same Alias in Parent and Subquery`, () => {
+  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 error when subquery uses same alias as parent (Discord bug)`, () => {
+    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 }) // CONFLICT: "vote" alias used here
+            .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(`workaround: rename alias in one of the queries`, () => {
+    const query = createLiveQueryCollection({
+      startSync: true,
+      query: (q) => {
+        const locksAgg = q
+          .from({ lock: locksCollection })
+          .join(
+            { v: votesCollection },
+            (
+              { lock, v } // Renamed to "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
+    // Each lock (2) joins with each vote for that lock
+    // Lock 1 has 2 votes, Lock 2 has 1 vote
+    // But locksAgg groups by lock, so we get 2 aggregated lock records
+    // Each of the 3 votes joins with its corresponding lock aggregate
+    expect(results.length).toBeGreaterThan(0)
+    expect(results.every((r) => r.lockName)).toBe(true)
+  })
+})

From bd77a671938ceb0130b1b617447ea017710ebe64 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 24 Oct 2025 18:50:28 +0000
Subject: [PATCH 3/6] docs: clean up investigation doc and add changeset
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 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 <noreply@anthropic.com>
---
 .../validate-duplicate-subquery-aliases.md    |   5 +
 INVESTIGATION_SAME_COLLECTION_BUG.md          | 201 +++++++-----------
 PR_UPDATE.md                                  |  62 ++++++
 3 files changed, 144 insertions(+), 124 deletions(-)
 create mode 100644 .changeset/validate-duplicate-subquery-aliases.md
 create mode 100644 PR_UPDATE.md

diff --git a/.changeset/validate-duplicate-subquery-aliases.md b/.changeset/validate-duplicate-subquery-aliases.md
new file mode 100644
index 000000000..4a3643d0d
--- /dev/null
+++ b/.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.
diff --git a/INVESTIGATION_SAME_COLLECTION_BUG.md b/INVESTIGATION_SAME_COLLECTION_BUG.md
index 502d24962..1a367e9c4 100644
--- a/INVESTIGATION_SAME_COLLECTION_BUG.md
+++ b/INVESTIGATION_SAME_COLLECTION_BUG.md
@@ -1,167 +1,120 @@
-# Investigation: Same Collection in Subquery and Main Query Bug
+# Discord Bug: Duplicate Collection Alias in Subqueries
 
-## Bug Report Summary (from Discord)
+## Bug Report (from Discord)
 
-When using the same collection with the same alias in both a subquery and the main query, two issues occur:
+**Reporter:** JustTheSyme
+**Date:** 2025-10-24
 
-1. **Empty Results**: When a subquery has a join with a collection, and the main query also uses that collection, the query returns empty results.
+When using the same collection with the same alias in both a subquery and the main query, two issues occurred:
 
-2. **Aggregation Cross-Leaking**: Aggregated values from subqueries show incorrect values (individual row values instead of aggregates).
+1. **Empty Results**: Subquery with joins returns `[]` instead of expected data
+2. **Aggregation Cross-Leaking**: Aggregated values show incorrect data (individual values instead of aggregates)
 
-Example:
-```typescript
-const locksAgg = q
-  .from({ lock: c.locksCollection })
-  .join({ vote: c.votesCollection }, ...) // Uses "vote" alias
-  .groupBy(...)
-  .select({ overallPercent: sum(vote.percent) })
-
-return q
-  .from({ vote: c.votesCollection })  // ALSO uses "vote" alias
-  .join({ lockAgg }, ...)
-  .select({ percent: vote.percent, overallPercent: lockAgg?.overallPercent })
-```
-
-Expected: `overallPercent` should be the sum (e.g., 45)
-Actual: `overallPercent` equals individual `percent` values (e.g., 30)
-
-## Root Cause Analysis
-
-###  1. Shared Input Streams
-
-The core issue is in the query compiler architecture:
-
-- All queries (parent and subqueries) receive the same `allInputs` map containing keyed streams for each collection alias
-- When a parent query and subquery both use the same alias (e.g., "vote"), they share the SAME input stream
-- IVM streams are stateful, and sharing them between different query contexts causes interference
-
-### 2. Caching Issues
-
-The query compiler caches compiled queries using `QueryIR` as the key. When a subquery is compiled multiple times in different contexts, it returns the cached result from the first compilation, which has the wrong input bindings.
-
-## Attempted Fix
-
-I implemented a partial fix in `packages/db/src/query/compiler/index.ts` and `packages/db/src/query/compiler/joins.ts`:
-
-1. **Input Filtering**: Created `collectQueryAliases()` to identify which collection aliases each query needs
-2. **Fresh Cache**: Each subquery compilation uses a fresh `WeakMap` cache to prevent incorrect caching
-
-### Code Changes
+### Example from Discord
 
 ```typescript
-// In processFrom() for QueryRef case:
-const subqueryAliases = collectQueryAliases(originalQuery)
-const filteredInputs: Record<string, KeyedStream> = {}
-for (const alias of subqueryAliases) {
-  if (allInputs[alias]) {
-    filteredInputs[alias] = allInputs[alias]
-  }
-}
-
-const subqueryCache = new WeakMap()
-const subqueryMapping = new WeakMap()
-
-const subQueryResult = compileQuery(
-  originalQuery,
-  filteredInputs,  // Filtered inputs
-  collections,
-  subscriptions,
-  callbacks,
-  lazySources,
-  optimizableOrderByCollections,
-  setWindowFn,
-  subqueryCache,  // Fresh cache
-  subqueryMapping
-)
+const votes = useLiveQuery((q) => {
+  const locksAgg = q
+    .from({ lock: c.locksCollection })
+    .join({ vote: c.votesCollection }, ({ lock, vote }) =>
+      eq(lock._id, vote.lockId),
+    )
+    .groupBy(({ lock }) => [lock._id])
+    .select(({ vote }) => ({
+      _id: vote.lockId,
+      totalPercent: sum(vote.percent),
+    }))
+
+  return q
+    .from({ vote: c.votesCollection })  // ⚠️ "vote" alias reused!
+    .join({ lockAgg }, ({ vote, lockAgg }) => eq(lockAgg._id, vote.lockId))
+    .select(({ vote, lockAgg }) => ({
+      ...vote,
+      overallPercent: lockAgg?.totalPercent,  // Shows wrong values
+    }))
+})
 ```
 
-## Current Status
-
-- ✅ Existing tests continue to pass (including nested subquery tests)
-- ❌ The specific bug is NOT fixed - tests still show empty results and cross-leaking
-
-## Why the Fix Doesn't Work
-
-Even with filtering and fresh caching, the fundamental issue remains: **parent and subquery still share the same input streams** when they use the same alias. The filtering only determines WHICH streams to pass, but if both need "vote", they get the same stream instance.
+**Expected:** `overallPercent` = sum of all votes (e.g., 45)
+**Actual:** `overallPercent` = individual vote percent (e.g., 30)
 
-## Proper Solution Required
+## Root Cause
 
-This bug requires a more substantial architectural change:
+When both parent query and subquery use the same alias for a direct collection reference (e.g., both use `vote: votesCollection`), they **share the same input stream**. IVM streams are stateful, and this sharing causes interference between query contexts, leading to:
+- Empty results when joins are involved
+- Incorrect aggregation values (context leaking)
 
-### Option 1: Separate Streams Per Context
-- Create independent input streams for each query compilation context
-- Subqueries would get their own streams, not share the parent's
-- Requires changes to how inputs are created and managed
+## Solution
 
-### Option 2: Stream Isolation
-- Implement a mechanism to "fork" or isolate streams when they're used in multiple contexts
-- May require changes to the IVM layer
-
-### Option 3: Alias Namespacing
-- Internally rename aliases in subqueries to avoid conflicts
-- E.g., parent uses "vote", subquery internally uses "vote_subquery_1"
-- Requires careful tracking and remapping of aliases
-
-## Solution Implemented
-
-After Sam's insight, the fix is to **validate and prevent** alias reuse, not to make it work:
+After consultation with Sam, the fix is to **validate and prevent** this pattern rather than make it work.
 
 ### Implementation
 
-Added validation that throws a clear error when a subquery uses the same alias as its parent query for DIRECT collection references:
+Added validation that throws a clear error when a subquery reuses a parent's collection alias:
 
-1. **New Error Type** (`DuplicateAliasInSubqueryError`):
+1. **New Error Type**: `DuplicateAliasInSubqueryError`
    - Clear message explaining the conflict
-   - Lists all parent aliases for context
+   - Lists parent query aliases for context
    - Suggests renaming the alias
 
-2. **Validation Logic**:
-   - `collectDirectCollectionAliases()`: Collects only CollectionRef aliases, not QueryRef
+2. **Validation Functions**:
+   - `collectDirectCollectionAliases()`: Collects only CollectionRef aliases (not QueryRef)
    - `validateSubqueryAliases()`: Checks for conflicts before compiling subqueries
-   - Only validates direct collection references to allow legitimate subquery wrapping
 
-### Key Insight
+3. **Smart Detection**:
+   - Only validates DIRECT collection references to allow legitimate subquery wrapping
+   - Allows: `q.from({ issue: subquery })` where `issue` refers to subquery output
+   - Prevents: Both using `{ vote: votesCollection }` directly
 
-The validation only checks **direct** collection references (CollectionRef), not subquery references (QueryRef). This allows:
+### Example Error
 
 ```typescript
-// ✅ ALLOWED: Different alias scopes
-const subquery = q.from({ issue: issuesCollection })
-return q.from({ issue: subquery })  // OK - "issue" refers to subquery output
+QueryCompilationError: Subquery uses alias "vote" which is already used in the parent query.
+Each alias must be unique across parent and subquery contexts.
+Parent query aliases: vote, lock.
+Please rename "vote" in either the parent query or subquery to avoid conflicts.
 ```
 
-```typescript
-// ❌ PREVENTED: Same collection, same alias
-const subquery = q.from({ lock: ... }).join({ vote: votesCollection }, ...)
-return q.from({ vote: votesCollection }).join({ lock: subquery }, ...)
-// Error: Both use "vote" for votesCollection directly
-```
-
-### Workaround for Users
+### User Workaround
 
-Rename the alias in either the parent or subquery:
+Simply rename the alias in either the parent or subquery:
 
 ```typescript
-// Discord bug - renamed "vote" to "v" in subquery
+// ✅ FIXED: Renamed "vote" to "v" in subquery
 const locksAgg = q
   .from({ lock: c.locksCollection })
   .join({ v: c.votesCollection }, ({ lock, v }) =>  // Renamed!
     eq(lock._id, v.lockId)
   )
+  .groupBy(({ lock }) => [lock._id])
+  .select(({ v }) => ({
+    _id: v.lockId,
+    totalPercent: sum(v.percent),
+  }))
 
 return q
   .from({ vote: c.votesCollection })  // No conflict now
-  .join({ lock: locksAgg }, ...)
+  .join({ lockAgg }, ({ vote, lockAgg }) => eq(lockAgg._id, vote.lockId))
+  .select(({ vote, lockAgg }) => ({
+    ...vote,
+    overallPercent: lockAgg?.totalPercent,
+  }))
 ```
 
----
+## Files Modified
 
-**Files Modified:**
 - `packages/db/src/errors.ts` - Added `DuplicateAliasInSubqueryError`
-- `packages/db/src/query/compiler/index.ts` - Added validation logic
-- `packages/db/src/query/compiler/joins.ts` - Added validation logic
-- `packages/db/tests/query/discord-alias-bug.test.ts` - Test for the Discord bug
+- `packages/db/src/query/compiler/index.ts` - Added validation in `processFrom()`
+- `packages/db/src/query/compiler/joins.ts` - Added validation in `processJoinSource()`
+- `packages/db/tests/query/discord-alias-bug.test.ts` - Test coverage for the bug
+
+## Testing
+
+Added comprehensive test coverage in `discord-alias-bug.test.ts`:
+- Validates the error is thrown when aliases conflict
+- Verifies the workaround (renaming) works correctly
+
+---
 
-**Investigation Date:** 2025-10-24
-**Solution Date:** 2025-10-24
-**Investigated & Fixed By:** Claude Code
+**Investigation & Solution:** 2025-10-24
+**Fixed By:** Claude Code
diff --git a/PR_UPDATE.md b/PR_UPDATE.md
new file mode 100644
index 000000000..1340508e9
--- /dev/null
+++ b/PR_UPDATE.md
@@ -0,0 +1,62 @@
+# PR Title
+fix: validate against duplicate collection aliases in subqueries
+
+# PR Body
+
+## Summary
+
+Fixes a Discord bug where using the same collection alias in both a parent query and subquery causes empty results or incorrect aggregation values.
+
+## Problem
+
+When both parent and subquery use the same alias for a direct collection reference:
+
+```typescript
+const locksAgg = q
+  .from({ lock: c.locksCollection })
+  .join({ vote: c.votesCollection }, ...)  // Uses "vote"
+
+return q
+  .from({ vote: c.votesCollection })  // Also uses "vote" directly
+  .join({ lock: locksAgg }, ...)
+```
+
+**Result:**
+- Empty query results
+- Incorrect aggregation (values from individual rows instead of aggregates)
+
+**Root Cause:** Both queries share the same input stream, causing interference.
+
+## Solution
+
+Added validation that throws a clear `DuplicateAliasInSubqueryError` when this pattern is detected.
+
+**Implementation:**
+- New error type with helpful message suggesting to rename the alias
+- `collectDirectCollectionAliases()`: Identifies conflicting aliases
+- `validateSubqueryAliases()`: Validates before compiling subqueries
+- Only validates DIRECT collection references (allows legitimate subquery wrapping)
+
+**User Fix:**
+Simply rename the alias in either the parent or subquery:
+
+```typescript
+const locksAgg = q
+  .from({ lock: c.locksCollection })
+  .join({ v: c.votesCollection }, ...)  // Renamed "vote" to "v"
+
+return q
+  .from({ vote: c.votesCollection })  // No conflict
+  .join({ lock: locksAgg }, ...)
+```
+
+## Testing
+
+- Added `discord-alias-bug.test.ts` with comprehensive test coverage
+- Validates error is thrown for conflicting aliases
+- Verifies workaround works correctly
+
+## Related
+
+Fixes Discord bug reported by JustTheSyme.
+See `INVESTIGATION_SAME_COLLECTION_BUG.md` for full investigation details.

From 1fbed65e30ab3bffcf811f1820f69aacb8defe30 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 24 Oct 2025 19:18:39 +0000
Subject: [PATCH 4/6] chore: clean up temporary documentation files
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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

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

Co-Authored-By: Claude <noreply@anthropic.com>
---
 INVESTIGATION_SAME_COLLECTION_BUG.md | 120 ---------------------------
 PR_UPDATE.md                         |  62 --------------
 2 files changed, 182 deletions(-)
 delete mode 100644 INVESTIGATION_SAME_COLLECTION_BUG.md
 delete mode 100644 PR_UPDATE.md

diff --git a/INVESTIGATION_SAME_COLLECTION_BUG.md b/INVESTIGATION_SAME_COLLECTION_BUG.md
deleted file mode 100644
index 1a367e9c4..000000000
--- a/INVESTIGATION_SAME_COLLECTION_BUG.md
+++ /dev/null
@@ -1,120 +0,0 @@
-# Discord Bug: Duplicate Collection Alias in Subqueries
-
-## Bug Report (from Discord)
-
-**Reporter:** JustTheSyme
-**Date:** 2025-10-24
-
-When using the same collection with the same alias in both a subquery and the main query, two issues occurred:
-
-1. **Empty Results**: Subquery with joins returns `[]` instead of expected data
-2. **Aggregation Cross-Leaking**: Aggregated values show incorrect data (individual values instead of aggregates)
-
-### Example from Discord
-
-```typescript
-const votes = useLiveQuery((q) => {
-  const locksAgg = q
-    .from({ lock: c.locksCollection })
-    .join({ vote: c.votesCollection }, ({ lock, vote }) =>
-      eq(lock._id, vote.lockId),
-    )
-    .groupBy(({ lock }) => [lock._id])
-    .select(({ vote }) => ({
-      _id: vote.lockId,
-      totalPercent: sum(vote.percent),
-    }))
-
-  return q
-    .from({ vote: c.votesCollection })  // ⚠️ "vote" alias reused!
-    .join({ lockAgg }, ({ vote, lockAgg }) => eq(lockAgg._id, vote.lockId))
-    .select(({ vote, lockAgg }) => ({
-      ...vote,
-      overallPercent: lockAgg?.totalPercent,  // Shows wrong values
-    }))
-})
-```
-
-**Expected:** `overallPercent` = sum of all votes (e.g., 45)
-**Actual:** `overallPercent` = individual vote percent (e.g., 30)
-
-## Root Cause
-
-When both parent query and subquery use the same alias for a direct collection reference (e.g., both use `vote: votesCollection`), they **share the same input stream**. IVM streams are stateful, and this sharing causes interference between query contexts, leading to:
-- Empty results when joins are involved
-- Incorrect aggregation values (context leaking)
-
-## Solution
-
-After consultation with Sam, the fix is to **validate and prevent** this pattern rather than make it work.
-
-### Implementation
-
-Added validation that throws a clear error when a subquery reuses a parent's collection alias:
-
-1. **New Error Type**: `DuplicateAliasInSubqueryError`
-   - Clear message explaining the conflict
-   - Lists parent query aliases for context
-   - Suggests renaming the alias
-
-2. **Validation Functions**:
-   - `collectDirectCollectionAliases()`: Collects only CollectionRef aliases (not QueryRef)
-   - `validateSubqueryAliases()`: Checks for conflicts before compiling subqueries
-
-3. **Smart Detection**:
-   - Only validates DIRECT collection references to allow legitimate subquery wrapping
-   - Allows: `q.from({ issue: subquery })` where `issue` refers to subquery output
-   - Prevents: Both using `{ vote: votesCollection }` directly
-
-### Example Error
-
-```typescript
-QueryCompilationError: Subquery uses alias "vote" which is already used in the parent query.
-Each alias must be unique across parent and subquery contexts.
-Parent query aliases: vote, lock.
-Please rename "vote" in either the parent query or subquery to avoid conflicts.
-```
-
-### User Workaround
-
-Simply rename the alias in either the parent or subquery:
-
-```typescript
-// ✅ FIXED: Renamed "vote" to "v" in subquery
-const locksAgg = q
-  .from({ lock: c.locksCollection })
-  .join({ v: c.votesCollection }, ({ lock, v }) =>  // Renamed!
-    eq(lock._id, v.lockId)
-  )
-  .groupBy(({ lock }) => [lock._id])
-  .select(({ v }) => ({
-    _id: v.lockId,
-    totalPercent: sum(v.percent),
-  }))
-
-return q
-  .from({ vote: c.votesCollection })  // No conflict now
-  .join({ lockAgg }, ({ vote, lockAgg }) => eq(lockAgg._id, vote.lockId))
-  .select(({ vote, lockAgg }) => ({
-    ...vote,
-    overallPercent: lockAgg?.totalPercent,
-  }))
-```
-
-## Files Modified
-
-- `packages/db/src/errors.ts` - Added `DuplicateAliasInSubqueryError`
-- `packages/db/src/query/compiler/index.ts` - Added validation in `processFrom()`
-- `packages/db/src/query/compiler/joins.ts` - Added validation in `processJoinSource()`
-- `packages/db/tests/query/discord-alias-bug.test.ts` - Test coverage for the bug
-
-## Testing
-
-Added comprehensive test coverage in `discord-alias-bug.test.ts`:
-- Validates the error is thrown when aliases conflict
-- Verifies the workaround (renaming) works correctly
-
----
-
-**Investigation & Solution:** 2025-10-24
-**Fixed By:** Claude Code
diff --git a/PR_UPDATE.md b/PR_UPDATE.md
deleted file mode 100644
index 1340508e9..000000000
--- a/PR_UPDATE.md
+++ /dev/null
@@ -1,62 +0,0 @@
-# PR Title
-fix: validate against duplicate collection aliases in subqueries
-
-# PR Body
-
-## Summary
-
-Fixes a Discord bug where using the same collection alias in both a parent query and subquery causes empty results or incorrect aggregation values.
-
-## Problem
-
-When both parent and subquery use the same alias for a direct collection reference:
-
-```typescript
-const locksAgg = q
-  .from({ lock: c.locksCollection })
-  .join({ vote: c.votesCollection }, ...)  // Uses "vote"
-
-return q
-  .from({ vote: c.votesCollection })  // Also uses "vote" directly
-  .join({ lock: locksAgg }, ...)
-```
-
-**Result:**
-- Empty query results
-- Incorrect aggregation (values from individual rows instead of aggregates)
-
-**Root Cause:** Both queries share the same input stream, causing interference.
-
-## Solution
-
-Added validation that throws a clear `DuplicateAliasInSubqueryError` when this pattern is detected.
-
-**Implementation:**
-- New error type with helpful message suggesting to rename the alias
-- `collectDirectCollectionAliases()`: Identifies conflicting aliases
-- `validateSubqueryAliases()`: Validates before compiling subqueries
-- Only validates DIRECT collection references (allows legitimate subquery wrapping)
-
-**User Fix:**
-Simply rename the alias in either the parent or subquery:
-
-```typescript
-const locksAgg = q
-  .from({ lock: c.locksCollection })
-  .join({ v: c.votesCollection }, ...)  // Renamed "vote" to "v"
-
-return q
-  .from({ vote: c.votesCollection })  // No conflict
-  .join({ lock: locksAgg }, ...)
-```
-
-## Testing
-
-- Added `discord-alias-bug.test.ts` with comprehensive test coverage
-- Validates error is thrown for conflicting aliases
-- Verifies workaround works correctly
-
-## Related
-
-Fixes Discord bug reported by JustTheSyme.
-See `INVESTIGATION_SAME_COLLECTION_BUG.md` for full investigation details.

From 632ef93be1523f7b000e4e657e4dd5044b79d292 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 24 Oct 2025 19:33:22 +0000
Subject: [PATCH 5/6] fix: run duplicate alias validation before query
 optimization
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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 <noreply@anthropic.com>
---
 packages/db/src/query/compiler/index.ts       | 55 +++++++++++------
 packages/db/src/query/compiler/joins.ts       | 59 +------------------
 .../db/tests/query/discord-alias-bug.test.ts  |  4 +-
 3 files changed, 41 insertions(+), 77 deletions(-)

diff --git a/packages/db/src/query/compiler/index.ts b/packages/db/src/query/compiler/index.ts
index 167e3fab9..621647206 100644
--- a/packages/db/src/query/compiler/index.ts
+++ b/packages/db/src/query/compiler/index.ts
@@ -100,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)
 
@@ -125,9 +130,6 @@ export function compileQuery(
   // of the same collection (e.g., self-joins) maintain independent filtered streams.
   const sources: Record<string, KeyedStream> = {}
 
-  // Collect direct collection aliases used in this query (for validation when processing subqueries)
-  const parentCollectionAliases = collectDirectCollectionAliases(query)
-
   // Process the FROM clause to get the main source
   const {
     alias: mainSource,
@@ -145,8 +147,7 @@ export function compileQuery(
     cache,
     queryMapping,
     aliasToCollectionId,
-    aliasRemapping,
-    parentCollectionAliases
+    aliasRemapping
   )
   sources[mainSource] = mainInput
 
@@ -406,17 +407,19 @@ function collectDirectCollectionAliases(query: QueryIR): Set<string> {
 }
 
 /**
- * Validates that a subquery doesn't reuse any collection aliases from its parent query.
- * Only checks aliases for direct collection references, not subquery references.
- * Throws DuplicateAliasInSubqueryError if conflicts are found.
+ * 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 validateSubqueryAliases(
-  subquery: QueryIR,
-  parentCollectionAliases: Set<string>
+function validateQueryStructure(
+  query: QueryIR,
+  parentCollectionAliases: Set<string> = new Set()
 ): void {
-  const subqueryCollectionAliases = collectDirectCollectionAliases(subquery)
+  // Collect direct collection aliases from this query level
+  const currentLevelAliases = collectDirectCollectionAliases(query)
 
-  for (const alias of subqueryCollectionAliases) {
+  // Check if any current alias conflicts with parent aliases
+  for (const alias of currentLevelAliases) {
     if (parentCollectionAliases.has(alias)) {
       throw new DuplicateAliasInSubqueryError(
         alias,
@@ -424,6 +427,26 @@ function validateSubqueryAliases(
       )
     }
   }
+
+  // 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)
+      }
+    }
+  }
 }
 
 /**
@@ -442,8 +465,7 @@ function processFrom(
   cache: QueryCache,
   queryMapping: QueryMapping,
   aliasToCollectionId: Record<string, string>,
-  aliasRemapping: Record<string, string>,
-  parentCollectionAliases: Set<string>
+  aliasRemapping: Record<string, string>
 ): { alias: string; input: KeyedStream; collectionId: string } {
   switch (from.type) {
     case `collectionRef`: {
@@ -462,9 +484,6 @@ function processFrom(
       // Find the original query for caching purposes
       const originalQuery = queryMapping.get(from.query) || from.query
 
-      // Validate that subquery doesn't reuse parent query collection aliases
-      validateSubqueryAliases(originalQuery, parentCollectionAliases)
-
       // Recursively compile the sub-query with cache
       const subQueryResult = compileQuery(
         originalQuery,
diff --git a/packages/db/src/query/compiler/joins.ts b/packages/db/src/query/compiler/joins.ts
index 8805b6f5b..505f90bf3 100644
--- a/packages/db/src/query/compiler/joins.ts
+++ b/packages/db/src/query/compiler/joins.ts
@@ -1,7 +1,6 @@
 import { filter, join as joinOperator, map, tap } from "@tanstack/db-ivm"
 import {
   CollectionInputNotFoundError,
-  DuplicateAliasInSubqueryError,
   InvalidJoinCondition,
   InvalidJoinConditionLeftSourceError,
   InvalidJoinConditionRightSourceError,
@@ -122,9 +121,6 @@ function processJoin(
 ): NamespacedAndKeyedStream {
   const isCollectionRef = joinClause.from.type === `collectionRef`
 
-  // Collect parent direct collection aliases for subquery validation
-  const parentCollectionAliases = collectDirectCollectionAliases(rawQuery)
-
   // Get the joined source alias and input stream
   const {
     alias: joinedSource,
@@ -143,8 +139,7 @@ function processJoin(
     queryMapping,
     onCompileSubquery,
     aliasToCollectionId,
-    aliasRemapping,
-    parentCollectionAliases
+    aliasRemapping
   )
 
   // Add the joined source to the sources map
@@ -419,52 +414,6 @@ function getSourceAliasFromExpression(expr: BasicExpression): string | null {
   }
 }
 
-/**
- * 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 that a subquery doesn't reuse any collection aliases from its parent query.
- * Only checks aliases for direct collection references, not subquery references.
- * Throws DuplicateAliasInSubqueryError if conflicts are found.
- */
-function validateSubqueryAliases(
-  subquery: QueryIR,
-  parentCollectionAliases: Set<string>
-): void {
-  const subqueryCollectionAliases = collectDirectCollectionAliases(subquery)
-
-  for (const alias of subqueryCollectionAliases) {
-    if (parentCollectionAliases.has(alias)) {
-      throw new DuplicateAliasInSubqueryError(
-        alias,
-        Array.from(parentCollectionAliases)
-      )
-    }
-  }
-}
-
 /**
  * Processes the join source (collection or sub-query)
  */
@@ -481,8 +430,7 @@ function processJoinSource(
   queryMapping: QueryMapping,
   onCompileSubquery: CompileQueryFn,
   aliasToCollectionId: Record<string, string>,
-  aliasRemapping: Record<string, string>,
-  parentCollectionAliases: Set<string>
+  aliasRemapping: Record<string, string>
 ): { alias: string; input: KeyedStream; collectionId: string } {
   switch (from.type) {
     case `collectionRef`: {
@@ -501,9 +449,6 @@ function processJoinSource(
       // Find the original query for caching purposes
       const originalQuery = queryMapping.get(from.query) || from.query
 
-      // Validate that subquery doesn't reuse parent query collection aliases
-      validateSubqueryAliases(originalQuery, parentCollectionAliases)
-
       // Recursively compile the sub-query with cache
       const subQueryResult = onCompileSubquery(
         originalQuery,
diff --git a/packages/db/tests/query/discord-alias-bug.test.ts b/packages/db/tests/query/discord-alias-bug.test.ts
index 7f547d4ef..8c5533bc0 100644
--- a/packages/db/tests/query/discord-alias-bug.test.ts
+++ b/packages/db/tests/query/discord-alias-bug.test.ts
@@ -74,7 +74,7 @@ describe(`Discord Bug: Same Alias in Parent and Subquery`, () => {
             )
             .select(({ vote, lock }) => ({
               voteId: vote._id,
-              lockName: lock.lockName,
+              lockName: lock!.lockName,
             }))
         },
       })
@@ -105,7 +105,7 @@ describe(`Discord Bug: Same Alias in Parent and Subquery`, () => {
           )
           .select(({ vote, lock }) => ({
             voteId: vote._id,
-            lockName: lock.lockName,
+            lockName: lock!.lockName,
           }))
       },
     })

From e75634d8ad98ddc238410e17a74f173f755ab1d5 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 31 Oct 2025 12:59:57 +0000
Subject: [PATCH 6/6] refactor: improve alias validation test naming and
 descriptions
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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 <noreply@anthropic.com>
---
 ...s-bug.test.ts => validate-aliases.test.ts} | 20 ++++++++-----------
 1 file changed, 8 insertions(+), 12 deletions(-)
 rename packages/db/tests/query/{discord-alias-bug.test.ts => validate-aliases.test.ts} (81%)

diff --git a/packages/db/tests/query/discord-alias-bug.test.ts b/packages/db/tests/query/validate-aliases.test.ts
similarity index 81%
rename from packages/db/tests/query/discord-alias-bug.test.ts
rename to packages/db/tests/query/validate-aliases.test.ts
index 8c5533bc0..9e7ed9978 100644
--- a/packages/db/tests/query/discord-alias-bug.test.ts
+++ b/packages/db/tests/query/validate-aliases.test.ts
@@ -38,7 +38,7 @@ function createTestCollections() {
   }
 }
 
-describe(`Discord Bug: Same Alias in Parent and Subquery`, () => {
+describe(`Alias validation in subqueries`, () => {
   let locksCollection: ReturnType<
     typeof createTestCollections
   >[`locksCollection`]
@@ -52,7 +52,7 @@ describe(`Discord Bug: Same Alias in Parent and Subquery`, () => {
     votesCollection = collections.votesCollection
   })
 
-  test(`should throw error when subquery uses same alias as parent (Discord bug)`, () => {
+  test(`should throw DuplicateAliasInSubqueryError when subquery reuses a parent query collection alias`, () => {
     expect(() => {
       createLiveQueryCollection({
         startSync: true,
@@ -68,7 +68,7 @@ describe(`Discord Bug: Same Alias in Parent and Subquery`, () => {
             }))
 
           return q
-            .from({ vote: votesCollection }) // CONFLICT: "vote" alias used here
+            .from({ vote: votesCollection }) // Reuses "vote" alias from subquery
             .join({ lock: locksAgg }, ({ vote, lock }) =>
               eq(lock._id, vote.lockId)
             )
@@ -81,17 +81,15 @@ describe(`Discord Bug: Same Alias in Parent and Subquery`, () => {
     }).toThrow(/Subquery uses alias "vote"/)
   })
 
-  test(`workaround: rename alias in one of the queries`, () => {
+  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 },
-            (
-              { lock, v } // Renamed to "v"
-            ) => eq(lock._id, v.lockId)
+            { v: votesCollection }, // Uses unique alias "v" instead of "vote"
+            ({ lock, v }) => eq(lock._id, v.lockId)
           )
           .select(({ lock }) => ({
             _id: lock._id,
@@ -111,10 +109,8 @@ describe(`Discord Bug: Same Alias in Parent and Subquery`, () => {
     })
 
     const results = query.toArray
-    // Each lock (2) joins with each vote for that lock
-    // Lock 1 has 2 votes, Lock 2 has 1 vote
-    // But locksAgg groups by lock, so we get 2 aggregated lock records
-    // Each of the 3 votes joins with its corresponding lock aggregate
+
+    // Should successfully execute and return results
     expect(results.length).toBeGreaterThan(0)
     expect(results.every((r) => r.lockName)).toBe(true)
   })