waggle-os/docs/redesign-warm-hive/PR35-BUILD-PLAN.md

Warm-Hive PR3.5 — Memory-Trust Build Plan

Synthesized from the 5 recon files in docs/redesign-warm-hive/pr35-recon/ (01–05), all verified on branch feature/warm-hive-pr3 @ dac7b696, 2026-06-16. This plan has two halves: Part 1 = the frame.source projection (the keystone enabler), Part 2 = the screen-19 Memory-Trust UI, built in phases on top of it.

Repo root: D:/Projects/waggle-os. Substrate: packages/hive-mind-core/src/mind/. Server: packages/server/src/local/routes/. UI: apps/web/src/.

No-fabrication contract (inherited from PR3): confidence, freshness, and trace-reason are the three places this PR could silently invent data. The plan gates each one off (PR3 streak pattern) wherever the substrate does not hold a real value. See §3 + §5.

---

Part 1 — frame.source projection (the keystone enabler)

The ⬡ provenance pill on Chat + Workspace is blocked by one missing column in two read paths. Recon 01 maps the FE-facing path (the /context route → WorkspaceBriefing); recon 02 maps the SSE step path. The DDL column already exists and is NOT NULL DEFAULT — no migration, no DDL change, no backfill. This is a pure read-side projection.

1.1 The column (no change — context only)

packages/hive-mind-core/src/mind/schema.ts:56-57 — source TEXT NOT NULL DEFAULT 'user_stated' CHECK (source IN ('user_stated','tool_verified','agent_inferred','import','system')). Persisted rows only ever hold these 5 values (the TS FrameSource union at frames.ts:25 is wider — personal|workspace|team_sync are search-time mind labels that fail the CHECK and never persist). The FE owns the label/icon map for the 5 values; the route returns the raw string.

1.2 Workspace Briefing path — REQUIRED (the FE pill keystone)

File A — packages/server/src/local/routes/workspaces.ts (GET /api/workspaces/:id/context, handler @ :364)

Ordered edits:

1. :376 — widen the let recentMemories local from Array<{ content: string; importance: string; date: string }> → Array<{ content: string; importance: string; source: string; date: string }>.
2. :377 — widen the let recentDecisions local from Array<{ content: string; date: string }> → Array<{ content: string; source: string; date: string }>. (Skipping 1+2 makes the server tsc fail against the narrower locals — and npm run build does NOT typecheck the sidecar, so this only surfaces under the §1.4 server tsc.)
3. :393-400 — recentMemories SELECT: add source to the column list and to the as Array<{...}> cast → SELECT content, importance, source, created_at FROM memory_frames ….
4. :402-406 — recentMemories .map() projection: add source: f.source,.
5. :409-417 — recentDecisions SELECT: add source to the column list and cast → SELECT content, source, created_at FROM memory_frames ….
6. :419-429 — recentDecisions .map() returned object: add source: f.source,.

(Exact before/after blocks are in recon 01 §2a/§2b — copy them verbatim.) Purely additive; no existing consumer breaks.

File B — apps/web/src/lib/types.ts (interface WorkspaceContext, :248-249)

7. Widen both inline item shapes with an optional source?:
   • recentDecisions?: Array<{ content: string; source?: string; date: string }>;
   • recentMemories?: Array<{ content: string; importance: string; source?: string; date: string }>;
   • Keep source optional so pre-PR3.5 sidecars still typecheck and the FE degrades to "no pill" when absent.

Consumer (no type change, render only) — apps/web/src/components/os/WorkspaceBriefing.tsx

8. recentMemories rendered at :186-197 (importance badge :189-193) and recentDecisions at :164-178. Swap the bare mono date <div> for <ProvenanceLine source={m.source} when={m.date} onClick={…} /> only when m.source is present; otherwise keep PR3's bare date <div> (the date-only fallback — never a fabricated source). This is the same affordance PR3 already left hooked.

DO NOT TOUCH — the parallel system-prompt builder. workspace-context.ts / workspace-state.ts (buildWorkspaceState → WorkspaceNowBlock) feeds the system prompt, not the FE pill, and its StateItem.source is a different axis (memory|session|awareness). Adding frame.source there is out of scope and would collide on the source name (recon 01 §4). (Note: recon 05 §7 names workspace-context.ts:283-284 as "the" projection gap — that is the system-prompt path; the FE pill keystone is the workspaces.ts /context route in recon 01. They are different routes; for PR3.5 the FE pill, do File A above, not workspace-context.ts.)

1.3 SSE step path — DECISION: project on auto_recall only, paired with the recallMemory widen (recon 02)

Recon 02 verdict: NEEDS-WIRING, not trivially projectable. A streamed step carries { content: string } only; the agent loop exposes onToolUse/onToolResult(name,input,result) with no frame/source; the real source is destroyed when recallMemory() flattens frames to string[] text (orchestrator.ts:453-457).

Project-or-defer decision:

• Blanket "source on every step" is WRONG by design — generic steps (bash, drafting, budget) have no provenance; stamping them is fabrication (PR3's refused move).
• Only the memory-recall step (auto_recall) has genuine provenance. Wiring it is in-scope for PR3.5 iff paired with the recallMemory return-shape widen. If we want to stay server-light this arc, DEFER the SSE step pill and keep PR3's "render the affordance, never fabricated provenance" stance — the Chat ActivityStream already gates on s.provenance presence, so nothing breaks.

Recommended for PR3.5: do the auto_recall slice (it is the honest, load-bearing one and the same "frame.source 1-field projection" the S2 handoff named). The 5 edits / 4 files:

1. packages/agent/src/orchestrator.ts:453-457 (load-bearing) — widen recallMemory() return to carry per-snippet provenance, e.g. add recalledFrames?: Array<{ text: string; source: FrameSource; sourceUrl?: string; when?: string }> alongside the existing recalled: string[]. Frame objects with .source are already in hand inside recallMemory — this is "stop flattening it", not a new query.
2. packages/server/src/local/routes/chat.ts:780-781 — emit source/provenance on the auto_recall step or its tool_result ({ content, provenance?: { source, when } } is additive, backward-compatible).
3. apps/web/src/lib/types.ts:474-479 — add optional provenance?: { source: string; when?: string } to StepContentBlock (and tolerate it in StreamEvent.data handling, :616-619).
4. apps/web/src/hooks/useChat.ts:152 — carry data.provenance onto the pushed step block.
5. apps/web/src/components/os/apps/chat-blocks/BlockRenderer.tsx:30-33 — project s.provenance into ActivityStep (the ActivityStream/ProvenanceLine path already gates on presence; remove only the part of the omitted-provenance comment that no longer holds). Leave all non-memory steps provenance-less by design.

1.4 Verification (Part 1)

# server route typecheck — REQUIRED; npm run build skips the sidecar (runs via tsx transpile-only)
npx tsc --noEmit --project packages/server/tsconfig.json
# agent (only if §1.3 done — recallMemory widen)
npx tsc --noEmit --project packages/agent/tsconfig.json
# FE typecheck — use the app tsconfig directly (the workspace alias is a silent no-op)
npx tsc --noEmit -p apps/web/tsconfig.app.json
npm run test -- --run            # FE unit + touched server suites
npm run lint

Live check: open a workspace with seeded memories → Chat + Workspace Overview render the ⬡ pill on rows that have a source; rows without a source show the bare date (no fabricated pill). Console: 0 errors.

---

Part 2 — Memory-Trust (screen 19), phased

Target screen: docs/design_handoff_waggle_app/design-files/screens/memory-trust.html (authoritative mock, 1:1 token match to PR3's warm tokens per recon 04 §8 — no remapping). Two view modes behind a segmented control: A "Manage memory" (default) and B "Why did you do that?". The standalone host is MemoryCenterApp.tsx (screen 19 extends/replaces it); the reusable core memory/MemoryCenterTab.tsx is shared by the Workspace Memory tab — change once, both update (recon 03).

Reuse, don't rebuild: ConfidenceBadge, EvidenceChip, DetailDrawer, EvidencePanel already exist in components/ui/ (commit afe96355, pre-PR3) and ship today via Memory Center. The new warm atoms are only the 4 listed in §4.

Phase 0 — Primitives (new warm atoms + token decision)

Files to create (apps/web/src/components/os/warm/, export from warm/index.ts:7-20):

• ConfidenceRing.tsx — the §5a 38px ring (see §4).
• ConfidenceBadge decision: the existing ui/confidence-badge.tsx uses the Hive DS --sem-* family; the warm screen wants --healthy/--attention/--risk. Token-family decision (founder call, see §5): align new Memory-Trust confidence atoms to the warm --sem-*→band mapping the screen 19 mock uses (green ≥85 / honey ≥60 / terracotta <60), OR reuse ui/ConfidenceBadge if its --sem-* bands render acceptably. Default recommendation: build ConfidenceRing against warm tokens (matches the mock exactly), reuse ui/ConfidenceBadge where a pill (not a ring) is wanted.
• EvidenceChip for the trace: reuse ui/evidence-chip.tsx (recon 03). Only build a thin TraceEvidenceChip wrapper if the §6b .ev chip needs the multi-segment confidence X% · source · when · still fresh format.
• DetailDrawer: reuse ui/detail-drawer.tsx (recon 03) for the memory-detail open.

Files to modify: ProvenanceLine.tsx — extend to optionally render the §5b 3-segment form ⬡ <id> · source: <src> · ● <freshness> (add a source:-prefix variant + a ● freshness segment colored healthy/attention). Today it renders ⬡ source · when only.

Tokens/primitives reused: all --honey/--healthy/--attention/--risk/--intel + washes + --r-lg 18px/--r-xl 26px + JetBrains Mono/Hanken already defined in both themes (index.css:162-168 dark / :298-304 light). HexAvatar, SectionLabel, DotLive, RunChip/chip patterns already exist.

Data: none (pure presentational atoms).

Phase A — Header / segmented control + editorial hero + stat bar

Files to create/modify:

• New MemoryTrustApp.tsx (or extend MemoryCenterApp.tsx) hosting the §1 sticky .controls bar: eyebrow Memory Trust · view, 2-button segmented switch (Manage memory default-on honey-fill #1a1407 ink | Why did you do that?), swapping .vlabel, theme toggle.
• §2 editorial hero per view (honey eyebrow + 28px/650 H1 with honey non-italic <em> accent
  • 64ch body with bold --text-2 spans). Verbatim copy in recon 04 §2.
• §3 stat bar (View A): 4 cards repeat(4,1fr)→2-col @820px.

Primitives/tokens: SectionLabel for eyebrows; honey-fill segment = .seg button.on treatment (background:var(--honey); color:#1a1407); warn cards use the --attention/color-mix border per recon 04 §3.

Data — REAL vs route-needed:

• Stat #1 "Memories in this hive" (142) — REAL, from GET /api/memory/stats (counts only, mind-isolation honored).
• Stat #2 "High confidence & fresh" (128) — DERIVABLE/PARTIAL: confidence is sparse (harvest-only), freshness is derivable from created_at. If confidence is absent for the mind, gate this card off (show "—" or hide), do not invent a count. See §3.
• Stat #3 "Stale · worth a review" (9) — DERIVABLE from created_at via computeTemporalScore (FE compute or thin route).
• Stat #4 "Awaiting your confirm" (3) — needs route: GET /api/memory?status=unreviewed (filter already works, memory-center.ts:198) — but nothing writes unreviewed today, so the count may legitimately be 0. Wire to the real query; do not seed a fake number.

Phase B — Search + filters (View A toolbar)

Files to modify: the §4 .toolbar inside MemoryTrustApp — search input (placeholder Search what Waggle knows… or ask it to forget something) + 4 filter chips (All on / Stale / Needs confirm / Forgotten).

Primitives/tokens: active chip = --honey-wash fill + --honey-line border (recon 04 §4); reuse warm chip pattern.

Data — REAL vs route-needed:

• Search → GET /api/memory?mind&q&kind&status&minConfidence&limit (memory-center.ts:167) — REAL.
• Stale filter → DERIVABLE client-side over returned created_at.
• Needs confirm filter → GET /api/memory?status=unreviewed — REAL query (may return 0).
• Forgotten filter → no tombstone exists (forget is a hard delete, frames.ts:321). Gate this chip off or relabel — there is no "forgotten" list to show. See §3.

Phase C — Memory rows (confidence ring + provenance + forget/correct/confirm/stale)

Files to create/modify: the §5 .mem row component (3-col [conf ring] [body] [actions]), rendered into .mems grid. Reuse the memory/MemoryCenterTab.tsx + MemoryCard.tsx pattern (already consumes DetailDrawer/ConfidenceBadge/EvidencePanel); add the warm row treatment.

Primitives/tokens: new ConfidenceRing (§4); extended ProvenanceLine (3-segment §5b); corrected banner = --healthy-wash; stale banner = --honey-wash+--honey-line; disputed = --risk border + strikethrough; danger-forget hover = --risk (recon 04 §5).

Data — REAL vs route-needed:

• Row content / id / source → REAL (from /api/memory Memory shape).
• Forget button → DELETE /api/memory/:id?mind=… — REAL, no new backend (hard delete + audit event). Row animates out then removed.
• Correct / edit button → PATCH /api/memory/:id (content + reclassify) — REAL, no new backend.
• Confidence ring → Memory.confidence, only present on harvested frames. Hide the ring (or show a neutral "—" state) when confidence is undefined — never default a number. See §3.
• Freshness ● → DERIVABLE from created_at (computeTemporalScore, 7-day boost / 30-day half-life). Present as honest age ("aging — last seen 6w ago"), never a stored %.
• Stale banner / "Still true?" → derivable trigger; Confirm action → MUST-BUILD route POST /api/memory/:id/confirm (set metadata.status='active', mirroring /archive at memory-center.ts:355). Cheap; the MemoryStatus rails exist.

Phase D — "Why did you do that?" trace (View B)

Files to create/modify: the §6 .trace card — HexAvatar header (trace #a1f9), 4-node connector chain (Goal→Recalled 3→Cross-checked→Acted; dots intel/honey/honey/healthy; evidence chip confidence 94% · source: chat · Tue · still fresh), 3-button footer (Looks right / That memory is wrong → correct it / Forget #M-204 & redo). Shared trust-principle footnote + green slide-up toast on both views.

Primitives/tokens: HexAvatar, DotLive, reused EvidenceChip; connector line per §6b; footer go-button honey-fill / ghost / danger per §6c.

Data — REAL vs route-needed (the honest hard part):

• Trace store is rich and populated for chat (execution_traces + TraceRecorder per turn, chat.ts:1277-1424): reasoning[], toolCalls[], outcome, cost, tokens.
• GAP 1 — chat traces aren't addressable by the agent-traces route. GET /api/agents/:id/traces (agents.ts:469) filters by the agent:{id} tag, but chat start() does NOT pass tags:['agent:…'] (chat.ts:1279-1285). Fix = either add the agent: tag at chat start(), OR add a thin GET /api/sessions/:id/traces reading traceStore.queryParsed({ sessionId }) (store already supports it, execution-traces.ts:328).
• GAP 2 — no frame↔trace backlink. Nothing links a memory_frame to the execution_trace that produced it (no trace_id). So per-frame "why is THIS memory here?" is MUST-BUILD (add trace_id to frame metadata at write time + a GET /api/memory/:id/trace resolver). For PR3.5 the honest, cheap win is a session/turn-scoped trace view (the real reasoning + tool calls), NOT a per-frame reason. Do NOT synthesize a "reason" string for a frame with no linked trace. If neither route lands this arc, View B renders against a real recent session trace or is gated behind "no trace yet" empty state — never fabricated.

Phase verification (each phase)

Run the §1.4 gate after each phase; live-smoke the screen in dark + light with 0 console errors before moving on (matches PR3's shipping bar).

---

3. Honest data gaps (recon 05)

Feature	REAL / DERIVABLE / MUST-BUILD	Plan
source (provenance class)	REAL (memory_frames.source)	Project per Part 1; FE owns the 5-value label map.
forget (delete)	REAL (DELETE /api/memory/:id, hard delete + audit)	Wire button straight to it. No backend.
correct (edit)	REAL (PATCH /api/memory/:id)	Wire edit/correct to it. No backend.
freshness / staleness	DERIVABLE (computeTemporalScore over created_at, 7d boost/30d half-life)	FE compute or thin helper. Present as honest age, never a stored "%".
confidence	PARTIAL (metadata blob; harvest-only, undefined for curated/agent/quick-capture frames)	Show ONLY when present; hide the ring/badge when undefined. NEVER default a number (PR3 streak-gate pattern). Stat #2 gated off if absent.
confirm / needs-confirm / verified	MUST-BUILD (no per-frame confirm lifecycle; unreviewed never written)	Add cheap POST /api/memory/:id/confirm (set metadata.status), mirror /archive. Queue = ?status=unreviewed. Do NOT show "verified ✓" unless source==='tool_verified' or status explicitly set.
per-frame "why?" trace	MUST-BUILD backlink (no trace_id on frames); session/turn trace is DERIVABLE	Ship session/turn-scoped View B from real traces (add agent: tag or /api/sessions/:id/traces). Never synthesize a reason for an unlinked frame.
"Forgotten" filter	NO DATA (hard delete = no tombstone)	Gate the chip off / relabel — there is no forgotten list.

Fabrication-risk flags (gate off, do not invent — PR3 streak precedent):

1. Confidence when undefined → hide ring, don't default.
2. Freshness → age, never a stored decay %.
3. Per-frame trace reason → only when a real linked trace exists.
4. "Forgotten" list → no tombstone; gate off.
5. Stat-card numbers → drive from the real query; a real 0 is honest, a fake 3/9/128 is not.

---

4. New primitives to build (recon 03 confirmed: 3 already exist — REUSE)

Already exist in components/ui/ (pre-PR3, commit afe96355) — do NOT rebuild: ConfidenceBadge, EvidenceChip, DetailDrawer, EvidencePanel. The handoff's claim they'd be in os/warm/ was a location error — they ship today via Memory Center.

Genuinely new warm atoms for screen 19 (one-line spec each):

• ConfidenceRing — 38px circular ring; number + 2px border both colored by band (≥85 --healthy / ≥60 --attention / <60 --risk); CONF mono caption beneath; renders the "no value" neutral state when confidence is undefined (no fabricated number).
• ProvenanceLine (extend, not new) — add the §5b 3-segment form ⬡ <id> · source: <src> · ● <freshness> (source:-prefix variant + ● freshness segment colored healthy/attention); keep the existing ⬡ source · when form + onClick → button.
• TraceEvidenceChip (thin wrapper over ui/EvidenceChip) — multi-segment trace chip confidence X% · source · when · still fresh in --surface/--line-soft, .src refs mono --intel; only if the plain EvidenceChip can't render the multi-segment string directly.
• DetailDrawer (reuse) — already exists; opened from a clickable memory row for the full memory detail (confidence/source/evidence/edit). No new build.

(Net new code: ConfidenceRing + the ProvenanceLine extension; optional TraceEvidenceChip.)

---

5. Risks & open questions for the founder

1. SSE step pill — do it now (auto_recall slice) or defer? Recon 02: in-scope only if paired with the recallMemory() return-shape widen (orchestrator.ts:453-457). If we want PR3.5 frontend-light, defer and keep PR3's affordance-only stance. Recommend: do the auto_recall slice (honest, load-bearing). Founder call on scope/budget.

2. Token-family decision (recon 03 §1b): warm --intel (provenance) vs Hive DS --sem-* (confidence bands) currently coexist. Screen 19's confidence rings use warm --healthy/--attention/--risk. Confirm: build ConfidenceRing against warm tokens and let ui/ConfidenceBadge keep --sem-*, or unify? Default: warm tokens for the ring (matches the mock 1:1).

3. Confirm route + status writer. POST /api/memory/:id/confirm is cheap, but nothing writes unreviewed today, so the "Awaiting your confirm" queue may legitimately be empty. Is that acceptable for launch (real-but-empty), or do we also wire the harvest-commit path to stamp unreviewed (larger)?

4. Per-frame "why?" backlink. True per-memory trace needs a trace_id on frame metadata at write time + a resolver (MUST-BUILD). For PR3.5, accept a session/turn-scoped View B (real traces, not per-frame)? Or invest in the backlink this arc?

5. "Forgotten" filter has no data (hard delete, no tombstone). Gate the chip off, relabel, or add a soft-delete tombstone (scope creep)? Recommend: gate off for now.

6. Two-mind scope for screen 19. MemoryCenterApp is two-mind (personal/workspace) and the Workspace Memory tab shares MemoryCenterTab. Does screen 19 replace MemoryCenterApp wholesale, or layer the Trust view as a new view alongside the existing 7 (memories·timeline·graph·harvest·weaver·wiki·evolution)? Affects blast radius.