@vessel-dsp/compiler 0.0.0-stage → 0.3.0

package/dist/port-full-scale.d.ts

@@ -0,0 +1,70 @@
+import { type Block, type Ports } from "./types";
+export type PortFullScaleVolts = {
+    readonly input: number | null;
+    readonly output: number | null;
+};
+/**
+ * Read from the lowered stamps rather than the declared devices, the same discipline
+ * `supply-reference.ts` uses and for the same reason: lowering is what collapses redundant
+ * supply declarations into one source, and the stamps are what the runtime executes.
+ *
+ * A transformer stamp is only consulted when it declares a `turnsRatio` **and** the output port
+ * sits on one of its secondary nodes. A mains transformer's windings are nodes too, and dividing
+ * by a power transformer's ratio would be arithmetic on an unrelated number.
+ */
+/**
+ * Read from the lowered stamps rather than the declared devices, the same discipline
+ * `supply-reference.ts` uses and for the same reason: lowering is what collapses redundant
+ * supply declarations into one source, and the stamps are what the runtime executes.
+ *
+ * **Propagated from the supply rather than looked up at the port**, which is the correction of
+ * 2026-09-03. The previous rung kept a `Map<NodeId, factor>` written by every transformer stamp
+ * that touched a node, so the answer depended on write order and on whether a stamp related the
+ * port to the *supply* at all. Two defects followed, and both are measured:
+ *
+ * - A coil with two loaded taps stamps a winding between them, and that stamp related
+ *   `orange-rockerverb`'s 16 Ω output to its 8 Ω sibling -- not to any supply. Written last, its
+ *   `x1.4142` replaced the `x0.1372` plate step-down and the amp's bound became 580 V, above its
+ *   own 410 V rail.
+ * - Nine of the 24 amps had **no** stamp on the output node and fell back to the bare rail:
+ *   `marshall-jcm800` reported 466.7 V for a speaker terminal. Their speaker jack sits on an
+ *   impedance selector's common, one 0.01 Ω throw away from the winding, and a direct node lookup
+ *   cannot cross it.
+ *
+ * So this walks outward from the supply nodes: a transformer stamp multiplies by its ratio in the
+ * direction travelled, and a selector throw is a near-short that carries the bound across
+ * unchanged. **The largest bound reaching the port wins**, which is what makes it an upper bound
+ * rather than a nominal level -- a selector's throws are alternative taps and any of them may be
+ * the closed one, so the loosest is the one that has to hold.
+ */
+/**
+ * Read from the lowered stamps rather than the declared devices, the same discipline
+ * `supply-reference.ts` uses and for the same reason: lowering is what collapses redundant
+ * supply declarations into one source, and the stamps are what the runtime executes.
+ *
+ * The composition is `maximum supply x the transformer factor at the port`. It is not a walk from
+ * the supply to the port: the B+ that drives an output transformer's plate winding arrives
+ * through a rectifier and a filter bank, so no transformer-only path connects the two --
+ * `fender-5f1-champ`'s speaker node is reachable from its 410 V winding only through its 5Y3 and
+ * two 16 uF caps. Tried and measured: a propagation reached the port on nothing.
+ *
+ * **Two corrections, 2026-09-03**, both from measuring all 24 corpus amps:
+ *
+ * - **The port may sit one near-short away from the winding.** Nine amps reported their bare rail
+ *   for a speaker terminal -- `marshall-jcm800` 466.7 V -- because their speaker jack sits on an
+ *   impedance selector's *common* and a direct node lookup cannot cross a 0.01 ohm throw. The
+ *   port's winding node is now found through selector and switch links.
+ * - **The smallest factor at that node wins.** A coil with two loaded taps stamps a winding
+ *   between them, and that stamp relates `orange-rockerverb`'s 16 ohm output to its 8 ohm sibling
+ *   rather than to any supply. Kept in a map written per stamp it replaced the plate step-down by
+ *   write order and the amp's bound became 580 V, above its own 410 V rail. Every stamp touching
+ *   the node constrains it at once, so the tightest is the one that has to hold.
+ *
+ *   The residual: a sibling-tap stamp whose factor happened to be *smaller* than the plate
+ *   step-down would be chosen and would under-report the bound, making a render louder rather
+ *   than quieter. No corpus coil is shaped that way -- a tap-to-tap ratio is within a factor of
+ *   two of one, and a plate-to-speaker ratio is 10x to 40x down.
+ */
+export declare function portFullScaleVolts(blocks: readonly Block[], ports?: Ports): PortFullScaleVolts;
+export declare function deriveFullScaleVolts(supplyVolts: number | null, turnsRatio: number | null): number | null;
+//# sourceMappingURL=port-full-scale.d.ts.map

package/dist/port-full-scale.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"port-full-scale.d.ts","sourceRoot":"","sources":["../src/port-full-scale.ts"],"names":[],"mappings":"AAmBA,OAAO,EAAE,KAAK,KAAK,EAAuB,KAAK,KAAK,EAAE,MAAM,SAAS,CAAC;AAEtE,MAAM,MAAM,kBAAkB,GAAG;IAChC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B,CAAC;AAEF;;;;;;;;GAQG;AACH;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,kBAAkB,CACjC,MAAM,EAAE,SAAS,KAAK,EAAE,EACxB,KAAK,CAAC,EAAE,KAAK,GACX,kBAAkB,CA8GpB;AA2CD,wBAAgB,oBAAoB,CACnC,WAAW,EAAE,MAAM,GAAG,IAAI,EAC1B,UAAU,EAAE,MAAM,GAAG,IAAI,GACvB,MAAM,GAAG,IAAI,CAQf"}

package/dist/port-full-scale.js

@@ -0,0 +1,235 @@
+// The largest voltage a port can physically present, so a chain can compare two blocks.
+//
+// `ChainRuntime` hands one slot's output straight to the next as a bare number. That works for
+// pedal-into-pedal only because their ranges coincide: a pedal's output is the voltage at its
+// output jack, ~0.1 to 2 V, while an amp's is the voltage at its speaker terminal --
+// `fender-5e3-deluxe-tweed` measures 7.08 V into its 8 ohm load. Feed one into the other and the
+// level is wrong by an order of magnitude, and nothing in the program said what either number
+// meant.
+//
+// **An upper bound, not a nominal level.** A node cannot swing beyond the rails feeding it, and
+// an output transformer steps that bound down by its turns ratio. Both facts are already in the
+// program, so this needs no new source declaration -- which matters, because the corpus does not
+// carry one: 31 amp jacks declare `V0dBFS` and every one of them is a monitor tap, no typed
+// speaker load declares it, and rated output power appears once in 24 amp packets.
+//
+// **`null` where it is not derivable**, and the chain then scales by 1 and says so. A fabricated
+// default here would be exactly the silent substitution this repository refuses elsewhere: it
+// would look like a level convention while being a guess.
+import { GROUND } from "./types.js";
+/**
+ * Read from the lowered stamps rather than the declared devices, the same discipline
+ * `supply-reference.ts` uses and for the same reason: lowering is what collapses redundant
+ * supply declarations into one source, and the stamps are what the runtime executes.
+ *
+ * A transformer stamp is only consulted when it declares a `turnsRatio` **and** the output port
+ * sits on one of its secondary nodes. A mains transformer's windings are nodes too, and dividing
+ * by a power transformer's ratio would be arithmetic on an unrelated number.
+ */
+/**
+ * Read from the lowered stamps rather than the declared devices, the same discipline
+ * `supply-reference.ts` uses and for the same reason: lowering is what collapses redundant
+ * supply declarations into one source, and the stamps are what the runtime executes.
+ *
+ * **Propagated from the supply rather than looked up at the port**, which is the correction of
+ * 2026-09-03. The previous rung kept a `Map<NodeId, factor>` written by every transformer stamp
+ * that touched a node, so the answer depended on write order and on whether a stamp related the
+ * port to the *supply* at all. Two defects followed, and both are measured:
+ *
+ * - A coil with two loaded taps stamps a winding between them, and that stamp related
+ *   `orange-rockerverb`'s 16 Ω output to its 8 Ω sibling -- not to any supply. Written last, its
+ *   `x1.4142` replaced the `x0.1372` plate step-down and the amp's bound became 580 V, above its
+ *   own 410 V rail.
+ * - Nine of the 24 amps had **no** stamp on the output node and fell back to the bare rail:
+ *   `marshall-jcm800` reported 466.7 V for a speaker terminal. Their speaker jack sits on an
+ *   impedance selector's common, one 0.01 Ω throw away from the winding, and a direct node lookup
+ *   cannot cross it.
+ *
+ * So this walks outward from the supply nodes: a transformer stamp multiplies by its ratio in the
+ * direction travelled, and a selector throw is a near-short that carries the bound across
+ * unchanged. **The largest bound reaching the port wins**, which is what makes it an upper bound
+ * rather than a nominal level -- a selector's throws are alternative taps and any of them may be
+ * the closed one, so the loosest is the one that has to hold.
+ */
+/**
+ * Read from the lowered stamps rather than the declared devices, the same discipline
+ * `supply-reference.ts` uses and for the same reason: lowering is what collapses redundant
+ * supply declarations into one source, and the stamps are what the runtime executes.
+ *
+ * The composition is `maximum supply x the transformer factor at the port`. It is not a walk from
+ * the supply to the port: the B+ that drives an output transformer's plate winding arrives
+ * through a rectifier and a filter bank, so no transformer-only path connects the two --
+ * `fender-5f1-champ`'s speaker node is reachable from its 410 V winding only through its 5Y3 and
+ * two 16 uF caps. Tried and measured: a propagation reached the port on nothing.
+ *
+ * **Two corrections, 2026-09-03**, both from measuring all 24 corpus amps:
+ *
+ * - **The port may sit one near-short away from the winding.** Nine amps reported their bare rail
+ *   for a speaker terminal -- `marshall-jcm800` 466.7 V -- because their speaker jack sits on an
+ *   impedance selector's *common* and a direct node lookup cannot cross a 0.01 ohm throw. The
+ *   port's winding node is now found through selector and switch links.
+ * - **The smallest factor at that node wins.** A coil with two loaded taps stamps a winding
+ *   between them, and that stamp relates `orange-rockerverb`'s 16 ohm output to its 8 ohm sibling
+ *   rather than to any supply. Kept in a map written per stamp it replaced the plate step-down by
+ *   write order and the amp's bound became 580 V, above its own 410 V rail. Every stamp touching
+ *   the node constrains it at once, so the tightest is the one that has to hold.
+ *
+ *   The residual: a sibling-tap stamp whose factor happened to be *smaller* than the plate
+ *   step-down would be chosen and would under-report the bound, making a render louder rather
+ *   than quieter. No corpus coil is shaped that way -- a tap-to-tap ratio is within a factor of
+ *   two of one, and a plate-to-speaker ratio is 10x to 40x down.
+ */
+export function portFullScaleVolts(blocks, ports) {
+    let supplyVolts = 0;
+    /** Smallest transformer factor found at each node. */
+    const portFactor = new Map();
+    /** Nodes joined to each other by a near-short: a selector throw or a switch. */
+    const shorted = new Map();
+    const join = (a, b) => {
+        if (a === undefined || b === undefined || a === GROUND || b === GROUND) {
+            return;
+        }
+        for (const [from, to] of [
+            [a, b],
+            [b, a],
+        ]) {
+            const set = shorted.get(from) ?? new Set();
+            set.add(to);
+            shorted.set(from, set);
+        }
+    };
+    const noteFactor = (node, factor) => {
+        if (node === undefined || node === GROUND) {
+            return;
+        }
+        portFactor.set(node, Math.min(portFactor.get(node) ?? factor, factor));
+    };
+    for (const block of blocks) {
+        if (block.kind !== "mna") {
+            continue;
+        }
+        for (const stamp of block.stamps) {
+            // **Both source kinds, and an amp needs the AC one.** A tube amp's B+ is rectified
+            // from a mains winding, so its supply appears as `ac-source` peaks and its
+            // `dc-source` maximum is zero: measured, `fender-5e3-deluxe-tweed` states 466.7 V
+            // peak of AC and 0 V of DC. Reading only `dc-source` returned `null` for three of
+            // the five compiling amps -- the exact silent gap this bound exists to close.
+            if (stamp.kind === "dc-source") {
+                supplyVolts = Math.max(supplyVolts, Math.abs(stamp.volts));
+                continue;
+            }
+            if (stamp.kind === "ac-source") {
+                supplyVolts = Math.max(supplyVolts, Math.abs(stamp.amplitudeVolts));
+                continue;
+            }
+            // Row indices, not node ids -- a block's stamps address its matrix rows, which is why
+            // the transformer branch below indexes `nodeIds` too. Passing them through raw found
+            // no winding for any of the nine amps this traversal exists for.
+            if (stamp.kind === "selector") {
+                join(block.nodeIds[stamp.common], block.nodeIds[stamp.throwNode]);
+                continue;
+            }
+            if (stamp.kind === "switch") {
+                join(block.nodeIds[stamp.a], block.nodeIds[stamp.b]);
+                continue;
+            }
+            if (stamp.kind !== "transformer") {
+                continue;
+            }
+            if (!Number.isFinite(stamp.turnsRatio) || stamp.turnsRatio <= 0) {
+                continue;
+            }
+            // The stamp is `Vp - n*Vs = 0`, so a node on the primary side is `n` times the other
+            // side and a node on the secondary side is `1/n` of it. **Which side a speaker sits
+            // on is not an assumption to make**: `fender-5e3-deluxe-tweed` lowers with its 8 ohm
+            // load on `primary` and its plates on `secondary`, and `fender-5f1-champ` the other
+            // way round, so both directions are recorded and the port's own node decides.
+            for (const row of [stamp.primaryPlus, stamp.primaryMinus]) {
+                noteFactor(block.nodeIds[row], stamp.turnsRatio);
+            }
+            for (const row of [stamp.secondaryPlus, stamp.secondaryMinus]) {
+                noteFactor(block.nodeIds[row], 1 / stamp.turnsRatio);
+            }
+        }
+    }
+    if (supplyVolts <= 0) {
+        // No supply stated, so no bound exists for either port. A passive pedal --
+        // `ernie-ball-vp-jr` -- lands here honestly.
+        return { input: null, output: null };
+    }
+    const outputNode = ports?.output ??
+        (() => {
+            for (const block of blocks) {
+                if (block.kind === "mna" && block.outputNode !== null) {
+                    return block.nodeIds[block.outputNode];
+                }
+            }
+            return undefined;
+        })();
+    const factor = outputNode === undefined
+        ? undefined
+        : factorNear(outputNode, portFactor, shorted);
+    return {
+        // **An input's bound is not derivable from the supply, so nothing is derived here.** The
+        // rails bound what a node can *reach*, which is the right bound for an output and the
+        // wrong one for an input: an amp's grid circuit sets its input sensitivity, and
+        // `fender-5e3`'s 466.7 V rail says nothing about it. Deriving it anyway gave that amp an
+        // input bound of 466.7 V, which would attenuate a 9 V pedal by 50x at that seam -- a
+        // fabricated number producing an audible error, which is worse than no number at all.
+        //
+        // The missing fact is an input sensitivity, **or a `V0dBFS` on the input jack -- and this
+        // comment used to record that no packet declared one.** Measured 2026-09-03: 98 of the 142
+        // corpus documents do, 77 pedals and 21 amps, at 0.1, 0.15, 0.2 and 1 V. `link.ts` reads
+        // them and prefers them over anything derived on either port. Null here still means the
+        // same thing -- nothing is inferred from rails -- and where no declaration exists the
+        // chain scales by 1 and `src/runtime/chain-scale.ts` says so.
+        input: null,
+        output: factor === undefined ? supplyVolts : supplyVolts * factor,
+    };
+}
+/**
+ * The transformer factor at `node`, or at the nearest node joined to it by near-shorts.
+ *
+ * Breadth-first so the nearest winding wins, and the smallest factor among equally near ones --
+ * an impedance selector reaches three taps at one hop, any of which the control may close, and
+ * the tightest bound is the one that has to hold for all of them.
+ */
+function factorNear(node, portFactor, shorted) {
+    const seen = new Set([node]);
+    let frontier = [node];
+    // Two hops covers a jack behind a selector behind a switch. Unbounded would let a chain of
+    // shorts borrow a factor from an unrelated winding across the amp.
+    for (let hop = 0; hop < 3 && frontier.length > 0; hop += 1) {
+        let best;
+        for (const at of frontier) {
+            const factor = portFactor.get(at);
+            if (factor !== undefined) {
+                best = best === undefined ? factor : Math.min(best, factor);
+            }
+        }
+        if (best !== undefined) {
+            return best;
+        }
+        const next = [];
+        for (const at of frontier) {
+            for (const neighbour of shorted.get(at) ?? []) {
+                if (!seen.has(neighbour)) {
+                    seen.add(neighbour);
+                    next.push(neighbour);
+                }
+            }
+        }
+        frontier = next;
+    }
+    return undefined;
+}
+export function deriveFullScaleVolts(supplyVolts, turnsRatio) {
+    if (supplyVolts === null || !Number.isFinite(supplyVolts) || supplyVolts <= 0) {
+        return null;
+    }
+    if (turnsRatio === null || !Number.isFinite(turnsRatio) || turnsRatio <= 0) {
+        return supplyVolts;
+    }
+    return supplyVolts / turnsRatio;
+}
+//# sourceMappingURL=port-full-scale.js.map

package/dist/port-full-scale.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"port-full-scale.js","sourceRoot":"","sources":["../src/port-full-scale.ts"],"names":[],"mappings":"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"}

package/dist/pot-orientation.d.ts

@@ -0,0 +1,114 @@
+import type { Device, Netlist, NodeId } from "./types";
+/**
+ * How far each node sits, in hops through DC-conducting devices, from a quiet DC reference --
+ * ground, or a supply's own terminal.
+ *
+ * This is the connectivity evidence a pot's orientation needs, in the same closed vocabulary
+ * `netlist.ts`'s `voltagePortRails` already uses to ask a related question ("is this node's
+ * potential already generated"): `dcConductingKinds` -- resistor, potentiometer, rheostat,
+ * inductor, switch, selector -- conduct a steady current, and nothing else in this set does, so
+ * an active device (a transistor, an op-amp, a diode) is never crossed. A quiet reference is
+ * ground itself or any terminal of a `voltage-source` or `rail` device -- **not** an op-amp
+ * output, which is actively driven with the signal and is the opposite of quiet.
+ *
+ * Computed once per netlist and passed down, not per pot: `boss-ds-1` alone lowers 82 regions,
+ * and the graph does not change between them.
+ */
+export declare function quietDistances(netlist: Netlist): ReadonlyMap<NodeId, number>;
+/**
+ * How far each node sits, in hops through DC-conducting devices, from an op-amp's own input
+ * terminal.
+ *
+ * A second, narrower quiet-reference class than `quietDistances`, kept separate rather than
+ * folded into it. An op-amp input under closed-loop negative feedback sits at a virtual
+ * reference regardless of the feedback network's own resistances -- a property of the feedback
+ * *topology*, not of any one element's value -- so seeding it is not the same evidence-standing-
+ * on-itself risk `netlist.ts`'s `generated()` was found to have (there, an op-amp's *output* was
+ * treated as an independent reference, which a feedback path can make circular: the output's own
+ * potential depends on the input it would be certifying). Measured 2026-08-14 (the rheostat-nine
+ * census, `docs/todo-archive/2026-08-14-the-rheostat-nine.md`): applied unconditionally, this
+ * evidence moves 24 pots, 15 of them reversing an orientation `quietDistances` alone already
+ * decided -- including undoing a same-day correction and overturning a pot where declaration
+ * order and connectivity previously agreed unanimously. `potTerminals` below therefore only
+ * consults this map when `quietDistances` leaves a pot's two ends **fully unreachable** (both
+ * infinite) -- never to override an already-finite decision, even a finite tie. Scoped that way,
+ * it moves exactly 6 pots and reverses none.
+ */
+export declare function opampInputDistances(netlist: Netlist): ReadonlyMap<NodeId, number>;
+/**
+ * How far each node sits, in hops through DC-conducting devices, from an op-amp's declared
+ * **output** terminal.
+ *
+ * The companion of `opampInputDistances` for the negative-feedback gain-stage class: a rheostat
+ * wired from an op-amp's declared output, through its track, to the same op-amp's declared
+ * inverting input is a gain-setting feedback element, and for that class a rising control must
+ * mean *more* feedback resistance (non-inverting gain is `1 + Rf/Rg`, so more `Rf` is more
+ * gain). `boss-os-2`'s `DRIVE` sits exactly there on both its 270 k sections: the wiper shares
+ * its node with the `output` terminal, the free end reaches the `inverting` terminal through a
+ * single series resistor, and the whole pocket is DC-isolated from ground, so
+ * `quietDistances` has no claim and the `opampInputDistances` tie above falls through to
+ * declaration order -- which oriented `VR3b` so its live resistance *fell* as the knob rose,
+ * running the pedal's Drive backwards (rendered: 6.3e-1 rms at 0.0 against 2.9e-1 at 1.0).
+ * The output-side distance below is the discriminating typed fact: which end the wiper is
+ * strapped to relative to the declared `output` role, not how close either end happens to sit
+ * to an input.
+ */
+export declare function opampOutputDistances(netlist: Netlist): ReadonlyMap<NodeId, number>;
+/**
+ * The set of nodes that are a declared op-amp **inverting** input, read from the declared
+ * `inverting` role rather than a folded terminal name (the same closed-vocabulary read
+ * `opampInputDistances` uses for its seeds, narrowed to the inverting half).
+ *
+ * Kept as a node set, not a distance map, because the one consumer below asks a yes/no
+ * question -- "does this pot's wiper sit on an inverting input?" -- not "how far is it from
+ * one". `opampInputDistances` cannot answer that: it seeds from *both* input roles, so a zero
+ * there does not say which input a node sits on.
+ */
+export declare function opampInvertingInputNodes(netlist: Netlist): ReadonlySet<NodeId>;
+/**
+ * How far each node sits, in hops through the **AC** graph (DC-conducting devices *plus*
+ * capacitors), from an op-amp's declared output terminal.
+ *
+ * The companion of `opampOutputDistances` for the one shape it cannot reach: a non-inverting
+ * gain pot whose wiper sits *on* the op-amp's declared inverting input. For that class the wiper
+ * is the DC hub -- both track ends reach ground, the inverting input, and the output through the
+ * wiper in exactly the same number of DC hops -- so every DC distance map this file has is a
+ * tie and is silent about which end the live half is. Capacitors are the one passive element
+ * that separates the two ends in that shape (the output couples to one end, ground to the
+ * other), so the discrimination has to follow them. `boss-ds-1`'s `VR1` is the corpus's sole
+ * instance: its two ends are a 2/2 DC-quiet tie, the wiper is on the inverting input, and
+ * only `AC` separates the output-coupled end (one cap, `C6`, from the output) from the
+ * ground-coupled end.
+ *
+ * Computed over the AC graph on purpose, not by adding a capacitor-aware variant to the DC
+ * maps: the DC maps are a validated "moves exactly 6 pots, reverses none" instrument and must
+ * stay DC, and folding a capacitor into them would change what every existing caller reads.
+ */
+export declare function opampOutputAcDistances(netlist: Netlist): ReadonlyMap<NodeId, number>;
+export declare function potTerminals(device: Device, quietDistance: ReadonlyMap<NodeId, number>, opampInputDistance: ReadonlyMap<NodeId, number>, 
+/**
+ * Distance to an op-amp's declared output terminal, for the negative-feedback
+ * gain-stage tie below. Empty by default: a call site that has no netlist in hand
+ * (the inert-control and operating-point screens) passes nothing and gets today's
+ * behaviour exactly, as with the other two maps.
+ */
+opampOutputDistance?: ReadonlyMap<NodeId, number>, 
+/**
+ * The declared role of the control that varies this pot, when the document states one.
+ * Only consulted for the rheostat exemption below; every other path ignores it, and a
+ * call site that has no role passes `null` and gets today's behaviour exactly.
+ */
+controlRole?: string | null, 
+/**
+ * Nodes that are a declared op-amp inverting input, for the negative-feedback gain-pot
+ * tie below. Empty by default: a call site with no netlist in hand (the inert-control and
+ * operating-point screens) passes nothing and gets today's behaviour exactly, as with the
+ * other evidence maps.
+ */
+invertingInputNodes?: ReadonlySet<NodeId>, 
+/**
+ * AC distance (DC + capacitors) to an op-amp's declared output, for the same gain-pot
+ * tie. Empty by default for the same reason.
+ */
+acOutputDistance?: ReadonlyMap<NodeId, number>): readonly [number, number, number];
+//# sourceMappingURL=pot-orientation.d.ts.map

package/dist/pot-orientation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pot-orientation.d.ts","sourceRoot":"","sources":["../src/pot-orientation.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAuIvD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAU5E;AAiBD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mBAAmB,CAClC,OAAO,EAAE,OAAO,GACd,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAgB7B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,oBAAoB,CACnC,OAAO,EAAE,OAAO,GACd,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAgB7B;AAED;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CACvC,OAAO,EAAE,OAAO,GACd,WAAW,CAAC,MAAM,CAAC,CAgBrB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,sBAAsB,CACrC,OAAO,EAAE,OAAO,GACd,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAgB7B;AA4CD,wBAAgB,YAAY,CAC3B,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,EAC1C,kBAAkB,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC;AAC/C;;;;;GAKG;AACH,mBAAmB,GAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAa;AAC5D;;;;GAIG;AACH,WAAW,GAAE,MAAM,GAAG,IAAW;AACjC;;;;;GAKG;AACH,mBAAmB,GAAE,WAAW,CAAC,MAAM,CAAa;AACpD;;;GAGG;AACH,gBAAgB,GAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAa,GACvD,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAwMnC"}