@vessel-dsp/runtime 0.2.0

package/dist/chain-advisories.js

@@ -0,0 +1,268 @@
+// What a chain can say about itself that no single program can.
+//
+// `ChainRuntime` scales between slots by the ratio of one slot's output full scale to the next
+// slot's input full scale (`Program.portFullScaleVolts`, derived in
+// `../compiler/port-full-scale.ts`). When either side is `null` the program did not state a
+// supply to derive the bound from, so there is no ratio to apply and the signal crosses at 1.0 --
+// which is the old behaviour, and is a guess about level rather than a statement about it.
+//
+// It then applies the **impedance divider** at the same seam (`seamDivider`), which is a different
+// question from the same connection: full scale says what units a number is in, loading says how
+// much of the signal survives the connection at all. Both default to 1 when unstated, and neither
+// invents a figure.
+//
+// Advisory rather than fail-closed, the same shape as `./supply-ground.ts`: the chain still runs,
+// and what is missing is a source fact, not a runtime capability.
+/**
+ * How far along the amplification path each coverage sits, so a rule can say "at or beyond" instead
+ * of naming one value and silently missing the others.
+ *
+ * Introduced because `speaker-signal-into-input` tested `produces === "speaker-electrical"` and
+ * therefore let **`miked` into an instrument input pass in silence** -- a full-rig capture feeding a
+ * pedal, which is the same kind error one rung further along. Ordering the vocabulary is what makes
+ * that class of miss impossible rather than a thing to remember.
+ */
+const COVERAGE_RANK = {
+    instrument: 0,
+    preamp: 1,
+    "speaker-electrical": 2,
+    miked: 3,
+};
+/**
+ * Seams where one side states no full scale. Pure, so a host can ask before playing.
+ *
+ * A one-slot chain has no seam and never reports.
+ */
+export function chainAdvisories(chain) {
+    const advisories = [];
+    for (let slot = 1; slot < chain.length; slot += 1) {
+        const upstream = chain[slot - 1]?.portFullScaleVolts.output ?? null;
+        const downstream = chain[slot]?.portFullScaleVolts.input ?? null;
+        if (upstream !== null && downstream !== null) {
+            continue;
+        }
+        const missing = upstream === null && downstream === null
+            ? "neither side"
+            : upstream === null
+                ? `slot ${slot - 1}'s output`
+                : `slot ${slot}'s input`;
+        advisories.push({
+            code: "unscalable-seam",
+            slots: [slot - 1, slot],
+            message: `between slot ${slot - 1} and slot ${slot}, ${missing} states a full-scale ` +
+                "voltage, so the signal crosses unscaled: a level mismatch here is not corrected " +
+                "and the receiving slot may be driven far above or below what it expects. The " +
+                "bound is derived from the program's own supplies, so a program declaring none " +
+                "cannot supply one",
+        });
+    }
+    // **A speaker terminal is not an instrument signal.** `speaker-electrical` means the output node
+    // *is* the transformer secondary -- tens of volts across an 8 or 16 ohm load, not the fraction of
+    // a volt a jack expects. Feeding that to a slot that wants instrument level is wrong in kind as
+    // well as level, and it is the shape of mistake that put an amp's preamp tap and another amp's
+    // speaker terminal in the same "plausible" column for a day.
+    //
+    // **Narrowed to what the receiver expects.** This used to fire whenever a `speaker-electrical`
+    // output fed *anything*, which would report the single most ordinary amp chain there is: an amp
+    // into a cabinet. A cab stage is exactly what a speaker terminal is for.
+    //
+    // **"At or beyond a speaker terminal", not "is a speaker terminal".** The first version of this
+    // tested one value and let `miked` through: a full-rig capture into a pedal reported nothing,
+    // though it is the same error one rung further along. `COVERAGE_RANK` is what closes that.
+    for (let slot = 1; slot < chain.length; slot += 1) {
+        const produces = chain[slot - 1]?.produces;
+        if (produces === undefined ||
+            COVERAGE_RANK[produces] < COVERAGE_RANK["speaker-electrical"]) {
+            continue;
+        }
+        if (chain[slot]?.expects !== "instrument") {
+            continue;
+        }
+        advisories.push({
+            code: "speaker-signal-into-input",
+            slots: [slot - 1, slot],
+            message: `slot ${slot - 1} produces a ${produces} signal -- at or past the speaker terminal -- ` +
+                `and it feeds slot ${slot}, whose input expects an instrument-level signal: this is a ` +
+                "difference of kind, not only of level, and no scaling makes it a valid connection",
+        });
+    }
+    // **The other direction is milder, and deliberately narrower.** A cabinet stage fed a signal that
+    // never passed a power amp is thin rather than wrong -- nothing is over-driven and nothing is
+    // damaged -- so it is reported, not treated as a kind error.
+    //
+    // **`preamp` is excluded on purpose, and that exclusion is load-bearing.** A preamp into an
+    // impulse response is an established, ordinary rig, and `mesa-boogie-mark-v` renders `preamp`
+    // coverage precisely because the signal-chain plan's decision 2 says to honour its declared
+    // handoff. Firing here on rank 1 would report that decision as a mistake on every chain.
+    //
+    // So only rank 0 into a speaker-terminal stage reports: an instrument-level signal with no
+    // amplification of any kind between it and a cabinet.
+    for (let slot = 1; slot < chain.length; slot += 1) {
+        const produces = chain[slot - 1]?.produces;
+        const expects = chain[slot]?.expects;
+        if (produces === undefined || expects === undefined) {
+            continue;
+        }
+        if (COVERAGE_RANK[produces] !== COVERAGE_RANK.instrument ||
+            COVERAGE_RANK[expects] < COVERAGE_RANK["speaker-electrical"]) {
+            continue;
+        }
+        advisories.push({
+            code: "instrument-into-speaker-stage",
+            slots: [slot - 1, slot],
+            message: `slot ${slot} expects a ${expects} signal -- one that has passed a power amp -- and ` +
+                `slot ${slot - 1} produces instrument level with no amplification stage between ` +
+                "them: the chain runs, but the cabinet colours a signal that never saw a power " +
+                "stage, which is audibly thin rather than incorrect",
+        });
+    }
+    // **A miked signal must not be miked again.** Now expressible, because the cabinet is a slot:
+    // two consecutive slots both *producing* `miked` means a cab stage was applied to a signal that
+    // already carries one.
+    //
+    // This is the only warnable cab arrangement, and deliberately so. A NAM amp capture produces
+    // `speaker-electrical`, so NAM into an IR is silent -- it is what most people do. A whitebox
+    // amp into an IR is silent for the same reason. **No cab stage at all is silent too**: a full-rig
+    // NAM, or a player who wants none, is a complete chain and nothing here should nag for one.
+    for (let slot = 1; slot < chain.length; slot += 1) {
+        if (chain[slot - 1]?.produces !== "miked" ||
+            chain[slot]?.produces !== "miked") {
+            continue;
+        }
+        advisories.push({
+            code: "cab-after-miked",
+            slots: [slot - 1, slot],
+            message: `slot ${slot - 1} already produces a miked signal -- a full-rig capture, or a ` +
+                `cabinet stage -- and slot ${slot} applies another one: the cabinet and microphone ` +
+                "colour the signal twice, which is audible as a hollow, over-filtered tone rather " +
+                "than a level error",
+        });
+    }
+    // **Only the asymmetric case is worth a word.** A divider needs an impedance on both sides, and
+    // the two ways it can be missing are not equally interesting:
+    //
+    //   - *Neither side declares* — the ordinary state of every corpus document today, and reporting
+    //     it would be a line of noise on every seam of every chain. Silence.
+    //   - *Either side is a processor* — a NAM or an IR has no impedance to declare, so there is
+    //     nothing missing. Silence, and this is why `portImpedanceOhms` is nullable as a whole
+    //     object rather than only per port.
+    //   - *One electrical side declares and the other does not* — someone measured half of a real
+    //     interaction and the other half silently defaulted to no loading at all. That is worth
+    //     naming, because the declared number looks like it is doing something and is not.
+    for (let slot = 1; slot < chain.length; slot += 1) {
+        const source = chain[slot - 1]?.portImpedanceOhms;
+        const load = chain[slot]?.portImpedanceOhms;
+        if (source === null ||
+            source === undefined ||
+            load === null ||
+            load === undefined) {
+            continue;
+        }
+        const out = source.output;
+        const inn = load.input;
+        if ((out === null) === (inn === null)) {
+            continue;
+        }
+        advisories.push({
+            code: "undividable-seam",
+            slots: [slot - 1, slot],
+            message: out === null
+                ? `slot ${slot} declares a ${inn} Ω input impedance but slot ${slot - 1} declares ` +
+                    "no output impedance, so no loading is applied and the declared figure has no " +
+                    "effect: a low input impedance is meant to load what drives it"
+                : `slot ${slot - 1} declares a ${out} Ω output impedance but slot ${slot} declares ` +
+                    "no input impedance, so the signal crosses without loading and the declared " +
+                    "figure has no effect",
+        });
+    }
+    return advisories;
+}
+/**
+ * Bypass requested on a packet that declares no bypass switch.
+ *
+ * `audio.bypass: "none"` is a declared absence (37 core-only lanes + 1 passive volume, 38 total
+ * after backfill) — not a missing field. A chain "bypass" on such a slot has nothing in the
+ * circuit to mean; wire is the only honest choice, and the slot must say so via advisory, not
+ * log. Hard-coded to the Program's carried declaration when present; missing field (pre-backfill
+ * programs) is treated as "switch" (has bypass) until Y lands `program.bypass`.
+ */
+export function bypassNotModelledAdvisories(slots) {
+    const advisories = [];
+    for (let idx = 0; idx < slots.length; idx++) {
+        const slot = slots[idx];
+        if (slot === undefined || slot.kind !== "program")
+            continue;
+        const bypassMode = slot.bypassMode ?? "effect";
+        if (bypassMode !== "wire" && bypassMode !== "buffer")
+            continue;
+        const bypass = slot.program.bypass;
+        if (bypass.declared === "none") {
+            advisories.push({
+                code: "bypass-not-modelled",
+                slots: [idx, idx],
+                message: `slot ${idx} bypass not modelled by this packet; slot is wired through (audio.bypass: "none" — declared absence, not a guess)`,
+            });
+        }
+        else if (bypass.kind === "not-in-audio-path") {
+            advisories.push({
+                code: "bypass-not-modelled",
+                slots: [idx, idx],
+                message: `slot ${idx} bypass switch is not in the audio path; slot is wired through`,
+            });
+        }
+    }
+    return advisories;
+}
+/**
+ * The multiplier applied to the signal crossing into `slot`.
+ *
+ * Two independent factors, multiplied:
+ *
+ *   - the **full-scale ratio**, converting between the two slots' own voltage normalisations, or 1
+ *     where either side states no supply to derive a bound from;
+ *   - the **impedance divider** `Zin / (Zout + Zin)`, the loading one slot's input puts on the
+ *     previous slot's output, or 1 where either electrical side declares none.
+ *
+ * They are separate questions and neither substitutes for the other: full scale is about the units
+ * a number is in, loading is about how much of the signal survives the connection. A seam can scale
+ * and not divide, or divide and not scale.
+ */
+export function seamScale(chain, slot) {
+    const upstream = chain[slot - 1]?.portFullScaleVolts.output ?? null;
+    const downstream = chain[slot]?.portFullScaleVolts.input ?? null;
+    const ratio = upstream === null || downstream === null || downstream === 0
+        ? 1
+        : upstream / downstream;
+    return ratio * seamDivider(chain, slot);
+}
+/**
+ * The resistive divider at a seam, or `1` when it cannot be computed.
+ *
+ * **Resistive and one-directional, which is a stated approximation rather than an oversight.** Real
+ * interaction between two stages is bidirectional and frequency-dependent, and only co-solving the
+ * adjacent blocks captures it -- the fidelity ceiling the unified plan §5.3 names and this
+ * deliberately does not attempt. What this does capture is the audible first-order half: a fuzz with
+ * a low input impedance loads the pickup or the pedal ahead of it, which is a large part of what that
+ * pedal *is*.
+ *
+ * **No default is invented anywhere.** A missing impedance yields 1, never an assumed "standard
+ * 1 MΩ input" -- a fabricated convention would be indistinguishable from a measurement in every
+ * downstream number. Measured on the corpus as of 2026-08-21 that means this returns 1 for every
+ * seam: **zero input jacks declare a typed impedance**, and the only four declarations anywhere are
+ * output impedances (`marshall-blues-breaker` 1 MΩ, `mxr-m117r-flanger` 1 kΩ,
+ * `mxr-noise-gate-line-driver` 10 kΩ, `pigtronix-philosophers-tone` 150 Ω). The mechanism is
+ * therefore inert until sources carry the input side, and `undividable-seam` is what says so out
+ * loud on a chain built from one of those four.
+ */
+export function seamDivider(chain, slot) {
+    const source = chain[slot - 1]?.portImpedanceOhms;
+    const load = chain[slot]?.portImpedanceOhms;
+    const out = source?.output ?? null;
+    const inn = load?.input ?? null;
+    if (out === null || inn === null) {
+        return 1;
+    }
+    const total = out + inn;
+    return total <= 0 ? 1 : inn / total;
+}
+//# sourceMappingURL=chain-advisories.js.map

package/dist/chain-advisories.js.map

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

package/dist/chain-scale.d.ts

@@ -0,0 +1,82 @@
+import type { Program } from "@vessel-dsp/compiler";
+/**
+ * Pure arithmetic: the multiplier `ChainRuntime` applies to one boundary's samples, from the
+ * two adjacent ports' full-scale voltages. `null` on either side is unity — see this
+ * module's header for why that is not a refusal.
+ */
+export declare function chainScaleFactor(outFullScaleVolts: number | null, inFullScaleVolts: number | null): number;
+/** One boundary where the chain fell back to unity because a full scale was `null`. */
+export type ChainScaleAdvisory = {
+    /** The boundary sits between this slot and the next. */
+    readonly slot: number;
+    readonly message: string;
+};
+/**
+ * Every boundary in an ordered chain where at least one side's full-scale voltage is `null`,
+ * so `ChainRuntime` applied unity there instead of the declared ratio.
+ *
+ * Mirrors `supplyGroundConflicts`'s shape deliberately: a chain-level fact, computed from
+ * the programs alone, carried alongside a successful load rather than blocking one.
+ */
+export declare function chainScaleAdvisories(programs: readonly Program[]): readonly ChainScaleAdvisory[];
+/**
+ * The multiplier the **worklet** applies to the chain's last slot before the samples reach the
+ * DAC, so a program that swings to its supply rail does not peg the output against it.
+ *
+ * **This lives here because it was living in exactly one place and that place was not reachable
+ * from a report.** It was inline in `src/web/v2-audio-worklet.ts`, which no instrument imports, so
+ * every corpus measurement was taken on the program's output in volts while the app played that
+ * output divided by up to 558.61 (`marshall-1959-super-lead-plexi`). A packet could read a healthy
+ * 5e-3 V and reach the speaker at -101 dBFS. Both halves have to read the same rule or the
+ * measurement is not of the product.
+ *
+ * Unity below 1.0 V rather than a gain: this normalises a rail down, it never boosts a quiet
+ * program up to meet the ceiling.
+ */
+export declare function dacScaleFactor(fullScaleOutVolts: number | null): number;
+/**
+ * A program's output level in the domain a listener is in: dBFS at the DAC, after
+ * `dacScaleFactor`.
+ *
+ * **Volts and dBFS are not interchangeable and the corpus has been treating them as if they
+ * were.** `report-input-dependence.ts`'s `AUDIBLE_FLOOR` comment reconciles its absolute-volts bar
+ * against a tier's `-50 dBFS` one by taking "full scale 1.0" -- true of no packet in the corpus,
+ * where the declared full scale runs 4.5 V to 558.61 V. Converted through the rule the app
+ * actually applies, a single volts threshold is a different dBFS bar for every packet: 1e-3 V is
+ * -60 dBFS at full scale 1.0, -79 dBFS on a 9 V pedal and -115 dBFS on the plexi.
+ */
+export declare function outputDbfs(rmsVolts: number, fullScaleOutVolts: number | null): number;
+/**
+ * The number a level conversion divides an output by: the port's declared 0 dBFS
+ * reference where it states one, the derived ceiling for speaker-electrical outputs,
+ * or the instrument operating reference convention.
+ *
+ * These are different quantities -- `link.ts` says so and keeps them apart -- and a folding
+ * consumer has to pick the one its question needs. A conversion into a level (a +/-1 file,
+ * a DAC scale, a dBFS audibility judgement) wants the **reference** where a source states it:
+ * it is what the source says full scale *means* rather than what the node can reach.
+ *
+ * For `speaker-electrical` stage coverage (power amp secondary into speaker tap), the
+ * transformer-stepped ceiling (30 V to 500 V) is physically right to prevent DAC wrapping.
+ *
+ * For `instrument` stage coverage (stompboxes/pedals), the DC supply rail (e.g. 9 V) is an
+ * electrical clipping ceiling, never an operating reference level. Falling back to the rail
+ * caused pedals without an explicit output reference to play 19 dB quieter than input
+ * (0.3 V / 9 V = -29.5 dBFS). When no output reference is declared:
+ * 1. Read `portReferenceVolts.input` if declared (preserving the pedal's declared operating scale).
+ * 2. Fall back to 1.0 V, the convention matching digital full scale (1.0 digital = 1.0 V),
+ *    which is the median and mode of the declared corpus population (59 of 65 declared inputs).
+ */
+export declare function outputConversionFullScale(contract: {
+    readonly portFullScaleVolts: {
+        readonly input: number | null;
+        readonly output: number | null;
+    };
+    readonly portReferenceVolts?: {
+        readonly input: number | null;
+        readonly output: number | null;
+    };
+    readonly stageCoverage?: Program["stageCoverage"];
+    readonly produces?: Program["stageCoverage"];
+}): number | null;
+//# sourceMappingURL=chain-scale.d.ts.map

package/dist/chain-scale.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chain-scale.d.ts","sourceRoot":"","sources":["../src/chain-scale.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAEpD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC/B,iBAAiB,EAAE,MAAM,GAAG,IAAI,EAChC,gBAAgB,EAAE,MAAM,GAAG,IAAI,GAC7B,MAAM,CAKR;AAED,uFAAuF;AACvF,MAAM,MAAM,kBAAkB,GAAG;IAChC,wDAAwD;IACxD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CACnC,QAAQ,EAAE,SAAS,OAAO,EAAE,GAC1B,SAAS,kBAAkB,EAAE,CAgB/B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,iBAAiB,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAEvE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAErF;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,yBAAyB,CACxC,QAAQ,EAAE;IACT,QAAQ,CAAC,kBAAkB,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IAC/F,QAAQ,CAAC,kBAAkB,CAAC,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IAChG,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC;IAClD,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC;CAC7C,GACC,MAAM,GAAG,IAAI,CAqBf"}

package/dist/chain-scale.js

@@ -0,0 +1,121 @@
+// The chain's level convention: multiply between slots by the ratio of declared full-scale
+// voltages, per the signal-chain plan
+// (thoughts/shared/plans/2026-08-21-signal-chain-and-amp-output-stage.md) §3.1 —
+//
+//   x_normalized(slot n+1) = y_normalized(slot n) * (fullScale(out n) / fullScale(in n+1))
+//
+// **Unity, not a refusal, when either side is `null`.** A program that declares no supply
+// gives `Program.ports` nothing to derive a ceiling from — see `../compiler/port-full-
+// scale.ts` — and the chain still has to produce audio: it is not wrong to play it, only
+// unable to say the boundary's level is correct. `chainScaleAdvisories` is the visible half
+// of that (structured, matching `../runtime/supply-ground.ts`'s pattern rather than a
+// console.warn), so a host can surface it without the render itself refusing.
+/**
+ * Pure arithmetic: the multiplier `ChainRuntime` applies to one boundary's samples, from the
+ * two adjacent ports' full-scale voltages. `null` on either side is unity — see this
+ * module's header for why that is not a refusal.
+ */
+export function chainScaleFactor(outFullScaleVolts, inFullScaleVolts) {
+    if (outFullScaleVolts === null || inFullScaleVolts === null) {
+        return 1;
+    }
+    return outFullScaleVolts / inFullScaleVolts;
+}
+/**
+ * Every boundary in an ordered chain where at least one side's full-scale voltage is `null`,
+ * so `ChainRuntime` applied unity there instead of the declared ratio.
+ *
+ * Mirrors `supplyGroundConflicts`'s shape deliberately: a chain-level fact, computed from
+ * the programs alone, carried alongside a successful load rather than blocking one.
+ */
+export function chainScaleAdvisories(programs) {
+    const advisories = [];
+    for (let slot = 0; slot < programs.length - 1; slot++) {
+        const out = programs[slot]?.portFullScaleVolts.output ?? null;
+        const nextIn = programs[slot + 1]?.portFullScaleVolts.input ?? null;
+        if (out === null || nextIn === null) {
+            advisories.push({
+                slot,
+                message: `slot ${slot}'s output or slot ${slot + 1}'s input declares no full-scale ` +
+                    "voltage (its program declares no supply), so the chain applies unity " +
+                    "scaling at this boundary instead of the declared ratio",
+            });
+        }
+    }
+    return advisories;
+}
+/**
+ * The multiplier the **worklet** applies to the chain's last slot before the samples reach the
+ * DAC, so a program that swings to its supply rail does not peg the output against it.
+ *
+ * **This lives here because it was living in exactly one place and that place was not reachable
+ * from a report.** It was inline in `src/web/v2-audio-worklet.ts`, which no instrument imports, so
+ * every corpus measurement was taken on the program's output in volts while the app played that
+ * output divided by up to 558.61 (`marshall-1959-super-lead-plexi`). A packet could read a healthy
+ * 5e-3 V and reach the speaker at -101 dBFS. Both halves have to read the same rule or the
+ * measurement is not of the product.
+ *
+ * Unity below 1.0 V rather than a gain: this normalises a rail down, it never boosts a quiet
+ * program up to meet the ceiling.
+ */
+export function dacScaleFactor(fullScaleOutVolts) {
+    return fullScaleOutVolts !== null && fullScaleOutVolts > 1.0 ? 1.0 / fullScaleOutVolts : 1.0;
+}
+/**
+ * A program's output level in the domain a listener is in: dBFS at the DAC, after
+ * `dacScaleFactor`.
+ *
+ * **Volts and dBFS are not interchangeable and the corpus has been treating them as if they
+ * were.** `report-input-dependence.ts`'s `AUDIBLE_FLOOR` comment reconciles its absolute-volts bar
+ * against a tier's `-50 dBFS` one by taking "full scale 1.0" -- true of no packet in the corpus,
+ * where the declared full scale runs 4.5 V to 558.61 V. Converted through the rule the app
+ * actually applies, a single volts threshold is a different dBFS bar for every packet: 1e-3 V is
+ * -60 dBFS at full scale 1.0, -79 dBFS on a 9 V pedal and -115 dBFS on the plexi.
+ */
+export function outputDbfs(rmsVolts, fullScaleOutVolts) {
+    return 20 * Math.log10(Math.max(rmsVolts * dacScaleFactor(fullScaleOutVolts), 1e-12));
+}
+/**
+ * The number a level conversion divides an output by: the port's declared 0 dBFS
+ * reference where it states one, the derived ceiling for speaker-electrical outputs,
+ * or the instrument operating reference convention.
+ *
+ * These are different quantities -- `link.ts` says so and keeps them apart -- and a folding
+ * consumer has to pick the one its question needs. A conversion into a level (a +/-1 file,
+ * a DAC scale, a dBFS audibility judgement) wants the **reference** where a source states it:
+ * it is what the source says full scale *means* rather than what the node can reach.
+ *
+ * For `speaker-electrical` stage coverage (power amp secondary into speaker tap), the
+ * transformer-stepped ceiling (30 V to 500 V) is physically right to prevent DAC wrapping.
+ *
+ * For `instrument` stage coverage (stompboxes/pedals), the DC supply rail (e.g. 9 V) is an
+ * electrical clipping ceiling, never an operating reference level. Falling back to the rail
+ * caused pedals without an explicit output reference to play 19 dB quieter than input
+ * (0.3 V / 9 V = -29.5 dBFS). When no output reference is declared:
+ * 1. Read `portReferenceVolts.input` if declared (preserving the pedal's declared operating scale).
+ * 2. Fall back to 1.0 V, the convention matching digital full scale (1.0 digital = 1.0 V),
+ *    which is the median and mode of the declared corpus population (59 of 65 declared inputs).
+ */
+export function outputConversionFullScale(contract) {
+    const declared = contract.portReferenceVolts?.output ?? null;
+    if (declared !== null && declared > 0) {
+        return declared;
+    }
+    const coverage = contract.stageCoverage ?? contract.produces;
+    if (coverage === "speaker-electrical") {
+        return contract.portFullScaleVolts.output;
+    }
+    if (coverage === "instrument") {
+        const inputRef = contract.portReferenceVolts?.input ?? null;
+        if (inputRef !== null && inputRef > 0) {
+            return inputRef;
+        }
+        return 1.0;
+    }
+    const inputRef = contract.portReferenceVolts?.input ?? null;
+    if (inputRef !== null && inputRef > 0) {
+        return inputRef;
+    }
+    return contract.portFullScaleVolts.output;
+}
+//# sourceMappingURL=chain-scale.js.map

package/dist/chain-scale.js.map

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

package/dist/chain-slot.d.ts

@@ -0,0 +1,130 @@
+import type { Program } from "@vessel-dsp/compiler";
+/** How far down the amplification chain a signal already is. The compiler's own vocabulary. */
+export type StageCoverage = Program["stageCoverage"];
+/**
+ * What the chain needs to know about a slot, whatever runs inside it.
+ *
+ * `Program` satisfies the produced/full-scale half structurally, which is deliberate: the seam
+ * arithmetic is identical for a compiled circuit and an injected processor, and writing it twice
+ * would be how the two drift apart.
+ */
+export type SlotContract = {
+    /** The coverage of this slot's **output**. */
+    readonly produces: StageCoverage;
+    /** The coverage this slot's **input** is meant to receive. */
+    readonly expects: StageCoverage;
+    readonly portFullScaleVolts: {
+        readonly input: number | null;
+        readonly output: number | null;
+    };
+    /**
+     * The port's declared 0 dBFS reference where the source states one, separate from the derived ceiling.
+     */
+    readonly portReferenceVolts?: {
+        readonly input: number | null;
+        readonly output: number | null;
+    };
+    /**
+     * Port impedances for the seam divider, or **`null` when this slot's ports are not electrical**.
+     *
+     * The two cases are different and must not collapse into one. A *circuit* seam with no declared
+     * impedance is **unknown** -- undeclared data, worth reporting once sources carry it. A
+     * *processor* seam has **nothing to declare**: a NAM capture already contains whatever loading
+     * existed when it was taken, and an impulse response or cab simulation is a filter rather than a
+     * source or a load. §3.2's own table says as much -- "IR / cabMic: unity, a filter, not a source".
+     *
+     * So a whole-object `null` means *not applicable*, and an inner `null` means *not stated*. Without
+     * that distinction the divider's advisory would fire on every NAM + cabinet chain, complaining
+     * about data that cannot exist.
+     */
+    readonly portImpedanceOhms: {
+        readonly input: number | null;
+        readonly output: number | null;
+    } | null;
+};
+/**
+ * A processor the host supplies: a NAM profile, an impulse response, the cab simulation.
+ *
+ * `process` takes one buffer and returns one buffer of the same length, sample-for-sample causal in
+ * the same sense `ReferenceRuntime.process` is -- the chain hands whole buffers between slots and
+ * relies on that.
+ *
+ * **A NAM amp capture declares `produces: "speaker-electrical"`, not `"miked"`.** A load-box
+ * capture is taken at the speaker terminal, which is what that value means -- the same coverage a
+ * whitebox amp's own output carries, so NAM + IR and amp + IR are one case rather than two. The great
+ * majority of captures on TONE3000 are taken through a reactive load box with no speaker and no
+ * microphone, precisely so the player adds their own IR, and NAM + IR is the ordinary chain. Only a
+ * profile that states it is a full-rig capture declares `miked`, and nothing here may infer that from
+ * a file name or a title.
+ */
+export type ExternalProcessor = SlotContract & {
+    /** Named in advisories and telemetry, since a processor has no program to point at. */
+    readonly id: string;
+    prepare(sampleRate: number): void;
+    process(buffer: Float64Array): Float64Array;
+};
+/**
+ * **Nothing here distinguishes a NAM from an IR, on purpose.** Both are buffer-in, buffer-out black
+ * boxes, so the seam arithmetic, the ordering and the advisories are identical; `id` is a label for
+ * messages, never a discriminator. What the chain asks is not *what kind of processor is this* but
+ * *what coverage does it produce* -- which is why a NAM amp capture and a whitebox amp's own output
+ * collapse to one case, and why a cab simulator and an impulse response do too.
+ *
+ * They are not, however, the same *kind* of process, and one consequence survives the abstraction.
+ * An impulse response is linear and time-invariant: an unscaled seam into it is purely a level error,
+ * and a gain after it undoes the damage exactly. A NAM is a neural capture of a **nonlinear** amp, so
+ * the same signal at half the level does not merely arrive quieter -- it arrives with different
+ * harmonic content, and no later gain recovers it. So an `unscalable-seam` reported into a nonlinear
+ * slot is a **tone** error, where into a linear one it is only a level error.
+ *
+ * That distinction is recorded rather than encoded. Adding a `linear` flag to grade the advisory's
+ * severity would be a field with one speculative consumer, and the advisory already names the seam;
+ * a host that knows its processor is nonlinear knows to take that seam more seriously.
+ */
+export type BypassMode = "wire" | "buffer" | "effect";
+/**
+ * Row 8 tail step 1 — host mapping: bypass state → chain mode, per `program.bypass.kind`.
+ *
+ * The Studio's slot toggle already reads ENGAGED/BYPASSED, but the worklet chain omitted
+ * bypassed slots, so a bypassed buffered pedal ran no buffer and the mode plumbing
+ * (`setBypassMode`, `effectiveBypassMode`) never engaged in product. The host now keeps
+ * the slot and states the mode instead of dropping it.
+ *
+ * Returns `null` when no honest mode exists yet: `buffered` bypass needs the compiler's
+ * `bufferProgram` derivation (row 8 step 2), and requesting `buffer` without one falls back
+ * to the full program — which would play the effect under bypass. The caller omits those
+ * slots exactly as before, until step 2 lands. Everything else maps:
+ * engaged → `effect`; bypassed `true-bypass` → `wire`; `hardwire` → `wire`, with the input
+ * loading a hardwired output switch leaves behind still unmodelled (23 pedals by census —
+ * named here, not silent); `none` / `not-in-audio-path` → `wire`, agreeing with the
+ * runtime's own demotion guard.
+ */
+export declare function resolveBypassMode(bypass: Program["bypass"], engaged: boolean): BypassMode | null;
+export type ChainSlot = {
+    readonly kind: "program";
+    readonly program: Program;
+    readonly bufferProgram?: Program;
+    readonly bufferProcessor?: ExternalProcessor;
+    readonly bypassMode?: BypassMode;
+} | {
+    readonly kind: "processor";
+    readonly processor: ExternalProcessor;
+    readonly bufferProcessor?: ExternalProcessor;
+    readonly bypassMode?: BypassMode;
+};
+/** A compiled circuit as a slot. `bufferProgram` is the buffer-only stages for buffered bypass. */
+export declare function programSlot(program: Program, bufferProgram?: Program): ChainSlot;
+/** A compiled circuit as a slot with explicit buffer processor (WASM). */
+export declare function programSlotWithBufferProcessor(program: Program, bufferProcessor: ExternalProcessor, bufferProgram?: Program): ChainSlot;
+/** An injected processor as a slot. */
+export declare function processorSlot(processor: ExternalProcessor): ChainSlot;
+/**
+ * The contract a slot presents to the seam arithmetic.
+ *
+ * A program's `expects` is `instrument` by construction -- its input is a jack. Nothing infers it,
+ * and no compiler field is needed for it.
+ */
+export declare function slotContract(slot: ChainSlot): SlotContract;
+/** How a slot names itself in a message. */
+export declare function slotLabel(slot: ChainSlot, index: number): string;
+//# sourceMappingURL=chain-slot.d.ts.map

package/dist/chain-slot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chain-slot.d.ts","sourceRoot":"","sources":["../src/chain-slot.ts"],"names":[],"mappings":"AA2BA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAEpD,+FAA+F;AAC/F,MAAM,MAAM,aAAa,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;AAErD;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG;IAC1B,8CAA8C;IAC9C,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,8DAA8D;IAC9D,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,QAAQ,CAAC,kBAAkB,EAAE;QAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;QAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;KAC/B,CAAC;IACF;;OAEG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE;QAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;QAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;KAC/B,CAAC;IACF;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,iBAAiB,EAAE;QAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;QAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;KAC/B,GAAG,IAAI,CAAC;CACT,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,iBAAiB,GAAG,YAAY,GAAG;IAC9C,uFAAuF;IACvF,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,OAAO,CAAC,MAAM,EAAE,YAAY,GAAG,YAAY,CAAC;CAC5C,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEtD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,CAChC,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAC,EACzB,OAAO,EAAE,OAAO,GACd,UAAU,GAAG,IAAI,CAsBnB;AAED,MAAM,MAAM,SAAS,GAClB;IACA,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,eAAe,CAAC,EAAE,iBAAiB,CAAC;IAC7C,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC;CAChC,GACD;IACA,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAC;IACtC,QAAQ,CAAC,eAAe,CAAC,EAAE,iBAAiB,CAAC;IAC7C,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC;CAChC,CAAC;AAEL,mGAAmG;AACnG,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE,aAAa,CAAC,EAAE,OAAO,GAAG,SAAS,CAEhF;AAED,0EAA0E;AAC1E,wBAAgB,8BAA8B,CAC7C,OAAO,EAAE,OAAO,EAChB,eAAe,EAAE,iBAAiB,EAClC,aAAa,CAAC,EAAE,OAAO,GACrB,SAAS,CAEX;AAED,uCAAuC;AACvC,wBAAgB,aAAa,CAAC,SAAS,EAAE,iBAAiB,GAAG,SAAS,CAErE;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,SAAS,GAAG,YAAY,CAa1D;AAED,4CAA4C;AAC5C,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAIhE"}