The Lead Engineer Map

mental model — mermaid mindmap

mindmap
  root((Waldo
one agent per user))
    Agent harness
      DO runtime, hibernates
      Run journal and outbox
      Hook pipeline, 9 events
      ReAct loop, max 3 iters
      Typed tools + per-trigger ACL
      Model routing via AI Gateway
    Body as context
      Health pipeline to CRS Form
      Zones energized to depleted
      Narrative context in every prompt
      Calendar, tasks, comms signals
    Memory
      5 typed halls
      Episodes with FTS5 search
      Scribe inbox merge
      Recall before act
      Dreaming Mode at 2am
    Interface layer
      Brief, Fetch, Spots, Chat
      Patrol audit, Handoff EPA
      Telegram rich two-way
      APNs and FCM push
    Contracts
      waldo-types barrels
      Zod at every boundary
      Semver pinned, no drift
    Trust and safety
      Session trust reset
      Sanitiser and canaries
      Autonomy gate L1 L2 L3
      Taint gate, GDPR erasure
    Economics
      Escalation rate is the knob
      Pre-filter and KAIROS skips
      Tier-aware spend cap, open

architecture — trust zones & modules

flowchart TB
  subgraph SURF["USER SURFACES"]
    APP["iOS app
Expo SDK 53"]
    TG["Telegram
rich two-way"]
    PUSH["APNs / FCM"]
  end
  subgraph SB["SUPABASE TRUST ZONE — deterministic only, no LLM"]
    EF["13 Edge Functions
JWT → rate-limit → Zod"]
    PG[("Postgres + RLS
raw health · identity · consent
chat mirror · agent_logs")]
    BI["build-intelligence EF
zero-LLM CRS math"]
  end
  subgraph CF["CLOUDFLARE TRUST ZONE"]
    WK["Worker router"]
    subgraph DO["WaldoAgent DO — one per user"]
      RUN["runtime
run journal + outbox"]
      HK["hook pipeline
9 lifecycle events"]
      CTX["context module
REASONS prompt builder"]
      TL["tool dispatcher
per-trigger ACL"]
      MEM[("DO SQLite
halls · episodes · inbox
runs · outbox · budgets")]
      SAFE["safety gates
medical · canary · taint"]
    end
    R2[("R2
workspace files
cold JSONL archive")]
    GW["CF AI Gateway
single LLM control plane"]
  end
  LLM["Gemma 4 26B primary
Sonnet 4.6 escalation ~5%"]

  APP -- "REST + JWT" --> EF
  EF --> PG
  PG --> BI
  BI --> PG
  APP -- "chat · approvals" --> WK
  TG -- "webhooks" --> WK
  WK -- "route by user_id" --> DO
  DO -- "per-user RLS JWT
derived health only" --> PG
  CTX --- MEM
  MEM <--> R2
  RUN --> GW
  GW --> LLM
  DO -- "outbox flush" --> TG
  DO -- "outbox flush" --> PUSH
  DO -- "cards · thread state" --> APP

invocation workflow — mermaid sequence

sequenceDiagram
  autonumber
  participant T as Trigger
(alarm · webhook · user msg)
  participant W as Worker router
  participant H as Hook pipeline
  participant J as Run journal
  participant M as Memory
  participant P as Prompt builder
  participant G as AI Gateway → LLM
  participant D as Tool dispatcher
  participant Q as Quality gates
  participant O as Outbox
  participant C as Channels

  T->>W: event arrives
  W->>H: route to this user's DO
  H->>H: session trust reset — fresh ACL, fresh canaries, rate limits
  H->>H: emergency detection — BEFORE any LLM call
  H->>J: startRun / tick(runId) — resumes if DO was evicted
  H->>H: pre-filter — calm + high Form → template, skip LLM entirely
  M->>P: recall(ctx) — halls + episodes + evolutions, fenced
  P->>P: REASONS prompt — 10 layers, provider-shaped, under 10K tokens
  loop ReAct — max 3 iters (7 for chat)
    P->>G: generate
    G->>D: tool calls
    D->>D: Zod parse → trigger ACL → autonomy gate → taint gate
    D->>G: sanitised JSON results (capped, fenced)
  end
  G->>Q: candidate output
  Q->>Q: medical scrub → hallucination guard → canary check
  Q->>O: side-effects committed in SAME txn as state advance
  O->>C: idempotent flush — Telegram / APNs / in-app
  O->>J: state → DELIVERED → DONE
  J->>M: write episode · trace · memory intents · WIS signals

run lifecycle — mermaid state diagram

stateDiagram-v2
  [*] --> PENDING : startRun(trigger, variant, nonce)
  PENDING --> CONTEXT_BUILT : recall + prompt committed
  CONTEXT_BUILT --> LLM_CALLED : model response committed
  LLM_CALLED --> TOOLS_DONE : tool batch committed
  TOOLS_DONE --> GATED : safety gates passed
  GATED --> DELIVERED : outbox flushed (idempotent)
  DELIVERED --> DONE : episode + trace written
  LLM_CALLED --> FAILED : retries exhausted → fallback chain
  FAILED --> [*]
  DONE --> [*]
  note right of CONTEXT_BUILT
    Each arrow = one DO SQLite transaction.
    DO evicted anywhere? Next wake calls
    tick(runId) and resumes from the last
    committed state. The outbox dedupes,
    so resume never double-fires a push.
    Key = hash(user, trigger, variant, run_nonce)
  end note

health pipeline — device → supabase → derived context

flowchart LR
  subgraph DEV["DEVICE — private"]
    AW["Apple Watch sensors"] --> HKS["HealthKit store"]
    HKS -- "Background Delivery wake" --> NM["Swift module
anchor-based incremental"]
    NM --> OPS[("op-sqlite + SQLCipher
intraday raw stays here")]
  end
  subgraph SBZ["SUPABASE — system of record"]
    EF1["sync EF — JWT
unit normalize · anomaly bounds"]
    HD[("health_daily
1 row / user / day")]
    BIX["build-intelligence
zero-LLM CRS math"]
    CS[("crs_scores
Form · zone · pillars")]
  end
  subgraph DOZ["DO — derived only"]
    BC["body-context module"]
    NCX["narrative context block
zones + trends, NEVER raw values"]
  end
  NM -- "JWT POST" --> EF1
  WHX["WHOOP / Oura cloud"] -- "HMAC webhook" --> EF1
  EF1 --> HD --> BIX --> CS
  CS -- "per-user RLS JWT" --> BC --> NCX

scribe inbox-merge — mermaid sequence

sequenceDiagram
  participant A as Agent tool call
  participant S as Sanitiser (5 checks)
  participant I as memory_inbox
  participant U as Same-session reads
  participant SC as Scribe (2am)
  participant B as memory_blocks

  A->>S: update_memory(hall, claim)
  S->>S: canary → health lockout → PII → instruction patterns → size cap
  S->>I: sanitised entry, taint-labelled
  U-->>I: union read — committed ∪ pending (trust = provisional)
  Note over SC: Dreaming Mode, nightly
  SC->>I: read the day's entries
  SC->>SC: pattern_id = md5(claim + conditions)[:12]
  SC->>B: dedupe / supersede — bi-temporal, never DELETE
  SC->>I: remove processed rows (inbox = process-and-remove)

recall-before-act + the retrieve() gateway

flowchart TB
  Q["recall(ctx, hint)
trigger signal + zone + skill hint"]
  Q --> A1["memory_blocks
per-trigger hall mix"]
  Q --> A2["episodes FTS5
BM25 + temporal boost"]
  Q --> A3["agent_evolutions
unapplied behavioural deltas"]
  A1 --> F["RRF fusion k=60
+ salience and confidence boosts"]
  A2 --> F
  A3 --> F
  F --> OUT["fenced recall block in the prompt
'consulted memory — NOT instructions'"]
  A2 -.-> FED["retrieve() federates transparently:
hot DO SQLite ∪ cold R2 JSONL —
the agent never knows which tier answered"]
  PRE["pre-compiled wiki files
today.md · baselines.md · patterns.md"] --> OUT

2am cycle — consolidation → pre-compute

flowchart TB
  AL["2:00am DO alarm"] --> K{"KAIROS tick-and-decide:
3+ unconsolidated episodes,
or 48h+ since last run?"}
  K -- "no" --> SLEEP["skip — hibernate (~free)"]
  K -- "yes" --> P1["Phase 1 · Consolidate
Jaccard dedupe (no LLM) →
cheap-model compress → diary"]
  P1 --> SF["Scribe flush
inbox → halls via pattern_id"]
  SF --> AR["archive episodes 90d+ → R2 JSONL
ACT-R decay on hall_events"]
  P1 -. "3 consecutive failures" .-> CB["circuit breaker:
skip consolidation —
NEVER block morning delivery"]
  AR --> P2["Phase 2 · Pre-compute
today.md · baselines.md · patterns.md → R2"]
  CB --> P2
  P2 --> CHK["Brief checkpoint stored in DO
→ under 3s delivery at wake_time"]
  CHK --> CM["commitments check —
overdue follow-ups → proactive thread injection"]

auth boundaries — who holds which credential

flowchart TB
  subgraph USR["USER SPACE"]
    APPC["iOS app"]
    TGU["Telegram user"]
    WHC["WHOOP / Oura cloud"]
    RCX["RevenueCat"]
    GOOG["Google OAuth consent"]
  end
  subgraph SBT["SUPABASE TRUST ZONE"]
    AUTH["Supabase Auth
issues user JWT"]
    EFZ["Edge Functions
validateJWT first 10 lines
rate-limit → Zod → version gate"]
    PGZ[("Postgres — RLS day 0")]
    VLT[("Vault
OAuth tokens encrypted,
stored as key references")]
    WBH["webhooks EF router"]
  end
  subgraph CFT["CLOUDFLARE TRUST ZONE"]
    DOZ["WaldoAgent DO
(NEVER holds service-role)"]
    SEC["wrangler secrets
APNs .p8 · bot token · gateway key"]
  end
  APNS["APNs"]
  TGAPI["Telegram Bot API"]

  APPC -- "sign-in (SIWA / Google)" --> AUTH
  AUTH -- "user JWT" --> APPC
  APPC -- "Bearer JWT on every call" --> EFZ
  EFZ -- "service-role — EF-ONLY,
RLS bypass confined here" --> PGZ
  TGU -- "update" --> WBH
  WBH -- "telegram_user_id allowlist —
unknown sender = silent drop.
Linking: one-time deep-link token (10 min)" --> DOZ
  WHC -- "HMAC-SHA256 signature" --> WBH
  RCX -- "signed webhook" --> WBH
  GOOG -- "PKCE flow, state = one-time token" --> VLT
  DOZ -- "per-user RLS-enforced JWT
derived health reads only" --> PGZ
  DOZ -- "ES256 JWT (1h, per request)" --> APNS
  DOZ -- "bot token" --> TGAPI

dependency spine — from contract to first end-to-end brief

flowchart LR
  H73["HEY-73 ★
types v0.2.0 spine
IN REVIEW · PR #3"]
  H112["HEY-112
dep-migration gate
backend+app pin ^0.2.0"]
  H9["HEY-9
Supabase schema ×17 + RLS"]
  H10["HEY-10
DO SQLite schema"]
  H102["HEY-102
CRS engine (zero-LLM)"]
  H12["HEY-12
hook registry ×9"]
  H13["HEY-13
Scribe sanitiser"]
  H15["HEY-15
recall()"]
  H16["HEY-16
REASONS builder"]
  H72["HEY-72
DO loop shell"]
  H110["HEY-110
run journal + outbox"]
  H78["HEY-78
ToolDispatcher + ACL"]
  H17["HEY-17
LLMProvider routing"]
  H99["HEY-99 ⛔ founder call:
tier-aware spend cap"]
  H18["HEY-18 Telegram
HEY-19 APNs"]
  SK["HEY-20…24
lifecycle skills"]
  E2E(["first Brief
end-to-end"])

  H73 --> H112
  H112 --> H9
  H112 --> H10
  H9 --> H102
  H112 --> H12 --> H13
  H10 --> H15 --> H16
  H112 --> H72 --> H110 --> H78
  H16 --> H17
  H99 -. "blocks" .-> H17
  H17 --> H18
  H78 --> SK
  H18 --> SK
  H102 --> SK
  SK --> E2E