From e9b54e399fa162d22f7a7530493590a4d89544ff Mon Sep 17 00:00:00 2001
From: Arnold Balliu <arnold.balliu@gmail.com>
Date: Thu, 16 Apr 2026 00:59:46 -0400
Subject: [PATCH] docs: document the even-segment rule for palace_path
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Firestore paths alternate collection/document, so any palace_path used
as a prefix for collection creation must have an even number of
segments — otherwise `db.collection(f"{palace_path}/{name}")` fails
with ValueError.

This bites anyone nesting the palace under a user doc (e.g.
"users/{id}/memory" feels natural but is 3 segments and produces an
invalid collection path). The fix is to add an anchor doc level
("users/{id}/memory/palace"), which Firestore materializes implicitly.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 docs/FIRESTORE_BACKEND.md | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/docs/FIRESTORE_BACKEND.md b/docs/FIRESTORE_BACKEND.md
index 3997534ab..728d2c852 100644
--- a/docs/FIRESTORE_BACKEND.md
+++ b/docs/FIRESTORE_BACKEND.md
@@ -39,6 +39,37 @@ col = backend.get_collection("projects/myapp", "mempalace_drawers")
 col = backend.get_collection("palace", "mempalace_drawers")
 ```
 
+#### `palace_path` must have an even number of segments
+
+Firestore paths alternate `collection/document/collection/document…`
+Odd-segment paths refer to collections; even-segment paths refer to documents.
+Since `palace_path` is used as a **document-level prefix** — the backend
+appends a collection name (e.g. `mempalace_drawers`) to it — `palace_path`
+must have an **even** number of segments. Passing an odd-segmented
+`palace_path` causes Firestore to reject calls with
+`ValueError: A collection path must have an odd number of components`.
+
+| `palace_path` | Segments | Full path with `mempalace_drawers` appended | OK? |
+|---|---|---|---|
+| `palace` | 1 (odd) | `palace/mempalace_drawers` (2, even) | ❌ |
+| `users/abc123` | 2 (even) | `users/abc123/mempalace_drawers` (3, odd) | ✅ |
+| `users/abc123/memory` | 3 (odd) | `users/abc123/memory/mempalace_drawers` (4, even) | ❌ |
+| `users/abc123/memory/palace` | 4 (even) | `users/abc123/memory/palace/mempalace_drawers` (5, odd) | ✅ |
+
+If you want to nest the palace beneath an intermediate collection (for
+instance, to keep MemPalace's subcollections out of the top-level namespace
+under a user doc), add an explicit virtual anchor document:
+
+```python
+# Nest under users/{id}/memory/<anchor>/…
+col = backend.get_collection("users/abc123/memory/palace", "mempalace_drawers")
+# → Firestore path: users/abc123/memory/palace/mempalace_drawers (5 segs ✅)
+```
+
+The anchor document (`palace` in the example) does not need to be explicitly
+written — Firestore materializes it automatically when the first child
+document is created beneath it.
+
 ### Document Schema
 
 Each document in Firestore: