driftlet 1.2.2 → 1.2.3

package/README.md

@@ -56,7 +56,7 @@ import { bandDiagram } from 'driftlet/plot';    // a level diagram as an SVG str
 ```
 
 Or straight from a CDN in a page, pinned to a version:
-`https://cdn.jsdelivr.net/npm/driftlet@1.2.2/src/index.js` (and `src/kit.js`, `src/plot.js`).
+`https://cdn.jsdelivr.net/npm/driftlet@1.2.3/src/index.js` (and `src/kit.js`, `src/plot.js`).
 TypeScript declarations ship in the package. Writing a demo with an LLM agent? Point it at
 [`llms.txt`](llms.txt).
 

package/docs/device.md

@@ -110,6 +110,11 @@ regions: [
   reactions) does: its `c0` fixes the amount it conserves. Concentrations are positive ($`\bar\mu`$ is
   logarithmic in them); to have none of a species in a region, leave it out of that region's
   material. In a strictly neutral region, $`\sum z \cdot c_0`$ must be zero.
+  Where two strictly neutral regions meet at a face that holds ions in equilibrium and their
+  `c0` leaves it out of equilibrium (a different fixed charge or immobile ion on each side), the
+  two nodes at the face start in it, as the face reaches it at $`t = 0^+`$: the ions it passes
+  shared between them so their $`\bar\mu`$ is equal across it and each side neutral, each
+  one's amount over the two nodes kept, everything else as `c0` has it.
   An entry can instead be a profile, `{ x: [...], values: [...] }`, against the device's x (m, not
   the region's own), piecewise linear between its points and constant beyond its ends, so a
   transient can start from a state it didn't simulate reaching: a packet already injected, a

package/docs/internals.md

@@ -83,4 +83,11 @@ The rest of `src/solver.js` is to be split along these lines, each piece with it
 A review of one module reads its contract, its code and its tests, and nothing else unless the
 contract points there. Each claim cites `file:line` with the line quoted, so it can be checked
 mechanically, and a finding comes with the device or script that shows it. A claim about code
-not in view is a question, not a finding.
+not in view is a question, not a finding. Two instruments check a change to the core beyond the tests'
+answers: `test/jacobian.test.js` (every row's derivatives against finite differences of its
+residual) and, for a move or refactor meant to change nothing, `tools/fingerprint.js`: a hash of
+the solver's state after every solve in the suite (on a fixed clock, so runs stopped by a time
+budget repeat), recorded before and after and compared. `tools/check-hook.js`, loaded into any run (`node --import
+./tools/check-hook.js …`: the tests, the law sweep, a fuzzer), checks the laws' cheap invariants
+as the solver goes: no row taken twice, none inactive, no stray ∂/∂V in a law's row, findLaws'
+structure unwritten.

package/docs/reliability.md

@@ -171,9 +171,47 @@ and in a time step's reading of its current), none of them in the sweep's device
 `test/laws.test.js`. On the code before those fixes the second family has 14 devices that
 disagree (a port's voltage at 0 for −1.42 V, θ 0.05 for 0.015, a contact 24 mV off); after, none,
 26 agree and 34 transients fail (see the roadmap). The first family's laws come out unchanged by
-the fixes, device by device, so its results above stand. On 1.2.2 the whole sweep, 870 devices, gives the
-same: 605 agree, 117 transients fail, and 13 differ, each a capacitive contact beside a membrane
-capacitor where the transient loses K⁺.
+the fixes, device by device, so its results above stand. On 1.2.2 the whole sweep, 870 devices,
+gives the same: 605 agree, 117 transients fail, and 13 differ, each a capacitive contact beside a
+membrane capacitor where the transient loses K⁺. Since a face out of equilibrium in `c0` starts
+in it (1.2.3), 607 agree and 115 fail, the same 13 differing.
+
+## Consistent: the derivatives
+
+A Jacobian entry that's wrong still converges to the right answer, its residual being right, so
+no test of answers sees it: it shows only as Newton taking longer, or failing on a harder device.
+`test/jacobian.test.js` compares the whole Newton system, column by column, with central
+differences of its own residual, on ten devices that between them write every law's row (flat
+stretches, affinities, amounts kept in balance rows and in circuit rows with an electrode's or a
+contact's charge, node-by-node laws with a surface, metals' charges), crowded statistics, face
+and port reactions and floating terminals. It checks inside a real `solve()` and a real
+`advance()`, at their second assembly, each in the unknowns Newton solves for there (a time step's
+charge rows included). It came from a cold review of `src/lawRows.js`, which found a node-by-node
+law's row keeping a port reaction's ∂/∂V (an extra Newton iteration, the answer the same); broken
+once each way (that entry back, a storage term 0.1% off in either time-step path), it fails.
+
+## Measured: how much the tests see
+
+A mutation run makes one small slip at a time in a module (an operator flipped, a comparison
+loosened, a statement dropped, a 0 for a 1), runs the tests on it, and counts the slips no test
+fails. On 18 Oct 2026, 120 of them, sampled from `src/laws.js` and `src/lawRows.js`'s 1420: 69
+failed a test, and 51 got through. Each of the 51 was then looked at:
+- In `src/laws.js` (29): 20 change no law on any of the law sweep's 735 devices, 2 only a
+  workspace's size, and 6 change laws on 12 to 635 of them while every answer stays right (the
+  islands', which Newton seldom needs; a λ read only by long steps). One changed the answers: it
+  held a capacitive contact's charge in the wrong law, and 85 of the sweep's devices came out
+  wrong, with all 470 tests passing. Its device is now in `test/laws.test.js`.
+- In `src/lawRows.js` (22): the Jacobian test had never seen islands' rows, a long step that
+  reads a law by its change, or a law with a surface or a capacitive electrode in a time step.
+  With them in (a charged pore, three of the sweep's devices), 6 more fail. Of the 16 left, 6
+  change nothing (a bound the loop never reaches), 1 only a heuristic's estimate, 2 the pivoting
+  of the small dense solve (robustness only), and 7 are narrow paths no device here takes: two
+  floating electrodes whose law counts the other's charge, an equilibrium face inside a flat
+  stretch, a contact's law read by its change.
+
+A slip that gives the right answer by another route isn't a gap; what the run found that was,
+was one wrong answer the sweep sees and the suite didn't, and a test that had never looked at
+two of the paths it claimed.
 
 ## Hard cases
 

package/llms.txt

@@ -30,9 +30,9 @@ materials, insertion hosts), data.md and reliability.md (what's validated, and t
 From a CDN, pin the version you tested against:
 
 ```js nocheck
-import { Device, units } from 'https://cdn.jsdelivr.net/npm/driftlet@1.2.2/src/index.js';
-import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@1.2.2/src/kit.js';
-import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@1.2.2/src/plot.js';
+import { Device, units } from 'https://cdn.jsdelivr.net/npm/driftlet@1.2.3/src/index.js';
+import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@1.2.3/src/kit.js';
+import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@1.2.3/src/plot.js';
 ```
 
 From npm: `driftlet`, `driftlet/kit`, `driftlet/plot`. Every export is listed at the end.
@@ -219,9 +219,9 @@ a CDN needs a long virtual-time budget, 30 s.)
 <span id="readout"></span>
 <div id="figure"></div>
 <script type="module">
-import { units } from 'https://cdn.jsdelivr.net/npm/driftlet@1.2.2/src/index.js';
-import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@1.2.2/src/kit.js';
-import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@1.2.2/src/plot.js';
+import { units } from 'https://cdn.jsdelivr.net/npm/driftlet@1.2.3/src/index.js';
+import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@1.2.3/src/kit.js';
+import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@1.2.3/src/plot.js';
 
 const def = build({
   T: 300,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "driftlet",
-  "version": "1.2.2",
+  "version": "1.2.3",
   "description": "Dependency-free 1D drift–diffusion–reaction (Poisson–Nernst–Planck) solver for semiconductors, electrochemistry and nerves, fast enough for live web demos",
   "type": "module",
   "exports": {
@@ -34,6 +34,7 @@
     "smoke": "node tools/smoke.js",
     "shots": "node tools/shots.js",
     "lawsweep": "node tools/lawsweep.js",
+    "fingerprint": "node tools/fingerprint.js",
     "prepublishOnly": "npm test && npm run types",
     "types": "rm -rf types && npx -y -p typescript@5 tsc --allowJs --declaration --emitDeclarationOnly --target es2022 --module nodenext --moduleResolution nodenext --outDir types src/index.js src/kit.js src/plot.js"
   },

package/src/lawRows.js

@@ -349,6 +349,8 @@ function lawAmount(s, cs) {
       cs.w[len++] = -f * cap * s.VT;
     });
   }
+  // (A typed array drops writes past its end without a word: the law's derivative would lose them.)
+  if (len > cs.idx.length) throw new Error(`internal: a law's derivative needs ${len} entries, its workspace holds ${cs.idx.length}`);
   cs.len = len;
   return { amount, reference, dV, gross }; // (dV by terminal)
 }

package/src/solver.js

@@ -1152,6 +1152,53 @@ export class Solver {
         }
       }
     }
+    // Two strictly neutral regions meeting at a face whose links hold ions in equilibrium: where
+    // c0 leaves the two sides out of it (a different fixed charge or immobile ion on each, so
+    // c₊c₋ differs across it), the face reaches it at t = 0⁺, before anything diffuses, and a
+    // first step made to take that jump met an exactly singular pivot. Start there: the ions the
+    // face passes shared between its two nodes in equilibrium (μ̄ equal across it), each one's
+    // amount over the two nodes kept, everything else as c0 has it. The one unknown is the jump
+    // in φ̂ across it (a Donnan potential), set by neutrality on one side; the other's follows,
+    // the two nodes' charge summing to what it was, zero.
+    for (let f = 0; f < interfaces.length; f++) {
+      const itf = interfaces[f], mL = materials[regions[f].material], mR = materials[regions[f + 1].material];
+      const strict = (m) => m.epsr === 0 && !m.conductor && !m.phiFree && m.ideal;
+      if (itf.phi.type !== 'neutral' || !strict(mL) || !strict(mR)) continue;
+      const gL = grid.regionEnd[f], gR = grid.regionStart[f + 1], bL = this.blockOfNode[gL] * M, bR = this.blockOfNode[gR] * M;
+      const pass = [];
+      for (let i = 0; i < n; i++) if (itf.links[i].type === 'equilibrium' && mL.present[i] && mR.present[i]) pass.push(i);
+      if (!pass.some((i) => z[i] !== 0)) continue;
+      const RT = model.RT, vL = grid.vol[gL], vR = grid.vol[gR];
+      const conc = (m, b, i) => m.cRef[i] * Math.exp(u[b + 1 + i] - m.mu0[i] / RT - z[i] * u[b]);
+      const amount = pass.map((i) => vL * conc(mL, bL, i) + vR * conc(mR, bR, i));
+      let qOther = regions[f].fixedCharge / FARADAY; // (the left node's charge from all it doesn't share)
+      for (let i = 0; i < n; i++) if (mL.present[i] && !pass.includes(i) && z[i] !== 0) qOther += z[i] * conc(mL, bL, i);
+      // At a jump D = φ̂_R − φ̂_L: c_L/c_R = (cRef_L/cRef_R)·exp((μ°_R − μ°_L)/RT + z D), the amount fixing both.
+      const split = (D) =>
+        pass.map((i, j) => {
+          const K = (mL.cRef[i] / mR.cRef[i]) * Math.exp((mR.mu0[i] - mL.mu0[i]) / RT + z[i] * D), cR = amount[j] / (vL * K + vR);
+          return [K * cR, cR];
+        });
+      const qL = (D) => split(D).reduce((q, [cL], j) => q + z[pass[j]] * cL, qOther); // (increasing in D)
+      const D0 = u[bR] - u[bL];
+      let lo = D0 - 1, hi = D0 + 1;
+      while (qL(lo) > 0 && lo > D0 - 1e3) lo -= 2 * (hi - lo);
+      while (qL(hi) < 0 && hi < D0 + 1e3) hi += 2 * (hi - lo);
+      if (!(qL(lo) <= 0 && qL(hi) >= 0)) continue; // (nothing the face shares can balance it: leave c0)
+      for (let it = 0; it < 200 && hi - lo > 1e-13 * Math.max(1, Math.abs(D0)); it++) {
+        const m = 0.5 * (lo + hi);
+        if (qL(m) < 0) lo = m;
+        else hi = m;
+      }
+      const D = 0.5 * (lo + hi), cs = split(D);
+      const keep = Float64Array.from({ length: n }, (_, i) => (mR.present[i] ? conc(mR, bR, i) : 0)); // (the right node's, before φ̂ moves)
+      u[bR] = u[bL] + D;
+      for (let i = 0; i < n; i++) if (mR.present[i] && !pass.includes(i)) u[bR + 1 + i] = Math.log(keep[i] / mR.cRef[i]) + mR.mu0[i] / RT + z[i] * u[bR];
+      pass.forEach((i, j) => {
+        u[bL + 1 + i] = Math.log(cs[j][0] / mL.cRef[i]) + mL.mu0[i] / RT + z[i] * u[bL];
+        u[bR + 1 + i] = Math.log(cs[j][1] / mR.cRef[i]) + mR.mu0[i] / RT + z[i] * u[bR];
+      });
+    }
     // An insertion host's φ is a gauge: c0 sets only its neutral combination's level, not how that
     // splits between its ion and its electrons. Start its ion level with the same ion's beside it
     // across a face (the equilibrium a link or a transfer reaction heads for), so its electrons,