# gravity-wells — well field, acceleration, integrators

## Lesson
Inverse-square attraction to authored wells with a softening floor,
plus the field guards (speed cap, shell, damping, focus boost) — and
the discipline of carrying a measured source defect faithfully:
the source stepper advances position by `v * 3.1 * dt` (POSITION_GAIN)
while its velocity channel is exact. The module keeps `stepSource`
faithful, documents the defect in a named constant, and ships
`rk4Step` (gain 1.0) as the contrast so a consumer chooses knowingly.

## Provenance
Carried copy (2026-11-07) of `~/workspace/materials/solo/gravity-wells.cjs`.
Source: N8toriousAi's authored engine in
`~/workspace/user/files/gravity-wells_27_1tq7.html` (wells L183-188,
acceleration L427-438, integrator L439-454, GLSL pull L226), extracted
2026-11-06. Original untouched; `program.cjs` is verbatim + header.
`check.cjs` preserves the source check's assertions verbatim (module
path only) and counts its lines via a child-process run.

## How to run
```
node check.cjs     # PASS <n> FAIL <m>
node example.cjs   # stepper-gain measurement + 600-step integrations
const G = require('./program.cjs');
```

## Worked example
`example.cjs` measures the zero-field position gain of both steppers
(source 3.1 vs RK4 1.0 on every axis), reports `accelerationAt` in the
shipped 4-well field, then integrates the same node 600 steps under
each stepper and prints both end states.

## Numbers reproduced
- Source check suite: **PASS 20 FAIL 0** (`ALL CHECKS PASSED`).
- Well table: 4 wells, masses 8.0 / 6.4 / 7.2 / 5.8, sum 27.4.
- Zero-field gains measured in the example: source [3.1, 3.1, 3.1],
  RK4 [1, 1, 1]; damping-rate conversion −ln(.918)·60 ≈ 5.134.
- 600-step integration (node at [6,0,0], v=[0,0,1.1]): source ends
  pos [4.7217, 0.3976, 3.1699] speed 0.0245; RK4 ends
  pos [5.3807, −0.0298, 0.2726] speed 0.054 — divergence is the
  documented gain, not drift.

## Consumers
Gravity-well ontology / context-field work (Gravity Memory well: "mass,
buoyancy, decay, and cross-project routes produce a task-shaped
context"); any lane integrating nodes in the well field.

## Honest limits
- `stepSource` is ancestor-faithful, defect included. New physics
  should default to `rk4Step` via `simulate(field, n, dt, {stepper:'rk4'})`.
- GLSL/CPU softening constants differ by surface (SOFTENING_CPU vs
  SOFTENING_GLSL, as authored); `potentialGLSL()` returns the source
  pull() verbatim — do not harmonize them silently.
