@vessel-dsp/compiler 0.5.0 → 0.7.0

package/dist/device-laws.js

@@ -19,7 +19,8 @@ import { checkDeclaredProgram } from "./declared-program.js";
 import { bjtPartRegisteredAsSections, identify, mayCarryRegistrySections, opampPartRegisteredAsOtherLaw, requiresIdentification, } from "./identify.js";
 import { isMultiDeviceTransistorShell } from "./unreadable-terminal-role.js";
 import { deriveBbdDelayFromNetlist, resolveClockModulationSource, deriveOpenOx2ClockLaw, derivePt2399DelayFromNetlist, deriveM50195DelayFromNetlist, OPEN_OX2_VDD_VOLTS, OPEN_OX2_VTH_VOLTS, OPEN_OX2_VF_VOLTS, OPEN_OX2_FLOOR_VOLTS, } from "./bbd-clock.js";
-import { foldPartId, foldToken, pinoutMatches, registryEntryFor, registryLawFor, registryModelFor, registryOpampGainBandwidth, registryOpampSwingDrop, terminalWithRole, withRecordedReads, } from "./registry.js";
+import { foldPartId, foldToken, pinoutMatches, registryEntryFor, registryLawFor, registryModelFor, registryOpampGainBandwidth, registryOpampSwing, opampOutputSwingOf, terminalWithRole, withRecordedReads, } from "./registry.js";
+import { GROUND } from "./types.js";
 /** Room-temperature thermal voltage; the diode law needs a reference somewhere. */
 export const THERMAL_VOLTAGE = 0.025_852;
 /**
@@ -333,17 +334,33 @@ function opampRails(device, rails, nodeToVoltage) {
     return { high, low };
 }
 /**
- * The rails an op-amp's output can reach: each supply rail pulled in by the part's stated drop.
- * An unstated drop, an unknown rail, or a drop that would close the pair leaves the rails as they
- * are, so a part with no entry renders bit-for-bit as before.
+ * The rails an op-amp's output can reach: each supply rail pulled in by the part's printed drop for
+ * that side, carried to this op-amp's own supply by the row's stated `translation`.
+ *
+ * `"constant"` applies the printed drops as printed. `"proportional"` multiplies both by the
+ * op-amp's supply span (`high - low`, so 9 for a 9 V single supply and 18 for a +-9 V pair) over the
+ * span the row was printed at. An unstated swing, an unknown rail, a span that is not positive, or a
+ * pair that would close the output interval (`high - dropHigh <= low + dropLow`) leaves the rails as
+ * they are, so a part with no entry renders bit-for-bit as before. `carried` is set only when the rails
+ * moved; `opamp-law-default-parameters` reads it to tell a pair used at its printed supply from one
+ * carried across a supply.
  */
-function railsAfterSwingDrop(rails, dropVolts) {
-    if (dropVolts === null || dropVolts <= 0 || rails.high === null || rails.low === null) {
-        return rails;
+function railsAfterSwing(rails, swing) {
+    if (swing === null || rails.high === null || rails.low === null) {
+        return { rails, carried: null };
     }
-    const high = rails.high - dropVolts;
-    const low = rails.low + dropVolts;
-    return high > low ? { high, low } : rails;
+    const span = rails.high - rails.low;
+    if (!(span > 0)) {
+        return { rails, carried: null };
+    }
+    const scale = swing.printed.translation === "proportional" ? span / swing.printed.supplyVolts : 1;
+    const highVolts = swing.highVolts * scale;
+    const lowVolts = swing.lowVolts * scale;
+    const high = rails.high - highVolts;
+    const low = rails.low + lowVolts;
+    return high > low
+        ? { rails: { high, low }, carried: { highVolts, lowVolts, circuitSupplyVolts: span } }
+        : { rails, carried: null };
 }
 /**
  * The one high-side and one low-side supply pin a device declares, read by the same role tokens
@@ -436,39 +453,32 @@ function quiescentSupplyDraw(device, registry, expanded, rails, nodeToVoltage) {
         { outcome: "law", device: id, law: { kind: "conductance", siemens: amps / span } },
     ];
 }
-/**
- * Nodes that reach a declared voltage through one two-terminal passive
- * (diode, capacitor, resistor, inductor). Covers the LT1054 → D17 → VA-rail
- * path where the charge pump's output is a diode away from the declared rail.
- */
-function buildOneHopVoltageMap(netlist, nodeToVoltage) {
-    const map = new Map();
+export function attachDeviceLaws(netlist, registry) {
+    const regulatedBase = registrySuppliedVoltages(netlist, registry);
+    const nodeToVoltage = buildNodeToVoltageMap(netlist, regulatedBase);
+    const devicesTouchingNode = deviceCountByNode(netlist);
+    // A pump's rail is derived from the declared input, so every derivation runs against
+    // the document's own voltages -- before any pump output joins the map -- and the
+    // derived supplies merge into the rail set after. A pump can never back itself.
+    const pumpDerivations = new Map();
     for (const device of netlist.devices) {
-        if (device.nodes.length !== 2 ||
-            (device.kind !== "diode" &&
-                device.kind !== "capacitor" &&
-                device.kind !== "resistor" &&
-                device.kind !== "inductor")) {
-            continue;
+        const derivation = pumpDerivation(device, registry, nodeToVoltage, devicesTouchingNode);
+        if (derivation !== null) {
+            pumpDerivations.set(device.id, derivation);
         }
-        const [a, b] = device.nodes;
-        const va = nodeToVoltage.get(a);
-        const vb = nodeToVoltage.get(b);
-        if (va !== undefined && b !== 0 && vb === undefined) {
-            map.set(b, va);
+    }
+    const regulated = [...regulatedBase];
+    for (const derivation of pumpDerivations.values()) {
+        if (derivation.kind !== "model") {
+            continue;
         }
-        else if (vb !== undefined && a !== 0 && va === undefined) {
-            map.set(a, vb);
+        regulated.push({ node: derivation.outputNode, volts: derivation.volts });
+        if (!nodeToVoltage.has(derivation.outputNode)) {
+            nodeToVoltage.set(derivation.outputNode, derivation.volts);
         }
     }
-    return map;
-}
-export function attachDeviceLaws(netlist, registry) {
-    const regulated = registrySuppliedVoltages(netlist, registry);
     const rails = supplyRails(netlist, regulated);
     const supply = supplyNodes(netlist);
-    const nodeToVoltage = buildNodeToVoltageMap(netlist, regulated);
-    const oneHopVoltage = buildOneHopVoltageMap(netlist, nodeToVoltage);
     const mainsFrequencyHz = mainsFrequency(netlist);
     // Stage 1 (`netlist.ts`) already resolved each control's real taper -- from the panel
     // control's own declaration, or failing that, from the first device bound to it -- onto
@@ -481,7 +491,6 @@ export function attachDeviceLaws(netlist, registry) {
     // is multi-section. Expanding into ordinary devices means partitioning, lowering and the runtime
     // see nothing new -- the alternative, a fourth `DeviceResolution` outcome, would have to be
     // understood by every consumer of one.
-    const devicesTouchingNode = deviceCountByNode(netlist);
     // Nodes inside a registered package, numbered past every node the document uses.
     const internalNodes = new Map();
     const firstInternal = Math.max(0, ...netlist.nodes) + 1;
@@ -497,7 +506,7 @@ export function attachDeviceLaws(netlist, registry) {
     const devices = [];
     const resolutions = [];
     for (const device of netlist.devices) {
-        const expanded = sectionDevices(device, registry, rails, supply, nodeToVoltage, internalNode, netlist);
+        const expanded = sectionDevices(device, registry, rails, supply, nodeToVoltage, internalNode, netlist, pumpDerivations.get(device.id) ?? null);
         const draw = quiescentSupplyDraw(device, registry, expanded !== null, rails, nodeToVoltage);
         if (draw !== null) {
             devices.push(draw[0]);
@@ -505,7 +514,7 @@ export function attachDeviceLaws(netlist, registry) {
         }
         if (expanded === null) {
             devices.push(device);
-            resolutions.push(resolveDevice(device, registry, rails, supply, taperByControl, mainsFrequencyHz, devicesTouchingNode, nodeToVoltage, oneHopVoltage, netlist));
+            resolutions.push(resolveDevice(device, registry, rails, supply, taperByControl, mainsFrequencyHz, devicesTouchingNode, nodeToVoltage, netlist));
             continue;
         }
         for (const [section, resolution] of expanded) {
@@ -550,6 +559,12 @@ export function declaredRegulatorTerminals(device, model) {
     // kinds whose vocabulary carries them (`regulator`, `power-converter`, `voltage-source`,
     // `rail`, `battery`), and an `ic` may declare nothing but `pin`. A device that reaches here
     // carrying a supply electrode was therefore declared as a kind entitled to state one.
+    // Charge-pump parts never take this path: their volts are derived per circuit from the
+    // input node, and the placeholder volts in their entries must not be stamped. They are
+    // bound by `pumpDerivation` instead, which runs before this is consulted.
+    if (isChargePumpPart(device)) {
+        return null;
+    }
     if (model.sections.length !== 1) {
         return null;
     }
@@ -604,7 +619,16 @@ export function declaredRegulatorTerminals(device, model) {
 }
 function sectionDevices(device, registry, rails, supply, nodeToVoltage, internalNode = () => {
     throw new Error("no internal-node allocator");
-}, netlist) {
+}, netlist, pump = null) {
+    // A decided pump never reaches generic expansion: the placeholder volts in the pump
+    // entries must not be stamped. An isolated pump defers to `resolveDevice`, which
+    // names the isolation before any pump question.
+    if (pump !== null) {
+        if (pump.kind === "isolated") {
+            return null;
+        }
+        return pumpSectionDevices(device, pump);
+    }
     // **`mayCarryRegistrySections`, not `requiresIdentification`.** An OTA reaches here so a
     // registered multi-section part (the BA662A's OTA plus its Darlington buffer) can be expanded;
     // when the registry has no matching entry this returns null and the caller falls through to
@@ -631,6 +655,25 @@ function sectionDevices(device, registry, rails, supply, nodeToVoltage, internal
     if (model.kind !== "sections" && model.kind !== "sections-core") {
         return null;
     }
+    // An explicit override cannot target one section of a package the registry expands: the
+    // section laws are the entry's numbers (a dual op-amp's two amplifiers share one part's
+    // figures), and `device.parameters` -- legacy or override -- never reach them. Accepting
+    // the block would be a silent drop, so it refuses by name instead. The way out is a
+    // source-declared `devices:` split, whose devices take the device-class law that the
+    // override does feed.
+    if (device.deviceOverride !== undefined) {
+        return [
+            [
+                device,
+                {
+                    outcome: "unsupported",
+                    device: device.id,
+                    reason: `part ${identity.partId} is expanded from a registry sections entry, whose numbers the override cannot replace: ` +
+                        `declare the package's devices explicitly (a "devices:" split) to take the device-class law an override feeds, or remove the DeviceOverride block`,
+                },
+            ],
+        ];
+    }
     // A `sections` entry's `terminals` index into the entry's canonical pin order, not the
     // declaration order the document happened to use. When the entry names its pins by role and
     // that naming is a clean bijection onto the device's declared terminals, resolve each
@@ -740,10 +783,12 @@ function sectionDevices(device, registry, rails, supply, nodeToVoltage, internal
         }
         // Read from the section's *parent* device, which is where the package's supply pins
         // are declared -- a section's own terminal list is only its three signal pins.
-        const sectionDrop = section.law.kind === "ideal-opamp" ? (section.law.outputSwingDropVolts ?? null) : null;
-        const sectionRails = railsAfterSwingDrop(opampRails(device, rails, nodeToVoltage), sectionDrop);
-        const railHigh = sectionRails.high;
-        const railLow = sectionRails.low;
+        const sectionSwing = section.law.kind === "ideal-opamp"
+            ? opampOutputSwingOf(section.law, identity.partId)
+            : null;
+        const sectionSwung = railsAfterSwing(opampRails(device, rails, nodeToVoltage), sectionSwing);
+        const railHigh = sectionSwung.rails.high;
+        const railLow = sectionSwung.rails.low;
         // An op-amp's rails come from the op-amp's own supply terminals or the circuit's supply set,
         // not from the registry -- the same substitution a declared `opamp` gets. A registry cannot know them:
         // it describes a part, and the rails are a property of the pedal the part is fitted to.
@@ -760,8 +805,16 @@ function sectionDevices(device, registry, rails, supply, nodeToVoltage, internal
                 // The registry states the part's gain; only the rails are the pedal's.
                 openLoopGain: section.law.openLoopGain,
                 // Kept on the lowered law so `findOpampLawDefaults` can tell a part that
-                // states how close it gets to the rails from one that does not.
-                ...(sectionDrop === null ? {} : { outputSwingDropVolts: sectionDrop }),
+                // states how close it gets to the rails from one that does not, and a pair
+                // used at its printed supply from one the lowering carried across a supply.
+                ...(sectionSwing === null
+                    ? {}
+                    : {
+                        outputSwingDropHighVolts: sectionSwing.highVolts,
+                        outputSwingDropLowVolts: sectionSwing.lowVolts,
+                        outputSwingPrinted: sectionSwing.printed,
+                    }),
+                ...(sectionSwung.carried === null ? {} : { outputSwingCarried: sectionSwung.carried }),
                 // The part's datasheet product, when the entry states one. Absent stays
                 // absent: it lowers to a `null` stamp, which the compile names.
                 ...(section.law.gainBandwidthHz === undefined
@@ -847,6 +900,34 @@ function barePinPosition(macro, roles, port) {
     }
     return position;
 }
+/**
+ * The terminal the audio leaves a chained two-section part at, or `null` when the part is not
+ * chained in this document.
+ *
+ * Chained means one thing: the first section's output and the second section's input are the same
+ * non-ground node, which is connectivity, not a name. All three terminals must resolve to exactly
+ * one role each, so a document that names the sections differently, or ties the second section's
+ * input to ground (the Deluxe Memory Man uses only section A), falls through to the single-section
+ * port unchanged.
+ */
+function cascadedAudioOut(device, macro, sectionAudioOut) {
+    const cascade = macro.ports.cascade;
+    if (cascade === undefined || sectionAudioOut === null) {
+        return null;
+    }
+    const roles = device.identity.terminalRoles;
+    const sectionOut = terminalWithRole(roles, cascade.sectionOut);
+    const nextIn = terminalWithRole(roles, cascade.nextIn);
+    const finalOut = terminalWithRole(roles, cascade.finalOut);
+    if (sectionOut === null || nextIn === null || finalOut === null || sectionOut !== sectionAudioOut) {
+        return null;
+    }
+    const joint = device.nodes[sectionOut];
+    if (joint === undefined || joint === GROUND || device.nodes[nextIn] !== joint) {
+        return null;
+    }
+    return finalOut;
+}
 /**
  * Thin wrapper that brackets the real resolution so every registry entry consulted while computing
  * this macro's parameters is recorded against the macro's device id. **No behaviour change** -- the
@@ -864,8 +945,9 @@ registry, netlist) {
     const roles = device.identity.terminalRoles;
     const audioIn = terminalWithRole(roles, macro.ports.audioIn) ??
         barePinPosition(macro, roles, "audioIn");
-    const audioOut = terminalWithRole(roles, macro.ports.audioOut) ??
+    const sectionAudioOut = terminalWithRole(roles, macro.ports.audioOut) ??
         barePinPosition(macro, roles, "audioOut");
+    const audioOut = cascadedAudioOut(device, macro, sectionAudioOut) ?? sectionAudioOut;
     // A second output, only for a part that declares one and a device that names it. Absent is
     // the ordinary case and stays a one-output macro: unlike the ports above, failing to find
     // this is not a refusal, because most parts genuinely have one output.
@@ -1309,6 +1391,12 @@ function registrySuppliedVoltages(netlist, registry) {
         if (device.parameters.volts !== undefined) {
             continue;
         }
+        // Pump parts never supply a static rail: their output is derived per circuit from
+        // the input node by `pumpDerivation`, and the placeholder volts in their entries
+        // must not leak into the rail set through a role that happens to read as an output.
+        if (isChargePumpPart(device)) {
+            continue;
+        }
         const identity = identify(device, registry);
         if (identity === null) {
             continue;
@@ -1421,29 +1509,375 @@ export function deviceCountByNode(netlist) {
     }
     return counts;
 }
+/**
+ * Charge-pump inverter parts, by folded part number: every spelling the DIY BOM census
+ * attributes to the family (TC1044S/SCPA, LT1054/CP, 7660 // SCPAZ, TC7662BC, ICL7660SCPA(Z),
+ * LTC1144, MAX1044/S) plus the order codes and package markings the datasheets print.
+ * Compared whole with `foldPartId`, never by substring: membership routes a part to the
+ * pump handling, it does not model it -- modelling needs a registry entry, and a member
+ * with no entry falls through to the honest unknown-chip path.
+ */
 const CHARGE_PUMP_PARTS = new Set([
-    "tc1044",
+    "tc1044s",
     "tc1044scpa",
-    "max1044",
+    "tc1044scoa",
+    "tc1044sepa",
+    "tc1044seoa",
+    "tc1044sija",
+    "tc1044smja",
+    "icl7660",
+    "icl7660cpa",
+    "icl7660cpaz",
+    "icl7660cba",
+    "icl7660cbaz",
+    "7660cpa",
+    "7660cpaz",
+    "7660cba",
+    "7660cbaz",
+    "icl7660a",
+    "icl7660acpa",
+    "icl7660acpaz",
+    "icl7660acba",
+    "icl7660acbaz",
+    "icl7660aiba",
+    "icl7660aibaz",
+    "7660acpa",
+    "7660acpaz",
+    "7660acba",
+    "7660acbaz",
+    "7660aiba",
+    "7660aibaz",
+    "icl7660s",
+    "icl7660scpa",
+    "icl7660scpaz",
+    "7660scpa",
+    "7660scpaz",
+    "tc7662b",
+    "tc7662bcpa",
+    "tc7662bepa",
+    "tc7662bcoa",
+    "tc7662beoa",
     "7662",
-    "lt1054cp",
     "lt1054",
+    "lt1054c",
+    "lt1054cp",
+    "lt1054cpe4",
+    "lt1054i",
+    "ltc1144",
+    "ltc1144cn8",
+    "ltc1144in8",
+    "ltc1144cs8",
+    "ltc1144is8",
+    "max1044",
+    "max1044cpa",
+    "max1044csa",
+    "max1044epa",
+    "max1044esa",
+    // Census spellings with no registry entry: routed here so a pump whose rail the
+    // document declares still opens honestly, and one whose rail is undeclared refuses
+    // as an unknown chip instead of claiming a modelled rail.
+    "tc7662bc",
+    "max1044s",
+    "7660",
 ]);
+/** Whether this device names a charge-pump inverter part, compared whole. */
+function isChargePumpPart(device) {
+    const partNumber = device.identity.partNumber;
+    if (partNumber === null) {
+        return false;
+    }
+    return CHARGE_PUMP_PARTS.has(foldPartId(partNumber));
+}
+/**
+ * The closed role vocabularies a pump's three supply terminals are bound by, compared as
+ * whole folded tokens by `terminalWithRole` -- never as substrings, never against a
+ * description. These query the ENTRY's role groups (which carry the datasheet pinout in
+ * package order), so a document naming its terminals in any order binds, and a document
+ * numbering its pins binds positionally instead.
+ */
+const PUMP_INPUT_ROLES = ["vplus", "vin", "vdd", "vcc", "input"];
+const PUMP_OUTPUT_ROLES = [
+    "negativeoutput",
+    "voutnegative",
+    "vout",
+    "voutput",
+    "out",
+    "output",
+];
+const PUMP_GROUND_ROLES = ["gnd", "ground"];
 /**
- * A charge-pump IC whose output node is already backed by a declared rail is a
+ * A charge-pump IC whose OUTPUT node is already backed by a declared rail is a
  * view-only structural anchor: the rail supplies the voltage, the IC adds nothing.
  * The Klon's MAX1044 is handled by `isElectricallyIsolated` (all nodes private);
  * this covers the wider class where the pump shares nets with the declared rail.
+ *
+ * Tests the pump's OUTPUT node, by role, and nothing else. The previous version asked
+ * whether ANY non-ground node of the pump touched a declared OR one-hop voltage, and a
+ * reservoir capacitor to ground was enough to satisfy it: with both Plumes rails deleted,
+ * nodes 35 and 36 each one-hop to 0 V through C102/C101, and the pump claimed a modelled
+ * rail on ground continuity alone. Ground is not a rail, and an input rail is not the
+ * output rail -- pigtronix's LT1054 sat on the same false positive through its input
+ * capacitor, and moogerfooger's 7662 through its output capacitor.
  */
-function isChargePumpWithDeclaredRail(device, nodeToVoltage, oneHopVoltage) {
-    const partNumber = device.identity.partNumber;
-    if (partNumber === null) {
+function isChargePumpWithDeclaredRail(device, nodeToVoltage) {
+    if (!isChargePumpPart(device)) {
         return false;
     }
-    if (!CHARGE_PUMP_PARTS.has(partNumber.toLowerCase())) {
+    const output = chargePumpOutputIndex(device);
+    if (output === null) {
         return false;
     }
-    return device.nodes.some((node) => node !== 0 && (nodeToVoltage.has(node) || oneHopVoltage.has(node)));
+    const node = device.nodes[output];
+    if (node === undefined || node === 0) {
+        return false;
+    }
+    return nodeToVoltage.has(node);
+}
+/**
+ * The index of the pump's inverted-output terminal, or `null` when the document does
+ * not settle it.
+ *
+ * A declared supply electrode decides first: a shell that states `ground` plus
+ * `negative` (or `positive`, the regulator convention deluxe-memory-man uses for its
+ * -15 V output) names its output outright. Otherwise the folded terminal names are read
+ * against the output vocabulary -- whole tokens, unambiguous or nothing.
+ */
+function chargePumpOutputIndex(device) {
+    const declared = device.identity.declaredTerminalRoles;
+    const onlyDeclared = (role) => {
+        const found = declared.flatMap((value, index) => value === role ? [index] : []);
+        return found.length === 1 ? found[0] : null;
+    };
+    const fromDeclaration = onlyDeclared("negative") ?? onlyDeclared("positive");
+    if (fromDeclaration !== null) {
+        return fromDeclaration;
+    }
+    return terminalWithRole(device.identity.terminalRoles, PUMP_OUTPUT_ROLES);
+}
+function pumpDerivation(device, registry, nodeToVoltage, devicesTouchingNode) {
+    if (!isChargePumpPart(device)) {
+        return null;
+    }
+    // Isolation stays the isolation reporter's beat: a pump on private nodes is view-only
+    // however it is part-numbered, and `resolveDevice` names it before any pump question.
+    if (isElectricallyIsolated(device, devicesTouchingNode)) {
+        return { kind: "isolated" };
+    }
+    const identity = identify(device, registry);
+    if (identity === null) {
+        return null;
+    }
+    const entry = registryEntryFor(registry, identity, device.nodes.length);
+    if (entry === null || entry.model.kind !== "sections") {
+        return null;
+    }
+    const section = entry.model.sections[0];
+    if (entry.model.sections.length !== 1 ||
+        section === undefined ||
+        section.law.kind !== "voltage-source" ||
+        section.terminals.length !== 2) {
+        return {
+            kind: "unbound",
+            detail: `part ${identity.partId} is routed to the charge-pump derivation but its registry ` +
+                `entry is not a single two-terminal voltage-source section, so no rail can be ` +
+                `derived from it`,
+        };
+    }
+    const sourceOhms = section.law.sourceOhms;
+    // Which package positions the supply input, inverted output, and reference sit at,
+    // read off the ENTRY's role groups -- the datasheet pinout in package order -- so one
+    // entry serves every declaration order that names its terminals at all.
+    const groups = entry.terminalRoleGroups;
+    const groupIndex = (vocab) => {
+        const wanted = new Set(vocab.map((alias) => foldToken(alias)));
+        const hits = [];
+        groups.forEach((group, index) => {
+            if (group.some((alias) => wanted.has(foldToken(alias)))) {
+                hits.push(index);
+            }
+        });
+        return hits.length === 1 ? hits[0] : null;
+    };
+    const inputPos = groupIndex(PUMP_INPUT_ROLES);
+    const outputPos = groupIndex(PUMP_OUTPUT_ROLES);
+    const groundPos = groupIndex(PUMP_GROUND_ROLES);
+    if (inputPos === null || outputPos === null || groundPos === null) {
+        return {
+            kind: "unbound",
+            detail: `part ${identity.partId} is registered as a charge pump but its entry does not ` +
+                `name a distinct supply input, inverted output, and ground reference`,
+        };
+    }
+    const roles = device.identity.terminalRoles;
+    const declared = device.identity.declaredTerminalRoles;
+    const onlyDeclared = (role) => {
+        const found = declared.flatMap((value, index) => value === role ? [index] : []);
+        return found.length === 1 ? found[0] : null;
+    };
+    // A declared supply electrode outranks the entry's pin numbering, the same rule the
+    // regulator path documents: the reference is `ground`, the inverted output is
+    // `negative` (or `positive`, the convention deluxe-memory-man's -15 V output uses),
+    // and the input is the one remaining terminal sitting on a declared nonzero voltage.
+    const declaredBinding = (() => {
+        const ground = onlyDeclared("ground");
+        const output = onlyDeclared("negative") ?? onlyDeclared("positive");
+        if (ground === null || output === null || ground === output) {
+            return null;
+        }
+        const candidates = roles
+            .map((_, index) => index)
+            .filter((index) => index !== ground && index !== output)
+            .filter((index) => {
+            const node = device.nodes[index];
+            if (node === undefined || node === 0) {
+                return false;
+            }
+            const volts = nodeToVoltage.get(node);
+            return volts !== undefined && volts !== 0;
+        });
+        if (candidates.length !== 1) {
+            return null;
+        }
+        return { input: candidates[0], output, ground };
+    })();
+    // Otherwise the folded terminal names, bound through the entry's own aliases so any
+    // declaration order lands on the right pins.
+    const roleBinding = (() => {
+        const input = terminalWithRole(roles, [...groups[inputPos]]);
+        const output = terminalWithRole(roles, [...groups[outputPos]]);
+        const ground = terminalWithRole(roles, [...groups[groundPos]]);
+        if (input === null || output === null || ground === null) {
+            return null;
+        }
+        if (new Set([input, output, ground]).size !== 3) {
+            return null;
+        }
+        return { input, output, ground };
+    })();
+    // Otherwise a bare-pin shell in package order: terminals numbered pin1..pinN fold to
+    // no role at all, so declaration order against the entry's package-order pinout is
+    // the only reading, exactly as the regulator entries already assume.
+    const positionalBinding = (() => {
+        if (!roles.every((role) => role === null)) {
+            return null;
+        }
+        if (entry.model.kind !== "sections" ||
+            entry.model.pinout.length !== roles.length) {
+            return null;
+        }
+        return { input: inputPos, output: outputPos, ground: groundPos };
+    })();
+    const binding = declaredBinding ?? roleBinding ?? positionalBinding;
+    if (binding === null) {
+        return {
+            kind: "unbound",
+            detail: `part ${identity.partId} is registered as a charge pump, but neither its terminal ` +
+                `names, its declared supply electrodes, nor its pin order bind a supply input, ` +
+                `inverted output, and ground reference: ${device.nodes.length} terminals against ` +
+                `a ${entry.model.pinout.length}-terminal pinout`,
+        };
+    }
+    const inputNode = device.nodes[binding.input];
+    const outputNode = device.nodes[binding.output];
+    const groundNode = device.nodes[binding.ground];
+    if (inputNode === undefined ||
+        outputNode === undefined ||
+        groundNode === undefined) {
+        return {
+            kind: "unbound",
+            detail: `part ${identity.partId} charge-pump binding names a terminal this component ` +
+                `does not declare`,
+        };
+    }
+    // The reference is circuit ground. A pump tied to anything else is a shell the
+    // derivation cannot place, not a rail against an unknown reference.
+    if (groundNode !== 0 || outputNode === 0) {
+        return {
+            kind: "unbound",
+            detail: `part ${identity.partId} charge-pump binding puts the reference off circuit ` +
+                `ground, so no rail can be derived from it`,
+        };
+    }
+    // The document keeps the last word: an output the document already drives --
+    // declared rail or regulator-supplied -- stays the document's, and the pump stays open.
+    if (nodeToVoltage.has(outputNode)) {
+        return { kind: "backed" };
+    }
+    const inputVolts = nodeToVoltage.get(inputNode);
+    if (inputVolts === undefined || inputVolts === 0) {
+        return { kind: "no-input" };
+    }
+    // An output no other device touches cannot move the solve: stamping it would only
+    // widen the circuit-wide rail extremes other devices fall back to.
+    if ((devicesTouchingNode.get(outputNode) ?? 0) < 2) {
+        return { kind: "unloaded" };
+    }
+    const lossVolts = entry.chargePumpLossVolts ?? 0;
+    return {
+        kind: "model",
+        inputNode,
+        outputNode,
+        groundNode,
+        inputVolts,
+        volts: -inputVolts - Math.sign(-inputVolts) * lossVolts,
+        sourceOhms: section.law.sourceOhms,
+    };
+}
+/**
+ * A derived pump rail as one ordinary section device plus its law, or the original device
+ * opened with the reason the derivation recorded. Never `null` for a device the
+ * derivation decided: the placeholder volts in the pump entries must not reach generic
+ * expansion, so every decided device is consumed here.
+ */
+function pumpSectionDevices(device, derivation) {
+    switch (derivation.kind) {
+        case "backed":
+            return [[device, openIc(device, "charge-pump-declared-rail")]];
+        case "no-input":
+            return [[device, openIc(device, "charge-pump-no-input")]];
+        case "unloaded":
+            return [[device, openIc(device, "charge-pump-output-unloaded")]];
+        case "unbound":
+            return [
+                [
+                    device,
+                    {
+                        outcome: "law",
+                        device: device.id,
+                        law: { kind: "open" },
+                        openReason: "registry-arity-mismatch",
+                        insteadOfRefusal: derivation.detail,
+                    },
+                ],
+            ];
+        case "model": {
+            const sectionId = `${device.id}#0`;
+            const sectionDevice = {
+                ...device,
+                id: sectionId,
+                nodes: [derivation.outputNode, derivation.groundNode],
+                identity: {
+                    ...device.identity,
+                    terminalRoles: canonicalRoles("voltage-source", 2),
+                    declaredTerminalRoles: canonicalRoles("voltage-source", 2),
+                },
+            };
+            return [
+                [
+                    sectionDevice,
+                    {
+                        outcome: "law",
+                        device: sectionId,
+                        law: {
+                            kind: "voltage-source",
+                            volts: derivation.volts,
+                            sourceOhms: derivation.sourceOhms,
+                        },
+                    },
+                ],
+            ];
+        }
+    }
 }
 /**
  * An OTA's signal terminals, bound by the names the device declares for them.
@@ -1652,7 +2086,7 @@ function packageDeviceParameters(device, registry) {
     }
     return parameters;
 }
-function resolveDevice(device, registry, rails, supply, taperByControl, mainsFrequencyHz, devicesTouchingNode, nodeToVoltage, oneHopVoltage, netlist) {
+function resolveDevice(device, registry, rails, supply, taperByControl, mainsFrequencyHz, devicesTouchingNode, nodeToVoltage, netlist) {
     // A component declared as one transistor that is really several devices in one shell. Opened
     // rather than stamped, for the reason `isNonExecutableIcSupportShell` opens an IC shell: there
     // is no single device here to describe, and a transistor law would invent one. Reported by
@@ -1685,7 +2119,7 @@ function resolveDevice(device, registry, rails, supply, taperByControl, mainsFre
             // `findElectricallyIsolatedIcs`, which compile() runs over the same predicate.
             return openIc(device, "electrically-isolated");
         }
-        if (isChargePumpWithDeclaredRail(device, nodeToVoltage, oneHopVoltage)) {
+        if (isChargePumpWithDeclaredRail(device, nodeToVoltage)) {
             // The rail the pump generates is separately declared as a voltage-carrying
             // port; the IC itself is a view-only structural anchor, not a solved model.
             return openIc(device, "charge-pump-declared-rail");
@@ -1903,6 +2337,7 @@ function resolveDevice(device, registry, rails, supply, taperByControl, mainsFre
                     if (declared.breakdownVolts !== undefined ||
                         declared.saturationCurrent !== undefined ||
                         declared.seriesResistance !== undefined ||
+                        declared.emissionCoefficient !== undefined ||
                         device.isLed === true) {
                         return {
                             outcome: "law",
@@ -1912,6 +2347,8 @@ function resolveDevice(device, registry, rails, supply, taperByControl, mainsFre
                                 breakdownVolts: declared.breakdownVolts ?? catalogued.breakdownVolts,
                                 saturationCurrent: declared.saturationCurrent ?? catalogued.saturationCurrent,
                                 seriesResistance: declared.seriesResistance ?? catalogued.seriesResistance,
+                                emissionCoefficient: declared.emissionCoefficient ?? catalogued.emissionCoefficient,
+                                thermalVoltage: declared.thermalVoltage ?? catalogued.thermalVoltage,
                                 isLed: device.isLed === true ? true : catalogued.isLed,
                             },
                         };
@@ -1928,7 +2365,8 @@ function resolveDevice(device, registry, rails, supply, taperByControl, mainsFre
                     // If it is an LED, use physical LED defaults (higher forward knee ~1.8V to 2.2V),
                     // otherwise use class defaults (1N4148-ish silicon signal diode).
                     saturationCurrent: device.parameters.saturationCurrent ?? (isLed ? 1e-12 : 2.52e-9),
-                    emissionCoefficient: 1.752,
+                    // The source's own `EmissionCoefficient` when it states one, else the class default.
+                    emissionCoefficient: device.parameters.emissionCoefficient ?? 1.752,
                     thermalVoltage: device.parameters.thermalVoltage ?? (isLed ? 0.05 : THERMAL_VOLTAGE),
                     // 0 for an ordinary diode. Read from the source, never inferred from a part
                     // number: `1N4733` is a 5.1 V zener and `1N4148` is not, and telling them apart
@@ -1984,10 +2422,10 @@ function resolveDevice(device, registry, rails, supply, taperByControl, mainsFre
                 },
             };
         case "opamp": {
-            const declaredDrop = registryOpampSwingDrop(registry, device.identity.partNumber);
-            const declaredRails = railsAfterSwingDrop(opampRails(device, rails, nodeToVoltage), declaredDrop);
-            const railHigh = declaredRails.high;
-            const railLow = declaredRails.low;
+            const declaredSwing = registryOpampSwing(registry, device.identity.partNumber);
+            const declaredSwung = railsAfterSwing(opampRails(device, rails, nodeToVoltage), declaredSwing);
+            const railHigh = declaredSwung.rails.high;
+            const railLow = declaredSwung.rails.low;
             // The gain-bandwidth product: the packet's own typed `GBP` first, else the datasheet figure
             // of the exact part id, else none. Never a class number -- `null` lowers to a stamp the
             // consoles run on their default, and `opamp-gain-bandwidth-default` names it.
@@ -2001,7 +2439,14 @@ function resolveDevice(device, registry, rails, supply, taperByControl, mainsFre
                     railHigh,
                     railLow,
                     openLoopGain: device.parameters.openLoopGain ?? DEFAULT_OPEN_LOOP_GAIN,
-                    ...(declaredDrop === null ? {} : { outputSwingDropVolts: declaredDrop }),
+                    ...(declaredSwing === null
+                        ? {}
+                        : {
+                            outputSwingDropHighVolts: declaredSwing.highVolts,
+                            outputSwingDropLowVolts: declaredSwing.lowVolts,
+                            outputSwingPrinted: declaredSwing.printed,
+                        }),
+                    ...(declaredSwung.carried === null ? {} : { outputSwingCarried: declaredSwung.carried }),
                     ...(gainBandwidthHz === null ? {} : { gainBandwidthHz }),
                 },
             };
@@ -2145,29 +2590,41 @@ function resolveDevice(device, registry, rails, supply, taperByControl, mainsFre
                 law: { kind: "voltage-source", volts, sourceOhms: SUPPLY_SOURCE_OHMS },
             };
         }
-        case "bjt":
+        case "bjt": {
+            // A registered part refines the class defaults, exactly as the diode and
+            // JFET-gate cases do. Exact part number only -- see `registryLawFor`.
+            // Declared parameters win over everything, every time: the entries exist
+            // to fill absence, not to overrule a packet that states the value.
+            // Unregistered parts keep the class default bit-identically.
+            const catalogued = registryLawFor(registry, device.identity.partNumber, "bjt");
+            const entry = catalogued !== null && catalogued.kind === "bjt" ? catalogued : null;
             return {
                 outcome: "law",
                 device: device.id,
                 law: {
                     kind: "bjt",
                     polarity: device.parameters.pnp === 1 ? "pnp" : "npn",
-                    saturationCurrent: device.parameters.saturationCurrent ?? SILICON_SATURATION_CURRENT,
-                    forwardBeta: device.parameters.beta ?? SILICON_FORWARD_BETA,
-                    reverseBeta: device.parameters.reverseBeta ?? 1,
-                    thermalVoltage: THERMAL_VOLTAGE,
+                    saturationCurrent: device.parameters.saturationCurrent ??
+                        entry?.saturationCurrent ??
+                        SILICON_SATURATION_CURRENT,
+                    forwardBeta: device.parameters.beta ?? entry?.forwardBeta ?? SILICON_FORWARD_BETA,
+                    reverseBeta: device.parameters.reverseBeta ?? entry?.reverseBeta ?? 1,
+                    thermalVoltage: device.parameters.thermalVoltage ??
+                        entry?.thermalVoltage ??
+                        THERMAL_VOLTAGE,
                     // Absent for every silicon part in the corpus, and for the one germanium
                     // packet whose `LeakageCurrent` is a sentence rather than a value.
-                    leakageAmps: device.parameters.leakageAmps ?? 0,
+                    leakageAmps: device.parameters.leakageAmps ?? entry?.leakageAmps ?? 0,
                 },
             };
+        }
         case "jfet": {
-            // A registered part refines the class gate, exactly as `GENERIC_TUBE_GRID`'s
+            // A registered part refines the class channel, exactly as `GENERIC_TUBE_GRID`'s
             // note says a registry entry should. Exact part number only -- see
-            // `registryLawFor`. The refinement is the gate term alone: the channel
-            // stays the declared-or-class law byte-for-byte (rank-dependent, and the
-            // database beta disagrees with at least one packet's record), so a covered
-            // part's channel is indistinguishable from an unregistered one's. Declared
+            // `registryLawFor`. The 2SK30A entry's channel repeats the class default by
+            // construction (rank-dependent, and the database beta disagrees with at
+            // least one packet's record), so a covered part's channel is
+            // indistinguishable from an unregistered one's. Declared
             // Vt0/Beta win over everything, every time: the entries exist to fill
             // absence, not to overrule a packet that states the value (the same overlay
             // the diode case applies). Unregistered parts keep the class default
@@ -2184,13 +2641,17 @@ function resolveDevice(device, registry, rails, supply, taperByControl, mainsFre
                     channel: device.parameters.pChannel === 1 ? "p" : "n",
                     // A JFET is depletion mode: it conducts at zero gate bias and pinches
                     // off as the gate goes negative, so the threshold is negative.
-                    thresholdVolts: device.parameters.thresholdVolts ?? JFET_DEFAULT_THRESHOLD_VOLTS,
-                    transconductance: device.parameters.transconductance ?? JFET_DEFAULT_TRANSCONDUCTANCE,
-                    channelLengthModulation: 0,
+                    thresholdVolts: device.parameters.thresholdVolts ??
+                        entry?.thresholdVolts ??
+                        JFET_DEFAULT_THRESHOLD_VOLTS,
+                    transconductance: device.parameters.transconductance ??
+                        entry?.transconductance ??
+                        JFET_DEFAULT_TRANSCONDUCTANCE,
+                    channelLengthModulation: entry?.channelLengthModulation ?? 0,
                     // Subthreshold conduction (see the `fet` law docs in types.ts): the
                     // gradual region a knee-biased JFET actually sweeps in. MOSFETs
                     // keep 0 below.
-                    subthresholdVolts: 0.07,
+                    subthresholdVolts: entry?.subthresholdVolts ?? 0.07,
                     // A JFET gate is a silicon PN junction, so it conducts once forward-biased.
                     // Saturation current and scale are **reused from the triode grid**, which
                     // `compact-mna-dynamic-triode-cell` reports 0 Newton failures with; the onset
@@ -2199,30 +2660,39 @@ function resolveDevice(device, registry, rails, supply, taperByControl, mainsFre
                     // part refines the current through its catalog entry, and the
                     // unregistered default stays exactly what it was.
                     gateSaturationCurrent: entry?.gateSaturationCurrent ?? 1.0e-5,
-                    gateOnsetVolts: 0.5,
-                    gateScaleVolts: 0.06,
+                    gateOnsetVolts: entry?.gateOnsetVolts ?? 0.5,
+                    gateScaleVolts: entry?.gateScaleVolts ?? 0.06,
                 },
             };
         }
-        case "mosfet":
+        case "mosfet": {
+            // The same registry refinement as the JFET channel above: a registered
+            // part refines the class defaults, declared parameters win, and
+            // unregistered parts keep the class default bit-identically. Exact part
+            // number only. This shares the `fet` law kind with JFET entries; part
+            // ids are disjoint across the two classes, so a lookup by exact folded
+            // part id cannot cross from one to the other.
+            const catalogued = registryLawFor(registry, device.identity.partNumber, "fet");
+            const entry = catalogued !== null && catalogued.kind === "fet" ? catalogued : null;
             return {
                 outcome: "law",
                 device: device.id,
                 law: {
                     kind: "fet",
                     channel: device.parameters.pChannel === 1 ? "p" : "n",
-                    thresholdVolts: device.parameters.thresholdVolts ?? 2,
-                    transconductance: device.parameters.transconductance ?? 1e-3,
-                    channelLengthModulation: 0,
+                    thresholdVolts: device.parameters.thresholdVolts ?? entry?.thresholdVolts ?? 2,
+                    transconductance: device.parameters.transconductance ?? entry?.transconductance ?? 1e-3,
+                    channelLengthModulation: entry?.channelLengthModulation ?? 0,
                     // Insulated gate: no subthreshold region is modelled, behavior unchanged.
-                    subthresholdVolts: 0,
+                    subthresholdVolts: entry?.subthresholdVolts ?? 0,
                     // An insulated gate draws no current at any bias. Zero, deliberately: this
                     // is what the law did for every FET before the JFET junction was added.
-                    gateSaturationCurrent: 0,
-                    gateOnsetVolts: 0,
-                    gateScaleVolts: 1,
+                    gateSaturationCurrent: entry?.gateSaturationCurrent ?? 0,
+                    gateOnsetVolts: entry?.gateOnsetVolts ?? 0,
+                    gateScaleVolts: entry?.gateScaleVolts ?? 1,
                 },
             };
+        }
         case "ota":
             return otaDeviceClassLaw(device);
         case "inverter":
@@ -2403,6 +2873,15 @@ const springReverbTanks = {
  * documents and deliberately leaves unfiled). Every remaining mismatch sits on `kind: ic`, where
  * naming any class is exactly what that kind is for. Adding a class here on speculation would be
  * vocabulary against unexercised data.
+ *
+ * A UJT relaxation-oscillator law was attempted on branch `indiejoseph/ujt-law` (2026-10-20):
+ * bar split at eta, emitter diode into the tap, conductivity modulation as a VCCS, plus a
+ * clamp diode for saturation. It oscillates at the right period while it runs, but the
+ * firing-point crossing is a Newton lottery (about one stalled peak in 70 cycles, then the
+ * hold poisons the run permanently) in the reference runtime, and ngspice timestep-collapses
+ * at the same instant -- see the branch report. The minimal addition is a hysteretic switch
+ * stamp (once-per-sample evaluation, no Newton involvement), which no existing stamp is.
+ * Until that exists this entry stays: opening is honest, stamping a BJT is not.
  */
 const unimplementedDeviceLaws = new Set([
     "circuit.unijunctiontransistor",
@@ -3480,15 +3959,19 @@ export function findIcsNotExecuted(lawed, original, registry) {
                 ? `${head}: it is registered as a source-boundary shell, drawn for topological continuity rather than execution, so it is compiled as open.`
                 : reason === "charge-pump-declared-rail"
                     ? `${head}: it is a charge pump whose generated rail the document declares separately, so the rail is modelled and the pump itself is compiled as open.`
-                    : reason === "registry-arity-mismatch"
-                        ? `${head}: ${resolution.insteadOfRefusal ?? "its registry entry could not bind the declared terminals"}. The part is registered, so this is an arity disagreement rather than an unknown chip: either the document declares a shell rather than the part's own pins, or the catalog needs an entry at this terminal count.${wiring} It is compiled as open rather than refusing the pedal.`
-                        : reason === "registry-open"
-                            ? `${head}: the registry states no executable model for it and it is compiled as open. Whatever it does in the real circuit is absent.`
-                            : reason === "declared-class-without-model"
-                                ? `${head}: no registered part model binds it -- ${resolution.insteadOfRefusal ?? "the registry supplied none"} -- and ${device.identity.partNumber === null
-                                    ? `its source names no part number and declares only the generic ${device.identity.declaredType}, so there is nothing to look up`
-                                    : `its source declares ${device.identity.declaredType}, a class this pipeline opens rather than refusing the pedal for`}. Fixing it means a registry entry, a pinout that fits, or a packet correction.`
-                                : `${head}: it was compiled as open by a path that records no reason, so this cannot say which. A new opening branch in \`resolveDevice\` needs to tag itself.`) + gapSuffix,
+                    : reason === "charge-pump-no-input"
+                        ? `${head}: it is a charge pump whose generated rail the document does not declare and whose supply input carries no declared voltage, so no rail can be derived from it and it is compiled as open. Whatever the pump does in the real circuit is absent.`
+                        : reason === "charge-pump-output-unloaded"
+                            ? `${head}: it is a charge pump whose supply input is declared but whose output terminal drives nothing else in the circuit, so stamping its derived rail would change nothing and it is compiled as open.`
+                            : reason === "registry-arity-mismatch"
+                                ? `${head}: ${resolution.insteadOfRefusal ?? "its registry entry could not bind the declared terminals"}. The part is registered, so this is an arity disagreement rather than an unknown chip: either the document declares a shell rather than the part's own pins, or the catalog needs an entry at this terminal count.${wiring} It is compiled as open rather than refusing the pedal.`
+                                : reason === "registry-open"
+                                    ? `${head}: the registry states no executable model for it and it is compiled as open. Whatever it does in the real circuit is absent.`
+                                    : reason === "declared-class-without-model"
+                                        ? `${head}: no registered part model binds it -- ${resolution.insteadOfRefusal ?? "the registry supplied none"} -- and ${device.identity.partNumber === null
+                                            ? `its source names no part number and declares only the generic ${device.identity.declaredType}, so there is nothing to look up`
+                                            : `its source declares ${device.identity.declaredType}, a class this pipeline opens rather than refusing the pedal for`}. Fixing it means a registry entry, a pinout that fits, or a packet correction.`
+                                        : `${head}: it was compiled as open by a path that records no reason, so this cannot say which. A new opening branch in \`resolveDevice\` needs to tag itself.`) + gapSuffix,
             ...(gapClass === undefined ? {} : { gapClass }),
         });
     }