@vessel-dsp/compiler 0.0.0-stage → 0.3.0

package/dist/stamp-partition.js

@@ -0,0 +1,472 @@
+// Compile-time stamp partitioning for MNA blocks.
+//
+// Classifies stamps into linear vs nonlinear (port rows), control-dependent vs
+// constant, and dynamic/reactive state. Precomputed at compile time and emitted on
+// the program as data, avoiding runtime re-classification or dynamic row allocations.
+import { atLeast, perBlock } from "./denomination.js";
+/**
+ * Which fields of each stamp kind hold a node id.
+ *
+ * One table rather than a switch per consumer. `remapStampNodes` used to restate this as 150
+ * lines of `{ ...stamp, anode: row(stamp.anode), cathode: row(stamp.cathode) }`, and
+ * `stampTerminals` in `sparse-schedule.ts` restates a near-copy of it again for a different
+ * purpose. That is the same fact written twice, and the documented failure mode of getting it
+ * wrong is severe: a stamp kind missing a case kept its authored node ids while every other
+ * stamp in the block moved to row indices, which is an element quietly wired to the wrong
+ * nodes that still renders.
+ *
+ * `satisfies` checks this harder than the switch did. The mapped type requires **every** stamp
+ * kind to appear -- a new kind is a compile error here -- and requires each listed name to be
+ * an actual key of that kind's own variant, so a typo or a field moved during a refactor fails
+ * to build rather than silently renumbering nothing.
+ */
+export const STAMP_SHAPES = {
+    conductance: { nodes: ["a", "b"], aux: 0, ports: "none", newton: false },
+    "controlled-conductance": {
+        nodes: ["a", "b"],
+        aux: 0,
+        ports: "none",
+        newton: false,
+        control: true,
+    },
+    "controlled-resistance": {
+        nodes: ["a", "b"],
+        aux: 0,
+        ports: "none",
+        newton: false,
+        control: true,
+    },
+    capacitor: {
+        nodes: ["a", "b"],
+        aux: 0,
+        ports: "none",
+        newton: false,
+        dynamic: true,
+    },
+    inductor: {
+        nodes: ["a", "b"],
+        aux: 0,
+        ports: "none",
+        newton: false,
+        dynamic: true,
+    },
+    switch: {
+        nodes: ["a", "b"],
+        aux: 0,
+        ports: "none",
+        newton: false,
+        control: true,
+    },
+    selector: {
+        nodes: ["common", "throwNode"],
+        aux: 0,
+        ports: "none",
+        newton: false,
+        control: true,
+    },
+    // A sine EMF is time-varying and linear: it differs between samples and is a constant
+    // within the system being solved at each one, exactly as the input source is.
+    "dc-source": {
+        nodes: ["positive", "negative"],
+        aux: 1,
+        ports: "none",
+        newton: false,
+    },
+    "ac-source": {
+        nodes: ["positive", "negative"],
+        aux: 1,
+        ports: "none",
+        newton: false,
+    },
+    "input-source": { nodes: ["node"], aux: 1, ports: "none", newton: false },
+    // A `coupled` port's write-back, same shape as `dc-source`: a same-sample source term,
+    // not a curve. The macro core it reads from is a delay line, which needs no Newton loop
+    // of its own either -- see couple.ts's header for why that stays true for this build.
+    "macro-audio-source": {
+        nodes: ["node"],
+        aux: 1,
+        ports: "none",
+        newton: false,
+    },
+    "logic-divider": {
+        nodes: ["clockNode", "qNode", "gndNode"],
+        aux: 1,
+        ports: "none",
+        newton: false,
+        dynamic: true,
+    },
+    // A VCCS is linear within a sample: transconductance couples the controlling input pair
+    // (inP, inN) to the output pair (outP, outN) across the Jacobian matrix.
+    vccs: {
+        nodes: ["outP", "outN", "inP", "inN"],
+        aux: 0,
+        ports: "none",
+        newton: false,
+    },
+    transformer: {
+        nodes: ["primaryPlus", "primaryMinus", "secondaryPlus", "secondaryMinus"],
+        aux: 1,
+        ports: "nodes-and-aux",
+        newton: false,
+    },
+    // A tank is stateful but not non-linear: within one sample it is a fixed conductance and a
+    // fixed Thevenin source. Its memory advances once per sample, after the solve. It still
+    // declares port rows, which is why `ports` and `newton` are separate facts here.
+    "spring-reverb": {
+        nodes: ["inputPlus", "inputMinus", "outputPlus", "outputMinus"],
+        aux: 1,
+        ports: "nodes",
+        newton: false,
+        dynamic: true,
+    },
+    // Rails make an op-amp saturate, which is the mode switch Newton is for. Without them it is
+    // a plain high-gain VCVS and the row stays linear.
+    "ideal-opamp": {
+        nodes: ["plus", "minus", "output"],
+        aux: 1,
+        ports: "railed-opamp",
+        newton: "railed-opamp",
+    },
+    diode: { nodes: ["anode", "cathode"], aux: 0, ports: "nodes", newton: true },
+    "tube-diode": {
+        nodes: ["plate", "cathode"],
+        aux: 0,
+        ports: "nodes",
+        newton: true,
+    },
+    bjt: {
+        nodes: ["base", "collector", "emitter"],
+        aux: 0,
+        ports: "nodes",
+        newton: true,
+    },
+    fet: {
+        nodes: ["gate", "drain", "source"],
+        aux: 0,
+        ports: "nodes",
+        newton: true,
+    },
+    triode: {
+        nodes: ["grid", "cathode", "plate"],
+        aux: 0,
+        ports: "nodes",
+        newton: true,
+    },
+    pentode: {
+        nodes: ["grid", "cathode", "plate", "screen"],
+        aux: 0,
+        ports: "nodes",
+        newton: true,
+    },
+    ota: {
+        nodes: ["plus", "minus", "bias", "output", "vee"],
+        aux: 0,
+        ports: "nodes",
+        newton: true,
+    },
+    optocoupler: {
+        nodes: ["ldrA", "ldrB", "ledAnode", "ledCathode"],
+        aux: 0,
+        ports: "nodes",
+        newton: true,
+    },
+    "analog-switch": {
+        nodes: ["a", "b", "control"],
+        aux: 0,
+        ports: "nodes",
+        newton: true,
+    },
+    compandor: {
+        nodes: ["rectIn", "rectCap", "cellIn", "sumNode", "vref"],
+        aux: 0,
+        ports: "nodes",
+        newton: true,
+        dynamic: true,
+    },
+    // Owns three consecutive auxiliary rows, which its matrix square covers but its port rows
+    // deliberately do not.
+    "clock-driver": {
+        nodes: ["cp1", "cp2", "vgg", "vdd", "ox1", "gnd"],
+        aux: 3,
+        ports: "nodes",
+        newton: true,
+    },
+    comparator: {
+        nodes: ["plus", "minus", "output", "vee"],
+        aux: 0,
+        ports: "nodes",
+        newton: true,
+    },
+    "linear-vca": {
+        nodes: ["plus", "minus", "output", "control"],
+        aux: 0,
+        ports: "nodes",
+        newton: true,
+    },
+};
+/** The shape entry for a stamp, with the table's per-kind literal types widened away. */
+export function stampShape(stamp) {
+    return STAMP_SHAPES[stamp.kind];
+}
+/** Read a named node field off a stamp. */
+export function stampNodeValue(stamp, field) {
+    return stamp[field];
+}
+/** The auxiliary rows a stamp owns, as absolute row indices. */
+export function stampAuxRows(stamp, nodeCount) {
+    const shape = stampShape(stamp);
+    if (shape.aux === 0)
+        return [];
+    const base = nodeCount + (stamp.sourceIndex ?? 0);
+    return Array.from({ length: shape.aux }, (_, offset) => base + offset);
+}
+/**
+ * Rewrite a stamp's node fields through `row`.
+ *
+ * The spread reassigns keys the stamp already carries, so their position in the object is
+ * unchanged -- which matters because a lowered stamp is serialised into the emitted program
+ * and key order is part of those bytes.
+ */
+export function remapStampNodes(stamp, row) {
+    const remapped = { ...stamp };
+    for (const field of stampShape(stamp).nodes) {
+        remapped[field] = row(stampNodeValue(stamp, field));
+    }
+    return remapped;
+}
+/**
+ * Does this stamp have to be re-evaluated inside a Newton loop?
+ *
+ * **The stamp-level twin of `partition.ts`'s `lawNeedsNewton`, and deliberately a second fact
+ * rather than a reuse of the first.** A law and its stamps are not the same list -- a jack's
+ * `port-engage` law lowers to a plain `conductance`, an `ac-source` law lowers to two stamps,
+ * an `open` law lowers to none -- and what a solver has to do is decided by what is in the
+ * block, not by what was in the document. `Block.linear` is read by the runtime to choose
+ * between one pass and an iteration cap, so it has to describe the stamps it will evaluate.
+ *
+ * The two mistakes are not symmetric, which is why the table has to be exhaustive. Calling a
+ * linear stamp nonlinear costs a few iterations; calling a nonlinear stamp linear makes
+ * `iterate` run one pass, evaluate the curve once from a zero start, and emit that as a solved
+ * answer -- no held sample, no telemetry, no diagnostic.
+ */
+export function stampNeedsNewton(stamp) {
+    const { newton } = stampShape(stamp);
+    if (newton === "railed-opamp") {
+        return stamp.railHigh !== null;
+    }
+    return newton;
+}
+/**
+ * Which runtime control moves a stamp's value, or `null` when it is constant.
+ *
+ * Read off the shape table's `control` flag. A stamp missing that flag would silently make a
+ * block look `controlFree`, and step 4's whole promise is that such a block's matrix is
+ * constant -- so the omission would be a factorisation frozen against a knob that still moves.
+ */
+export function stampControl(stamp) {
+    return stampShape(stamp).control === true
+        ? (stamp.control ?? null)
+        : null;
+}
+/**
+ * Which rows a stamp's device law actually writes into the Jacobian / RHS, or `null` when the
+ * stamp writes none.
+ *
+ * Read off the shape table's `ports`, which is a **separate fact from `newton`** and not a
+ * synonym for it. `transformer` and `spring-reverb` are both linear within a sample yet
+ * declare port rows, so deriving this from `stampNeedsNewton` would drop them.
+ *
+ * The returned order is not significant: `computeStampPartition` feeds these into a `Set` and
+ * sorts it.
+ */
+export function stampPortRows(stamp, nodeCount) {
+    const shape = stampShape(stamp);
+    if (shape.ports === "none")
+        return null;
+    if (shape.ports === "railed-opamp" &&
+        stamp.railHigh === null) {
+        return null;
+    }
+    const rows = shape.nodes.map((field) => stampNodeValue(stamp, field));
+    return shape.ports === "nodes"
+        ? rows
+        : [...rows, ...stampAuxRows(stamp, nodeCount)];
+}
+/**
+ * Whether a stamp carries dynamic/reactive state (e.g. companion state across time steps).
+ */
+export function stampIsDynamic(stamp) {
+    return stampShape(stamp).dynamic === true;
+}
+/**
+ * Compute the complete stamp partition for an MNA block.
+ */
+export function computeStampPartition(stamps, nodeCount) {
+    const ports = new Set();
+    const linearStampIndices = [];
+    const nonlinearStampIndices = [];
+    const constantStampIndices = [];
+    const controlStampIndices = [];
+    const dynamicStampIndices = [];
+    for (let index = 0; index < stamps.length; index += 1) {
+        const stamp = stamps[index];
+        const rows = stampPortRows(stamp, nodeCount);
+        const isLinear = rows === null;
+        if (isLinear) {
+            linearStampIndices.push(index);
+        }
+        else {
+            nonlinearStampIndices.push(index);
+            for (const row of rows) {
+                if (row !== 0) {
+                    ports.add(row);
+                }
+            }
+        }
+        const isControl = stampControl(stamp) !== null;
+        if (isControl) {
+            controlStampIndices.push(index);
+        }
+        const isDynamic = stampIsDynamic(stamp);
+        if (isDynamic) {
+            dynamicStampIndices.push(index);
+        }
+        const isSignalSource = stamp.kind === "input-source" ||
+            stamp.kind === "macro-audio-source" ||
+            stamp.kind === "ac-source";
+        if (isLinear && !isControl && !isDynamic && !isSignalSource) {
+            constantStampIndices.push(index);
+        }
+    }
+    // Auxiliary rows owned by sources whose non-ground terminals are all in `ports` have no
+    // off-diagonal coupling into the linear interior `L`. Leaving such an aux row in `L` creates an
+    // all-zero row in `M_lin[L][L]` when source resistance is zero, making `M_lin[L][L]` singular
+    // and dropping the source excitation. Promoting the aux row to `ports` couples it directly to
+    // the port equations.
+    for (const stamp of stamps) {
+        const auxRows = stampAuxRows(stamp, nodeCount);
+        if (auxRows.length === 0)
+            continue;
+        const nodes = stampShape(stamp).nodes.map((f) => stampNodeValue(stamp, f));
+        const nonGroundNodes = nodes.filter((n) => n !== 0);
+        if (nonGroundNodes.length > 0 &&
+            nonGroundNodes.every((n) => ports.has(n))) {
+            for (const aux of auxRows) {
+                ports.add(aux);
+            }
+        }
+    }
+    return {
+        portRows: [...ports].sort((a, b) => a - b),
+        linearStampIndices,
+        nonlinearStampIndices,
+        constantStampIndices,
+        controlStampIndices,
+        dynamicStampIndices,
+    };
+}
+/**
+ * Thresholds for solving a block by eliminating its linear interior and iterating only the
+ * nonlinear port rows (the runtime's Schur-complement path).
+ *
+ * All three must hold, and they are a cost model rather than a correctness rule -- eliminating
+ * a block that fails them is still a correct solve, just a slower one. The ratio says the
+ * interior is worth removing at all, the floor keeps the extra bookkeeping off small blocks,
+ * and the cubic saving estimates the dense-factorisation work actually avoided.
+ */
+const ELIMINATE_MIN_UNKNOWN_RATIO = 2.4;
+const ELIMINATE_MIN_UNKNOWNS = 12;
+/**
+ * **Per BLOCK, and typed so it cannot be compared against a per-packet figure.** A prediction
+ * stated in these units was measured in packet units on 2026-09-11 and the resulting null was
+ * meaningless -- 84% of a block became 0.3% of a packet, and four independent checks passed it
+ * because each was correct at the level it was stated. The type now makes that comparison fail
+ * to compile rather than fail to be noticed.
+ */
+const ELIMINATE_MIN_ALGEBRAIC_SAVING = perBlock(5000);
+/**
+ * Whether a block should carry the eliminated (Schur-complement) solve.
+ *
+ * Shared by `lower.ts`, which decides it when a region is first lowered, and `couple.ts`,
+ * which must re-decide it after adding a stamp. The two carried byte-identical copies of this
+ * predicate, so a threshold changed in one and not the other would have made a coupled block
+ * disagree with the same block uncoupled.
+ */
+export function shouldEliminate(unknowns, portRowCount, linear, 
+/**
+ * The document's `convergence-opt-in` flag. Where set, a nonlinear block with port rows is
+ * eliminated regardless of the cost rule -- it overrides the cost veto, but not the
+ * linear / zero-port guard above, which a portless or linear block cannot use elimination
+ * for at all.
+ */
+convergenceOptIn = false) {
+    if (linear || portRowCount === 0) {
+        return false;
+    }
+    if (convergenceOptIn) {
+        return true;
+    }
+    if (derivedAdmissionEnabled()) {
+        return derivedShouldEliminate(unknowns, portRowCount);
+    }
+    return (unknowns / portRowCount >= ELIMINATE_MIN_UNKNOWN_RATIO &&
+        unknowns >= ELIMINATE_MIN_UNKNOWNS &&
+        atLeast(perBlock(unknowns ** 3 - portRowCount ** 3), ELIMINATE_MIN_ALGEBRAIC_SAVING));
+}
+/**
+ * **The measured dense-versus-sparse penalty**, from the WASM console. First measured 2026-08-25
+ * on two matched-size pairs (`boss-ch-1`/`orange-gro100` at 85 unknowns, `boss-ce-5`/
+ * `mxr-carbon-copy` at ~100) and pinned at 1.9 with the caveat that it "should grow with size".
+ * The 2026-09-17 re-fit measured the on/off cost of the five large amps (72-119 unknowns) directly
+ * -- jcm800 1.41x, vox 1.85x, peavey 2.57x, sunn 2.57x, rockerverb 2.98x -- and fitting
+ * `R = C (p/n)^b` to those gives **C = 7.2, b = 1.98 (R^2 = 0.79)**. The constant was ~4x too low
+ * (the "grows with size" direction was right) but the exponent is **~2, not the 1.5** the
+ * sparse-cost hypothesis predicted: the phase-2 cost regression is a too-low constant, not a
+ * size-dependent exponent. **Measured, not chosen** — which is the whole point of using it here.
+ */
+const MEASURED_DENSIFICATION = 7.2;
+/**
+ * The derived admission rule, behind `VESSEL_DERIVED_ELIMINATION=1`.
+ *
+ * **Cost goes as unknowns² × nonlinear count** — fitted across ten packets with WASM-measured cost,
+ * `R² = 0.674`. Elimination replaces an `n`-unknown iterated system with a `p`-unknown one, and its
+ * own factorisation is prepare-time for a linear interior. What it costs per sample is
+ * **densification**: the port system is dense where the original may have been sparse. So:
+ *
+ * ```
+ * admit when   MEASURED_DENSIFICATION * p²  <  n²      i.e.  n/p > sqrt(7.2) = 2.68
+ * ```
+ *
+ * **No free constant.** `7.2` is the measured on/off of the two solve paths at 72-119 unknowns and
+ * the exponent is fitted (~2); neither was chosen to admit or reject any particular packet — which
+ * is the failure this replaces. Lowering `2.4` until it admitted the three packets whose saving had
+ * been predicted would have made the prediction and the admission one choice, and no later
+ * measurement could have separated them.
+ *
+ * **`ELIMINATE_MIN_UNKNOWNS` is still consulted and is still hand-set.** The model has **no term
+ * for fixed per-block overhead**, and without one the inequality admits every block with any
+ * interior — 241 of 241, which is not a predicate. The floor stands in for that missing term, and
+ * the sample straddling it (15 admitted blocks below, 31 above) is designed to retire it: if a
+ * 7-unknown block predicted at 84% delivers nothing, the overhead is the whole saving at that size
+ * and the crossover **is** the floor, derived rather than chosen.
+ */
+export function derivedShouldEliminate(unknowns, portRowCount) {
+    if (portRowCount === 0) {
+        return false;
+    }
+    return (MEASURED_DENSIFICATION * portRowCount ** 2 < unknowns ** 2 &&
+        unknowns >= ELIMINATE_MIN_UNKNOWNS);
+}
+/**
+ * Off by default, and deliberately so: enabling it changes the compiled program of a large share of
+ * the corpus, which moves all seven gates at once and would not localise a failure. It is measured
+ * on a registered sample spanning the prediction range first — see
+ * `artifacts/docs/validation/2026-09-11-what-actually-drives-cpu-cost.md`.
+ */
+function derivedAdmissionEnabled() {
+    // Guarded like the runtime's limiter trace: the compiler also runs in the browser, where
+    // `process` does not exist. A measurement-only switch does not earn a CompileOptions field
+    // threaded through lower.ts and couple.ts, so it stays an environment read.
+    return typeof process !== "undefined" && process.env?.VESSEL_DERIVED_ELIMINATION === "1";
+}
+//# sourceMappingURL=stamp-partition.js.map

package/dist/stamp-partition.js.map

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

package/dist/supply-reference.d.ts

@@ -0,0 +1,19 @@
+import type { Block, Program } from "./types";
+/**
+ * Read from the lowered `dc-source` stamps rather than the declared `rail`/`battery` devices,
+ * for the same reason `over-driven-node.ts` reads stamps: lowering is what collapses a
+ * redundant pair of supply declarations into one source, and the stamps are what the runtime
+ * executes and the deck is emitted from.
+ *
+ * Zero-volt sources are ignored. A `0 V` source is a ground tie, not a supply, and counting it
+ * would make an unpowered circuit look powered.
+ *
+ * **`dual-rail` is not the same as `positive-ground`, and conflating them would be the whole
+ * bug.** `klon-centaur` (`+9`, `+18`, `-9`) and `earthquaker-devices-plumes` (`+9`, `-9`) each
+ * derive a negative rail from a charge pump inside an ordinary center-negative pedal, so their
+ * *external* supply is the same as every other pedal's. What matters for a shared supply is
+ * whether a positive rail exists at all, which is why the chain rule below is stated that way
+ * and not as "positive-ground versus everything".
+ */
+export declare function supplyReference(blocks: readonly Block[]): Program["supplyReference"];
+//# sourceMappingURL=supply-reference.d.ts.map

package/dist/supply-reference.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"supply-reference.d.ts","sourceRoot":"","sources":["../src/supply-reference.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAE9C;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAC9B,MAAM,EAAE,SAAS,KAAK,EAAE,GACtB,OAAO,CAAC,iBAAiB,CAAC,CA6B5B"}

package/dist/supply-reference.js

@@ -0,0 +1,66 @@
+// Which terminal of its supply a circuit references to ground.
+//
+// A pedal's DC jack is center-negative or center-positive, and **that convention is not an
+// electrical fact this pipeline can read or needs to**: MNA solves node voltages against a
+// reference node, so once the source says which node is the supply and what sign it carries,
+// how the barrel is wired is invisible to the solve. Nothing in the corpus declares barrel
+// polarity, and nothing here reads it.
+//
+// What *is* electrical is the **sign of the supply relative to ground**. A germanium PNP fuzz
+// references the battery's positive terminal to ground and runs a negative rail — measured over
+// the corpus, five packets do: `dallas-arbiter-fuzz-face-ac128`,
+// `dallas-rangemaster-original-treble-booster`, `sola-sound-mki-tone-bender`,
+// `sola-sound-tone-bender-professional-mkii`, and `maestro-fz-1a` at **-1.5 V**. Get that sign
+// wrong and the PNP stages never reach conduction, which is silence rather than a wrong tone.
+//
+// The reason a program carries this at all is that it is the one supply fact a *chain* needs:
+// two pedals on one physical supply must agree about which terminal is ground, and a chain of
+// programs is where that can be checked (`src/runtime/supply-ground.ts`). It is not a
+// simulation input — each program is solved against its own declared rails either way.
+/**
+ * Read from the lowered `dc-source` stamps rather than the declared `rail`/`battery` devices,
+ * for the same reason `over-driven-node.ts` reads stamps: lowering is what collapses a
+ * redundant pair of supply declarations into one source, and the stamps are what the runtime
+ * executes and the deck is emitted from.
+ *
+ * Zero-volt sources are ignored. A `0 V` source is a ground tie, not a supply, and counting it
+ * would make an unpowered circuit look powered.
+ *
+ * **`dual-rail` is not the same as `positive-ground`, and conflating them would be the whole
+ * bug.** `klon-centaur` (`+9`, `+18`, `-9`) and `earthquaker-devices-plumes` (`+9`, `-9`) each
+ * derive a negative rail from a charge pump inside an ordinary center-negative pedal, so their
+ * *external* supply is the same as every other pedal's. What matters for a shared supply is
+ * whether a positive rail exists at all, which is why the chain rule below is stated that way
+ * and not as "positive-ground versus everything".
+ */
+export function supplyReference(blocks) {
+    let positive = false;
+    let negative = false;
+    for (const block of blocks) {
+        if (block.kind !== "mna") {
+            continue;
+        }
+        for (const stamp of block.stamps) {
+            if (stamp.kind !== "dc-source") {
+                continue;
+            }
+            if (stamp.volts > 0) {
+                positive = true;
+            }
+            if (stamp.volts < 0) {
+                negative = true;
+            }
+        }
+    }
+    if (positive && negative) {
+        return "dual-rail";
+    }
+    if (positive) {
+        return "negative-ground";
+    }
+    if (negative) {
+        return "positive-ground";
+    }
+    return "unpowered";
+}
+//# sourceMappingURL=supply-reference.js.map

package/dist/supply-reference.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"supply-reference.js","sourceRoot":"","sources":["../src/supply-reference.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,EAAE;AACF,2FAA2F;AAC3F,2FAA2F;AAC3F,6FAA6F;AAC7F,2FAA2F;AAC3F,uCAAuC;AACvC,EAAE;AACF,8FAA8F;AAC9F,gGAAgG;AAChG,iEAAiE;AACjE,8EAA8E;AAC9E,+FAA+F;AAC/F,8FAA8F;AAC9F,EAAE;AACF,8FAA8F;AAC9F,8FAA8F;AAC9F,sFAAsF;AACtF,uFAAuF;AAIvF;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,eAAe,CAC9B,MAAwB;IAExB,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC5B,IAAI,KAAK,CAAC,IAAI,KAAK,KAAK,EAAE,CAAC;YAC1B,SAAS;QACV,CAAC;QACD,KAAK,MAAM,KAAK,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;YAClC,IAAI,KAAK,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;gBAChC,SAAS;YACV,CAAC;YACD,IAAI,KAAK,CAAC,KAAK,GAAG,CAAC,EAAE,CAAC;gBACrB,QAAQ,GAAG,IAAI,CAAC;YACjB,CAAC;YACD,IAAI,KAAK,CAAC,KAAK,GAAG,CAAC,EAAE,CAAC;gBACrB,QAAQ,GAAG,IAAI,CAAC;YACjB,CAAC;QACF,CAAC;IACF,CAAC;IACD,IAAI,QAAQ,IAAI,QAAQ,EAAE,CAAC;QAC1B,OAAO,WAAW,CAAC;IACpB,CAAC;IACD,IAAI,QAAQ,EAAE,CAAC;QACd,OAAO,iBAAiB,CAAC;IAC1B,CAAC;IACD,IAAI,QAAQ,EAAE,CAAC;QACd,OAAO,iBAAiB,CAAC;IAC1B,CAAC;IACD,OAAO,WAAW,CAAC;AACpB,CAAC"}

package/dist/supply-short.d.ts

@@ -0,0 +1,32 @@
+import type { Netlist, SupplyShortWarning } from "./types";
+/**
+ * A diode whose **anode sits on a supply node and whose cathode sits on ground** is forward
+ * biased by the whole supply. In a real circuit that is a dead short: the junction conducts
+ * until something fails.
+ *
+ * The runtime does not diverge on it, which is why this went unseen. `DIODE_VOLTAGE_LIMIT` caps
+ * the junction voltage at `0.9 V` before the current is computed, so instead of running away the
+ * diode settles at about **1 A** — and the supply is an ideal source, so it simply sinks that
+ * current and the pedal renders a plausible level. `ibanez-ts808` renders a gain of `0.506` with
+ * a 1 A short on its rail. The clamp is a convergence device that turned out to be hiding a
+ * circuit defect, which is the same shape as several other masks found the same day.
+ *
+ * **Directness is required, and it is what makes this precise.** The check asks that the anode
+ * be *on* a node a `voltage-source` or `rail` device terminates, and the cathode be ground
+ * itself. An indicator LED fed through a series resistor does not match, because its anode sits
+ * on the resistor's node rather than the supply's — so the common legitimate arrangement is
+ * excluded by construction rather than by a special case.
+ *
+ * Measured over the pedal corpus: **6 diodes across 6 packets** match structurally, of which the
+ * two that compile carry `1.074 A` each. The other four are in the unsupported population, so
+ * they are flagged the moment their packets compile.
+ *
+ * The warning states the structure and the polarity, and does **not** claim the source is wrong.
+ * A protection diode reversed in the source and a protection diode this pipeline has mis-read
+ * look identical from here; what makes it reportable is that either way the compiled circuit
+ * contains a short. Checked on `ibanez-ts808`: the source itself declares `anode` on the 9 V
+ * node and `cathode` on ground, so the role reading is not at fault there — but that is a
+ * per-packet finding rather than something this stage should assert.
+ */
+export declare function findSupplyShorts(netlist: Netlist): readonly SupplyShortWarning[];
+//# sourceMappingURL=supply-short.d.ts.map

package/dist/supply-short.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"supply-short.d.ts","sourceRoot":"","sources":["../src/supply-short.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAU,OAAO,EAAU,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAM3E;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,gBAAgB,CAC/B,OAAO,EAAE,OAAO,GACd,SAAS,kBAAkB,EAAE,CAuD/B"}