@vessel-dsp/compiler 0.0.0-stage → 0.2.0

package/dist/terminal-role.d.ts

@@ -0,0 +1,109 @@
+/**
+ * **What a terminal IS — typed, with per-terminal evidence.**
+ *
+ * **The defect:** 1260 terminals across the corpus's open devices carry `role: pin`. One value.
+ * `vinl` is indistinguishable from `A0`, `SUM` from `VCC`. It is the fourth instance of the
+ * missing-field defect and the worst of them, because the first three blocked a classification, a
+ * declaration and an ownership claim while **this one blocks a MEASUREMENT**: the fidelity
+ * counterfactual must bridge a device's audio-bearing terminals, cannot tell which those are, and
+ * therefore bridges all of them — a DRAM's address bus included — giving an upper bound (37) where
+ * a number was wanted.
+ *
+ * **The remediation is a pattern this repository already trusts, not a new design.** The triode
+ * registry carries per-parameter `source` citations plus an entry-level
+ * `terminalProfileEvidenceStatus`; `CLAUDE.md` names it the provenance template for the whole
+ * registry. This is that template extended to the classes that never got it.
+ */
+export type TerminalRole = 
+/** Carries signal. The only role the audio-path counterfactual may bridge. */
+"audio" | "supply" | "ground"
+/** Address lines: a bus, never a signal path. */
+ | "address"
+/** Data lines, parallel or serial. */
+ | "data" | "clock"
+/** Mode, enable, reset, chip-select: a parameter stream, not audio. */
+ | "control"
+/**
+ * **Added because the corpus forces it.** A DAC's `VREF` sets full-scale output: it is neither a
+ * supply rail nor a signal, and calling it either loses the distinction that makes it useful.
+ * `RKM14L492-103F` in `boss-dd-2` and `boss-dsd-3` carries one.
+ */
+ | "reference";
+/**
+ * **How a role is known. Two kinds, and the second is deliberately weaker.**
+ *
+ * `direct-source` is the strong kind: a datasheet pinout, a service-note terminal map, or the
+ * packet's own declared node role (for `supply`/`ground`, cited to the node ledger) — the way the
+ * triode registry cites a Koren coefficient.
+ *
+ * **`packet-validated-shell` is circumstantial and is named so it reads that way**: it is not the
+ * source document saying what a terminal is, it is *our own packet's deck* having pushed a signal
+ * through it. It buys the shells that have **no part number at all** —
+ * `boss-st-2:ANALOG_INPUT_SUPPORT` can never have a datasheet — at the price of being admissible
+ * for exactly one role.
+ *
+ * **It is asymmetric, and the direction is the unwelcome one.** A deck can only ever ADD an audio
+ * terminal, never remove one, so this kind can move a device from `drops` to `stays` and never the
+ * reverse. A ceiling that improves because of it is a bug, not a result.
+ */
+export type TerminalRoleEvidenceKind = "direct-source" | "packet-validated-shell";
+/**
+ * **A role and the evidence for it. Both required — a role without evidence is refused.**
+ *
+ * **The banned inference is reading the pin's NAME.** `vinl` looking like audio and `A0` looking
+ * like an address is exactly the substring classification `CLAUDE.md` forbids, and it is forbidden
+ * because **a pin name is a label, not a fact**. It is also how this corpus already went wrong once:
+ * four tremolo optocouplers are wired from their terminals' *names*, one of the two surviving name
+ * vocabularies.
+ */
+export type TerminalRoleEvidence = {
+    readonly kind: "direct-source";
+    readonly role: TerminalRole;
+    /** The cited authority: a datasheet pinout, a service-note terminal map, a node ledger. */
+    readonly source: string;
+} | {
+    /**
+     * **Admissible for `audio` and nothing else.** Address, data and clock are not evidenceable
+     * this way at all: a deck that drives a bus line proves nothing about what the line carries,
+     * and supply/ground need no deck because the packet already declares them.
+     */
+    readonly kind: "packet-validated-shell";
+    readonly role: "audio";
+    /** The packet-local deck, by path. It must exist and must have passed. */
+    readonly deck: string;
+    /**
+     * **The specific path through this terminal that the deck exercises**, as the deck's own
+     * driven node and probed node. "The deck covers this component" is NOT this field: the
+     * claim is that signal passes through *this terminal*, and a component-level citation
+     * cannot support a per-terminal claim.
+     */
+    readonly signalPath: string;
+};
+/** Strong or circumstantial. Reported wherever a populated profile is summarised. */
+export declare function evidenceStrength(e: TerminalRoleEvidence): "source" | "circumstantial";
+/**
+ * **`unpopulated` is a first-class state and a CORRECT outcome**, not a gap. If a role cannot be
+ * evidenced it stays unpopulated, and a consumer must handle that rather than guess.
+ */
+export type TerminalProfile = {
+    readonly status: "unpopulated";
+    readonly reason: string;
+} | {
+    readonly status: "populated";
+    /** Keyed by the terminal's declared name. */
+    readonly terminals: Readonly<Record<string, TerminalRoleEvidence>>;
+};
+export declare function validateTerminalProfile(p: TerminalProfile): readonly string[];
+/**
+ * **The terminals the audio-path counterfactual may bridge.**
+ *
+ * **Returns `null` when the profile is unpopulated**, and the caller must then fall back to
+ * bridging everything and **report its result as an upper bound** — which is exactly what the
+ * ceiling of 37 is today. The distinction between "measured" and "bounded" lives here.
+ *
+ * **A device needs at least TWO audio terminals to bridge anything.** One audio pin connects
+ * nothing, which is why an R2R ladder with eleven data lines and a single `SUM` should leave the
+ * audio path once its profile is populated.
+ */
+export declare function audioTerminals(p: TerminalProfile | undefined): readonly string[] | null;
+//# sourceMappingURL=terminal-role.d.ts.map

package/dist/terminal-role.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal-role.d.ts","sourceRoot":"","sources":["../src/terminal-role.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,YAAY;AACvB,8EAA8E;AAC5E,OAAO,GACP,QAAQ,GACR,QAAQ;AACV,iDAAiD;GAC/C,SAAS;AACX,sCAAsC;GACpC,MAAM,GACN,OAAO;AACT,uEAAuE;GACrE,SAAS;AACX;;;;GAIG;GACD,WAAW,CAAC;AAEf;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,wBAAwB,GAAG,eAAe,GAAG,wBAAwB,CAAC;AAElF;;;;;;;;GAQG;AACH,MAAM,MAAM,oBAAoB,GAC7B;IACA,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,2FAA2F;IAC3F,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACvB,GACD;IACA;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,wBAAwB,CAAC;IACxC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,0EAA0E;IAC1E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEL,qFAAqF;AACrF,wBAAgB,gBAAgB,CAC/B,CAAC,EAAE,oBAAoB,GACrB,QAAQ,GAAG,gBAAgB,CAE7B;AAED;;;GAGG;AACH,MAAM,MAAM,eAAe,GACxB;IAAE,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC3D;IACA,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,6CAA6C;IAC7C,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC,CAAC;CAClE,CAAC;AAEL,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,eAAe,GAAG,SAAS,MAAM,EAAE,CA8B7E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,eAAe,GAAG,SAAS,GAAG,SAAS,MAAM,EAAE,GAAG,IAAI,CAKvF"}

package/dist/terminal-role.js

@@ -0,0 +1,46 @@
+/** Strong or circumstantial. Reported wherever a populated profile is summarised. */
+export function evidenceStrength(e) {
+    return e.kind === "direct-source" ? "source" : "circumstantial";
+}
+export function validateTerminalProfile(p) {
+    if (p.status === "unpopulated")
+        return p.reason.trim() === ""
+            ? ["`unpopulated` must say why -- an unexplained absence is indistinguishable from an oversight"]
+            : [];
+    const out = [];
+    for (const [name, e] of Object.entries(p.terminals)) {
+        if (e.kind === "direct-source") {
+            if (e.source.trim() === "")
+                out.push(`terminal "${name}" declares role \`${e.role}\` with no source -- A ROLE ASSIGNED WITHOUT EVIDENCE IS REFUSED. Cite a datasheet pinout, a service-note terminal map, or the packet's declared node role.`);
+            continue;
+        }
+        // Checked at runtime as well as in the types: registry entries are authored as data and can
+        // reach this function from JSON, where the union's discrimination buys nothing.
+        if (e.role !== "audio")
+            out.push(`terminal "${name}" claims role \`${e.role}\` from \`packet-validated-shell\` -- REFUSED. That kind evidences \`audio\` and nothing else: address, data and clock are not evidenceable from a deck at all, and supply/ground are already evidenced by the packet's declared node role.`);
+        if (e.deck.trim() === "")
+            out.push(`terminal "${name}" claims \`packet-validated-shell\` with no deck -- REFUSED. Name the packet-local deck that passed.`);
+        if (e.signalPath.trim() === "")
+            out.push(`terminal "${name}" claims \`packet-validated-shell\` with no signal path -- REFUSED. "The deck covers this component" cannot support a per-terminal claim; name the driven node and the probed node.`);
+    }
+    return out;
+}
+/**
+ * **The terminals the audio-path counterfactual may bridge.**
+ *
+ * **Returns `null` when the profile is unpopulated**, and the caller must then fall back to
+ * bridging everything and **report its result as an upper bound** — which is exactly what the
+ * ceiling of 37 is today. The distinction between "measured" and "bounded" lives here.
+ *
+ * **A device needs at least TWO audio terminals to bridge anything.** One audio pin connects
+ * nothing, which is why an R2R ladder with eleven data lines and a single `SUM` should leave the
+ * audio path once its profile is populated.
+ */
+export function audioTerminals(p) {
+    if (p === undefined || p.status === "unpopulated")
+        return null;
+    return Object.entries(p.terminals)
+        .filter(([, e]) => e.role === "audio")
+        .map(([name]) => name);
+}
+//# sourceMappingURL=terminal-role.js.map

package/dist/terminal-role.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal-role.js","sourceRoot":"","sources":["../src/terminal-role.ts"],"names":[],"mappings":"AAyFA,qFAAqF;AACrF,MAAM,UAAU,gBAAgB,CAC/B,CAAuB;IAEvB,OAAO,CAAC,CAAC,IAAI,KAAK,eAAe,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,gBAAgB,CAAC;AACjE,CAAC;AAcD,MAAM,UAAU,uBAAuB,CAAC,CAAkB;IACzD,IAAI,CAAC,CAAC,MAAM,KAAK,aAAa;QAC7B,OAAO,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE;YAC5B,CAAC,CAAC,CAAC,6FAA6F,CAAC;YACjG,CAAC,CAAC,EAAE,CAAC;IACP,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,KAAK,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,EAAE,CAAC;QACrD,IAAI,CAAC,CAAC,IAAI,KAAK,eAAe,EAAE,CAAC;YAChC,IAAI,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE;gBACzB,GAAG,CAAC,IAAI,CACP,aAAa,IAAI,qBAAqB,CAAC,CAAC,IAAI,6JAA6J,CACzM,CAAC;YACH,SAAS;QACV,CAAC;QACD,4FAA4F;QAC5F,gFAAgF;QAChF,IAAK,CAAC,CAAC,IAAqB,KAAK,OAAO;YACvC,GAAG,CAAC,IAAI,CACP,aAAa,IAAI,mBAAmB,CAAC,CAAC,IAAI,6OAA6O,CACvR,CAAC;QACH,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE;YACvB,GAAG,CAAC,IAAI,CACP,aAAa,IAAI,sGAAsG,CACvH,CAAC;QACH,IAAI,CAAC,CAAC,UAAU,CAAC,IAAI,EAAE,KAAK,EAAE;YAC7B,GAAG,CAAC,IAAI,CACP,aAAa,IAAI,qLAAqL,CACtM,CAAC;IACJ,CAAC;IACD,OAAO,GAAG,CAAC;AACZ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,cAAc,CAAC,CAA8B;IAC5D,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,CAAC,MAAM,KAAK,aAAa;QAAE,OAAO,IAAI,CAAC;IAC/D,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;SAChC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,OAAO,CAAC;SACrC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC;AACzB,CAAC"}

package/dist/terminal-roles.d.ts

@@ -0,0 +1,59 @@
+/**
+ * How a supply names the terminal it drives, and the terminal it returns through.
+ *
+ * **These were two pairs, not one, until 2026-09-01.** `device-laws.ts` (stage 3, building the
+ * drive/return node sets that decide whether a jack contact engages onto a stranded supply
+ * node) accepted `{positive, hot, plus}` / `{negative, return}`. `lower.ts` (stage 5, choosing
+ * which end of a supply a stamp drives) accepted those plus `{line, anode, +}` /
+ * `{cathode, minus, neutral}`. Same question, two answers, three tokens apart -- so a supply
+ * declaring `line` was a drive terminal when lowering and invisible to stage 3, which decides
+ * jack engagement.
+ *
+ * Resolved as the **union**, because both stages are asking which end is which and the wider
+ * vocabulary is the more complete answer to that question, not a laxer one.
+ *
+ * **Measured before merging, so this is a consolidation and not a behaviour change.** Across
+ * all 142 corpus packets, only five role tokens appear on a `voltage-source` at all:
+ * `positive` (46), `negative` (45), `hot` (1), `return` (1) and `midpoint` (1). None of the six
+ * divergent tokens occurs, so no packet's classification moves. The divergence was latent, and
+ * the point of merging it now is that the next packet spelling a rail `line` gets one answer
+ * instead of two.
+ *
+ * `midpoint` is deliberately in neither set: a centre tap is not a drive end or a return end,
+ * and the stages that consult these are asking about polarity.
+ */
+export declare const supplyDriveRoles: ReadonlySet<string>;
+/**
+ * Role tokens that name a terminal's **position or its winding half, and deliberately carry no
+ * electrode evidence** — so a resolver that cannot orient a device from them has read the
+ * document correctly rather than failed to.
+ *
+ * **Why this set exists.** Four asymmetric-device resolvers in `lower.ts` fall back to
+ * declaration order when they cannot read a role, and that fallback serves two situations one
+ * predicate could not previously tell apart: a document of bare lugs, which carries no
+ * orientation evidence and where declaration order is all there is, and a document that *named*
+ * its terminals in a spelling the resolver does not know, where declaration order is a guess.
+ * The first is correct and must stay silent; the second is the silent-mis-wiring class the
+ * 2026-09-02 census measured. This set is the escape hatch that separates them.
+ *
+ * Every entry is named as exactly this case by a resolver's own docstring already, and each is
+ * corpus-evidenced: `diodeTerminals` says it "falls back to declaration order for `a,b` and bare
+ * **`a`/`b` removed 2026-09-03, because a diode is not a symmetric device.** They were here for
+ * "a diode's bare `a`/`b` lugs, which carry no orientation evidence" -- and that reading is wrong
+ * in a way a mutation study caught: reversing such a diode moves the program, so declaration
+ * order is not "the document's intended reading", it is a guess this set was suppressing the
+ * warning about. What remains is genuinely symmetric: the two ends of a winding, where either
+ * order is the same circuit.
+ *
+ * The older note read: `diodeTerminals` says "falls back to declaration order for `a,b` and bare
+ * "`ac_a`/`ac_b` and `heater_a`/`heater_b` are symmetric windings that name no polarity ... so
+ * both fall back to declaration order" (`fender-5f1-champ`'s filament bus and `hiwatt-dr103`'s
+ * heater bus). Nothing here feeds a resolver, so adding a token changes no wiring — it only
+ * declares that this spelling's fallback was intended.
+ *
+ * A `lugN` or bare `pinN` needs no entry: `terminalRoleToken` already folds a bare pin number to
+ * `null`, and a `lug1`/`lug3` names a pot's track end, which `potTerminals` resolves by its own
+ * quiet-distance rule rather than by orientation.
+ */
+export declare const orientationFreeRoles: ReadonlySet<string>;
+//# sourceMappingURL=terminal-roles.d.ts.map

package/dist/terminal-roles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal-roles.d.ts","sourceRoot":"","sources":["../src/terminal-roles.ts"],"names":[],"mappings":"AAsBA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,gBAAgB,EAAE,WAAW,CAAC,MAAM,CAO/C,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,oBAAoB,EAAE,WAAW,CAAC,MAAM,CAKnD,CAAC"}

package/dist/terminal-roles.js

@@ -0,0 +1,92 @@
+// Terminal-role vocabularies shared by more than one stage.
+//
+// **Why this file exists.** The corpus spells one terminal many ways, and the design rule is
+// refuse rather than guess, so every stage that has to recognise a role carries a closed set of
+// the spellings it accepts. That is correct. What is not correct is two stages carrying their
+// *own* closed set for the *same* question, because the two then drift: the sets below were
+// found defined twice, under the same names, in different files, and two of them had already
+// diverged by three tokens each.
+//
+// The rule this file establishes: **a role vocabulary consulted by more than one stage lives
+// here, once.** A vocabulary only one stage reads stays with that stage -- it cannot drift
+// against anything. This is phase 1 of R1 in
+// `thoughts/shared/plans/archive/2026-08-31-v2-complexity-reduction-plan.md`, and it is deliberately
+// the half that needs nothing from `@vessel-dsp/core`: consolidating duplication that already
+// exists inside this repository. Canonicalising the spellings themselves, upstream, is the
+// other half and is still gated on the core parser contract.
+//
+// Nothing here is a substring or regex test. Every set is compared as whole values against
+// tokens `terminalRoleToken` has already folded (case dropped, separators stripped, a leading
+// `pinN` removed), which is what keeps this on the right side of the repository's rule against
+// reading authored prose.
+/**
+ * How a supply names the terminal it drives, and the terminal it returns through.
+ *
+ * **These were two pairs, not one, until 2026-09-01.** `device-laws.ts` (stage 3, building the
+ * drive/return node sets that decide whether a jack contact engages onto a stranded supply
+ * node) accepted `{positive, hot, plus}` / `{negative, return}`. `lower.ts` (stage 5, choosing
+ * which end of a supply a stamp drives) accepted those plus `{line, anode, +}` /
+ * `{cathode, minus, neutral}`. Same question, two answers, three tokens apart -- so a supply
+ * declaring `line` was a drive terminal when lowering and invisible to stage 3, which decides
+ * jack engagement.
+ *
+ * Resolved as the **union**, because both stages are asking which end is which and the wider
+ * vocabulary is the more complete answer to that question, not a laxer one.
+ *
+ * **Measured before merging, so this is a consolidation and not a behaviour change.** Across
+ * all 142 corpus packets, only five role tokens appear on a `voltage-source` at all:
+ * `positive` (46), `negative` (45), `hot` (1), `return` (1) and `midpoint` (1). None of the six
+ * divergent tokens occurs, so no packet's classification moves. The divergence was latent, and
+ * the point of merging it now is that the next packet spelling a rail `line` gets one answer
+ * instead of two.
+ *
+ * `midpoint` is deliberately in neither set: a centre tap is not a drive end or a return end,
+ * and the stages that consult these are asking about polarity.
+ */
+export const supplyDriveRoles = new Set([
+    "positive",
+    "plus",
+    "hot",
+    "line",
+    "anode",
+    "+",
+]);
+/**
+ * Role tokens that name a terminal's **position or its winding half, and deliberately carry no
+ * electrode evidence** — so a resolver that cannot orient a device from them has read the
+ * document correctly rather than failed to.
+ *
+ * **Why this set exists.** Four asymmetric-device resolvers in `lower.ts` fall back to
+ * declaration order when they cannot read a role, and that fallback serves two situations one
+ * predicate could not previously tell apart: a document of bare lugs, which carries no
+ * orientation evidence and where declaration order is all there is, and a document that *named*
+ * its terminals in a spelling the resolver does not know, where declaration order is a guess.
+ * The first is correct and must stay silent; the second is the silent-mis-wiring class the
+ * 2026-09-02 census measured. This set is the escape hatch that separates them.
+ *
+ * Every entry is named as exactly this case by a resolver's own docstring already, and each is
+ * corpus-evidenced: `diodeTerminals` says it "falls back to declaration order for `a,b` and bare
+ * **`a`/`b` removed 2026-09-03, because a diode is not a symmetric device.** They were here for
+ * "a diode's bare `a`/`b` lugs, which carry no orientation evidence" -- and that reading is wrong
+ * in a way a mutation study caught: reversing such a diode moves the program, so declaration
+ * order is not "the document's intended reading", it is a guess this set was suppressing the
+ * warning about. What remains is genuinely symmetric: the two ends of a winding, where either
+ * order is the same circuit.
+ *
+ * The older note read: `diodeTerminals` says "falls back to declaration order for `a,b` and bare
+ * "`ac_a`/`ac_b` and `heater_a`/`heater_b` are symmetric windings that name no polarity ... so
+ * both fall back to declaration order" (`fender-5f1-champ`'s filament bus and `hiwatt-dr103`'s
+ * heater bus). Nothing here feeds a resolver, so adding a token changes no wiring — it only
+ * declares that this spelling's fallback was intended.
+ *
+ * A `lugN` or bare `pinN` needs no entry: `terminalRoleToken` already folds a bare pin number to
+ * `null`, and a `lug1`/`lug3` names a pot's track end, which `potTerminals` resolves by its own
+ * quiet-distance rule rather than by orientation.
+ */
+export const orientationFreeRoles = new Set([
+    "aca",
+    "acb",
+    "heatera",
+    "heaterb",
+]);
+//# sourceMappingURL=terminal-roles.js.map

package/dist/terminal-roles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal-roles.js","sourceRoot":"","sources":["../src/terminal-roles.ts"],"names":[],"mappings":"AAAA,4DAA4D;AAC5D,EAAE;AACF,6FAA6F;AAC7F,gGAAgG;AAChG,8FAA8F;AAC9F,4FAA4F;AAC5F,6FAA6F;AAC7F,iCAAiC;AACjC,EAAE;AACF,6FAA6F;AAC7F,2FAA2F;AAC3F,6CAA6C;AAC7C,qGAAqG;AACrG,8FAA8F;AAC9F,2FAA2F;AAC3F,6DAA6D;AAC7D,EAAE;AACF,2FAA2F;AAC3F,8FAA8F;AAC9F,+FAA+F;AAC/F,0BAA0B;AAE1B;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAwB,IAAI,GAAG,CAAC;IAC5D,UAAU;IACV,MAAM;IACN,KAAK;IACL,MAAM;IACN,OAAO;IACP,GAAG;CACH,CAAC,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAwB,IAAI,GAAG,CAAC;IAChE,KAAK;IACL,KAAK;IACL,SAAS;IACT,SAAS;CACT,CAAC,CAAC"}

package/dist/transformer.d.ts

@@ -0,0 +1,181 @@
+import { type Device, type DeviceLaw, type NodeId } from "./types";
+/**
+ * How many `(device, terminal)` references touch each node across the whole netlist.
+ *
+ * Existence evidence, not a corpus-wide cost: `transformerWindings` is the only reader, and
+ * only when its own terminal grouping turns up a winding with a single, unpaired end. A node
+ * this stage never asks about -- ground, or any node two ordinary components share -- costs
+ * nothing extra to have counted.
+ */
+export declare function nodeOccurrenceCounts(devices: readonly Device[]): Map<NodeId, number>;
+/**
+ * A transformer's windings, as coupled pairs against its primary.
+ *
+ * **Positional order was silently wrong on 45 of the corpus's 55 transformers.** This read
+ * `device.nodes` as exactly `[primary+, primary-, secondary+, secondary-]` and dropped every
+ * terminal past the fourth without a word. Only 10 transformers have four terminals; the rest
+ * have five to thirteen. `tycobrahe-octavia` is the compiled case: its `T1` is
+ * `[primarya, primaryb, secondarya, secondaryct, secondaryb, shieldnc]`, so the old reading
+ * coupled `(secondarya, secondaryct)` — **half the secondary** — and left `secondaryb` driven by
+ * nothing. Since `secondarya` and `secondaryb` each feed a diode anode with the centre tap
+ * grounded, that is a full-wave rectifier reduced to half-wave, which is the difference between
+ * an octave-up pedal and a fuzz.
+ *
+ * Grouping is by **terminal-role token compared whole** against the closed table below, never by
+ * substring or by position. A role this table does not name is a refusal rather than a guess: a
+ * winding assembled from tokens nobody has checked would silently couple the wrong pair, which is
+ * the failure this replaces.
+ *
+ * A centre tap splits its winding into two halves in series. Each half carries half the turns, so
+ * its primary-to-half ratio is **twice** the declared one — the declared `Ratio` is read as
+ * primary-to-*full*-winding, which is the conventional statement for a tapped secondary and is
+ * documented here because the source cannot say which it meant.
+ *
+ * **One declared ratio is applied to every secondary.** `declaredRatio` is exact for a single
+ * secondary, tapped or not, whose halves genuinely share a ratio -- which is every transformer
+ * that reaches the coupled path, because a ratio is only ever derived for a transformer whose
+ * primary carries signal.
+ *
+ * ## Driven windings: a power transformer needs no primary
+ *
+ * **A transformer the source specifies by its winding voltages is lowered as one `ac-source` per
+ * winding, and its primary is not modelled at all.** Decided 2026-08-14 after measuring the amp
+ * corpus; `netlist.ts`'s `transformerWindingVolts` carries the argument for why the primary side
+ * is not needed and this function is where that is executed.
+ *
+ * The physics: the B+ rail comes from the HV secondary through the rectifier and the filter
+ * network, and a cap-input rectifier's behaviour is fixed by the secondary RMS, the rectifier
+ * drop and the load. The primary is the mains side, and nothing downstream of it is audio. So a
+ * winding whose own RMS the source states can be driven directly, and the mains number the
+ * previous formulation demanded -- unstateable for the multi-tap primaries this corpus is full of
+ * -- drops out.
+ *
+ * **What this models that the coupled form did not.** `vox-ac15-top-boost` declares no supply
+ * component at all: under the coupled form its power transformer's primary would be driven by
+ * nothing and its B+ would solve to zero, a wrong answer that renders. A driven winding asserts
+ * the voltage the source states regardless of what the mains side of the document contains.
+ *
+ * **What this does not model, plainly.** A real transformer sags: winding resistance, leakage
+ * inductance and core loss make B+ fall as the power tubes draw, and that sag is part of how an
+ * amp sounds. **No source in this corpus states any of those**, so none of them is modelled and
+ * none is guessed. The series impedance is `SUPPLY_SOURCE_OHMS`, the repository's existing
+ * one-ohm default for every supply, carried on the law -- it is there so an ideal source cannot
+ * deliver unbounded current into a rectifier, and it is **not** a winding resistance: a real HV
+ * winding is tens to hundreds of ohms. Read a B+ from this model as the no-load rail. Likewise
+ * there is no cross-winding coupling (loading the HV winding does not disturb the heaters) and
+ * nothing on the mains side can switch the amp off any more, because there is no longer a path
+ * from the mains inlet to the secondaries; the standby switch, which sits after the rectifier,
+ * is unaffected.
+ *
+ * **The centre tap is two sources about the tap, not one across the winding.** A `370-0-370`
+ * winding with the tap grounded gets `V(a) - V(tap) = E` and `V(tap) - V(b) = E`, so `a` and `b`
+ * swing in antiphase about the tap at 370 V RMS each -- which is what makes the full-wave
+ * rectifier downstream full-wave. One 740 V source across `a`-`b` would leave the tap
+ * undetermined and the rectifier fed wrongly. The pairing is the same one the coupled form
+ * already uses, and the stated voltage is per half by the corpus's own convention, so it is
+ * applied to each half directly and never doubled.
+ *
+ * **Every winding must have a voltage if any does.** A transformer on this path has no ratio to
+ * fall back on by construction, so a winding with no typed voltage is refused by name rather than
+ * silently dropped or defaulted -- `fender-bassman` and `marshall-jtm45` both state their
+ * rectifier-heater winding only as prose ("assumed from GZ34 heater, unprinted on selected
+ * schematic"), and that is a source gap to report, not a number to invent.
+ *
+ * **A tapped primary swaps which winding is the shared reference, added 2026-08-14.** Three
+ * amp output transformers (`fender-5e3-deluxe-tweed`, `marshall-jtm45`, `vox-ac30-top-boost`)
+ * declare a **centre-tapped primary** -- the ordinary push-pull shape, plate-to-plate with the
+ * centre tap at B+ -- which the original code refused outright: "no single reference winding".
+ * That refusal is still correct for a primary tapped *and* carrying no other complete winding to
+ * pivot on, but a push-pull output transformer always has one: the secondary. Every winding on
+ * one core shares the same volts-per-turn, so if `declaredRatio = Vprimary_full / Vsecondary_full`
+ * (exactly what the impedance-pair rung above already derives), then for a centre tap splitting
+ * the primary into two equal halves:
+ *
+ *   V(half) = V(primary_full) / 2
+ *   V(secondary_full) = V(primary_full) / declaredRatio = (2 * V(half)) / declaredRatio
+ *   =>  V(secondary_full) = (2 / declaredRatio) * V(half)
+ *
+ * So stamping the secondary as the shared reference and each primary half as a winding coupled
+ * to it needs `2 / declaredRatio` per half -- applied directly, not doubled again. Verified
+ * against `fender-5e3-deluxe-tweed`'s own numbers: `declaredRatio = sqrt(8000/8) ≈ 31.62`,
+ * swapped ratio `2/31.62 ≈ 0.0632`, and `0.0632 * 15.81 = 1` confirms the round trip
+ * (`1/0.0632 ≈ 15.81 = declaredRatio/2`, the per-half ratio the un-swapped direction would have
+ * used).
+ *
+ * The swap needs **exactly one** other complete, untapped winding to pivot on; zero or several is
+ * refused rather than guessed. It cannot arise on the driven path, which models no primary.
+ *
+ * **A winding with only one declared end is dropped if connectivity says it is dangling, and
+ * refused by name otherwise -- also 2026-08-14.** `vox-ac30-top-boost`'s output transformer
+ * declares a `secondary_8` terminal beside its typed, wired `secondary_16` -- "8 Ω alternate
+ * source-visible tap" in the source's own words, a second impedance tap on the same core with no
+ * companion end of its own. Its node touches no other component anywhere in the document (checked
+ * against `nodeOccurrenceCounts`, connectivity rather than a spelling), so nothing this stage
+ * could stamp for it would change the solved circuit, and it is dropped exactly as `shieldnc`
+ * already is. This is deliberately **not** a blanket rule for the `secondary8`/`secondary_8`
+ * spelling: a future packet that actually wires an alternate tap to a load has a node other
+ * components touch, and that packet refuses by name instead -- a real multi-tap secondary in use
+ * is a different device law this stage does not have, not a winding to silently drop.
+ */
+export type LoweredWinding = {
+    readonly kind: "coupled";
+    readonly primaryPlus: number;
+    readonly primaryMinus: number;
+    readonly plus: number;
+    readonly minus: number;
+    readonly turnsRatio: number;
+} | {
+    readonly kind: "driven";
+    readonly plus: number;
+    readonly minus: number;
+    readonly amplitudeVolts: number;
+    readonly frequencyHz: number;
+    readonly sourceOhms: number;
+};
+/**
+ * Nodes where a transformer meets a **selector switch** and nothing else.
+ *
+ * Connectivity, never a spelling: a node qualifies when the devices touching it are one
+ * transformer and one or more plain `switch`es, with no third kind. An output transformer's
+ * impedance selector is exactly that shape -- `hiwatt-dr103`'s `SW_IMPEDANCE_SELECTOR` has one
+ * `common` and three throws, each throw sharing a node with one secondary tap of
+ * `T_OUTPUT_TH7549_2`.
+ *
+ * **`switch` and not `selector`, deliberately, and this is the whole boundary of this rule.** This
+ * repository already models a real 1-of-N selector as its own device kind: `selector` stamps every
+ * throw of every pole and lets a control decide which conducts, resolving its position from a
+ * declared `Options:` list against `Position:`. That is the right answer for an ohms selector -- it
+ * makes the taps *switchable*, so the reflected load changes with the selection, which is the half
+ * that matters for power-stage distortion.
+ *
+ * These two packets do not reach it: they declare `kind: switch` with a `SelectedState: 16 ohms`
+ * property rather than the `Options`/`Position` pair the classifier reads. So this rule is the
+ * narrow, exact thing that can be said meanwhile -- an unselected throw is open, and an open
+ * secondary contributes nothing -- and it **stops applying by construction** the moment a packet
+ * declares its selector properly, because a `selector` is not a `switch` and this predicate counts
+ * only the latter. It cannot defeat the better model; it is superseded by it.
+ */
+export declare function selectorTapNodes(devices: readonly Device[]): ReadonlySet<NodeId>;
+/**
+ * The coils this transformer declares, reduced to the pairs of nodes a stamp needs.
+ *
+ * **Read, not reconstructed.** Until `@vessel-dsp/core@0.6.35` a transformer's terminals gave no
+ * statement of which coil each belonged to, so this stage grouped them with a 110-entry table
+ * keyed on folded terminal spellings -- `primaryplus`, `hvreda345vac`, `powertubeheatercenter0v`.
+ * That table covered the corpus because it was written from the corpus, one packet at a time, and
+ * a transformer nobody had transcribed yet arrived as a refusal naming a winding class instead of
+ * the real fault, which was that the document never said what its coils were.
+ *
+ * Everything the table encoded beyond the grouping stays where it was:
+ *
+ * - **`end: a|b|tap` is coil order plus each terminal's own role.** The ends are the terminals
+ *   whose declared role is `winding`; a `windingTap` sits physically where the list puts it.
+ * - **`end: unconnected` was never winding structure.** A tap the document wires to nothing is a
+ *   connectivity fact, read from `terminalOccurrences` below exactly as before.
+ * - **`end: selectable` likewise.** Which mains tap is live is a property of the selector switch,
+ *   and the refusal below still names that switch rather than the transformer.
+ */
+export declare function transformerWindings(device: Device, law: Extract<DeviceLaw, {
+    kind: "transformer";
+}>, terminalOccurrences: ReadonlyMap<NodeId, number>, selectorTaps: ReadonlySet<NodeId>): readonly LoweredWinding[];
+//# sourceMappingURL=transformer.d.ts.map

package/dist/transformer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transformer.d.ts","sourceRoot":"","sources":["../src/transformer.ts"],"names":[],"mappings":"AAaA,OAAO,EAAU,KAAK,MAAM,EAAE,KAAK,SAAS,EAAE,KAAK,MAAM,EAAE,MAAM,SAAS,CAAC;AAE3E;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAQpF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4GG;AACH,MAAM,MAAM,cAAc,GACvB;IACA,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC3B,GACD;IACA,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEL;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,WAAW,CAAC,MAAM,CAAC,CA6BhF;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mBAAmB,CAClC,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,OAAO,CAAC,SAAS,EAAE;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,CAAC,EAChD,mBAAmB,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,EAChD,YAAY,EAAE,WAAW,CAAC,MAAM,CAAC,GAC/B,SAAS,cAAc,EAAE,CA4M3B"}