Lodestone — the geo-anchored cache platform

Status: Phase 0 (Cairn phone MVP) BUILT 2026-07-23 + Phase 1a (server-side transcode → in-app recording re-enabled) BUILT 2026-07-23

• Phase 1b (glasses arrival playback, sim-validated) BUILT 2026-07-23; the rest is planning. The shared substrate under SIGNAL (the AR pursuit game, /for-matt) and Cairn (CAIRN.md, the legacy layer). This doc specs the platform; the two product docs spec the surfaces. Phase 0 code: migration 560_lodestone.sql, /api/lodestone/*, /cairn — see the build sequence below.

Lodestone = internal codename only (a lodestone is a naturally magnetized stone that points the way — it draws you to a place; stone-kinship with Cairn). Not a consumer brand.

Decided 2026-07-23:

• Build order → Cairn phone MVP first (Phase 0 below). Cleanest ethics, max Lovio reuse, de-risks the substrate before PvP + money.
• Architecture → hybrid. Lodestone (anchors/payloads/triggers), the family graph, and Lovio live in HiveJournal's backend; SIGNAL and Cairn are separate branded front-ends hitting that shared API. Brand separation (SIGNAL's game/crypto identity vs. Cairn's sacred one) without rebuilding the core. See §Architecture.

The thesis in one sentence

Build one persistent network of real-world places that a phone or glasses can leave a payload at and a voice can unlock — then let very different products (a high-stakes game, a generational memory vault) ride on the same rails.

Everything below is in service of one substrate, many surfaces. The game funds and battle-tests the tech; the legacy layer is why it's worth building.

Domain model (the core objects)

Deliberately product-agnostic. A "cache" doesn't know if it's a dead drop or a grandmother's story — the payload + rules decide.

• Anchor — a place with meaning. { id, owner_id, lat, lng, alt?, radius_m, place_label, status, created_at }. The geofence is radius_m around the point.
• Payload (polymorphic, kind discriminates):
  • game_clue / dead_drop / intel (SIGNAL)
  • memory_story → { audio_url, voice_id, transcript } (Cairn)
  • puzzle → a challenge that must be answered to proceed
  • trackable → a movable object with a goal (+ optional bounty)
• Trigger — when the payload fires: arrival (geofence enter) · time_window · kin (family-graph relationship) · interest_flag (descendant started tracing) · sequence (prior anchor completed — multi-cache) · match_context (only live during a SIGNAL match).
• Access — who may unlock: public · family (family graph) · match_participants · private. Cairn adds consent flags.
• Discovery — known (shown on a map in advance) vs reveal_on_arrival.
• Logbook — append-only entries on an anchor: who found it, and Cairn's "add a stone" (each generation layers its own story on the same place).
• Trackable ledger — pickups/drops as a trackable moves anchor→anchor; carries an optional bounty (ties to the economy layer).

One table family (lodestone_anchors, lodestone_payloads, lodestone_visits, lodestone_trackables) serves both products. RLS + service role, matching the downstream_* / glasses_* convention.

Architecture (decided — hybrid)

• HiveJournal backend owns the core: the Lodestone tables, the geo-trigger engine, the family graph, and the Lovio pipeline — exposed as a versioned /api/lodestone/* surface. One source of truth for anchors, access, and identity; the expensive/sensitive logic stays server-side.
• SIGNAL and Cairn are separate branded front-ends that call that API. They share auth + the family graph + Lovio but present as their own apps — SIGNAL cold cyan and stakes, Cairn warm Emberkiln and permanence. Neither rebuilds the core; brand separation is a front-end concern.
• Matt's NLU runs client-side in each front-end (local, offline), calling back only to resolve an anchor payload or record a visit.

The four subsystems to build

1. The geo-trigger engine

• Client geofences (phone GPS / glasses) fire "near anchor X."
• Server verifies proximity and resolves trigger + access → returns payload (or 403/425-not-yet). Never trust the client's "I'm here" alone.
• Offline tolerance: pre-download a zone's anchor manifest; resolve geofence
  • NLU locally; sync visits when the connection returns. (Half a game zone has no signal; a homeland village may have none.)

2. Location attestation (the existential one)

GPS spoofing is trivial and the SIGNAL pot makes it lucrative. Before any money rides on "I reached this place," we need attestation: dwell time, motion signature (accelerometer/step cadence consistent with having walked there), plausible speed between anchors, and — where possible — device integrity signals. This is the gate on the entire economy layer. Cairn doesn't need it (no adversary), which is one more reason Cairn ships first.

3. The NLU command / gatekeeper layer (Matt's engine)

Two jobs, one engine, both local + bounded + offline:

• Command grammar (SIGNAL): a fixed verb set — mark, regroup, play clue, where's my team. Speech → { verb, slots } → app action.
• Gatekeeper (Cairn): a talkable anchor — it asks who you are in the family before it opens ("I only open for blood"); the engine decides locally whether the answer unlocks.
• Contract: deterministic speech → intent with a golden test suite (his ethos exactly). Sits in front of any cloud call; cloud is the fallback, not the path.

4. Authoring + moderation

• Authoring: drop a pin, attach a payload, set trigger + access. Cairn reuses the Lovio record/seal flow almost wholesale.
• Moderation: public anchors are user-generated content pinned to real places — trespassing, unsafe spots, harassment. Needs a report/review path before any public tier. Family/private tiers sidestep this early.

How the two surfaces consume it

Reuse map — most of this exists

• Lovio capsule pipeline (create → seal → deliver → unlock, custody-outlives- owner, read-only-for-the-dead) → Cairn payloads + unlock. /dashboard/lovio.
• Living Voice / voice clone (lovio_user_voices + ttsSegment) → Cairn narration in the ancestor's voice.
• Family graph (family_members, linked accounts, invites) → kin access + inheritance descent.
• Glasses app (apps/glasses, Mentra session.audio.playAudio) → arrival playback + voice capture.
• Citizen Scientist Map — precedent for a location-privacy floor (city-centroid, never exact) to borrow for public-tier privacy.
• Platform hygiene — recordHeartbeat + CRON_REGISTRY toggles for any matchmaking / trackable-sweep crons; migration + jest golden-test conventions.

Build sequence (crawl → walk → run)

Each phase is independently shippable and de-risks the next.

• Phase 0 — Cairn phone MVP. ✅ BUILT 2026-07-23. No glasses, no NLU, no money. Record an audio story → drop a pin → family-scoped → arrive and it plays on your phone. Mostly Lovio + a geofence. Proves the "the place talks to you" magic with the cleanest possible ethics (living person records + plays their own stories). Shipped: migration 560_lodestone.sql (anchors / payloads / visits), /api/lodestone/* (backend service + routes, server-verified haversine core golden-tested), and the /cairn front-end. Apply migration 560 to prod; the record→arrive→hear e2e is a human validation step (needs a phone in a real geofence). See the Phase 0 section below + INDEX.md.
  • Phase-0 shipping detail: it launched upload-only — the in-browser recorder was pulled because browsers record WebM/Opus (Chrome) or MP4/AAC (Safari), and iOS Safari can't decode WebM/Opus, so a recorded story would silently fail to play for a family member on an iPhone.
• Phase 1a — Server-side transcode → in-app recording. ✅ BUILT 2026-07-23. A new transcodeToMp3 (services/lodestone-audio.ts, bundled render-kit ffmpeg — no new dep, local CPU) re-encodes any non-MP3 upload to MP3 (44.1 kHz / 128 kbps) inside the POST /anchors create flow before storage, so a clip recorded in any browser plays on every device. The /cairn Record button is restored alongside the upload input. No schema change.
• Phase 1b — Glasses playback. ✅ BUILT 2026-07-23 (sim-validated; device deferred to a human). The same Cairn unlock, arrival-triggered, through apps/glasses. The homeland moment, for real. Location source decided: the @mentra/sdk exposes device GPS — session.location.subscribeToStream({ accuracy: 'tenMeters' }, …) (returns an unsubscribe fn), comfortably fine for the 75 m fence, so no phone-driven fallback was needed. On each fix the glasses hit a thin backend wrapper GET /api/glasses/lodestone/nearby?lat=&lng= (nearestCairnStory reuses nearbyForUser + the haversine core → the single NEAREST playable in-range story + a spoken intro line, records the visit server-side), then session.audio.speak(intro) → playAudio(audio_url). A getLocationStream() provider seam lets CAIRN_SIM_LAT/LNG (or a test) inject a fixed coord, so the whole poll → speak → play loop is desk/CI-testable without hardware (apps/glasses/src/cairn.ts + cairn.test.ts); it's event-driven off the location stream (no cron/heartbeat), dedupes by anchor id, and is off by default (CAIRN_ENABLED). The real on-device arrival still needs the Mentra Live in hand + a real/spoofed GPS fix — human-only.
• Phase 2 — NLU gatekeeper. Matt's engine as the talkable-cache threshold. His first real integration, low-stakes.
• Phase 3 — SIGNAL match layer. Real-time team sync, zones, clue sequences, PvP — no money yet. Proves the game is fun before it's risky.
• Phase 4 — Location attestation. Anti-spoof hardening. The gate.
• Phase 5 — Economy. Crypto pot + rake, behind legal/regulatory clearance (wagering law by region, money transmission, KYC — reuse the coaching-payouts Stripe Connect rails where they fit).

The hard problems (named, not hand-waved)

1. Anti-spoof vs. a live pot — existential for Phase 5; see §2.
2. Custody over decades — who keeps a Cairn alive 50 years on? Endowment? A trust? Handoff to the family graph on death? Unsolved.
3. Regulation — wagering + money transmission (SIGNAL); per-region.
4. Physical safety — a stakes-driven street pursuit; rules of play + zone design must design out sprinting-into-traffic.
5. Privacy & minors — geo-pinning personal/family history to public places; consent; counsel-gated (inherits the Living Voice bright lines).
6. Moderation — public UGC at real coordinates (§Authoring).

Decisions

• ✅ Build order → Cairn phone MVP first (2026-07-23). See Phase 0.
• ✅ App shape → hybrid (2026-07-23): shared HJ backend, separate branded SIGNAL / Cairn front-ends. See §Architecture.
• ⬜ Genealogy — partner (Ancestry / FamilySearch / MyHeritage) or our own light tree? (Defer past Phase 0 — the MVP is family-graph-scoped, no external tree needed yet.)
• ⬜ Physical marker option — an NFC/engraved stone at the real place, or pure AR/GPS?
• ⬜ Name the platform — keep Lodestone internal, or give it a real name?

Phase 0 — Cairn phone MVP (the next build)

The chosen first slice, spelled out. No glasses, no NLU, no money.

• Record → anchor → arrive → hear. A user records an audio story (reusing the Lovio record/seal flow), drops a pin on a map, scopes it to a family member (or the whole family graph), and sets an arrival trigger. The recipient, when physically inside the geofence, gets a notification and plays it.
• Backend: lodestone_anchors + lodestone_payloads(kind='memory_story') + lodestone_visits; /api/lodestone/anchors (CRUD) and /api/lodestone/nearby (proximity resolve, server-verified). Reuse Lovio for audio storage + voice, the family graph for access.
• Front-end: a Cairn web front-end (map + record + a "near you" list) — the first of the hybrid front-ends, hitting the shared API.
• Ethics floor: living person records + plays their own real stories, family-scoped only. No cloned-voice-of-the-dead, no public tier, in Phase 0 — that keeps it inside the existing Lovio consent posture with nothing new to clear. City-centroid privacy floor borrowed from the Citizen Scientist Map for any coarse display.
• Acceptance: stand in a geofence on a phone, hear the story that was left there for you. That's the whole magic, proven, before a single other phase.