Expand request review tooling and KB

docs/kb/systems/chunk-storage-streaming.md

@@ -1,48 +1,47 @@
 # Chunk Storage And Streaming
 
-## What It Does
+## What It Owns
 
-World data is stored as per-chunk JSON files and loaded into the editor as chunk neighborhoods around a center chunk. The runtime caches chunk payloads, shifts neighborhoods as the viewport moves, and saves dirty chunks in batches.
+This system owns the world-mode chunk model: loading chunk neighborhoods, composing chunk data into the current editor session, and persisting chunk updates back to disk.
 
-## Key Files
+## Core Behaviors
+
+- Load a neighborhood of chunks around a world position.
+- Compose room layers from chunk-local rows into a temporary larger editing surface.
+- Compose sparse height layers from chunk data.
+- Compose placed instances and overlays from chunk payloads.
+- Batch-save chunk changes back to the API.
+
+## Important Data
+
+Chunk payloads can contribute:
+
+- `roomLayers`
+- `heightLayers`
+- `instances`
+- `backgroundTileId`
+- chunk coordinates and dimensions
+
+## Important Files
 
 - `server.js`
 - `src/worldChunking.ts`
 - `src/worldshaperStudio/bootstrap.ts`
 - `src/worldshaperStudio/runtime.ts`
-- `src/worldshaperStudio/persistenceController.ts`
 
-## Endpoints It Uses
+## Known Behavior Notes
 
-- `GET /api/world/:worldId/chunk/:chunkX/:chunkY`
-- `POST /api/world/:worldId/chunk/:chunkX/:chunkY`
-- `GET /api/world/:worldId/chunks`
-- `POST /api/world/:worldId/chunks/batch-save`
+- The bootstrap path currently loads a neighborhood around an initial bookmark or world center instead of streaming every chunk in the world.
+- Exact chunk access is grid-based, so many performance requests should start with profiling the current neighborhood/cache path before proposing spatial trees.
+- World mode is not editing one isolated chunk in a vacuum; it edits a composed surface backed by many chunk records.
 
-## Important Data And Rules
+## Relationships
 
-- chunks are stored as `content/worlds/<worldId>/chunks/<x>_<y>.json`
-- world neighborhoods are requested as a square around a center chunk
-- runtime keeps a chunk cache and tracks dirty chunk keys
-- chunk payloads include `roomLayers`, `heightLayers`, `instances`, and optional `backgroundTileId`
+- Feeds `Layers And Tile Editing`, which paints onto the composed chunk neighborhood.
+- Feeds `World Overview`, which visualizes and transforms chunk-level records.
+- Depends on `Persistence And Save Pipeline` to write chunk mutations.
+- Feeds `Rendering And Viewport`, which only draws what the currently loaded chunk neighborhood exposes.
 
-## Invariants And Constraints
+## Triage Hints
 
-- Exact chunk lookup is grid-based and direct.
-- The editor does not load the entire world for normal editing.
-- Small tile edits must sync back into the correct cached chunk.
-- Save flow should preserve chunk-local edits without rebuilding unrelated chunks.
-
-## Common Request Themes
-
-- chunk loading speed
-- chunk streaming behavior
-- per-chunk backgrounds
-- chunk transforms, duplication, deletion
-- performance questions around indexing and caching
-
-## Triage Questions
-
-- Is the request about storage, fetch patterns, cache behavior, or save behavior?
-- Does it affect only visible chunks or the full world?
-- Is the user asking for chunk-local data, or freeform world overlays that break chunk assumptions?
+Requests about chunk loading, chunk transforms, chunk duplication, world streaming, chunk persistence, spatial indexing, and neighborhood performance should start here.