UUIDv8 Poincaré Icosapheric Browser — Build Brief

gist.md

UUIDv8 Poincaré Icosapheric Browser — Build Brief

Owner: SoMaCoSF
Status: In build
Base repo: https://github.com/SoMaCoSF/poincake
Goal: Turn Poincake into a hyperbolic knowledge browser where every entity is a self-describing GYST UUIDv8, and navigation follows icosahedral/dither3d glyph logic.

---

1. What exists now

• src/model/note.ts: Note = { id: NoteId, anchor: GridAnchor, content, appearance, createdAt, updatedAt }
• src/model/arrow.ts: Arrow = { id, from, to, label, appearance, createdAt, updatedAt }
• src/model/worldFile.ts: zod-validated import/export preserving image bytes internally.
• src/grid/tilingAddress.ts: combinatorial anchoring (chartId, walk, local).
• src/geometry/*.ts: hyperbolic disk math and Möbius transforms.
• src/app: React UI shell and interaction controllers.

This is the minimal and correct seam to extend. IDs are pure strings, so we can swap them for UUIDv8 without breaking geometry.

---

2. UUIDv8 spec to implement

128-bit GYST UUIDv8
 0            12            24            48            52            64            66
 │             │             │             │             │             │             │
 └─ Type ──────┴─ Namespace ─┴─ Timestamp ─┴─ Version=8 ─┴─ Fractal ────┴─ Variant ──┴─ Random ─┘
 12 bits       12 bits       24 bits        4 bits         12 bits        2 bits        62 bits

Fields:

• type: note, arrow, asset, portal, world, agent, escrow, endpoint
• namespace: knowledge domain hash
• timestamp: creation time, seconds
• fractal: depth (0-15), domain (0-15), generation (0-15)

Packing:

fractal = ((depth & 0xF) << 8) | ((domain & 0xF) << 4) | (generation & 0xF)

---

3. What to build first

1. src/model/uuid.ts

   • generator/parser/validators for GYST UUIDv8
   • extractors for each semantic field
   • limited procedural glyph seed derivation for dither3d-style visuals

2. Model migration

   • NoteId and ArrowId → UUIDv8 alias
   • factory helpers: newNote(...) auto-assigns a typed UUIDv8
   • world file schema accepts UUIDv8 strings as IDs

3. Spatial mapping

   • optional heuristic: map fractal depth toward radial position and namespace to angle sector
   • this gives a seeded default layout; user placement still wins

4. Visual affordance

   • node hue/shape influenced by type and depth
   • portal notes carry a target UUIDv8 or world-anchor payload
   • simple UUID palette for now; later replace with dither3d glyph

5. Import / export

   • world file continues to serialize the same payloads
   • Zod schema relaxes ID to UUID format string; round-trip must remain stable

---

4. Code paths to edit

• src/model/uuid.ts (new)
• src/model/note.ts
• src/model/arrow.ts
• src/model/worldFile.ts
• optional UI: src/app/AppMenu.tsx, src/app/NoteEditorOverlay.tsx

---

5. Logic diagrams

5.1 Entity creation

createNote
  └─ generate UUIDv8(type='note', namespace=..., depth=...)
       └─ Note.id = UUIDv8
       └─ default anchor :=  seededGridAnchor(depth)  // optional heuristic

5.2 Navigation / search

searchUUID(uuid)
  └─ decode(uuid)
       ├─ type → filter / mode
       ├─ namespace → sector color / region
       └─ depth → preferred ring distance

5.3 Hierarchical unfold

note.depth=3
  └─ children UUIDs share namespace and depth+1
  └─ display as cluster near parent tile

---

6. File layout plan

src/
  model/
    uuid.ts
    note.ts        // use UUIDv8 for NoteId, auto-generate on creation
    arrow.ts       // use UUIDv8 for ArrowId
    worldFile.ts   // schema accepts UUIDv8
  uuid/
    index.ts       // reexports

---

7. Commands to run locally

cd C:/Users/Phoenix/poincake
npm install
npm run dev

---

8. Immediate follow-ups

• Write src/model/uuid.ts and tests.
• Wire generator into src/model/note.ts.
• Add optional defaultAnchorFromUUID() helper.