The Thinking Machine Observatory

Observe. Intervene. Compare.

A local-first scientific instrument for inspecting next-token prediction, changing the sampler and preserving counterfactual branches as immutable traces.

Start here

I want to…	Read or run
try the two-minute teaching loop	User guide
understand what the evidence means	Scientific status
make a code or documentation change	Developer guide
start a fresh coding-agent session	Agent operating contract
review release readiness	Generated release evidence
deploy or roll back the static app	Static release runbook (wrangler.toml at repo root)

Current instrument

Phase 5 turns the capability-gated laboratory into an evidence-bound public release candidate:

• an exact, deterministic sampler with temperature, top-k, top-p, greedy mode, suppression, forcing and xoshiro128** seeded selection;
• a schema 1.2 ancestry bundle with content-addressed float32 payloads, explicit import limits and lossless schema 1.0/1.1 migration;
• candidate tables, entropy, selection explanations and Jensen–Shannon branch comparison;
• a responsive React observatory that can force the runner-up, suppress candidates, commit child traces and export JSON;
• all eight guided experiments as versioned protocols with executable observation predicates and append-only reflections;
• a pinned DistilGPT2 fp32 WASM worker that transfers all 50,257 final-position logits;
• source-framework golden vectors and accepted/rejected backend comparison reports;
• exact token-ID continuation, serialised PRNG cursors, explicit seed resets and stale-response-safe generation controls;
• immutable historical forks, first-divergence comparison and portable ancestor-complete export/import;
• transactional IndexedDB notebook storage with payload reference counts, quota preflight and parent-deletion protection; and
• a verified token specimen bench with visible boundaries, code points, derived UTF-8 bytes, a semantic table and copyable text;
• session-scoped capability declarations plus deliberate unavailable states for hidden states, attention, probes and projections; and
• a 78-criterion acceptance ledger whose summary cannot promote blocked or unrun evidence;
• keyboard, semantic, reduced-motion, forced-colour, zoom and responsive Playwright journeys across Chromium, Firefox and WebKit;
• a same-origin offline application shell that leaves cross-origin model caching to the pinned runtime path;
• checked static-host CSP/security headers, bundle budgets, privacy wording and third-party notices; and
• unit, coverage and Playwright release-evidence tests in CI.

The source candidate is implemented, but the release decision remains evidence-gated. Physical device, screen-reader, deployed-origin and learner-study results stay blocked or not-run until they are actually observed; see the generated release evidence summary.

The default score field remains intentionally labelled illustrative so the instrument is immediately useful without a 327.8 MB download. Its ten logits are a teaching fixture, not model output. The optional fp32 WASM path is separately labelled verified measured and may enter exact sampling/replay. WebGPU fp16 remains measured but unverified.

Run it

Requirements: Node.js 24+ and pnpm 11+.

pnpm install --frozen-lockfile
pnpm dev

Open http://localhost:5173.

pnpm check          # formatting, lint, strict types, fixtures, unit tests and build
pnpm test:coverage  # exact-core coverage thresholds
pnpm build          # static production bundle
pnpm phase5:verify  # acceptance, contrast, static policy and evidence integrity
pnpm phase5:budgets # checked production-asset budgets after build
pnpm e2e            # Chromium, Firefox and WebKit release journeys

The ordinary end-to-end suite targets all three Playwright engines. Install them once per development machine:

pnpm exec playwright install chromium firefox webkit

Try the hero loop

1. Inspect the locked “The night sky was” teaching fixture.
2. Change temperature, top-k, top-p, mode or seed without mutating the baseline.
3. Suppress a candidate or choose Force runner-up branch.
4. Commit the preview as an immutable child trace.
5. Compare selection, entropy and Jensen–Shannon divergence in the Branch Chamber.
6. Export the selected schema-valid trace as JSON.

The user guide explains the controls, evidence labels, local storage and recovery paths without requiring knowledge of the repository architecture.

Or load Verified WASM in the full-vocabulary panel, pause on the complete distribution, advance or run several exact-prefix steps, fork a historical token, save locally and export/import its ancestry bundle. The initial implementation deliberately reruns the full token-ID prefix; it does not claim unverified KV-cache equivalence.

The token specimen bench follows the selected branch and pending step. Inspect the exact IDs and decoded fragments, compare derived UTF-8 bytes in the table, then select a guided protocol. A protocol reports observed, pending or blocked from its evidence predicates; saving a reflection does not manufacture completion. Live-trace reflections travel with export and explicit notebook saves.

Architecture

The browser application consumes small packages rather than owning scientific logic itself.

Start with the canonical architecture map for the implemented runtime, dependency graph, evidence boundaries and links to the detailed flows.

Workspace	Responsibility
apps/observatory	React shell, observatory design system and interaction orchestration
packages/domain	Dependency-free scientific and trace vocabulary
packages/sampler	Pure deterministic sampler and trace-owned PRNG
packages/trace-schema	Legacy/compact schemas, replay, DAG lineage and local notebook
packages/instruments	Probability view models, comparisons and selection explanations
packages/experiments	Versionable guided experiment registry
packages/inference-worker	Typed worker protocol, capability detection and model adapter
fixtures/traces	Deterministic schema examples checked for drift in CI
model-tools	Pinned source generation, tolerances and backend evidence

The dependency direction is deliberate: UI and runtimes depend on the exact core; the exact core never depends on React, ONNX or a visual renderer.

Scientific status

Path	Source	Status	Allowed use
Teaching fixture	Ten authored candidate logits	Illustrative	Exact sampler learning, branching and replay demonstrations
Sampler and metrics	Pure TypeScript calculations	Exact and tested	Derived values and deterministic replay
Local DistilGPT2 WASM	Pinned Xenova/distilgpt2 fp32 graph	Verified measured	Full-vocabulary sampling and replay
Local DistilGPT2 WebGPU	Pinned Xenova/distilgpt2 fp16 graph	Unverified measured	Inspection only; trace commitment disabled
Local DistilGPT2 int8	Pinned graph and retained comparison report	Rejected	Evidence only; never offered to the exact sampler
Hidden states, attention and probes	Session capability registry	Unavailable	Zero allocation; never simulated or inferred

The interface uses Measured, Derived, Projected, Probed and Interventional evidence labels. It does not claim to reveal thought, intent, consciousness or a complete causal explanation.

Local model path

The optional worker uses @huggingface/transformers@3.8.1, pinned model/tokenizer revisions, fp32 on WASM and fp16 on WebGPU. Loading the accepted WASM graph may fetch 327.8 MB. Prompts and logits remain in the browser and no inference service is called.

The accepted distilgpt2-wasm-fp32-v1 profile compares four complete vectors with the pinned PyTorch source: exact token IDs/fragments, exact top-1 and top-50 ordering, maximum absolute error below 0.000077 and zero causal-prefix error. The previously used int8 graph failed ranking and causal checks and is explicitly rejected. See the checked reports rather than treating the status label as self-authenticating.

The large, network-backed smoke is opt-in and intentionally excluded from ordinary CI:

RUN_LIVE_MODEL=1 pnpm exec playwright test tests/e2e/live-model.spec.ts

The ordinary offline-weight gate still re-hashes the checked full-vocabulary fixtures and proves the accepted hero vector selects/replays token 3223 (" dark"):

pnpm fixtures:check
pnpm trace:verify:live

Privacy and storage

• No account or backend is required.
• No analytics or prompt telemetry is present.
• Model files use the browser/runtime cache.
• The production service worker caches same-origin application-shell assets for offline revisit; it does not cache the cross-origin model itself.
• Compact trace bundles are downloaded only when the user explicitly exports them.
• IndexedDB persistence is explicit: the user chooses Save to local notebook. Payloads are deduplicated, quota failure is atomic and parents with descendants cannot be deleted accidentally.

Documentation

• Documentation map
• User guide
• Developer guide
• Canonical architecture map
• Runtime and interaction flows
• Trace, replay and persistence integrity
• Release, offline and deployment boundary
• Human and AI agent guide
• Five-phase implementation plan
• Contribution workflow
• Session 01 handover
• Session 02 handover
• Session 03 handover
• Session 04 handover
• Session 05 handover
• Post-Phase-5 engineering review
• Phase 1–4 integration hardening
• Phase 4 readiness contract
• Phase 5 readiness contract
• Release evidence ledger and generated decision
• Static release runbook
• Privacy statement
• Third-party notices
• Architecture decisions
• Model verification boundary
• Original product and architecture package

Next high-value slice

The Phase 5 source candidate is already frozen at ae9f7605a9cf613695c4363faa3e5250b67673a8. CI run 28 established the illustrative desktop path. Do not mix app repairs with evidence promotion.

Evidence still needed on this candidate: current hero screenshots, deployed-origin smoke, one named screen-reader pass, available Android/Safari checks, the opt-in DistilGPT2 journey, and the consented two-minute learner protocol.

The next source candidate, if taken, should repair 1.1 PRNG replay, compact cursor chaining, live logit hashing, cache-first navigation, skip-target focus, Force/Suppress names and a real tab-order journey — then rebind evidence. Hidden states, attention, logit-lens probes and semantic projections remain unavailable until an exact purpose-built output profile passes the independent gate.

See the post-Phase-5 review for the defect list and owner decisions.