docs: Add garbage collection documentation and update references

Author: rafikhan

packages/firestore/devdocs/garbage-collection.md

@@ -0,0 +1,62 @@
+# Garbage Collection (LRU)
+
+This document details how the SDK manages local cache size to prevent unbounded growth. It explains the distinction between Eager and LRU collection, the criteria for deletion, and the sequence-number-based algorithm used to identify old data.
+
+## Strategies: Eager vs. LRU
+
+The SDK employs two different strategies depending on the persistence mode:
+
+1.  **Eager GC (Memory Persistence)**:
+    *   Used when persistence is disabled (in-memory only).
+    *   **Behavior**: When a query is stopped (`unsubscribe()`), the SDK immediately releases the reference to the data. If no other active query references those documents, they are deleted from memory instantly.
+    *   **Pros/Cons**: extremely memory efficient, but offers no offline caching across app restarts.
+
+2.  **LRU GC (Disk Persistence)**:
+    *   Used when persistence is enabled (IndexedDB).
+    *   **Behavior**: When a query is stopped, the data remains on disk. A background process periodically checks the total cache size. If it exceeds a threshold, the "Least Recently Used" data is purged.
+    *   **Pros/Cons**: Supports offline apps and faster re-querying, but requires complex management of "Sequence Numbers" to track usage.
+
+*The rest of this document focuses on the LRU strategy.*
+
+## What is Collected?
+
+Garbage collection runs in the background. It does not indiscriminately delete data. It looks for **Eligible** items:
+
+### 1. Inactive Targets
+A `Target` (internal query representation) is eligible for collection if it is no longer being listened to by the user.
+
+### 2. Orphaned Documents
+A document is only eligible for collection if it is **Orphaned**. A document is Orphaned if:
+*   **No Active Targets**: It does not match *any* currently active query listener.
+*   **No Pending Mutations**: There are no local edits (Sets/Patches) waiting to be sent to the backend.
+
+> **Note**: Mutations are *never* garbage collected. They are only removed once the backend accepts or rejects them.
+
+## Key Concepts
+
+### Sequence Numbers (The Logical Clock)
+To determine "recency," the SDK maintains a global `last_sequence_number` in the `target_globals` table.
+*   **Tick**: Every transaction (write, query listen, remote update) increments this number.
+*   **Tagging**: When a Target is actively listened to or updated, its `last_listen_sequence_number` is updated to the current global tick.
+*   **Effect**: Higher numbers = More recently used.
+
+### The Reference Map (`target_documents`)
+This table acts as a reference counter linking Documents to Targets.
+*   **Active Association**: If `target_id: 2` matches `doc_key: A`, a row exists.
+*   **Sentinel Rows (`target_id: 0`)**: If a document exists in the cache but is not matched by *any* specific target (perhaps previously downloaded, or part of a target that was deleted), it may have a row with `target_id: 0`. This marks the document as present but potentially orphaned.
+
+## The Collection Algorithm
+
+The `LruGarbageCollector` runs periodically (e.g., every few minutes).
+
+1.  **Threshold Check**: It calculates the byte size of the current cache. If `CurrentSize < CacheSizeBytes` (default 100MB), the process aborts.
+2.  **Calculate Cutoff**:
+    *   The GC decides how many items to cull (e.g., 10%).
+    *   It queries the `target_documents` table, ordered by `sequence_number` ASC.
+    *   It finds the sequence number at the 10th percentile. This becomes the **Upper Bound**.
+3.  **Sweep Targets**:
+    *   Any Target in the `targets` table with a `last_listen_sequence_number` <= **Upper Bound** is deleted.
+    *   This removes the "Active" link for any documents associated with that target.
+4.  **Sweep Documents**:
+    *   The GC scans for documents that have *no* rows in `target_documents` (or only sentinel rows) AND have a sequence number <= **Upper Bound**.
+    *   These "Orphaned" documents are deleted from the `remote_documents` table.

packages/firestore/devdocs/overview.md

@@ -44,7 +44,8 @@ To navigate the internals of the SDK, use the following guide:
 *   **[Query Lifecycle](./query-lifecycle.md)**: The state machine of a query. **Read this** to understand how querying and offline capabilities work.
 
 ### Subsystem Deep Dives
-*   **[Persistence Schema](./persistence-schema.md)**: A reference guide for the IndexedDB tables (e.g., `remote_documents`, `mutation_queues`).
+*   **[Persistence Schema](./persistence-schema.md)**: A reference guide for the IndexedDB tables.
+*   **[Garbage Collection](./garbage-collection.md)**: Details the LRU algorithm, Sequence Numbers, and how the SDK manages cache size.
 *   **[Query Execution](./query-execution.md)**: Details on the algorithms used by the Local Store to execute queries (Index Scans vs. Full Collection Scans).
 *   **[Bundles](./bundles.md)**: How the SDK loads and processes data bundles.
 

packages/firestore/devdocs/persistence-schema.md

@@ -33,7 +33,10 @@ While the Android/iOS SDKs use SQLite, the JS SDK uses IndexedDB Object Stores.
 
 ### `target_documents` (The Index)
 *   **Concept**: A reverse index mapping `TargetID` $\leftrightarrow$ `DocumentKey`.
-*   **Purpose**: Optimization. When a query is executed locally, the SDK uses this index to quickly identify which documents belong to a specific TargetID without scanning the entire `remote_documents` table.
+*   **Purpose**:
+    1.  **Query Execution**: Quickly identify documents for a query.
+    2.  **Garbage Collection**: Acts as a reference counter. If a document has entries here with active TargetIDs, it cannot be collected.
+*   **Sentinel Rows**: A row with `TargetID = 0` indicates the document exists in the cache but may not be attached to any active listener. These are primary candidates for Garbage Collection.
 *   **Maintenance**: This is updated whenever a remote snapshot adds/removes a document from a query view.
 
 ## Metadata & Garbage Collection Stores

packages/firestore/devdocs/query-lifecycle.md

@@ -79,22 +79,15 @@ When a user calls `unsubscribe()`, data is **not** immediately deleted.
 
 ## Phase 6: Garbage Collection (The "Death" of a Query)
 
-Since data persists after `unsubscribe()`, the SDK must actively manage disk usage. This is handled by the **LruGarbageCollector**.
-
-### Sequence Numbers
-Every transaction (write, listen, update) increments a global `last_sequence_number` in the `target_globals` table.
-*   **Active Targets**: When a query is listened to, its `target` entry is updated with the current global sequence number.
-*   **Inactive Targets**: Old queries retain older sequence numbers.
-
-### The GC Process
-When the SDK detects memory/disk pressure (or periodically):
-1.  **Reference Delegate**: Scans the `target_documents` reverse index.
-2.  **Orphan Check**: It identifies documents that belong *only* to Targets that are:
-    *   Inactive (0 listeners).
-    *   Old (Sequence number is below the GC threshold).
-3.  **Purge**:
-    *   The document is deleted from `remote_documents`.
-    *   The `Target` metadata is eventually removed from the `targets` table.
+Since data persists after `unsubscribe()`, the SDK must actively manage disk usage.
+
+*   **Eager GC**: If persistence is disabled, data is cleared from memory immediately when the listener count hits 0.
+*   **LRU GC**: If persistence is enabled, the data remains on disk for offline availability.
+
+The **LruGarbageCollector** runs periodically to keep the cache within the configured size (default 40MB/100MB). It uses a "Sequence Number" system to track when data was last used.
+
+For a detailed walkthrough of the algorithm, Sequence Numbers, and Orphaned Documents, see **[Garbage Collection](./garbage-collection.md)**.
+
 
 ## Debugging Tips