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

Status · Shipped v0.9.1 (2026-10-23; /lab in src/routes/lab/, kernel src/lib/physics/, MCP server/mcp, server/lab-api, RFC-037, TA.md §components "Physics Lab", CHANGELOG [0.9.1]); Amendment 01 tiers T0–T4 + MCP present, full goal-set coverage against A01.3 not verified · was: 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 (ALL of it ships in v0.9 — see Amendment 01 A01.5/A01.7)

• 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.

SUPERSEDED by Amendment 01 (operator "all of it," 2026-08-29): the original plan shipped only T0–T1 in v1 and deferred T2/T3/T4. v0.9 now ships ALL tiers T0–T4 + the MCP (OAuth, gated beta). The build order still starts with the card model + Notebook + Focus (T0–T1, mobile-safe, de-risks the kernel in-process), then Canvas + wiring + promote (T2), then the generative media layer (T3, always in the labelled register), then the agentic ask-box (T4) — but all of them land in v0.9, not as a roadmap. Sequencing ≠ deferral. Details: A01.5 (goal ladder), A01.7 (T4 ask-box + MCP access model).

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. SUPERSEDED by Amendment 01 (§below): the Lab does add a foundational classical-mechanics domain (F=ma, weight, momentum, energy) that the existing spaceflight formulas rest on. It still does not add N-body, CFD, or higher-precision propagation — the fidelity ceiling is unchanged; only the floor is extended downward to first principles.
• Generative art is not v1-gating. SUPERSEDED by Amendment 01 (operator: "all of it"). The generative illustrative layer (T3) ships in v0.9 — but sequenced after the deterministic figures and always in the labelled illustration register (never on the data path). Not gating; still in scope.
• The agentic "ask" box (T4) is not v1. SUPERSEDED — T4 ships in v0.9. It rides on the MCP server + the goal-aware registry, so it lands after those, but it is in scope.
• MCP public multi-user auth is not v1. SUPERSEDED — OAuth ships in v0.9. Still sequenced bearer-token private beta first, then public OAuth 2.1 — both in v0.9.
• Still genuinely out of scope: a full CAS / arbitrary code execution (above); npm publication of the kernel; and any new numerical-fidelity physics (N-body/CFD/higher-precision) — the catalogue grows with closed-form formulas only.

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.

---

Amendment 01 (2026-08-29) — first principles, the milestone ladder, full coverage

Status · Shipped v0.9.1 (realized by RFC-037 A01; goal picker with 25 goals per TA.md; result of the adversarial review not verified) · was: Draft, operator-approved shape (session 2026-08-29) · Pending adversarial review (advisor / Fable-5) before slicing · Sources · this session's design dialogue; kernel//science capability audit · Companion notes · docs/wip/_archive/2026-08-29-kernel-scope-expansion-classical-mechanics.md, docs/wip/_archive/2026-08-29-s1-kernel-boundary-manifest.md · RFC delta · RFC-037 Amendment 01

This amendment widens PRD-033 from "liberate the existing spaceflight engine" to "a first-principles physics learning environment that exposes the entire built physics library as a ladder of mission goals." The original body (above) stands; this refines the audience, the pedagogy, the scope (one non-goal reversed), and the organizing model.

A01.1 · The audience widens — the first-principles learner

Add a first-class audience to the table in §"Who it serves": the learner building up from zero — a curious high-schooler / early-undergrad who wants to understand all of it in one place, from first principles. Not "I already know the Hohmann transfer, show me the numbers" (the existing STEM-student framing) but "I don't yet know why a rocket leaves the ground — teach me, starting from why a ball falls." Musk/Tesla framing: you reason up from bedrock (gravity pulls down, thrust pushes up, thrust must beat weight), never down from an answer. The emotional target: a learner finishes a goal and says "I understand how this works, fundamentally" — not "I got the right number."

A01.2 · The organizing model — goals, not a formula palette

The Lab is not a grid of formulas you browse; it is a ladder of mission-goal milestones, each a scenario that lines up the physics and adds new slices on top of the last, so that completing the goals = understanding all of spaceflight. Each milestone is simultaneously three things — this triple identity is the core of the design:

1. A curriculum — the learner's ordered path through the goal.
2. A validation scenario — the S2.5 "workbench coverage" end-to-end exercise of the kernel.
3. An engineering anchor — the acceptance scenario that proves a slice actually works.

First principles compound: the foundation introduced in M1 (F=ma, gravity, thrust, momentum) reappears at every later milestone — landing is thrust-vs-gravity again, a gravity assist is momentum exchange again, an orbit is centripetal force again. Six escalating situations, four principles paying off — that is the pedagogy, not six unrelated lessons.

A01.3 · Full coverage — the complete goal set (two families)

"Full coverage" is a hard requirement: every computable capability already built into the kernel must have a home in some goal. The audit (kernel exports + the authored /science topic taxonomy) yields two families:

Family A — the spaceflight spine ("get to space"): M1 Launch a rocket → orbit · M2 Get to the Moon · M3 Land on the Moon (airless) · M4 Get to Mars · M5 Land on Mars (atmospheric EDL) · M-return Come home (deorbit → heat shield → splashdown) · M6 Leave the solar system (escape + gravity assist). "Land on any world" generalizes M3/M5 across every body descent-physics supports — atmospheric (Earth/Mars/Venus/Titan), airless (Moon/Mercury), gas-giant probe (Jupiter, pressure-end), and micro-g small bodies (comet 67P, Ryugu/Bennu/Eros/Itokawa). Full coverage (below) means each gets a pulling goal — the micro-g case is thrust-vs-gravity at 10⁻⁴ g, on-brand for the compounding first principles (Fable-5 round-2 NEW-1).

M-return added post-Fable-5 (MAJOR 5). descent-physics explicitly supports Earth as the return body (LEO deorbit → heat-shield + parachutes → splashdown) and transEarthCoast exists — yet the first draft's ladder launched, transferred, and landed elsewhere but nobody ever came home. A first-principles learner expects "how did Apollo get home / why the heat shield," and it is the emotional mirror of M3/M5. Full coverage now includes it.

Family B — observe & orbit ("understand the sky"): G7 Observe the sky (where/when to see planets) · G8 Moon phases (ships — moonPhase is a built capability; eclipse geometry is an optional budgeted extension, new closed-form physics the kernel lacks — Fable-5 MINOR 4 — decided at goal-enumeration, not a full-coverage requirement since it isn't a built capability) · G9 Track a satellite / catch the ISS · G10 Choose an orbit (LEO/GEO/SSO regimes).

Cross-cutting: "How a rocket engine works" (the 8 /science/propulsion sub-topics — cycles, fuels, Isp, TWR; feeds M1) · "Scales & time" (light-time, AU, sidereal day).

Explicitly out of the Lab's computable scope (honest boundary — part of full coverage, not a gap): the editorial /science domains cosmology, exoplanets, life-in-space, history, reading-list, watch-list are context content, not computable physics. The Lab teaches what the kernel computes; these remain /science reading.

A01.4 · Scope change — a foundational classical-mechanics kernel domain

The one reversed non-goal (see the struck line in §Non-goals). The Lab adds a new pure kernel subdomain for classical mechanics — the primitives the spaceflight formulas already rest on but never exposed: kinematics (free-fall, projectile), dynamics (F=ma, weight, drag), momentum, energy & work, gravitation. This is new physics relative to the original PRD and is adopted deliberately.

The honest scope, corrected post-Fable-5 (BLOCKER 2). The first draft framed this as "only the floor extends downward; the ceiling is unchanged." That is internally false — the milestone ladder also needs bounded new astrodynamics sideways at higher rungs: SOI/patched-conic radius (M2), ignition-altitude/hover-thrust (M3), gravity-assist v∞-rotation

• Oberth (M6 — assists today are authored waypoints, not computed), eclipse geometry (G8). So the real scope is: new physics is added both downward (mechanics floor) and sideways (per-milestone astrodynamics), each a small named closed-form formula, budgeted per milestone and pulled demand-driven (RFC-037 A01.2b/A01.3). What stays out of bounds is unchanged: no N-body, CFD, or higher-precision numerical propagation — the fidelity ceiling holds; what grows is the catalogue of exact/closed-form formulas.

Compose honestly (Fable-5 MAJOR 4). "A drop through Titan is the same EDL integrator" was wrong — a drop from rest is the integrator's singular case (it divides by velocity), and Titan isn't in the gravity table cited. The real reuse is the per-body helpers (bodyGravity/bodyAirDensity) under a purpose-built free-fall integrator; the insight (general mechanics and spaceflight are the same physics at different altitudes) holds, the implementation claim was corrected. Taxonomy + depth tiers: companion note; the "too complex" cut (friction, collisions, rotational, fluids, thermo) is demand-driven — nothing lands until a goal pulls it (RFC-037 A01.3), which is where the cut actually falls.

A01.5 · MVP = the ENTIRE ladder (operator, 2026-08-29 — corrects an earlier misread)

The v0.9 MVP is the whole stacked ladder — every goal in both families, plus the kernel, the mechanics domain, the Lab views, and the MCP server. There is NO subset. "Everything that respects this PRD + RFC-037 is the MVP." v1.0 is where the operator adds even more, beyond what these docs describe. (An earlier draft of this section wrongly said "MVP = M1 only, rest is roadmap" — that was a misunderstanding, now reversed. M1 is the first thing built, not the boundary of what ships.)

Full coverage is therefore the definition of done, not an aspiration: every computable capability in the kernel — including gas-giant-probe and micro-g small-body descent (A01.3) — gets a pulling goal, because we ship every goal. This is the hard requirement RFC-037 A01.3's coverage ledger enforces.

Build order still starts at M1, and additivity is still the architectural bet. M1 is built first because it proves the machine (kernel → registry → FigureSpec → Notebook → workbench validation) end to end on one goal. The bet — each subsequent milestone is scenario-authoring + a budgeted bit of new physics, with no structural rebuild — is then validated live at the first additivity checkpoint, M2 (Fable-5 MAJOR 1): if M2 needs a contract change rather than just new FormulaDefs + FigureSpec kinds, the architecture failed and we learn it after one milestone, not ten. Every milestone from M1 through M-return and Family B ships in v0.9; the re-slicing step sizes the full ladder.

Progression UI stays minimum (no skill-tree); each goal's critical path lives as data, rendered as a plain authored Notebook.

A01.6 · The natural-language "ask" (T4) — reaffirmed as the payoff, still not v1

"Explain what it takes to launch a rocket" typed in plain language, answered by selecting goal formulas, computing, and drawing — is T4, an upper layer over the MCP + the goal-aware registry. Unchanged from the original ladder: it lands after the MCP proves the kernel to strangers. The milestone/goal model is precisely what gives a future NL layer a structured target to resolve a human goal against.