PRD-033 — Physics Lab (the scientific base, liberated)

Status · Draft — epic kickoff Sources · PRD-002 (Mission Configurator / /plan) · PRD-003 (Mission Arc) · PRD-032 (Launch) · PRD-008 (Science) · 01_Orrery_Vision.md §audiences · ADR-030 (fly-physics pure-function isolation) Audiences · STEM student, curious learner, the contributor (PA §audiences) — and a new fourth: the agent (an MCP client acting for any of the three) Promises · real physics not approximations that mislead · educational at every level · fail honestly · open source and contributable (PA §promises) Principles · physics first · fail honestly · attribution is design · data over code (PA §principles) Why this is a PRD · Orrery has quietly become a small, accurate, unit-tested spaceflight-physics engine — Lambert solvers, a JPL ephemeris, a powered-ascent integrator, per-body EDL, a J2 satellite propagator — but every formula is trapped inside a scripted surface. You can watch Curiosity fly to Mars; you cannot ask "what if the Isp were 20 seconds higher?" and see the answer. This proposes to liberate that engine into a shared physics kernel and give it two brand-new front doors: a Physics Lab where a human plays with the formulas in a live, media-rich, sketch-illustrated notebook, and a hosted MCP server where an agent calls the same formulas as tools. It is the difference between a museum where you watch, and a workshop where you build. Getting the honesty contract right — computed truth kept visibly distinct from generated illustration — is the make-or-break, because the moment we draw pretty pictures around numbers, we risk teaching fiction. That is a product decision, not a silent PR.

---

A STEM student opens /lab. Blank graph-paper canvas. She types a question into a card: Tsiolkovsky — how much Δv does a mass ratio of 12 buy me at 350 s Isp? A number appears — 8.6 km/s — but so does a small hand-drawn-looking curve in the margin: Δv against mass ratio, her point marked with a circled dot, the vacuum-Isp of a real RL10 sketched in for scale. She drags the Isp slider; the curve redraws live and a pencil-style annotation updates: "+20 s Isp → +0.4 km/s here." She pulls a second card and wires the output orbit of an ascent into a transfer — the canvas draws the parking orbit stretching into a heliocentric ellipse, periapsis circled, the Δv budget stacked as a little waterfall beside it. Nothing here is a cartoon: every line is integrated from the same equations /fly flies. She exports the whole page as a lab report and pastes it into her problem set. She never wrote a line of code.

The problem

Orrery's physics is world-class and completely inaccessible as physics. It powers /fly, /plan, /explore, /science — but only along the rails those surfaces lay down. There is no way to:

• Ask a free-form question — "plot the entry corridor for Mars vs Titan," "what mass ratio do I need for TLI," "when is the next cheap Mars window." The numbers exist; the surface to pose the question does not.
• See the working, drawn. /plan draws one thing (the porkchop). The other twenty formulas produce numbers with no picture. A number without a diagram teaches far less than the same number with the transfer ellipse, the force diagram, the loss waterfall drawn around it.
• Reach the engine from outside. A developer, a researcher, or an agent cannot call solveLambert or integrateAscent without cloning the repo and booting SvelteKit. The contributor promise (PA §audiences) stops at the app's edge.

The scientific base is a library trapped inside a building. This opens two doors.

North star

Two references, held simultaneously:

• An astrophysicist's notebook — the real thing: graph paper, integrals worked in the margin, a quick sketch of the geometry next to every result, the page a record of thinking, not a form with outputs. Feynman's diagrams were doodles that happened to be exact. That is the register: warm, hand-made, and rigorously true at the same time.
• A live scientific instrument — every figure is computed, reproducible, exportable, and correct to the fidelity we honestly claim. The bar for the look is the same bar /fly holds for cinematics and /posters holds for print: this must feel like Orrery, top to bottom, not a bolted-on calculator.

The tension between those two — hand-drawn warmth vs instrument-grade truth — is the whole design problem, and §"The honesty line" is how we resolve it.

The two front doors

Door 1 — the Physics Lab (/lab, human-facing). A free-form canvas/notebook where each formula in the kernel is a card: inputs become live controls, outputs become numbers and auto-drawn figures. Cards can be compared, branched, and — the payoff — wired together into a full authored mission worksheet (ascent → injection → transfer → capture → descent), the whole pipeline drawn as one annotated storyboard. It is /fly's physics, authored by the user instead of scripted.

Door 2 — the MCP server (mcp. subdomain, agent-facing). The same kernel, exposed as authenticated tools any MCP client (Claude.ai, Claude Code, third parties) can call over the network. An agent asks a natural-language question; the server runs the real formulas and returns structured results — including the same figure descriptions the Lab renders. This is the contributor promise extended from "fork the repo" to "call it from anywhere," and it is where the Lab's own natural-language "ask" box eventually gets its brain.

Both doors open onto one room: the shared kernel. Neither reimplements physics.

The Lab is a subsystem — one card model, three views

Door 1 is not a single screen; it is a small subsystem built on one atom. The atom is a card: a formula instance = (which formula, its bound inputs, any wiring to other cards, and the FigureSpec it emits). A card is portable data, so the same card renders in three views that match three distinct intents:

• Canvas — prototyping. A spatial graph on the teal grid where cards are dragged freely and an output socket wires into another card's input. Ephemeral, exploratory, no narrative — the whiteboard.
• Notebook — keeping. An ordered, narrated sequence of cards; the durable, exportable artifact you're actually building. A card here can reference the result of the card above it.
• Focus — drilling in. One card, full-screen: big figure + full control rail + the /science derivation. A lens callable from either workspace, not a workspace itself.

Cards move between views: you promote a card (or a wired subgraph) from Canvas into a Notebook. One model, three windows — this is what makes the Lab a subsystem rather than three routes. The genuinely novel/expensive parts are localized and named honestly: the Canvas wiring/graph engine, card serialization/portability across views and sessions, and the fact that a spatial Canvas has no honest mobile story (it degrades to read-only on phones). Those costs are why the sequence below front-loads the Notebook, not the Canvas.

The media-driven layer — figures that draw themselves

The feature that makes the Lab feel like a notebook rather than a calculator: results auto-generate diagrams. Every kernel result carries a declarative description of what should be drawn (a FigureSpec), and the Lab renders it. The catalogue, all computed from pure functions, all free:

• transfer ellipse (departure / arrival / periapsis marked) · porkchop heatmap · Δv-budget waterfall · rocket free-body force diagram at altitude · ascent profile triptych (altitude · velocity · dynamic-pressure vs time) · EDL entry corridor per body · orbit / ground-track · sky chart (alt-az) · Tsiolkovsky sensitivity curve · cislunar ECI trajectory.

Type a parameter, get a publication-grade annotated figure instantly. On top of that exact layer sits an optional illustrative layer — generative sketches and margin art (via the existing image pipeline) and grounded natural-language annotations that read like a physicist's notes — for warmth and shareability.

The honesty line (make-or-break)

The moment we draw art around numbers, we can accidentally present fiction as fact — a violation of the deepest promise (PA §"real physics, not approximations that mislead"; §"attribution is design"; §"fail honestly"). The resolution has three parts:

1. Computed ≠ illustrated, always visibly. Exact figures (integrated from the kernel) and generative/illustrative art occupy visually and semantically distinct registers, and every artifact is labelled with its provenance — same discipline as the image pipeline and /science fact-checking.
2. The "sketchy-but-exact" sweet spot. The default notebook aesthetic — graph paper, hand-annotated vectors, margin doodles — is rendered as deterministic SVG styled to look hand-drawn. The warmth is styling; the content is computed. This gets the notebook feel without generative cost, latency, or honesty risk. Generative art is a clearly-labelled layer on top, never on the data path.
3. One authoritative ephemeris, honestly labelled. The kernel holds two planet-position models of different fidelity (a fast /fly approximation and a JPL-accurate solve). The Lab and MCP expose the accurate one as authoritative; the approximation, if exposed at all, is labelled fast with a stated error bound. And when the physics says no — Lambert finds no window, TWR < 1, not enough Δv — the Lab explains the failure, it does not hide it (PA §"fail honestly").

Who it serves

Audience	What the Lab / MCP gives them
STEM student	Real vis-viva / Lambert / Tsiolkovsky numbers with the figure drawn, verifiable, exportable into coursework. The tool that turns "I know the Hohmann transfer in principle" into "I've watched it respond to my inputs."
Curious learner	A playground: sweep a slider, watch the trajectory bend. Understanding through play, not a textbook.
The contributor / developer	The kernel as a real library + an MCP endpoint — call the physics from a script, a notebook, or an agent, without cloning the app.
The agent	Typed, authenticated physics tools over the network — the app's engine as an agent capability.

The tier ladder (this is the roadmap)

• T0 — parameterized figures. Every formula gets sliders → a live figure. (Generalizes /plan's porkchop to the whole kernel.)
• T1 — the notebook canvas. Linked cards, scenario comparison, export with Orrery's placard styling.
• T2 — composition. Wire formulas into a full authored mission worksheet, drawn as one storyboard.
• T3 — the media layer. Labelled generative sketches + grounded margin-notes; shareable lab-report artifacts.
• T4 — agentic. A natural-language "ask" box; the MCP server drives the kernel, the Lab renders. The loop closes.

Mapped to the subsystem: v1 ships the shared card model + the Notebook + Focus views (T0–T1) in the sketchy-but-exact aesthetic — the durable, mobile-safe artifact and the PRD north star, which de-risks the kernel by exercising it in-process before the MCP server exposes it to strangers. The Canvas workspace + wiring + promote is T2, landed second once the card-graph engine is proven — deliberately not front-loaded, because the wiring engine and its (absent) mobile story are the expensive, novel parts. T3–T4 ride on the same kernel and FigureSpec contracts v1 establishes, so they cost a consumer, not a rewrite.

Why now

The engine is done and, per the 2026-08-08 inventory, already ~80% pure and unit-tested (ADR-030's discipline spread repo-wide). /plan already proves the "formula → live figure" loop with the porkchop. The image pipeline, the placard-overlay aesthetic, and the lavish artifact export all exist. The gap between "we have the physics" and "you can play with the physics" is now mostly packaging and one beautiful surface.

Success looks like

• A student computes a Δv budget in /lab, exports the drawn figure into a problem set, and it's right.
• A learner drags the Isp slider and watches the sensitivity curve bend, and gets why staging matters without being told.
• A developer points Claude at mcp.orrerylearn.com and asks for a 2033 Mars window, and gets a real Lambert answer with a figure.
• Someone screenshots a /lab page and it is unmistakably Orrery — the notebook looks as considered as /fly looks cinematic.
• Nobody ever mistakes a generated sketch for a computed result, because the line is always visible.

Non-goals (v1)

• Not a full CAS / Jupyter. No arbitrary user code execution; the palette is the kernel's vetted formulas, not a Python sandbox.
• No new physics. The Lab exposes today's fidelity, honestly labelled — it does not add N-body, CFD, or higher-precision propagation.
• Generative art is not v1-gating. The sketchy-but-exact deterministic figures ship first; the generative illustrative layer (T3) is a labelled follow-on.
• The agentic "ask" box (T4) is not v1. It depends on the MCP server, which lands after the Lab proves the kernel.
• MCP public multi-user auth is not v1. A private-beta credential precedes public OAuth.

The look & feel — notebook metaphor, the sketchy-but-exact figure language, layout, controls, export — is specified in the forthcoming UXS (visual-anchored on real screenshots, signed off before build). The technical architecture — the kernel package boundary, the FigureSpec contract, MCP hosting/auth, and the data strategy — is specified in RFC-037.