# /bowl — Physics requirements, project plan, and research foundation

**Prototype revision 0.3 · November 11, 2026 · Intended location: ohdeven/bowl/**

**Status: a first exploratory browser prototype has been authorized and built. Research validation remains incomplete; no production deployment has been performed. See [the prototype guide](docs/PROTOTYPE.md).**

See [README.md](README.md) for reproduction instructions and [the research status](docs/RESEARCH_STATUS.md) for extracted pattern data, engine limitations, and actual benchmark results. Requirements below remain targets unless explicitly verified there.

## 1. Purpose and scientific standard

Build a browser-based tenpin bowling laboratory: configure a ball and release, a lane and conditioner, and a pin rack; compute the shot; then inspect the complete motion from any viewpoint and at any recorded time. Ball motion, deflection, pinfall, and subsequent collisions must emerge from physical models rather than authored animation or strike probabilities.

“Academic grade” means documented assumptions, traceable inputs, reproducible experiments, convergence studies, and validation against measurements. It cannot mean exact reproduction of every pinfall from manufacturer marketing specifications. Small changes in pin placement, friction, and release produce different collision sequences. More timesteps cannot compensate for missing material data.

**Recommended approach:** a calibrated six-degree-of-freedom multibody model, spatially resolved lane lubrication, a specialized ball–lane traction model, and simultaneous frictional contact solving. Provide a practical research mode and a slower reference mode. Use uncertainty ensembles when the initial conditions or material properties are not precisely known.

The first scientific deliverable should be validated ball trajectories and isolated collisions. Full-rack predictions follow only after those pass. Treat the browser as both an experiment runner and an analysis instrument; simulation may finish more slowly than playback.

### Scope decisions proposed for review

- Conventional free-fall tenpin bowling first. String pins require a separate tether, tension, entanglement, and pinsetter model and are deferred.
- One lane, gutters, pin deck, kickbacks, rear cushion, pit, ball, and ten independent pins; configurable spare racks.
- Real Brunswick product presets plus clearly labeled generic material presets. Historical products are acceptable experimental subjects; availability and competition eligibility are separate metadata.
- Static fresh oil first for calibration; depletion, ball pickup, redistribution, and carrydown are required subsequent research stages.
- No animated bowler is needed: the experiment begins at a precisely defined release state.
- “PBC” in the request is unresolved. Do not silently substitute USBC, PWBA, or PBA. Identify the intended organization/event before importing its patterns. PBA and Kegel are verified source families; USBC supplies equipment standards.
- `/bowl/` is the intended route beneath the existing ohdeven site. Integration with navigation and production hosting remains deferred. The local prototype is now implemented at this path.

## 2. Functional requirements

| ID | Requirement | Acceptance evidence |
|---|---|---|
| R01 | Configure ball model, weight variant, diameter, coverstock, surface preparation, measured roughness, wear, temperature, core/inertia, drilling, and initial surface oil | Saved scenario reproduces every input; unknown properties remain explicitly unknown |
| R02 | Configure release position, clearance above lane, velocity vector, speed, launch/elevation angles, rev rate, axis tilt, axis rotation, handedness, and core orientation relative to the release axis | UI conventions convert to one unambiguous position, quaternion, and angular-velocity vector; left/right mirror tests |
| R03 | Support symmetric and asymmetric cores and custom measured mass properties | Correct free rotation and conservation checks; no artificial lateral “hook force” |
| R04 | Configure synthetic and wood lane materials, coating, roughness, topography, panel joints, deck and wall properties | Material and geometry maps are independently inspectable and versioned |
| R05 | Import versioned oil recipes and measured oil maps, including dual-conditioner applications | Total-volume checks, original source reference, machine settings, and reconstruction uncertainty retained |
| R06 | Simulate loft, landing, bounce, skid, hook, rolling, track migration, and gutter entry | Phase labels are derived diagnostics, never hard-coded trajectory stages |
| R07 | Simulate ball–pin, pin–pin, pin–deck, pin–gutter, pin–kickback, and rear-cushion contacts, including repeated contacts | No scripted knockdowns; contact history identifies participating bodies and impulses |
| R08 | Simulate full 3D pin translation, spin, tipping, rocking, sliding, airborne motion, and settling | Actual pin shapes and mass distribution drive motion; arbitrary pin configurations work |
| R09 | Set up → simulate → inspect; cancel long runs, show progress, rerun, compare shots, and batch parameter sweeps | Rendering responsiveness is independent of solver speed |
| R10 | Pause, play, reverse, scrub, set speed, step by render frame or solver step, and jump between impacts | Identical recorded state at a selected time regardless of playback direction |
| R11 | WASD free flight with mouse look, Q/E vertical movement, speed adjustment, reset, orbit selected object, and saved viewpoints | Camera works during pause and forward/reverse replay and cannot affect physics |
| R12 | Click every modeled subject: ball, individual pin, lane location, oil cell, gutter, wall, or contact glyph | Inspector displays selected-time values, units, coordinate frame, source, and confidence |
| R13 | Inspect force/impulse vectors, torque, velocity, spin, slip, contact normal, energy, track, and local material/oil state | Smooth-force values are distinguished from impulse-derived averages and unavailable peak forces |
| R14 | Generate spatial impact, skid, rolling, scraping, and secondary-collision sounds | Events are time-aligned, material-sensitive, and driven by physics quantities |
| R15 | Save/export/import scenarios, runs, source metadata, trajectories, contacts, and analysis tables | Schema-versioned round trip; replay works without rerunning the solver |
| R16 | Show uncertainty ranges, uncalibrated inputs, validity domains, solver settings, and convergence status | Every run has a scientific metadata manifest |
| R17 | Support desktop browsers with keyboard and mouse; accessible numeric controls and object list | Camera capture releases with Escape; text inputs never trigger movement; selection works without pointer lock |

### Inspector and analysis behavior

The inspector must separate **constant properties**, **instantaneous state**, **contact interval data**, and **derived summaries**. For example, ball mass is constant; angular velocity varies; an impact impulse integrates over an interval; entry angle summarizes an event. A fixed lane has zero velocity but can carry a contact reaction.

Show body and world coordinate vectors, body axes, contact points, linear/angular momentum, translational/rotational energy, torque contributions, local oil thickness and composition, and material provenance. For pins also report tilt, center-of-mass height, displacement from spot, total traveled path length, and standing/fallen classification. For a lane click, show topography, roughness, conditioner, and change from the initial oil state.

Allow hidden subjects to be selected using an object list, transparent/section views, and contact filters. Include a contact timeline and graphs of speed, spin, slip, lateral position, energy, and contact impulse. Sampling or display decimation must not be presented as full-resolution physical data.

## 3. Coordinates, units, and initial conditions

Use SI internally: meters, kilograms, seconds, radians, newtons, newton-seconds, pascal-seconds, and kelvin. Display pounds, mph, feet, boards, RPM, degrees, cP, and mL as user options. Conversion constants: inch = 0.0254 m; foot = 0.3048 m; lb mass = 0.45359237 kg; mph = 0.44704 m/s; RPM = 2π/60 rad/s; cP = 0.001 Pa·s; dyn/cm = 0.001 N/m.

World frame: +X to the bowler's right, +Y down lane, +Z upward. Origin: foul-line center at lane surface. Store board convention and viewing direction explicitly. Geometry center, center of mass, and core reference frame are different quantities.

Define release height as **ball-bottom clearance**, with center height derived from radius and local lane elevation; also permit direct center-position entry. Define velocity elevation separately from axis tilt. Axis tilt is the spin-axis elevation above the lane plane. Axis rotation is a signed rotation of the spin-axis horizontal projection away from the pure-forward-roll axis; the UI must show a preview arrow and handedness convention. Store the resulting world angular vector, not just two ambiguous angles. For travel along +Y, pure forward rolling has angular velocity along −X in this frame.

A quaternion maps body coordinates into world coordinates; store scalar-first `[w,x,y,z]`, normalized. Angular velocity is stored in world coordinates. Body inertia is about its center of mass. Pin geometry origin is the center of the base, with a separate COM offset.

## 4. Physical model and governing equations

The following is the **proposed model**, not a claim that coefficients are already measured. Implement each equation with its assumptions, parameter units, validity range, tests, and source record. Newton–Euler mechanics is the governing foundation; the bowling-specific paper below is a useful trajectory benchmark, not proof of a complete pinfall or lubricant model. [MIT rigid-body equations](https://ocw.mit.edu/courses/16-07-dynamics-fall-2009/5e1d8699338146e5127080b880b906d6_MIT16_07F09_Lec28.pdf), [Ji et al., bowling simulation](https://arxiv.org/abs/2210.06753).

### 4.1 Translation, rotation, and free flight — all moving bodies

For mass m, COM position x, velocity v, orientation q, angular velocity ω, and rotation matrix R(q):

```text
ẋ = v
m v̇ = m g + Σ Fcontact + Fair
Iworld = R Ibody Rᵀ
ω̇ = Iworld⁻¹ [τworld − ω × (Iworld ω)]
q̇ = ½ [0, ωworld] ⊗ q
τworld = Σ (rcontact × Fcontact) + Σ Mcontact
E = ½ m |v|² + ½ ωᵀ Iworld ω + m g0 z
```

Here g = (0,0,−g0), and contact lever arms are measured from the COM. Integrate orientation with an exponential-map/quaternion method and monitor normalization. Include gyroscopic dynamics; an asymmetric core does not turn correctly if inertia is replaced by one scalar.

During loft, gravity is mandatory. Optional air drag is `Fair = −½ ρair CD A |vrel| vrel`; characterize its sensitivity before adding lift or aerodynamic spin torque. The zero-drag vertical drop benchmark is `vz² = vz0² + 2 g0 Δz`, with Δz the positive fall distance. Do not infer impact force from drop height without compliance/contact duration.

### 4.2 Ball inertia and drilling

For principal radii of gyration ki, `Ii = m ki²`. Ball catalog RG values are lengths, usually inches, and must be converted before squaring. If confirmed by the product's axis definitions:

```text
klow = RG
khigh = RG + totalDifferential
kmid = khigh − intermediateDifferential
Iprincipal = diag(m klow², m kmid², m khigh²)
```

For an ideal low-RG-axis symmetric ball, the two high principal radii are equal; this is an explicit idealization. Catalogs without intermediate differential do not prove the drilled ball remains symmetric. Confirm ASY/intermediate-differential convention before converting it. Reconstructing inertia does not reconstruct a unique core shape.

For holes, inserts, and plugs, integrate/subtract their mass and inertia in a common reference frame and recenter at the new COM using the parallel-axis theorem:

`Iabout O = Iabout COM + m [(d·d) 1 − d dᵀ]`.

Need hole dimensions, density distribution or measured post-drilling inertia, and core orientation relative to pin/PSA markings. A decorative core mesh must not determine scientific mass properties. Track flare emerges from evolving orientation and surface-contact tracks.

### 4.3 Contact kinematics and skid/roll diagnostics

For bodies A/B touching at a world point:

```text
u = (vA + ωA × rA) − (vB + ωB × rB)
un = u·n
ut = u − un n
```

Use n pointing from B toward A. Approaching contact has un < 0. For a ball on the lane, the contact point uses the sphere's geometric center and the actual surface normal, with the lever arm measured from its COM.

Skid means appreciable tangential relative velocity; rolling means small |ut| while support persists. Use absolute and normalized slip diagnostics with hysteresis, and publish their thresholds. Hook is lateral path curvature `κ = |vx ay − vy ax| / (vx² + vy²)^(3/2)` where speed is nonzero. These are observations of dynamics, not forces or predetermined phases.

### 4.4 Normal and tangential contact — practical research solver

Use unilateral nonpenetration, normal impulses, and friction-cone constraints. For an isolated frictionless impact, the diagnostic formula is:

```text
Kn = 1/mA + 1/mB
     + n·[(IA⁻¹(rA×n))×rA + (IB⁻¹(rB×n))×rB]
Jn = −(1+e) un / Kn          (approaching contact only)
ΔvA = +J/mA;  ΔvB = −J/mB
ΔωA = IA⁻¹(rA×J); ΔωB = −IB⁻¹(rB×J)
```

For a fixed body, inverse mass/inertia contributions are zero. J includes normal and tangential components. Solve the full coupled contact system for simultaneous collisions; this isolated formula is not an algorithm for serially resolving a crowded rack.

For sustained rigid contacts, solve a discrete complementarity/contact constraint system with nonnegative normal impulse and nonpenetration; apply restitution only to sufficiently fast new impacts. Tangential sticking requires `|Jt| ≤ μs Jn`; sliding saturates the calibrated friction cone opposing slip, using μk. Tangential effective mass is generally a matrix, so independently clamping Cartesian components is not equivalent to a circular cone.

Restitution is a material-pair and impact-condition parameter: `e = e(pair, |un|, location, temperature, wear)`. It is not a universal “bounciness” value for every surface. Suppress repeated restitution on persistent contacts and avoid adding damping twice.

**Force reporting:** J is a momentum transfer in N·s. `Favg = J/Δtinterval` is only an interval average. A rigid solver cannot determine the true peak force or waveform. Store the interval and label that distinction in every graph and export.

### 4.5 Compliant contact — slower reference mode

Use a calibrated normal compliance law, initially Hertz/Hunt–Crossley type:

```text
Fn = max(0, k δ^(3/2) (1 + α δ̇))
k = (4/3) E* sqrt(R*)
1/E* = (1−νA²)/EA + (1−νB²)/EB
1/R* = 1/RA + 1/RB          (sphere/sphere; plane curvature is zero)
```

δ is indentation, δ̇ is positive on compression, E is Young's modulus, ν is Poisson ratio, and α has units s/m. Calibrate damping from impact experiments; α is not automatically equal to restitution. Hertz assumptions are smooth local geometry and small elastic deformation. Layered polymer-coated wood pins, flat pin bases, and compliant lane supports may require fitted effective laws or local finite-element reference models.

Use tangential contact displacement history with spring/damping traction projected onto a Coulomb bound, transporting history as the normal rotates. Resolve contact times with enough substeps for convergence. Do not run this force law on top of a rigid normal impulse for the same contact. Project Chrono documents both nonsmooth constraint contact and smooth compliant contact and is a candidate independent reference tool. [Chrono contact formulations](https://api.projectchrono.org/collisions.html).

### 4.6 Ball–lane traction and lubrication

A coefficient depending only on pattern color is insufficient. Traction depends on material pair, slip speed, normal load, film thickness, temperature, surface texture, and surface oil history.

**Stage A: calibrated reduced model.** Use measured tables or fitted curves `μeff(h, |ut|, N, T, cover, roughness, oilComposition)` with separate static/sliding behavior. A candidate speed law at fixed other conditions is:

`μ(vs) = μc + (μs − μc) exp[−(vs/vS)^p]`.

Then sliding traction is `Ft = −μ(vs) N ut/|ut|`. Near zero slip solve sticking constraints; do not divide by zero or normalize numerical noise. Fit μc, μs, vS, and p from data. This is an empirical reduced model, not a viscosity-to-friction conversion.

**Stage B: mixed lubrication reference.** Split support into asperity and fluid components: `N = Nasp + Nfluid`. Candidate traction integrates boundary and fluid shear over the contact patch:

`Ft = ∫patch (tboundary + tfluid) dA`, with Newtonian shear magnitude approximately `η |ut|/h` only where a continuous film exists. Pressure-driven shear can also contribute. Weight asperity friction by asperity load, not total load; do not add a full μN law to a full fluid law and count resistance twice.

For an isoviscous, incompressible, thin Newtonian film, a local Reynolds reference is:

`∂h/∂t + ∇·[h Umean − (h³/(12η))∇p] = 0`.

Include elastic deflection, load balance, supply/starvation boundaries, and cavitation as appropriate. This is not valid across dry patches or automatically valid for non-Newtonian oil. Use patch-scale reference calculations and validated surrogate tables rather than a whole-lane fluid mesh at audio or collision rates. [COMSOL Reynolds formulation](https://doc.comsol.com/6.4/doc/com.comsol.help.cfd/cfd_ug_fluidflow_thinfilm.12.19.html).

For shear-thinning conditioner, investigate a fitted Carreau–Yasuda law:

`η(γ̇,T) = η∞(T) + [η0(T)−η∞(T)] [1+(λ(T)γ̇)^a]^((n−1)/a)`.

Here γ̇ is shear rate, λ is a time scale, and n < 1 gives shear thinning. This is a candidate constitutive model, not an established fit for Kegel Terrain. Obtain a rheogram and temperature data before assigning its coefficients. Nominal cP alone cannot identify them.

### 4.7 Oil deposition, depletion, pickup, and carrydown

Represent initial lane film `h(x,y)` and conditioner fractions, plus a material-coordinate oil map on the rotating ball. A lane machine recipe is an application instruction, not a direct measurement of the final film.

Reconstruct deposition by distributing each documented load through a calibrated machine transfer kernel; account for forward/reverse travel, buffering, brush drop distance, speed, tank identity, and pump settings. Require `Σ hcell Acell` to agree with deposited volume within an explicitly measured transfer loss. Do not treat a heatmap RGB value, “ratio,” or machine load count as thickness without a documented conversion.

A coarse conservation update is:

```text
∂h/∂t + ∇·Q = Sdeposit − Spickup − Sabsorb
Vlane + VballSurface + Vabsorbed + Vremoved = Vinitial + Vadded
```

Carrydown is deposition from the moving ball back onto downstream lane cells. Track oil transfer separately by conditioner species; blend viscosity is not assumed to be an arithmetic average. Use conservative, nonnegative updates and a calibrated contact-footprint kernel. Roughness and surface absorption parameters must be measured. Start with fresh-lane single shots, then validate sequences against pre/post oil scans.

### 4.8 Rolling, spin resistance, and topography

A first fitted rolling resistance torque is `Mroll = −b N ωroll/|ωroll|`, where b has units of length, with a near-zero regularization or static resistance treatment. For spin about the contact normal, use a separately calibrated torsional friction moment, for example a bound proportional to `μspin N a`, where a is contact-patch radius. These are dissipative models requiring measurement; do not double-count losses already contained in a fitted traction curve.

On a surface `z = zlane(x,y)`, compute the normal from its gradient. Gravity, normal force, and friction then produce slope effects without extra ad hoc steering. Include measured pin-deck and kickback geometry, gutter transitions, seams, and panel compliance where sensitivity warrants it.

### 4.9 Pin stability, collision cascades, and energy

Pins are shaped rigid bodies with measured COM and inertia, not cylinders or capsules in the final validated model. A simple static tipping benchmark about a support edge is `Fhorizontal zforce > m g0 b`, with b the horizontal COM-to-edge distance. The dynamic simulator must solve contact and gravity; it must not apply this inequality as a universal knockdown rule.

For an isolated normal impact, approximate dissipated normal energy is `ΔEn = ½ meff (1−e²) un²`, with `meff = 1/Kn`. This does not replace the full energy budget when friction and multiple contacts couple translation and spin. Compute complete pre/post kinetic energy, gravity work, and dissipative work and distinguish solver correction energy.

## 5. Pin crash chain-reaction strategy

1. Construct the pin's external profile from authoritative dimensions or a scan. Use a smooth profile/reference collider and converged convex decomposition for the browser solver. Mesh rendering and collision shape are independently versioned. Preserve the neck, belly, base curvature, and flat support area.
2. Assign each pin its own measured mass, COM, inertia, coating, base material, placement error, and wear. Use identical nominal pins only as a labeled controlled experiment.
3. Settle the rack under gravity; record the settled state and verify that solver error does not produce spontaneous motion.
4. Use broad-phase collision detection plus accurate narrow-phase manifolds and swept/continuous collision detection for fast translating and rotating objects. Ball, pins, deck, gutters, kickbacks, cushion, and pit remain in one world.
5. At each step, find connected contact islands and solve their contacts together with friction and angular response. A ball contacting two pins and the lane must not become three unrelated one-dimensional collisions.
6. Record contact creation, persistence, separation, and re-impact. Retain multiple contact points when physically relevant; aggregate adjacent collider-piece contacts without multiplying friction artificially.
7. Continue until kinetic activity falls below documented settling thresholds for a sustained duration, or a maximum run time is reached. Report timeout as unresolved; do not force remaining pins to fall or stand.
8. Allow messengers, wall rebounds, sliding fallen pins, and ball recontacts to emerge. Do not remove bodies immediately upon entering the pit if they can still rebound into play.
9. Build a time-ordered interaction graph: node = body/event; edge = measured impulse/work transfer. Simultaneous contact islands are coupled events; avoid claiming a uniquely identifiable “pin A caused pin B” where the solution is collective.
10. Classify final standing pins from support, orientation, COM, and continued stability, separately from competitive scoring rules. A briefly tilted pin that recovers is not automatically fallen.

Validate isolated ball–pin impacts at several offsets, pin–pin head/belly/base impacts, pin tipping and rocking, deck sliding, kickback rebound, two/three-pin clusters, then full racks. Compare trajectories and event timing before comparing strike percentages. Report pinfall probabilities over measured input variation, with confidence intervals and sensitivity rankings.

## 6. Authoritative starting data and fact sheets

**Evidence labels:** Published = explicitly stated by source; Derived = calculated from published/measured inputs; Measured = obtained under recorded conditions; Assumed = provisional; Missing = not obtained. Published does not mean experimentally complete.

### 6.1 Equipment geometry and methods

Use the **USBC Equipment Specifications and Certifications Manual, March 2026** as the current located baseline. Selected anchors: foul line to headpin center 60 ft ± ½ in; pin spacing 12 in ± 1/16 in; nominal lane width 41½ in; wood pin target height 15 in and target mass 3 lb 8 oz. The pin table's restitution target is 0.670, with 0.605–0.735 limits; it is a standardized test result, not a universal collision-pair coefficient. Import full geometry/tolerances from the relevant sections during data work. [USBC March 2026 manual](https://images.bowl.com/bowl/media/assets/usbc/equipment%20specs/26_231-26-march-es-manual.pdf).

USBC also lists laboratory methods for ball-on-lane friction, lane friction/roughness, pin COM and RG, pin restitution, and viscosity. Obtain their exact procedures before interpreting laboratory values. [USBC manufacturer and test-method index](https://bowl.com/equipment-specifications/manufacturers).

### 6.2 Brunswick ball fact-sheet seed catalog

Numbers below are **15 lb undrilled catalog values**, with RG/differentials in inches. Every other weight needs its own row; lighter balls can have different cores. Product numbers and full surface preparation must be retained in the eventual dataset.

| Ball | Cover / core | RG | Total differential | Intermediate | Initial use and primary source |
|---|---|---:|---:|---:|---|
| Crown Jewel | Polyester / Bullet | Missing | Missing | Missing | Low-traction material comparison; 10–16 lb offered in sheet. [Manufacturer sheet](https://brunswickbowling.nyc3.cdn.digitaloceanspaces.com/production/downloads/Ball-Info-Sheets/Crown_Jewel_Info_Sheet_0721-11.pdf) |
| U-Motion | Solid urethane / U-Motion | 2.596 | 0.020 | Not supplied | Urethane baseline; 500/1000 Siaair finish. [Manufacturer sheet](https://brunswickbowling.com/uploads/downloads/Ball-Info-Sheets/U-Motion_Info_Sheet_0220-04.pdf) |
| Rhino | R-16 reactive / Light Bulb | 2.524 | 0.030 | Not supplied | Record exact color/SKU: sheet includes solid and pearl variants and different finishes. [Manufacturer sheet](https://brunswickbowling.nyc3.cdn.digitaloceanspaces.com/production/downloads/Ball-Info-Sheets/Rhino_Line_Info_Sheet.pdf) |
| Ivory Rhino Pro | HK22 Activator Plus 3.0 Pearl / Vintage Light Bulb | 2.568 | 0.032 | Not supplied | Pearl reactive comparison; 500/1000/1500 Siaair plus factory compound. [Manufacturer page](https://brunswickbowling.com/products/balls/retired/ivory-rhino-pro) |
| Mesmerize | HK22C EVO Solid / Tri-Elliptic | 2.510 | 0.056 | 0.017 | Asymmetric comparison; 500/1500 Siaair. [Manufacturer sheet](https://brunswickbowling.com/uploads/downloads/Ball-Info-Sheets/Mesmerize_Info_Sheet_0424-44.pdf) |

Weight dependence examples: Mesmerize 14 lb has RG 2.533, differential 0.056, ASY 0.016; 12 lb has 2.593/0.041/0.014. Rhino 10 lb has RG 2.800 and differential 0.002. Do not rescale the 15 lb tensor to represent all weights. The cited sheets support these values.

Missing for all presets: complete drilled inertia and COM, measured radius, cover friction curves, dynamic modulus/damping, absorption/transfer parameters, roughness after actual preparation, and ball–pin restitution under relevant conditions. Grit labels are preparation instructions, not measured micrometer roughness. Manufacturer performance scores are not physical coefficients.

### 6.3 Brunswick lanes and pins

| Asset | Published foundation | Missing measurements |
|---|---|---|
| Pro Lane synthetic | Manufacturer identifies system and targeting features. [Lane systems](https://brunswickbowling.com/bowling-centers/equipment-parts-supplies/center-operations/lanes) | Dry/oiled friction against each cover, roughness spectrum, local slope, support stiffness, seams, aging |
| Anvilane synthetic | Manufacturer describes 3/8 in panels. [Lane systems](https://brunswickbowling.com/bowling-centers/equipment-parts-supplies/center-operations/lanes) | Same measurements; thickness alone does not determine compliance or traction |
| Wood lane with finish | Generic experimental comparison pending exact wood, finish, and installation documentation | Surface species/finish, maintenance, humidity, roughness, compliance, friction, topography |
| Brunswick Max Crown | Maple body, SURLYN ionomer cover, neutral base. [Manufacturer product page](https://brunswickbowling.com/bowling-centers/equipment-parts-supplies/center-maintenance/pins/max-pins-crown) | Individual mass/COM/inertia, coating thickness and modulus, contact damping, base/deck friction, modal response |
| Score King | Manufacturer brochure identifies wood construction and black base | Same measurements; do not reuse Max coefficients without comparison |
| Max Life synthetic | Separate synthetic pin construction in manufacturer brochure | Actual internal structure, inertia, restitution, damping, and acoustic modes |

Source for the latter two: [Brunswick center-products brochure, pin section](https://brunswickbowling.com/uploads/document-library/Brunswick-Center-Products-Brochure.pdf). Product construction descriptions do not establish measured collision properties. Check approval lists against the chosen season separately from physics presets.

### 6.4 PBA and Kegel pattern sources

Use the [official PBA oil-pattern page](https://www.pba.com/player-resources/oil-patterns) for sanctioned pattern versions and [Kegel Pattern Library](https://patternlibrary.kegel.net/) for Kegel machine recipes. Kegel documents downloadable PDF sheets and KOSI text files, with length, volume, ratio, loads, and machine information. [Kegel library documentation](https://www.kegel.net/pattern-library-app).

Initial comparison set:

| Pattern family/version | Intended purpose | Research state |
|---|---|---|
| 2026 PBA Cheetah 35 | Short-pattern comparison | Atlas Pro PDF extracted and visually checked; 35 ft, 28.785 mL |
| 2026 PBA Chameleon 39 | Intermediate-pattern comparison | Atlas Pro PDF extracted and visually checked; 39 ft, 32.935 mL |
| 2026 PBA Shark 48 | Long-pattern comparison | Atlas Pro PDF extracted and visually checked; 48 ft, 32.435 mL |
| Kegel machine-specific recipes | Cross-check machine implementation | Official PBA archives include Kegel sheets rendered for Atlas Pro; other machine formats inventoried but not decoded |
| Measured local house pattern | Calibration and repeatability | Need center, machine, recipe, and oil scans |

Official download links: [Cheetah archive](https://www.pba.com/sites/pba/files/2026-03/2026-pba-animal-cheetah-35.zip), [Chameleon archive](https://www.pba.com/sites/pba/files/2026-03/2026-pba-animal-chameleon-39.zip), [Shark archive](https://www.pba.com/sites/pba/files/2026-03/2026-pba-animal-shark-48.zip). These ZIP archives have now been downloaded and hashed. Their one-page PDF recipes were text-extracted and visually checked, with all load-volume and forward/reverse total checks passing. See [patterns.json](data/patterns.json) for factual rows and source/member SHA-256 hashes. The sheets name only KEGEL as tank contents; specific conditioner and viscosity remain unresolved. Printed distances are rounded, including one nonzero Cheetah load printed at 0 → 0 ft. Machine deposition and actual oil-film thickness remain unmeasured. Other archive formats are inventoried, not decoded.

PBA notes that site conditions can lead to event-specific volume adjustments. Therefore use `organization + season + event + revision + machine + conditioner`, never just “Shark.” A PBA name does not establish that Kegel oil was used. Keep recipe provider, pattern owner, lane-machine manufacturer, and conditioner manufacturer as separate fields.

### 6.5 Kegel conditioner specifications

| Product | Published viscosity | SI conversion | Published surface tension | Primary source |
|---|---:|---:|---:|---|
| Fire | 45.1 cP | 0.0451 Pa·s | 23.3 dyn/cm | [Kegel Fire](https://www.kegel.net/fire) |
| Ice | 40.9 cP | 0.0409 Pa·s | 23.2 dyn/cm | [Kegel Ice](https://www.kegel.net/ice) |
| Current | 52.0 cP | 0.0520 Pa·s | 23.3 dyn/cm | [Kegel Current](https://www.kegel.net/current) |
| Terrain | 81.0 cP | 0.0810 Pa·s | 23.2 dyn/cm | [Kegel Terrain](https://www.kegel.net/terrain) |

These are nominal product-page values. Measurement temperature, shear rate, spindle, batch, density, pressure response, and uncertainty are not supplied beside these numbers. Do not fill them by assumption. Terrain is explicitly described by Kegel as non-Newtonian/shear-thinning; its nominal value is not a constant operating viscosity. Obtain SDS/TDS and rheometry directly from the source links or manufacturer.

Source conflict to resolve: an older distributor-hosted Kegel catalog surfaced with Fire surface tension 23.6 dyn/cm, while the current manufacturer page gives 23.3. Preserve both dated observations if imported; use the directly checked manufacturer value provisionally and ask for batch-specific confirmation. Shipping weight is not fluid density. Oil viscosity does not by itself establish ball traction.

## 7. Physics data schema

Use versioned JSON manifests validated by JSON Schema; large arrays use typed binary chunks. The following is a **schema design**, not implementation code. Store immutable asset definitions separately from mutable runtime state and measured observations.

| Entity | Required fields and relationships |
|---|---|
| SourceRecord | id, title, publisher, URL, publication/revision/access dates, page/table/section, archived-file hash when acquired, license/redistribution status |
| Parameter | value or null, unit, evidenceStatus, sourceId, uncertainty model, measurement conditions, validity range, derivation, notes; null must never silently become zero |
| MaterialDefinition | id/version; density, elasticity, damping, roughness and texture direction, thermal data; links to acoustic model and experimental records |
| BallDefinition | model/SKU/weight variant; radius, mass, COM offset, principal inertia, principal-frame orientation, cover/core IDs, surface preparation, drilled geometry, reference markings |
| PinDefinition | product/version, profile/mesh/collider hashes, mass, COM offset, full inertia, base/coating/body material IDs, wear and acoustic model |
| LaneDefinition | geometry, board convention, topography and roughness maps, region material IDs, deck/gutter/kickback/cushion/pit definitions, installation and measurement metadata |
| ConditionerDefinition | product/batch, density, viscosity model and coefficients with test conditions, surface tension, composition compatibility, absorption/transfer parameters |
| PatternRecipe | organization, season, event, patternId/revision, sourceId, machine, conditioner/tank IDs, pump delivery, speed tables, forward/reverse loads, brush/buff settings, reported volume and ratio definition |
| OilField | x/y grid convention, dimensions, spacing, thickness meters, species fractions, temperature, timestamp, initialization method, reconstruction uncertainty, total volume |
| SurfaceOilState | bodyId, body-coordinate surface mesh/grid, species volumes/thickness, absorbed inventory, last-update time |
| ContactLaw | material pair, regime, friction/restoration/compliance models, parameter references, calibrationDatasetId, validity domain, modelVersion |
| Scenario | asset IDs and versions, explicit overrides, initial body states, release metadata, rack placements, environmental conditions, initial oil hash, seed, solver configuration |
| BodyState | bodyId, time/step, COM position, quaternion, linear/angular velocity, optional acceleration, force/torque breakdown, activity/support state |
| ContactSample | stable contact/island IDs, body A/B, time and interval, world point(s), normal B→A, COM lever arms, gap/indentation, pre/post relative velocity, normal/tangent impulses, optional resolved force, friction regime, material IDs, energy/work diagnostics |
| CollisionEvent | eventId, contactIds, time range, participants, new/persistent/reimpact status, aggregate impulse, peak force only if resolved, energy estimate and method, links to preceding coupled events |
| RunManifest | scenario hash, code/build/engine/model versions, precision, platform, timestep policy, tolerances, iteration counts, seed, data hashes, warnings, convergence report, start/end/status |
| ReplayChunk | runId, time range, body-state arrays, contacts, oil deltas, sample rate, compression, checksum, exact/interpolated flag |
| Checkpoint | solver internal snapshot, contact caches, bodies, oil maps, RNG state, time; required for restarting simulation, not merely viewing replay |
| AcousticEvent | contact/eventId, physical time, source position, material pair, impulse/work/contact duration, mode/sample selection, random seed, gain calibration, uncertainty |
| Observation | experiment ID, instrument/calibration, raw data hashes, time alignment, specimen IDs, measurement uncertainty, repeat count, environmental conditions |
| ValidationResult | model/run IDs, observation IDs, metric definition, error, confidence interval, pass threshold, calibration versus held-out split |

**Data invariants:** masses and radii positive; inertia symmetric positive-definite and physically realizable; principal moments obey triangle inequalities; quaternions normalized; thickness and species inventories nonnegative; fractions sum to one where oil exists; every ID resolves; time is monotonic within chunks; all vectors state their frame; units are checked at boundaries. Restitution is in [0,1] for passive baseline contact models. Contacts obey equal/opposite impulse bookkeeping.

Record provenance at the parameter level. A ball may combine catalog mass, measured drilled inertia, and assumed friction; one blanket “verified” flag would hide this. Store correlated uncertainty where measurements share a systematic error. An experimental observation must never be overwritten by a model prediction.

## 8. Browser software and replay plan

### Proposed stack and alternatives

| Layer | Recommendation | Reason / decision gate |
|---|---|---|
| Application | TypeScript, Vite, conventional DOM UI; optional lightweight UI framework | Numeric controls, schemas, tables, and accessible inspectors; choice can match site conventions later |
| 3D rendering | Three.js, initially WebGL2; evaluate WebGPURenderer | Few moving bodies; rendering is not the accuracy bottleneck. Official WebGPU renderer offers WebGL2 fallback but documents migration/feature caveats. [Three.js renderer guide](https://threejs.org/manual/pages/webgpurenderer) |
| Browser physics | Rapier 3D/WASM as first engineering candidate, behind an adapter | Broad/narrow phase, rigid dynamics, contact infrastructure, snapshots and CCD; not a complete bowling traction model. [Rapier](https://rapier.rs/) |
| Specialized solver | Rust/WASM module with explicit inertia, calibrated traction, oil transport, and contact telemetry | Spike must establish what can be expressed through bindings/hooks; use a custom Rust build if JS bindings lack required access |
| Independent reference | Native double-precision research solver, potentially Project Chrono SMC/NSC | Compare formulation, numerical precision, collision geometry, and convergence without claiming native tools are already browser-ready |
| Background execution | Web Worker; transferable binary buffers first | Main thread stays responsive. SharedArrayBuffer only if hosting isolation headers and support are verified |
| Storage | IndexedDB for runs; JSON plus binary downloadable bundles | Offline review, chunked replay, quota handling, explicit export before eviction |
| Sound | Web Audio with AudioWorklet for synthesis, positional sources and room response | Browser-native audio graph; feature-test required APIs. [Web Audio specification](https://www.w3.org/TR/webaudio/) |
| Validation | Headless numerical test runner plus browser integration/replay tests | Physics verification independent of visuals |

Do not select an engine from an attractive bowling demo. The engine spike must demonstrate full inertia and gyroscopic response, persistent frictional contacts, contact-level impulse extraction, custom traction integration without double counting, dynamic/dynamic CCD, stable pin bases, and reproducible snapshots. Rapier's documented determinism depends on identical engine version, initialization, ordering, and deterministic input math; our added model must meet those conditions too. [Rapier determinism](https://rapier.rs/docs/user_guides/javascript/determinism/), [integration parameters](https://rapier.rs/docs/user_guides/javascript/integration_parameters/), [CCD](https://rapier.rs/docs/user_guides/javascript/rigid_body_ccd/).

Evaluate a custom double-precision Rust solver if required hooks, precision, or contact law are unavailable. This costs substantially more validation effort. Keep the renderer independent so a solver change does not replace the UI. Do not mix two independent dynamics engines for interacting ball/pins without a validated coupling scheme.

### Time integration and performance

- Fixed physical outer steps independent of display refresh; benchmark 240, 480, 960 Hz and finer as needed. These are investigation settings, not claimed adequate rates.
- Use collision substeps/CCD and a documented timestep schedule; compliant reference contact may require much smaller steps based on contact duration/stiffness.
- Compare dt, dt/2, dt/4, solver iteration counts, collider resolution, oil-cell resolution, and float precision. Publish residuals and convergence plots.
- Use a single authoritative simulation clock. Camera movement never advances physics. Background-tab throttling must not change outcomes.
- Target responsive 60 fps replay on a designated reference laptop, with graceful 30 fps graphics fallback; benchmark on identified devices before promising runtime. Research simulation may run slower than real time.
- Eleven moving bodies require 13 pose/velocity scalars each. At 64-bit storage, 1,000 Hz for 15 seconds is roughly 17.2 MB before contacts, metadata, and oil fields; contact telemetry can dominate. Use configurable dense contact windows and chunked data, not a full oil-grid snapshot every physics step.
- Keep a high-precision authoritative result. Optional compressed display tracks must retain stated error bounds and must not replace scientific exports.

### Reverse playback and seeking

Frictional, inelastic physics is dissipative. **Reverse playback reads recorded states; it does not integrate with negative time.** Store poses, velocities, contact samples, and oil-state changes. Interpolate position and quaternion for visual smoothness only between appropriate samples; preserve exact collision boundaries and mark interpolated values. Do not smooth impulses into fictional force curves.

Use an indexed timeline and periodic checkpoints. Oil replay restores a prior oil snapshot plus deltas. Re-simulation from a checkpoint also needs solver/contact caches and RNG state. Editing release settings creates a new run; moving the camera never does. Cache enough data that reverse playback requires no rerun.

Scientific inspection shows the nearest exact solver sample or explicitly labeled interpolation. Playback rate modifies presentation time only. Negative playback defaults to muted audio; optional reversed audio is an editorial playback effect, not a physical prediction. Pause stops excitation; seeking cancels queued audio and clears stale reverberation.

## 9. Physically informed sound

Sound needs material vibration and acoustic propagation as well as force. An impact impulse does not uniquely determine timbre or loudness; a contact-point force history, stiffness, damping, geometry, and radiation behavior supply additional information. Published modal-contact work specifically identifies artifacts when rigid-solver force fluctuations are used directly for sound. [Zheng and James, modal contact sound](https://www.cs.cornell.edu/projects/Sound/mc/).

| Event | Physics inputs | Proposed synthesis |
|---|---|---|
| Ball landing/drop | Normal speed, impulse, estimated contact duration, ball/lane material, landing location, lane support modes | Calibrated impact sample or modal excitation; distinguish dull wood-panel response from cover response |
| Sliding/skid | `Pslip = max(0, −Ft·ut)`, roughness spectrum, speed, oil film, normal load | Filtered texture noise with envelope tied to dissipative power; texture spatial wavelengths map to temporal frequencies by speed |
| Rolling | Rolling-resistance power, speed, roughness, seams, load, cover modulus | Surface-driven microimpact/texture synthesis; pure rolling may sound even when macroscopic slip is zero |
| Ball–pin / pin–pin crash | Contact point, direction, impulse, duration, pre/post energy, material pair, body orientation | Independently excite each body's modes or matched samples; sum secondary impacts at their actual times |
| Fallen pin scraping / bouncing | Slip work, successive impulses, contact regions, supporting surface | Continuous scrape plus discrete reimpacts, with event deduplication |
| Kickback / pit | Impulse, wall/cushion compliance, geometry, material | Separate resonances/absorptive samples; avoid reusing pin–pin timbre |

A modal body model uses:

```text
M ü + C u̇ + K u = f(t)
for each mass-normalized mode j:
q̈j + 2 ζj ωj q̇j + ωj² qj = φjᵀ f(t)
p(listener,t) = Σ Hj(listener,orientation) qj(t)
```

Here qj is a modal coordinate (not the orientation quaternion), ζj is damping ratio, ωj is modal frequency, and Hj is a calibrated acoustic transfer operator. For an impulse, modal velocity excitation depends on the mode shape at the contact location and the impulse direction. Precompute modes from measured geometry/materials or identify them from controlled taps. Layered and anisotropic pins need more than a single generic wood modulus. [Modal sound formulation](https://www.cs.columbia.edu/cg/pdfs/1375314017-fractureSound_comp.pdf).

For a practical first model, sample selection and gain can be conditioned on impulse and energy; fit gain against recordings. For fixed waveform normalization/duration, amplitude scales approximately with square root of acoustic energy, not linearly with force. Acoustic energy is only a calibrated fraction of dissipated mechanical energy.

Distance propagation in a free field has pressure amplitude approximately proportional to 1/r and intensity to 1/r², with travel delay r/c. Use a finite near-source distance, directivity, occlusion, stereo/HRTF panning, frequency-dependent room absorption, and measured reverberation. Camera position/orientation sets listener position/orientation. Optional Doppler needs a documented policy for rapidly moving cameras and non-unit playback speed.

Sound-pressure level is `Lp = 20 log10(prms / 20 µPa)`. Browser digital amplitude is not calibrated physical SPL without device calibration. Display relative dBFS or calibrated source estimates honestly. Never label an arbitrary volume knob as measured decibels at the ear.

Needed recordings: isolated drops at known heights, ball rolls at several speeds on dry/oiled surfaces, pin taps at head/belly/base, pin–pin impacts, deck scrapes, wall impacts, and room impulse responses; include microphone response, distance, direction, sampling rate, and calibrated gain. Prevent resting-contact solver jitter from creating hum. Audio worklet operates at audio sample rate using reconstructed contact excitation, not raw 240 Hz force values treated as an audio waveform.

## 10. Missing data and research work packages

| Priority | Gap | Acquisition / experiment | Consequence if unavailable |
|---|---|---|---|
| Critical | Cover/lane/oil traction versus slip, load, thickness, temperature | USBC methods plus controlled instrumented rolling/sliding trials; replicated specimens | Trajectory presets remain qualitative/uncalibrated |
| Critical | Post-drilling ball inertia, COM, core orientation | Manufacturer data, pendulum/inertia measurement, documented drilling/CAD | Axis migration and flare predictions uncertain |
| Critical | Actual oil film from recipe and machine | Original PDF/KOSI files, machine calibration, cross-lane scans at multiple distances | Pattern heatmap remains a reconstruction, not a measurement |
| Critical | Pin and ball collision laws | High-speed synchronized video, isolated impacts, force measurement if feasible | Cannot claim accurate crash forces or pinfall prediction |
| Critical | Pin inertia and COM, base geometry/friction | Weighing, balance and pendulum tests, scans, tilt/slide tests | Tipping, rocking, and messenger behavior uncertain |
| High | Conditioner rheology, especially Terrain | Manufacturer TDS/SDS, temperature-controlled shear sweep, density and surface tension | Nominal viscosity cannot support mixed-lubrication calibration |
| High | Oil pickup/absorption/redeposition | Marked-ball tracking, mass/film measurements and oil scans before/after repeated shots | Carrydown/breakdown remains provisional |
| High | Lane topography, material pair friction, panel support | Surface scan, roughness measurements, local compliance tests | Center-specific trajectory/carry differences unexplained |
| High | Kickback, gutter, pit and cushion response | Geometry survey, restitution/compliance tests | Full pin-cascade predictions incomplete |
| High | Tracking observations with known release states | Calibrated multi-camera capture and spin markers; independent tracking if accessible | No reliable held-out trajectory validation |
| Medium | Acoustic modes and room response | Controlled impact recordings and modal identification | Physically conditioned sound only, not calibrated acoustics |
| Medium | Browser performance, precision, hook access | Reproducible engine benchmark after planning approval | Framework decision remains conditional |
| Clarification | Meaning of PBC, desired historical/current events, first calibration center | User/source confirmation | Leave those catalog entries unresolved |

Before importing commercial documents, retain attribution and verify redistribution rights. Public access does not imply permission to bundle complete proprietary sheets or textures. Research links and extracted factual parameters can remain distinct from redistributed assets.

### Measurement design

Select a manageable matrix: one polyester, one urethane, one symmetric reactive, one asymmetric reactive; at least two available weights where feasible; one known synthetic lane; dry plus measured short/medium/long oil configurations. Vary speed, rev rate, tilt, rotation, loft, and lateral release across a documented design of experiments. Use repeat shots to estimate release variation and instrument uncertainty. Randomize test order where lane transition can confound comparisons; rescan/recondition or model history explicitly.

Fit parameters on a calibration subset and evaluate held-out releases, specimens, and patterns. Publish residuals and uncertainty; do not tune all coefficients to reproduce one dramatic strike. Assess identifiability: different friction/inertia combinations can fit one trajectory, so combine trajectory, spin, slip, and isolated material measurements.

## 11. Validation and acceptance gates

The following numerical targets are **proposed engineering targets**, subject to measurement resolution and review. They are not achieved results.

| Gate | Required evidence |
|---|---|
| V0: mathematical correctness | SI conversion and schema tests; free fall; torque-free principal rotation; asymmetric rotation invariants; equal/opposite impulses; isolated restitution; uniform-sphere rolling and skid-to-roll analytical benchmarks |
| V1: numerical convergence | dt/2 and dt/4 studies; solver residuals; collision-shape and oil-grid refinement; no tunneling/spurious energy; log departures rather than hiding them |
| V2: material calibration | Traction, restitution and compliance datasets with uncertainty and documented domain; separate fit and held-out cases |
| V3: trajectory prediction | Starting targets: ≤0.5 board lateral RMSE, ≤0.2 m/s entry-speed error, ≤0.5° entry-angle error on held-out controlled shots; also track spin/tilt and entire path, not just endpoints |
| V4: collision prediction | Initial isolated-impact targets: ≤5% post-impact velocity error and ≤2 ms timing error where camera resolution permits; report normalized error sensibly near zero velocity |
| V5: full-rack validation | Compare trajectories, leave distributions, timing and carry probability with confidence intervals; exact pinfall equality is not a universal pass criterion for uncertain shots |
| V6: replay and inspection | Exact recorded state recovered at arbitrary timestamps in either direction; contact IDs and oil state consistent; camera/input has no effect on run hash |
| V7: browser operation | Named browser/device matrix; responsive camera during simulation, graceful cancel, memory/quota handling, reproducible export/import and no silent data loss |
| V8: acoustics | Impact synchronization within one playback frame, no resting-body buzz, held-out spectral/envelope comparisons and documented listening tests; no uncalibrated absolute SPL claims |

For a homogeneous sphere on a horizontal dry plane, constant kinetic friction gives `v̇ = −μg` and spin-up magnitude `ω̇ = 5μg/(2R)` during forward sliding with zero initial spin. The slip-to-roll time is `troll = 2v0/(7μg)` in that restricted case. This is a useful analytic test, not the model for a real weighted bowling ball.

Monitor physical energy balance and numerical energy injection separately. In conservative tests require a predeclared relative drift tolerance over the experiment duration; in dissipative tests compare energy loss to modeled work. Full-rack chaotic divergence calls for converged distributions and local contact validation, not forced matching of trajectories far after impact.

## 12. Build sequence, deliverables, and review checkpoints

| Phase | Work | Deliverable / exit criterion |
|---|---|---|
| 0 — Initial review | Agree scope, ambiguity, scientific claims, source catalog, data gaps, first specimens and lane | User authorized research and small benchmarks; specimen access and PBC remain unresolved |
| 1 — Data and methods | Acquire original sheets, recipe archives, test procedures; define parameter/source schemas; design measurement campaign | Seed equipment/conditioner data, three extracted recipes, schemas and measurement protocol now available; empirical acquisition pending |
| 2 — Numerical/engine feasibility | Isolated rigid-body and contact benchmarks; evaluate custom traction, telemetry, precision, CCD, and snapshots | Initial Rapier experiments recorded: seven groups pass, CCD stress sweep fails; custom contact binding remains a decision gate |
| 3 — Ball–lane laboratory | Loft/landing, inertia, spin, calibrated fresh-oil trajectories, coordinate controls | V0–V3 evidence for the chosen material combinations |
| 4 — Pin laboratory | Measured pins, isolated impacts, rack contacts, boundaries and energy/contact audit | V4, then full-rack V5; retain uncertainty flags |
| 5 — Browser research viewer | Setup controls, free camera, object picking, graphs, force overlays, timeline/reverse and exports | V6–V7; useful even while experimental datasets expand |
| 6 — Oil history | Conservative oil/ball-surface transfer; successive-shot experiments | Pre/post oil and trajectory validation across a shot sequence |
| 7 — Acoustics | Calibrated sample/modal pipeline, event scheduling, listener/room model | V8 and clear fidelity labels |
| 8 — Release candidate | Cross-browser benchmarks, reproducibility audit, docs, integration at /bowl/ | Reviewed evidence package and scoped limitations before publication |

Phases overlap only where dependencies permit: capture design and source acquisition can proceed while engine feasibility is evaluated; polished graphics must not displace physics validation. Schedule and budget should be estimated after measurement access and the engine spike are established. The limiting resource is likely empirical characterization rather than rendering eleven moving objects.

### Proposed future project layout

```text
ohdeven/bowl/
  REQUIREMENTS.md                 this review document
  docs/                          model derivations, experiments, validation reports
  data/sources/                  provenance manifests and permitted source artifacts
  data/equipment/                balls, pins, lane definitions
  data/patterns/                  recipes and reconstructed/measured fields
  data/calibration/               observations and fitted models
  physics/                       solver adapter and Rust/WASM research modules
  app/                           setup, viewer, timeline, inspector, audio
  tests/                         analytic, numerical, browser and replay checks
```

The layout above remains the intended final structure. The current research subset also contains `README.md`, `research/`, seed JSON datasets and schemas, a pinned npm environment, and reports under `docs/`. An exploratory `app/` now exists with static bundles in `assets/`; a validated production `physics/` implementation does not.

## 13. Decisions to make during review

1. Confirm the intended “PBC” source and the first exact PBA/Kegel pattern editions.
2. Select the first physical ball specimens, pin product, lane installation, and access to measurement equipment/data.
3. Agree that practical calibrated rigid-body simulation is the first deliverable, with compliant/mixed-lubrication reference work supporting it.
4. Approve or revise the initial accuracy targets, hardware/browser baseline, and scope of the first oil-transition experiments.
5. Decide how much drilling detail, historical equipment, and absolute acoustic calibration belongs in the first validated release.

**Current recommendation:** continue contact-law and collision feasibility work and obtain measured data before choosing final friction coefficients, promising pinfall accuracy, or promoting the exploratory interface as a validated simulator. The first visual prototype is now authorized and implemented; measured calibration remains unavailable.