# KAIVERSE + Oracle Social — Hard Part Plan (phase 2+)

> Written before signup/agent UX work. Re-skim after each social surface lands —
> new constraints may change zone/place linking.

**Status:** phase-2 **started** (2026-07-16) — overlay depth, LOD hysteresis, zone manifest stub, places API. Full mesh/streaming still open.  
**Owner:** Ryan · Implementer: continue eyeball fly-tests for hard visuals.

---

## 0. North star

One society, two skins:
- **2D Oracle OS** — Home Feed, Shorts, Chat, profiles, groups (present).
- **3D KAIVERSE** — same accounts; groups claim a **planet place**; live social activity can mirror in-world (future).

Humans and guests are the **same public-user path**. Social AIs are first-class; industrial AIs stay host-only.

---

## 1. Planet render / LOD / distance / scale math

### 1.1 Goals
- Correct **apparent size** of planets, ships, buildings at near / mid / far distances.
- No “pop” or flat discs at horizon; no mesh exploding when camera approaches.
- Stable **world units**: 1 unit = N meters (document constant in `kaiverse.js` / native client).

### 1.2 Work items
1. Inventory current distance math (camera far plane, planet radius, LODs) in browser `kaiverse.js` and any `src/bin/kaiverse` paths.
2. Define scale table: planet radius, building footprint, avatar height, draw distances.
3. LOD rungs: impostor / low / mid / high; hysteresis so LODs don’t thrash.
4. Verify **FIRST-PERSON** flight controls stay untouched (additive render-only layers only).
5. Eyeball loop with owner: fly → screenshot → tune (hard visual items — no blind bulk edits).

### 1.3 Later verification
- Screenshots at 10m / 1km / 10km from a known planet.
- No NaN camera / infinite matrix warnings in console.

---

## 2. Zone loading (multi-file assets)

### 2.1 Goals
- Split world into **zones** (planet regions / biomes / social parcels).
- Load only nearby zone packs; unload far packs to cap memory.
- Manifest-driven: `zones/<id>/manifest.json` → meshes, textures, collision, spawn points.

### 2.2 Work items
1. Design zone manifest schema (id, bounds AABB, assets[], streamPriority).
2. Loader: async fetch + cache; cancel in-flight when leaving zone.
3. Prefer many medium files over one giant bundle for progressive load.
4. Error surface: missing zone → placeholder prop + log, never hard crash shell.

### 2.3 Later verification
- Enter zone A only A’s assets in GPU memory estimate; leave A, enter B → A released.

---

## 3. Mesh overlays / glitch fixes (current pain)

### 3.1 Known failure modes (to catalogue in code)
- Mesh overlays z-fighting / depth fighting.
- Incorrect normals or double-sided flags causing flicker.
- Overlay scale not matching parent mesh.
- Transparent overlays sorting wrong (alpha order).
- Stale overlay after zone unload (ghost geometry).

### 3.2 Work items
1. Reproduce each bug with a minimal scene flag (`?debugOverlay=1`).
2. Fix depth: polygonOffset / render order / separate pass.
3. Parent–child transform: overlays must use same world matrix pipeline as host mesh.
4. Unload hooks: dispose geometry + materials on zone exit.
5. Regression checklist in SCRATCH with before/after notes (owner fly-test).

### 3.3 Later verification
- No flicker at grazing angles; no ghost meshes after 10 zone swaps.

---

## 4. Social object → place link (2D ↔ 3D)

### 4.1 Data model (proposed)
```
Place {
  id, tenantId?, groupId?,
  planetId, lat, lon | xyz,
  kind: 'building' | 'land' | 'room',
  label, createdBy, createdAt
}
```
- Group / page / agent hub in Oracle OS **may** own one Place.
- Creating a group later: “Pick planet from discovered set → spawn parcel.”

### 4.2 Work items
1. Persist places in tenant or shared public store (not host secrets).
2. KAIVERSE API: list places near camera; resolve place by groupId.
3. Spawn placeholder building from place record (box/glTF later).
4. Click in-world → open 2D group/profile; click group → “Enter place” jumps camera.

### 4.3 Guest rules
- Public users see public places only; no host telemetry overlays.
- Create place = member/guest allowed for **own** groups only.

---

## 5. Live simulation bridge (feed ↔ world)

### 5.1 Goals
- Posts / shorts / chat spikes can update in-world props (billboards, room lights).
- Not full physics sim day one — event stream is enough.

### 5.2 Work items
1. Event bus: `social.event` { type, actorId, placeId?, ts, payload }.
2. Throttle updates (max N/sec per place).
3. 2D-only users never blocked if KAIVERSE offline.

---

## 6. Shorts / Home Feed (product alignment)

Already in flight as social baseline; hard-part only needs:
- Media URLs that can become billboard textures in places.
- Guest isolation on media APIs (no host paths).

---

## 7. Suggested phase order (after signup/agent)

1. **P0** — Home Feed + Shorts vertical player (2D), guest-safe.  
2. **P1** — Place schema + “group has place” metadata.  
3. **P2** — Zone manifest + load/unload.  
4. **P3** — Overlay/depth bugfix pass with owner fly-tests.  
5. **P4** — Live social → world mirrors.  
6. **P5** — 3D-first default shell (optional).

---

## 8. Constraints (must not violate)

- No whole-file rewrite of `oracle.html` / `kaiverse.js`.
- Do not break first-person flight feel.
- Hard visuals: iterate with owner screenshots.
- Secrets stay out of guest APIs.

---

## 9. Re-skim notes (update after social work)

| Date | Note |
|------|------|
| (initial) | Signup/agent first; KAIVERSE plan-only this goal. |
| 2026-07-16 | Public users now have profile (bio/pronouns/tz/email/locationLabel/interests) + social agents (`/api/social-agents`, DiceBear avatar). Place.createdBy can be userId or agentId. Guest public channels tightened (no kai-training in allowlist). |
| 2026-07-16 | Hard-part code: `shared/kaiverse-hard-part.mjs` (LOD hyst, zone validate, placeOnPlanet); `kaiverse-graphics.js` atmo/cloud polygonOffset; `kaiverse.js` overlay LOD + dispose + zones bootstrap; `POST/GET /api/kaiverse/places`; example zone manifest. |

---

## 10. Files likely involved later

- `kaiverse.js`, `oracle.html` (surgical)
- `tools/oracle-discord/command-center-server.mjs` (places API)
- `src/bin/kaiverse/` only if owner switches focus to native client
- Zone asset dirs under `kaiverse_assets/` or `public/` (TBD)