@vessel-dsp/compiler 0.0.0-stage → 0.3.0

package/dist/device-laws.d.ts

@@ -0,0 +1,237 @@
+import { type PartRegistry, type PartSection } from "./registry";
+import type { FirmwareClass } from "./firmware-class";
+import type { Block, Device, DeviceResolution, ElectricallyIsolatedIcWarning, IcNotExecutedWarning, LawedNetlist, OpenIcGapClass, UnimplementedDeviceLawWarning, Netlist, NodeId } from "./types";
+/** Room-temperature thermal voltage; the diode law needs a reference somewhere. */
+export declare const THERMAL_VOLTAGE = 0.025852;
+/**
+ * Closed and open switch resistances. Not arbitrary: the ratio sets the matrix
+ * condition number, so 1e-2 to 1e9 is chosen to be electrically indistinguishable
+ * from ideal at audio levels while staying far from the solver's precision limit.
+ */
+export declare const SWITCH_ON_OHMS = 0.01;
+/**
+ * The terminal a jack's switch contact makes against, and the terminal a supply calls
+ * its return. Closed sets, compared whole.
+ *
+ * There is deliberately **no set of contact role names**. The corpus names switch
+ * contacts eleven ways (`batterySwitch`, `switch`, `switched`, `contact_top`,
+ * `normalSwitch`, `switch_black`, ...) and they do not share a sense: a battery contact
+ * makes against the sleeve, a `switched_tip` makes against the tip, and a `normalSwitch`
+ * on a stereo output *breaks* when a plug goes in. A name table gets the sense wrong on
+ * two of those three, and closing a signal contact to the sleeve shorts it to ground.
+ * See `portEngage` for what is derived instead.
+ */
+/**
+ * Series impedance of a pedal supply, in ohms: the **default position of what belongs to a
+ * user-selectable power profile**, not a physical claim about one cell.
+ *
+ * Decided by Joseph, 2026-08-13: source impedance is an *input profile on the UI*, alongside the
+ * other things a player chooses about how a pedal is fed. A fresh alkaline, a sagging one and a
+ * regulated adapter are three profiles a user picks between, so this stage does not have to guess
+ * which the packet meant — a question that has no answer, since a schematic draws a 9 V battery
+ * symbol and internal resistance is a property of the cell rather than of the drawing.
+ *
+ * Until that control exists, this is the default, and it is the low end of the plausible range so
+ * the default errs toward the ideal behaviour it replaces: a fresh 9 V alkaline measures 1-2 ohms,
+ * a depleted one tens, an adapter well under one. Measured, one ohm moves a working pedal's rail by
+ * about 10 mV — `boss-bd-2-blues-driver` by `9.9 mV`, `boss-ge-7` by `19 mV` — and the corpus's
+ * ngspice agreement is unchanged at 31.
+ *
+ * **What zero cost.** Zero is the one value known to be wrong, since no real supply has it, and it
+ * let a supply deliver unbounded current: `ibanez-ts808` drew **193 A** through the short
+ * `diode-forward-across-supply` warns about and still rendered a plausible gain of 0.506. One ohm
+ * collapses that rail instead, which is also what let the diode's `limitJunction` land after two
+ * reverts.
+ *
+ * **Not a battery model.** It does not deplete and it does not tell an adapter from a cell. Both
+ * are the profile's job once it exists; this is the mechanism and one defensible default.
+ */
+export declare const SUPPLY_SOURCE_OHMS = 1;
+export declare const SILICON_SATURATION_CURRENT = 1e-14;
+export declare const SILICON_FORWARD_BETA = 100;
+/**
+ * The JFET law's own parameters when the source types neither `Vt0` nor `Beta`. Not a part: no
+ * datasheet in the corpus prints these, and a 2N5952 or 2SK30A whose document leaves them untyped
+ * runs on them regardless of its grade. Exported so `compile.ts` can name every device that does
+ * (`fet-law-default-parameters`) against the values actually stamped, not a second copy.
+ */
+export declare const JFET_DEFAULT_THRESHOLD_VOLTS = -2;
+export declare const JFET_DEFAULT_TRANSCONDUCTANCE = 0.001;
+/** How a supply names the terminal current comes back to. */
+export declare const SWITCH_OFF_OHMS = 1000000000;
+export declare function attachDeviceLaws(netlist: Netlist, registry: PartRegistry): LawedNetlist;
+/**
+ * A multi-section part as one device per section, or `null` when the part is not multi-section.
+ *
+ * Each section device carries only the terminals that section uses, in the order the registry gave
+ * them, and its `identity.terminalRoles` are the canonical role names for its law's arity. That is
+ * what lets lowering treat it as an ordinary device: a section of a dual op-amp is indistinguishable
+ * from a packet that declared that half as its own `opamp` component, which is how the packets that
+ * already compile transcribe the same chip.
+ *
+ * A section naming a terminal the device does not have is a registry error and refuses the pedal,
+ * rather than silently dropping a section and rendering half a circuit.
+ */
+/**
+ * A single-section `voltage-source` model on a regulator or converter that declares which terminal
+ * is its output and which is its reference, resolved from those declarations.
+ *
+ * `null` whenever the document does not settle it: a different law, more than one section, a kind
+ * whose format vocabulary has no supply electrodes, or an output/reference role declared zero or
+ * several times. Every one of those falls through to the entry's pin naming exactly as before.
+ */
+export declare function declaredRegulatorTerminals(device: Device, model: {
+    readonly kind: "sections" | "sections-core";
+    readonly sections: readonly PartSection[];
+}): ReadonlyArray<readonly [Device, DeviceResolution]> | null;
+/**
+ * Is every one of this device's nodes private to itself — touched by no other device and
+ * never ground?
+ *
+ * A component that shares no net with anything cannot affect the solve, however it would
+ * have been modelled: physically, a disconnected chip does nothing. Refusing the whole
+ * pedal for it is over-strict; several packets deliberately carry such blocks as declared
+ * view-only power clusters (klon-centaur's `MAX1044_CLUSTER_VIEW_ONLY` draws the charge
+ * pump on four nodes nothing else touches, and separately declares the rails it produces
+ * as voltage-carrying ports — its own record says "not a solved terminal charge-pump
+ * model"). The resolution is `open` plus a LOUD compile warning, so a cluster isolated by
+ * a wiring mistake rather than by intent is still named, never silently swallowed.
+ *
+ * Deliberately narrow: ONE shared node — even ground — defeats it. pigtronix's LT1054
+ * drives a diode-doubler from its switching pin, shares nets, and keeps refusing.
+ */
+export declare function isElectricallyIsolated(device: Device, devicesTouchingNode: ReadonlyMap<NodeId, number>): boolean;
+/** How many devices touch each node, counting a device once however many terminals it lands. */
+export declare function deviceCountByNode(netlist: Netlist): Map<NodeId, number>;
+/**
+ * An OTA whose four signal connections come from the **DIP-8 package order** rather than from
+ * anything the document states about its electrodes.
+ *
+ * Exported so `findUnreadableTerminalRoles` can report exactly the devices this fallback catches,
+ * instead of mirroring its condition. A warning kept on a different test from the resolver it
+ * guards is how a silent mis-wiring was introduced once already in this compiler, on a switch,
+ * and the same shape would be available here: the fallback needs eight all-null *names*, and a
+ * predicate that asked about declared roles instead would report a different set of devices.
+ *
+ * The assumption itself is sound and deliberate -- reading a role-less eight-terminal shell as its
+ * package beats reading positions 0..3, which puts the output on pin 3. It is still an assumption
+ * the source does not make, which is the whole reason it should say so out loud.
+ */
+export declare function otaPackageOrderAssumed(device: Device): boolean;
+/**
+ * The devices opened by `declaresUnimplementedDeviceLaw`, so a packet is told which stated device
+ * is absent from its program rather than silently receiving the nearest law.
+ */
+export declare function findUnimplementedDeviceLaws(lawed: LawedNetlist): readonly UnimplementedDeviceLawWarning[];
+/**
+ * Every integrated circuit the source declares and the program does not execute.
+ *
+ * **A residue reporter, deliberately.** It does not ask the five opening predicates their
+ * questions again -- it reads the reason `resolveDevice` recorded when it chose the `open`. So a
+ * sixth opening path added later is reported the day it is added, as `unrecorded`, instead of
+ * joining the silent class this exists to close; and no copy of a resolver's question can drift
+ * from the resolver, which is the defect that bit this file twice on 2026-09-03.
+ *
+ * `electrically-isolated` is excluded because `findElectricallyIsolatedIcs` already names those
+ * devices and says more about them than this could. The exclusion is on the recorded decision, not
+ * on a re-run of `isElectricallyIsolated`, for the reason above.
+ *
+ * Runs after section expansion, which is what makes it safe: a package the registry could expand
+ * is no longer in `lawed.netlist.devices` at all, so a working dual op-amp cannot appear here.
+ * Non-IC opens are out of scope and stay so -- a ground symbol and an unwired jack contact carry
+ * no element because the symbol has none, which is not a hole in the model.
+ */
+/**
+ * `digital-delay-line` as a composition of primitives (board-p3 row 4):
+ * an integer delay line plus one multiply-accumulate for the feedback mix.
+ *
+ * The op order mirrors the kernel's own evaluation order exactly -- read the
+ * delayed sample, publish it, write back tap plus feedback times delayed --
+ * so the interpreter reproduces its bits rather than approximating them.
+ * Length-mode priority mirrors the kernel's branch priority (clock control,
+ * then parameter port, else capacity). Returns `null` for anything but this
+ * model, and for a block carrying `modulation`, which the kernel has no
+ * branch for: there is no faithful composition of a port the kernel ignores.
+ */
+export declare function decomposeDigitalDelayLine(block: Extract<Block, {
+    kind: "macro";
+}>): Extract<Block, {
+    kind: "composed";
+}> | null;
+/**
+ * `bucket-brigade-delay-line` as a composition of primitives (board-p3
+ * row 4): input coupling estimator, fractionally interpolated delay line,
+ * write-back.
+ *
+ * Op order mirrors the kernel exactly -- couple the tap to AC, read the
+ * delayed sample with linear interpolation, publish it, write the AC back --
+ * and length priority mirrors its branches (clock, clock-law, modulation,
+ * parameter).
+ *
+ * Deliberately no `converter` op: the shipped kernel performs no conversion
+ * stage (no companding, no quantization -- `grep compand` finds a device
+ * law and comments), so a bit-identical decomposition has nowhere to put
+ * one. The enum gains `converter` when a decomposition needs it, not before.
+ */
+export declare function decomposeBucketBrigadeDelayLine(block: Extract<Block, {
+    kind: "macro";
+}>): Extract<Block, {
+    kind: "composed";
+}> | null;
+/**
+ * `digital-reverb-module` as a composition of primitives (board-p3 row 4):
+ * four parallel feedback combs averaged, two series allpass diffusers,
+ * output gain. A Schroeder reverb, which is what the kernel is.
+ *
+ * Arithmetic mirrors the kernel term for term: combs accumulate
+ * left-to-right then scale by exactly one quarter (a power of two, so the
+ * multiply rounds like the kernel's divide), allpasses keep the kernel's
+ * multiply order. The kernel has no clock, parameter, or modulation
+ * branches, so those ports are dropped rather than carried -- carrying a
+ * port the kernel ignores would imply behaviour the composition does not
+ * have. `decaySeconds` travels per comb op; the echo-density tables and
+ * the allpass coefficient stay interpreter-owned, exactly as today.
+ */
+export declare function decomposeDigitalReverbModule(block: Extract<Block, {
+    kind: "macro";
+}>): Extract<Block, {
+    kind: "composed";
+}> | null;
+/**
+ * Emit compositions for the three decomposed models, passthrough for
+ * everything else (board-p3 row 4, the flip). Called once per program after
+ * `couple` wires ports: decompositions read fully-resolved blocks, so an
+ * earlier flip would compose unwired placeholders. A `null` decomposition
+ * (a port the kernel ignores, a model outside the three) keeps the macro
+ * block rather than failing the program.
+ */
+export declare function composeMacroBlocks(blocks: readonly Block[]): readonly Block[];
+/**
+ * Which phase-3 bucket a gap-candidate open IC belongs in (board-p3 row 1).
+ *
+ * Pure over typed and structural evidence only: the entry's `firmwareClass`
+ * (compared whole-value, never prose) and whether the chip shares a net with
+ * a device the program executes. `fixed-function` means no program is
+ * missing, so the only question left is what covers the chip's behaviour: an
+ * executing macro (memory inside a delay kernel, e.g. a 4164 behind an
+ * M50195P) or an executing law (a redundant view of modelled behaviour, e.g.
+ * a single-terminal divider placeholder on an executing divider's clock
+ * net). Everything else stays `programmable-no-program` -- including
+ * `undetermined` firmware, which is an open question rather than evidence of
+ * a fixed function, so the phase-3 set keeps the row until proven otherwise.
+ */
+export declare function classifyOpenIcGap(input: {
+    readonly firmwareClass: FirmwareClass;
+    readonly sharesNodeWithExecutedMacro: boolean;
+    readonly sharesNodeWithExecutedLaw: boolean;
+}): OpenIcGapClass;
+export declare function findIcsNotExecuted(lawed: LawedNetlist, original: Netlist, registry: PartRegistry): readonly IcNotExecutedWarning[];
+/**
+ * The loud half of `isElectricallyIsolated`: every identification-requiring device whose
+ * nodes are all private got an `open` law instead of a refusal, and each one is named here
+ * so a cluster isolated by a wiring mistake rather than by intent is never silently
+ * swallowed. Runs over the ORIGINAL netlist (pre-section-expansion), because isolation is a
+ * property of the drawn component, not of a registry section.
+ */
+export declare function findElectricallyIsolatedIcs(netlist: Netlist): readonly ElectricallyIsolatedIcWarning[];
+//# sourceMappingURL=device-laws.d.ts.map

package/dist/device-laws.d.ts.map

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