core-labs/core
1
0
Fork 0
Code Issues Pull requests 1 Projects Releases Packages Wiki Activity Actions
core/docs/workbench/UI-UX-GUIDE.md
Shay 7ead395eeb feat(workbench): Lived Life surface — the always-on heartbeat made felt (read-only, persist-first) 
The L10 heartbeat (chat/always_on, #747) holds CORE alive over uptime but had no
surface. This adds the read-only Lived Life route that renders the continuous-life
evidence: the heartbeat over uptime + the resume-as-same-life verdict — both halves
of "one continuous life" on one surface.

Persist-first, never recompute engine-owned values:
- chat/always_on: serialize_report + write_lived_life persist a run deterministically
  (sorted keys) to engine_state/lived_life.json; run_continuous gains an opt-in
  report_path so a real continuous-life run leaves its evidence where the workbench
  reads it. closure_ceiling is persisted so the artifact is self-describing.
- workbench/lived_life.py: projection + a fail-closed validate() gate — the wrong=0
  analogue for the continuity surface: closure_held/closure_observed/totals/converged
  are each re-checked against the per-beat measurements, and resume_status is re-checked
  against identity-vs-current-substrate, so a tampered artifact RAISES rather than
  rendering a false claim (a beat lying about a breached ceiling, an inflated closure,
  a miscounted total, a falsely-claimed resume).
- workbench/readers.lived_life(): reads the artifact, computes the resume verdict from
  the persisted identity vs the canonical engine_identity_for_config (fail-soft ->
  "unknown", like IdentityContinuity). Honest absence when no run has been persisted.
- GET /lived-life + LivedLife/LivedLifeHeartbeat schemas (snapshot regenerated; the
  schema-drift gate proves every field is mirrored in src/types/api.ts).

The resume verdict made felt: would_resume / substrate_changed / unknown IS the L11
reboot guarantee (a reboot recomputes identity and refuses if it differs) — so the
surface shows this life wakes up as ITSELF, not a copy. The per-reboot lineage chain
stays owned by Runs > Identity (honest cross-link).

Frontend: /lived-life route (Evidence section, route count 15 -> 16). Renders the
headline (heartbeats, closure-held-by-construction, learned-while-idle, at-rest, resume
pill), the summary, the heartbeat timeline (closure flat below the ceiling — read, never
repaired), and the resume verdict. Honest absence + ADR-0162 route conformance
(loading/error/empty), fail-closed like Vault/Calibration.

Tests (non-vacuous): 12 backend (every tamper case raises; resume tracks identity vs
substrate; run_continuous(report_path) round-trips a readable+valid artifact) + 4
frontend render tests (recorded life renders; a breached beat shows the warning, never a
false "held"; a changed substrate shows would-refuse, never a false resume; absent shows
honest absence). All workbench Python (167) + affected vitest (167) + tsc + vite build
green; architectural invariants green.

engine_state/lived_life.json is runtime state (gitignored, ADR-0146 pattern).
2026-06-14 16:45:03 -07:00

8.6 KiB
Raw Blame History

CORE Workbench UI/UX Guide

Date: 2026-06-13 Status: Wave M B3.5 guide

1. What Workbench Is And Is Not

CORE Workbench is a local operator/auditor surface for deterministic CORE evidence. It is a cognition observatory, replay debugger, proposal review station, eval console, calibration reader, and audit surface.

It is not a generic chatbot shell, not a dashboard over invented metrics, not a mutation console, and not a visualization proof. Every visible claim should trace to a backend read model, committed artifact, or existing allowlisted execution path.

2. How To Run It

Backend:

core workbench api

Frontend:

cd workbench-ui
pnpm dev

Default API health check:

curl http://127.0.0.1:8765/health

3. Evidence Model

The workbench has one evidence grammar. A selected item publishes an EvidenceSubject; the RightInspector and Evidence Chain Rail render only fields that subject actually carries.

Evidence subject kinds:

  • turn
  • proposal
  • eval_result
  • artifact
  • run
  • pack
  • vault_entry
  • audit_event
  • calibration_class

Missing detail is rendered as "detail not loaded" or "not recorded", never as a successful proof.

4. Current Route Map

The route registry in workbench-ui/src/app/routes.ts is the source of truth. Current route count: 16.

Section Route Path Shortcut Purpose
Converse Chat /chat ⌘1 Execute a normal CORE turn and journal evidence.
Cognition Trace /trace ⌘2 Inspect turn surfaces, grounding, verdicts, and trace hashes.
Cognition Contemplation /contemplation Palette Inspect persisted contemplation process traces.
Determinism Tour /tour Palette Guided determinism tour: a curated narrative over the real demos with "what this proves / does not prove" honesty cards.
Determinism Replay /replay ⌘3 Re-execute journaled turns in a sealed fresh runtime and compare envelopes.
Determinism Demos /demos Palette Run registered determinism demos.
Evidence Proposals /proposals ⌘4 Review cognition and math proposal evidence.
Evidence Runs /runs ⌘6 Browse recorded run/session evidence.
Evidence Lived Life /lived-life Palette Watch the always-on heartbeat hold one continuous life (closure read-not-repaired over uptime + learned-while-idle).
Evidence Vault /vault ⌘8 Inspect persisted vault metadata when persistence exists.
Evidence Audit /audit ⌘9 Read deterministic audit events.
Discipline Evals /evals ⌘5 Run/read allowlisted eval lanes and wrong=0 ledgers.
Discipline Calibration /calibration Palette Inspect practice-class reliability and license verdicts.
Substrate Packs /packs ⌘7 Browse language/runtime pack metadata.
Substrate CORE-Logos /logos Palette Inspect CORE-Logos pack identity and safety.
Settings Settings /settings ⌘0 Manage local UI preferences; engine config remains CLI-only.

Pinned route shortcuts cover Chat through Settings. All routes are searchable in the command palette.

5. What Each Route Proves

Route Proves
Chat The local runtime can produce a typed turn envelope and journal it.
Trace The journal carries user, articulation, walk, grounding, verdict, and hash evidence.
Contemplation Persisted contemplation process reports expose cold attempt, checkpoint enrichment, proposal boundary, and grounded-after scenes.
Replay A selected journaled prompt can be replayed through the sealed replay comparator; equivalence is leaf-based.
Demos Registered demo scenarios pass or fail with recorded scenario evidence and proof/entailment DAGs where the demo emits them.
Proposals Proposal evidence, replay facts, and ratification commands are inspectable without applying mutation.
Runs Recorded run/session references, checkpoint gaps, and identity-continuity verdicts are discoverable.
Lived Life A persisted always-on run shows the engine living + learning over uptime, with closure (versor_condition < 1e-6) read as evidence each beat (never repaired); the surface's closure_held is consistency-checked against the per-beat measurements, so it can never paint a breached field as valid.
Vault Persisted vault metadata is inspectable when persistence is configured.
Audit Audit events are readable with payload digests and mutation-boundary flags.
Evals Allowlisted eval lanes and wrong/correct/refused metrics are visible.
Calibration Practice classes show engine-owned Wilson floor and PROPOSE/SERVE license verdicts.
Packs Pack manifests, checksums, and determinism metadata are visible.
Settings UI preferences are local-only; density mode is consumed by shell/design tokens; runtime status is read-only.

6. What Each Route Does Not Prove

Route Does not prove
Chat Does not prove replay equivalence until Replay verifies a journaled turn.
Trace Does not prove correctness; it exposes recorded state.
Contemplation Does not ratify findings or prove open-ended learning; it reads committed reports only.
Replay Does not distinguish nondeterminism from unrecorded origin-state influence.
Demos Does not generalize beyond registered scenarios.
Proposals Does not ratify unless an admitted handler path is explicitly invoked.
Runs Does not reconstruct missing checkpoints or synthesize identity continuity when manifest evidence is absent.
Vault Does not expose live in-process memory.
Audit Does not create a new event store.
Evals Does not run unsafe or sealed holdout lanes from the UI.
Calibration Does not mutate a license and does not claim serving wrong=0 from practice data.
Packs Does not apply pack mutation.
Settings Does not edit engine configuration.

7. Evidence Subjects And Address Grammar

Canonical addresses:

  • turn -> /trace/<turnId>
  • proposal -> /proposals/<proposalId>
  • eval_result -> /evals/<laneId>
  • artifact -> /replay/<artifactId>
  • run -> /runs/<sessionId>
  • pack -> /packs/<packId>
  • vault_entry -> /vault?inspect=vault:<entryIndex>
  • audit_event -> /audit?inspect=audit:<eventId>
  • calibration_class -> /calibration?inspect=calibration:<className>

?inspect= means the RightInspector is open on that subject. Malformed inspect values are dropped rather than interpreted.

8. Command Palette And Keyboard Model

⌘K opens the command palette. Route commands derive from the route registry; Demos and Calibration are palette-visible even though they do not have digit shortcuts.

Keyboard help is live-registry driven. It shows only shortcuts currently bound by mounted components. It must not advertise unreachable commands.

9. Empty/Error/Loading Doctrine

Every route with remote evidence must provide:

  • a specific loading label,
  • an empty state that names what is absent and gives a next action,
  • an error state with failure, mutation status, reproducer, and retry safety.

No route should use vague "thinking" text or imply mutation happened when it did not.

10. Proposal Vs Ratification Boundary

Proposal views are read-only unless a narrow admitted handler explicitly exists. Suggested CLI commands are copyable operator affordances, not UI execution. Pack mutation and general corpus mutation remain proposal-only until reviewed.

11. Calibration / Wrong=0 Discipline

Calibration reads committed practice artifacts and applies engine-owned core.reliability_gate functions. It shows how a class earns PROPOSE or SERVE license. Practice can contain wrong attempts; those wrong attempts are the learning signal.

The global wrong=0 frame reads serving metrics from committed serving reports. It mirrors counts honestly; if a report says wrong is non-zero, the UI must show non-zero wrong.

12. CORE-Logos / Packs Current And Next State

Today, Packs exposes manifest/checksum/determinism metadata. It is the current Substrate neighborhood for language/runtime pack inspection.

The planned CORE-Logos Studio is not built yet. It should enter as read-only readers and proposal-only draft artifacts before any ratification-enabled handler family is admitted.

13. Known Absences And Follow-Up Items

  • Full Phase C cognitive pipeline visualizer is absent.
  • Field substrate / versor_condition reader is absent.
  • Identity continuity route is absent.
  • Full B4 leeway annotations are not admitted; B4a nullable LeewayEvidence read models exist first.
  • CORE-Logos Studio route is not built.
  • Universal proposal artifact envelope is designed, not implemented as a UI substrate.