@vessel-dsp/compiler 0.0.0-stage → 0.2.0

package/dist/power-domain-control.js

@@ -0,0 +1,142 @@
+/**
+ * The kinds that separate the mains and HT domains from the audio graph.
+ *
+ * A supply, a rail and a battery are the domain's origin. A **transformer** is here because its
+ * windings couple magnetically rather than electrically: a mains primary and a heater secondary
+ * share no node, and treating the device as a conductor would make every rail reachable from the
+ * wall socket.
+ */
+const DOMAIN_BOUNDARY_KINDS = new Set([
+    "voltage-source",
+    "current-source",
+    "battery",
+    "rail",
+    "transformer",
+    "ground",
+]);
+/**
+ * The devices reachable from the audio ports without crossing a domain boundary.
+ *
+ * Ground is excluded as a hop for the reason a shared-node test always must: nearly every device
+ * touches it, so counting it makes the whole circuit one neighbourhood.
+ */
+function devicesReachableFromPorts(netlist, ports) {
+    const byNode = new Map();
+    for (const device of netlist.devices) {
+        if (DOMAIN_BOUNDARY_KINDS.has(device.kind)) {
+            continue;
+        }
+        for (const node of device.nodes) {
+            if (node === 0) {
+                continue;
+            }
+            const bucket = byNode.get(node) ?? [];
+            bucket.push(device);
+            byNode.set(node, bucket);
+        }
+    }
+    const seenNodes = new Set(ports);
+    const seenDevices = new Set();
+    const queue = [...ports];
+    while (queue.length > 0) {
+        const node = queue.pop();
+        for (const device of byNode.get(node) ?? []) {
+            if (seenDevices.has(device.id)) {
+                continue;
+            }
+            seenDevices.add(device.id);
+            for (const next of device.nodes) {
+                if (next !== 0 && !seenNodes.has(next)) {
+                    seenNodes.add(next);
+                    queue.push(next);
+                }
+            }
+        }
+    }
+    return seenDevices;
+}
+/**
+ * A device exposed as a sweepable user control that is **power-domain hardware**: it sits outside
+ * the audio graph and no panel entry claims it.
+ *
+ * **Why this is reported rather than decided.** Structure cannot tell a user control from fixed
+ * hardware on this side of the boundary. A standby switch and a mains fuse are both switches in
+ * the supply, and one belongs on the front panel while the other belongs inside the chassis --
+ * only the document can say which. So the compiler names the ambiguity and the fix is a
+ * `deviceInterface.controls` entry, or a kind that is not a switch.
+ *
+ * **A rule was attempted and it does not exist.** The promising one was "a switch declaring a
+ * `FuseRating` is a fuse, therefore not a control" -- legal evidence, since it reads the presence
+ * of a typed property rather than a name, and 26 corpus switches declare one. It fails on its own
+ * data: `mesa-boogie-dual-rectifier`'s `SRC_POWER_SWITCH_FUSE_4A`, `orange-rockerverb`'s
+ * `SRC_PRIMARY_POWER_SWITCH_AND_FUSE` and `sunn-beta-lead`'s `SRC_POWER_SWITCH_FUSE` are each a
+ * power switch *and* a fuse in one two-terminal component, and a power switch is exactly the user
+ * control the rule would have suppressed. Narrowing it to "two terminals and no switch-shaped
+ * property" keeps all three, because a fuse and a combined switch-and-fuse are structurally
+ * identical: two terminals, one closed contact. The difference is whether a human operates it,
+ * which is not a fact about the circuit.
+ *
+ * **Measured 2026-09-04: 67 of the corpus's 958 program controls**, across the packets that
+ * model their own power supply. It read 80 before `boss-bf-2`'s three service trims were
+ * declared, and 76 before every signal jack became a seed -- see the note in the function. They are mains switches,
+ * voltage selectors, and mains, HT and heater fuses -- `vox-ac30-top-boost` alone contributes
+ * `SW_MAINS`, a 230/120 selector and four fuses. A fuse offered to a player as a knob to sweep is
+ * the shape of the problem.
+ *
+ * **The traversal's one known imprecision** is at the B+ boundary: it stops at the transformer but
+ * not at the rectifier and filter, so B+ nodes stay reachable through a tube's plate. That keeps
+ * `SW1_STANDBY` and `S_STANDBY_SWITCH` out of this warning, which is right -- a standby switch is
+ * a front-panel control -- and also keeps `F2_HT_FUSE` out, which is not.
+ */
+export function findPowerDomainControls(netlist, 
+// A control carries the `role` and `label` its `deviceInterface.controls` entry gave it, so
+// "the panel does not claim this" is exactly both being absent -- no second pass over the
+// document, and no way for the two readings to drift apart.
+controls, ports) {
+    // **Every signal jack is a seed, not just the two selected ports.**
+    //
+    // A `.vdsp` names one input and one output port, and on a two-channel amp that selects one
+    // channel: `fender-super-reverb-aa1069`'s port is its *Vibrato* input, so the Normal channel
+    // hangs off a jack the traversal never started from. Combined with the transformer cut --
+    // which stops the walk re-entering from the speaker-side output port -- the search was
+    // effectively one-directional from a single channel's input, and it called three
+    // `Normal-Volume` pots and `soldano-slo-100`'s `SRC_PRESENCE_25K` power-domain hardware.
+    //
+    // Seeding every jack node drops the count from 76 to 67 and rescues all nine. It also rescues
+    // `soldano-slo-100`'s `SRC_F1_BPLUS_FUSE`, which is a false negative -- a B+ fuse is not a
+    // panel control -- and that trade is deliberate: this warning offers candidates for a human
+    // decision, and naming a Presence knob as power hardware costs more than missing one fuse.
+    const jackNodes = netlist.devices
+        .filter((device) => device.kind === "jack")
+        .flatMap((device) => device.nodes)
+        .filter((node) => node !== 0);
+    const unclaimed = controls.filter((control) => (control.role ?? null) === null && (control.label ?? null) === null);
+    if (unclaimed.length === 0) {
+        return [];
+    }
+    const reachable = devicesReachableFromPorts(netlist, [
+        ...ports,
+        ...new Set(jackNodes),
+    ]);
+    const warnings = [];
+    for (const { id } of unclaimed) {
+        if (reachable.has(id)) {
+            continue;
+        }
+        const device = netlist.devices.find((candidate) => candidate.id === id);
+        if (device === undefined) {
+            continue;
+        }
+        warnings.push({
+            code: "power-domain-control",
+            device: id,
+            detail: `${device.kind} ${id} is offered as a sweepable control, but it sits outside the ` +
+                "audio graph -- unreachable from either port without crossing a supply, rail or " +
+                "transformer -- and no `deviceInterface.controls` entry claims it as a panel " +
+                "control. Power-domain hardware, not a control: declare it on the panel if a " +
+                "player operates it, and give it a kind that is not a switch if one does not.",
+        });
+    }
+    return warnings;
+}
+//# sourceMappingURL=power-domain-control.js.map

package/dist/power-domain-control.js.map

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

package/dist/proxy-declaration.d.ts

@@ -0,0 +1,121 @@
+/**
+ * **A declared proxy: a macro that stands in for a part it is not.**
+ *
+ * `RDD63H101` is a 144-pin microcode-driven digital delay processor bound to
+ * `bucket-brigade-delay-line` — an analog charge-transfer model. That binding may well be the right
+ * engineering call: removing it makes `boss-dd-2` and `boss-dsd-3` silent, which **trades a stated
+ * approximation for an unstated absence** and destroys information. What is wrong today is not the
+ * binding; it is that **nothing in the catalog says it is a stand-in**, so it reads as an identity
+ * claim, and the packets' own records say that chip's microcode is unavailable.
+ *
+ * **This is format item 8's shape, one level up.** The author knew the macro was an approximation
+ * and had nowhere to say so, so they wrote the only thing the format allowed: a binding that
+ * asserts identity. **Every required assertion with no "approximate, because" option manufactures
+ * a false claim**, and the coping strategies are the same three — overstate it, omit it and lose
+ * the reason, or write prose beside it.
+ *
+ * **Why this is a separate construct from item 8's reason field, since the unification was asked
+ * for.** They share the principle and not the payload. An absent part number needs a reason a
+ * *consumer* can branch on — unknown, excluded, not-applicable — and nothing more. A proxy needs
+ * three things a *fidelity* query must be able to read separately, and merging them into one
+ * free-text annotation would lose exactly the field that does the work: `doesNotReproduce`. **One
+ * generic "declared inexactness" bag would be uncheckable, which is the property both constructs
+ * exist to provide.** They belong in one format package and not in one field.
+ */
+/**
+ * **A thing the model fails to reproduce, written so it can be RUN.**
+ *
+ * The test: *could someone who has never read this declaration run it and get a number that either
+ * agrees or does not?* — *"does not reproduce the microcode's modulation behaviour"* fails that;
+ * *"delay time does not track the clock, measured as time-of-first-energy"* passes it.
+ *
+ * **This is the falsifier, and it is the reason a declaration is not paperwork.** Each entry
+ * becomes the **acceptance row for the real block** when someone finally writes it: the measurement
+ * is already chosen, the expected value of the stand-in is already recorded, and a real model has
+ * to move that number. A prose sentence here gives the next person nothing to run.
+ */
+export type Measurable = {
+    /** What is not reproduced. */
+    readonly claim: string;
+    /** How to measure it, in terms someone who has not read this could execute. */
+    readonly measurement: string;
+    /** What THIS model yields for that measurement -- the number a real block must move. */
+    readonly standIn: string;
+    /**
+     * **`registered-unrun` is a PRE-REGISTRATION WITHOUT A FIXTURE, and it is not the same thing as
+     * a refuted claim.** Nine `subsumes` claims were withdrawn on 2026-09-11 because they were shown
+     * **false**; a well-formed measurable that no packet can currently run is **unrun**, which is a
+     * different state. Deleting it destroys the evidence that the claim was stated *before* any
+     * measurement — and pre-registration is the thing this method exists to make valuable.
+     *
+     * **What it must never do is look like it ran, or count toward anything measured.**
+     */
+    readonly status: "measured" | "registered-unrun";
+    /** `registered-unrun` only: what fixture would run it. Required, so the claim names its own cure. */
+    readonly fixture?: string;
+    /** `registered-unrun` only: withdraw if no fixture exists by this date. A registration with no expiry is a permanent excuse. */
+    readonly expires?: string;
+};
+export type ProxyDeclaration = {
+    /** The real part and what it actually is — not what the macro models. */
+    readonly standsFor: string;
+    /** Why the stand-in is defensible at all, in terms a reviewer can disagree with. */
+    readonly justification: string;
+    /**
+     * **What the proxy does NOT reproduce. Required, and required to be non-empty.**
+     *
+     * A proxy that reproduces everything is not a proxy, it is a model — so an empty list is
+     * always an error, never a well-behaved case. This is the field that makes the declaration
+     * cost something: an author who cannot name a single thing their stand-in fails to reproduce
+     * has not examined it.
+     */
+    readonly doesNotReproduce: readonly Measurable[];
+    /**
+     * **True by construction, so passing proves nothing.** Kept apart from `doesNotReproduce`
+     * because listing a structural invariant among measurables inflates the count of things
+     * measured — the same inflation this programme spent 2026-09-11 removing. A compiler check is
+     * the right home for these; they are recorded here so the boundary is visible.
+     */
+    readonly structuralInvariants?: readonly string[];
+};
+export type ProxyViolation = {
+    readonly field: string;
+    readonly problem: string;
+};
+/** Structural validation. A declaration that cannot fail is not a declaration. */
+export declare function validateProxy(p: ProxyDeclaration): readonly ProxyViolation[];
+/**
+ * **A CITED DESIGN-TIME DERIVATION — a different claim from `subsumes`, with a different check.**
+ *
+ * `subsumes` claims **parametric dependence**: mutate the device's spec and the macro's parameters
+ * move. That is the only form a census can trust without reading anything, and it is what
+ * `scripts/report-subsumption-mutant.ts` tests.
+ *
+ * A design-time derivation is legitimate and **the mutant would reject it**, because the value is a
+ * literal in the catalog rather than a computed expression. So it gets its own field and its own
+ * check: **RECOMPUTATION**. Apply the cited formula to the cited values and require it to reproduce
+ * the constant.
+ *
+ * > **A cited derivation that does not reproduce the constant is a guess with a footnote**, and
+ * > recomputation catches that where a citation alone does not.
+ *
+ * **The nine withdrawn `subsumes` claims could be re-made this way, and cannot be**: the constant
+ * is `stages: 1024`, which is the **MN3007's datasheet stage count** — the macro's default. The
+ * same 1024 appears in `boss-rv-6`, whose Renesas reverb DSP has a 64Mbit SDRAM and no bucket
+ * brigade anywhere. **No formula from three 64Kx1 DRAMs lands on 1024 stages of a device class the
+ * pedal does not contain.**
+ */
+export type DerivedFrom = {
+    /** Which macro parameter this derives. */
+    readonly parameter: string;
+    /** The device whose spec determines it, by canonical part id. */
+    readonly fromPart: string;
+    /** The source, cited to edition and page, as the triode registry cites per parameter. */
+    readonly citation: string;
+    /** The arithmetic, stated so it can be re-run -- not a pointer at the parts. */
+    readonly formula: string;
+    /** What the formula yields. Must equal the constant the entry declares. */
+    readonly recomputes: number;
+};
+export declare function validateDerivation(d: DerivedFrom, declared: number): readonly ProxyViolation[];
+//# sourceMappingURL=proxy-declaration.d.ts.map

package/dist/proxy-declaration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy-declaration.d.ts","sourceRoot":"","sources":["../src/proxy-declaration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,UAAU,GAAG;IACxB,8BAA8B;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,+EAA+E;IAC/E,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,wFAAwF;IACxF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;;;;;;OAQG;IACH,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,kBAAkB,CAAC;IACjD,qGAAqG;IACrG,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,gIAAgI;IAChI,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC9B,yEAAyE;IACzE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,oFAAoF;IACpF,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B;;;;;;;OAOG;IACH,QAAQ,CAAC,gBAAgB,EAAE,SAAS,UAAU,EAAE,CAAC;IACjD;;;;;OAKG;IACH,QAAQ,CAAC,oBAAoB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAClD,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAElF,kFAAkF;AAClF,wBAAgB,aAAa,CAAC,CAAC,EAAE,gBAAgB,GAAG,SAAS,cAAc,EAAE,CAoC5E;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,MAAM,WAAW,GAAG;IACzB,0CAA0C;IAC1C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,iEAAiE;IACjE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,yFAAyF;IACzF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,gFAAgF;IAChF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,2EAA2E;IAC3E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC5B,CAAC;AAEF,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,cAAc,EAAE,CAU9F"}

package/dist/proxy-declaration.js

@@ -0,0 +1,50 @@
+/** Structural validation. A declaration that cannot fail is not a declaration. */
+export function validateProxy(p) {
+    const out = [];
+    if (p.standsFor.trim() === "")
+        out.push({ field: "standsFor", problem: "must name the real part and what it actually is" });
+    if (p.justification.trim() === "")
+        out.push({ field: "justification", problem: "must say why the stand-in is defensible" });
+    if (p.doesNotReproduce.length === 0)
+        out.push({
+            field: "doesNotReproduce",
+            problem: "must name at least one thing the proxy fails to reproduce -- a proxy that reproduces everything is a model, not a proxy",
+        });
+    for (const [i, m] of p.doesNotReproduce.entries()) {
+        if (m.status === "registered-unrun") {
+            if ((m.fixture ?? "").trim() === "")
+                out.push({ field: `doesNotReproduce[${i}].fixture`, problem: "a registered-unrun claim must name the fixture that would run it" });
+            if ((m.expires ?? "").trim() === "")
+                out.push({ field: `doesNotReproduce[${i}].expires`, problem: "a registration with no expiry is a permanent excuse" });
+        }
+        // **All three parts are required, because two of them are the falsifier.** A `claim` alone
+        // is prose; a `measurement` without a `standIn` cannot be compared; a `standIn` without a
+        // `measurement` cannot be reproduced.
+        if (m.claim.trim() === "")
+            out.push({ field: `doesNotReproduce[${i}].claim`, problem: "is empty" });
+        if (m.measurement.trim() === "")
+            out.push({
+                field: `doesNotReproduce[${i}].measurement`,
+                problem: "must say how to measure it -- a claim nobody can run is not a falsifier",
+            });
+        if (m.standIn.trim() === "")
+            out.push({
+                field: `doesNotReproduce[${i}].standIn`,
+                problem: "must give the number THIS model yields, which is what a real block has to move",
+            });
+    }
+    return out;
+}
+export function validateDerivation(d, declared) {
+    const out = [];
+    for (const [k, v] of [["parameter", d.parameter], ["fromPart", d.fromPart], ["citation", d.citation], ["formula", d.formula]])
+        if (v.trim() === "")
+            out.push({ field: k, problem: "is empty" });
+    if (d.recomputes !== declared)
+        out.push({
+            field: "recomputes",
+            problem: `the cited formula yields ${d.recomputes} and the entry declares ${declared} -- a cited derivation that does not reproduce the constant is a guess with a footnote`,
+        });
+    return out;
+}
+//# sourceMappingURL=proxy-declaration.js.map

package/dist/proxy-declaration.js.map

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

package/dist/registry.d.ts

@@ -0,0 +1,323 @@
+import type { DeviceLaw, MacroModel, PartIdentity } from "./types";
+/**
+ * One section of a multi-section part: a law plus which of the device's terminals it uses.
+ *
+ * `terminals` are indices into the device's own terminal list, given in the canonical order the
+ * law's lowering expects -- two ends for a two-terminal law, `plus, minus, output` for an op-amp.
+ * That order is the contract, because a section bypasses the terminal-role lookup lowering does
+ * for a whole device: an 8-pin dual op-amp has two outputs and two inverting inputs, so no single
+ * role token can name either of them unambiguously.
+ */
+export type PartSection = {
+    readonly law: DeviceLaw;
+    readonly terminals: readonly number[];
+};
+/**
+ * The terminal order a `sections` model's indices assume, as role tokens, index-aligned with the
+ * device's own terminal list. `null` means that position carries no role token to check against.
+ *
+ * **Positional indices are only meaningful against a known declaration order, and the corpus proves
+ * two documents can order the same chip differently.** `boss-ce-2b` declares a `TL022CP` as
+ * `pin1_OUT_B, pin2_IN_B_MINUS, pin3_IN_B_PLUS, pin4_VEE, pin5_IN_A_PLUS, ...` -- physical pin
+ * order -- while `boss-bf-2` declares the same part number grouped by section, as
+ * `outA, invertingInputA, nonInvertingInputA, outB, ...`. One entry's `terminals` indices are
+ * correct for exactly one of those, and applied to the other they wire an amplifier's output to
+ * its input.
+ *
+ * Without this field that mistake is silent: every index resolves, every section stamps, and the
+ * pedal renders a plausible wrong circuit. With it, a document the entry was not written against
+ * refuses by name instead. It is the same reasoning as `identify`'s whole-token comparison -- a
+ * coverage bound is acceptable, a wrong answer is not.
+ */
+export type PartPinout = readonly (string | null)[];
+/**
+ * What the registry knows about a part. Either it reduces to lumped elements the
+ * solver can stamp, or it is a DSP algorithm with ports that the runtime implements.
+ *
+ * **`sections` exists because most real chips are multi-section and neither other arm can express
+ * one.** A dual op-amp is two amplifiers on eight pins: not one `law`, which produces a single
+ * element, and not a `macro` either, because a macro becomes its own block solved *outside* the MNA
+ * system while an op-amp's output depends on the feedback network that depends on its output.
+ * Lowering it to a separate DSP block breaks the loop that makes it an amplifier.
+ *
+ * A `sections` part is expanded by stage 3 into one ordinary device per section, so partitioning,
+ * lowering and the runtime see nothing new.
+ */
+/**
+ * Where a macro's ports sit, named by terminal role rather than by terminal index.
+ *
+ * **This is the same problem `PartPinout` solves for `sections`, with a better answer available.**
+ * A positional index is only meaningful against a known declaration order, and the corpus orders
+ * one bucket brigade three ways: `boss-ce-2` declares `gnd, cp1, in, vgg, vdd, cp2, out1, out2`,
+ * `boss-dm-2` declares the same family part as `gnd, cp2, out1, out2, vdd, cp1, in, vgg`, and
+ * `electro-harmonix-electric-mistress` declares a two-terminal shell as `input, output`. One entry
+ * carrying indices is correct for exactly one of those and silently mis-wires the rest.
+ *
+ * `sections` cannot escape indices — a dual op-amp has two outputs and two inverting inputs, so no
+ * single role token names either unambiguously, which is why that arm refuses on a pinout guard
+ * instead. A macro's audio in and audio out are exactly one terminal each, so a role token *does*
+ * name them, and resolving by role is order-independent rather than order-checked. One entry then
+ * serves every declaration order that names its terminals at all.
+ *
+ * The bound is the same one `identify` accepts: whole-token comparison cannot invent a match, but
+ * the transcriber must have used a spelling listed here. A packet numbering its pins `pin1..pin8`
+ * produces no role tokens and is refused by name rather than guessed at.
+ */
+export type MacroPortRoles = {
+    /** Aliases for the audio input terminal. Compared as whole folded tokens. */
+    readonly audioIn: readonly string[];
+    /** Aliases for the audio output terminal. Compared as whole folded tokens. */
+    readonly audioOut: readonly string[];
+    /**
+     * Aliases for a **second** audio output terminal, for a part that has two.
+     *
+     * A BBD is the case this exists for: an MN3208/BL3208 brings out OUT1 and OUT2, and a design
+     * puts a balance trimmer across them because the signal appears on both while the clock
+     * feedthrough appears in antiphase, so the pot nulls the clock and keeps the audio. Declaring
+     * only OUT1 left OUT2 driven by nothing, and the trimmer then acted as a plain attenuator
+     * against whatever bled through its own track -- measured on `mxr-carbon-copy` as **6.0 dB
+     * lost across four brigades at the trimmers' centre default against 0.67 dB with the wipers
+     * on the driven pin**, which a compandor downstream then squared.
+     *
+     * Empty (the default for every part that does not set it) means the part has one output, and
+     * nothing about the single-output path changes.
+     */
+    readonly audioOut2?: readonly string[];
+    /**
+     * Aliases for the terminal whose network derives the `parameter` port, if the part has one.
+     *
+     * Optional in effect rather than in type: an empty list means the part has none. Unlike the
+     * audio ports, failing to resolve this is not a refusal — `couple.ts` documents an absent
+     * `parameter` port as the safe default, where an absent audio port is an amputation.
+     */
+    readonly parameter: readonly string[];
+};
+/**
+ * A macro as the registry states it: everything `MacroModel` carries except the terminal indices
+ * and the pedal-specific parameters, which stage 3 resolves per device.
+ *
+ * Same split as `sections`' op-amp rails, and for the same reason — a registry describes a part,
+ * and where its terminals landed and how fast its clock runs are properties of the pedal it was
+ * fitted to.
+ */
+/**
+ * 0-indexed physical terminal positions for a document that numbers its pins (`pin1`, `pin2`, ...
+ * -- `terminalRoleToken` returns null for those) and so carries no role tokens. Only consulted when
+ * every terminal is bare; a document that names even one terminal resolves by role, never by these.
+ */
+export type MacroBarePinPositions = {
+    readonly audioIn: number;
+    readonly audioOut: number;
+    readonly parameter?: number;
+};
+export type MacroPartModel = {
+    readonly modelId: string;
+    /** Part-intrinsic parameters only. Pedal-specific ones are merged in at resolution. */
+    readonly parameters: Readonly<Record<string, number>>;
+    readonly ports: MacroPortRoles;
+    readonly barePinPositions?: MacroBarePinPositions;
+    readonly audioPortImpedanceOhms: MacroModel["audioPortImpedanceOhms"];
+    readonly parameterReferenceVolts: number | null;
+};
+export type PartModel = {
+    readonly kind: "law";
+    readonly law: DeviceLaw;
+} | {
+    readonly kind: "sections";
+    readonly sections: readonly PartSection[];
+    /** The declaration order `sections[*].terminals` index into. See `PartPinout`. */
+    readonly pinout: PartPinout;
+} | {
+    readonly kind: "macro";
+    readonly macro: MacroPartModel;
+} | {
+    /**
+     * A chip whose silicon holds both lumped analog stages and a sampled
+     * core (first case: the PT2399's internal filter op-amps around its
+     * ADC/RAM/DAC): `sections` expand to ordinary MNA devices exactly as
+     * the `sections` arm does, and `core` resolves to the macro block
+     * exactly as the `macro` arm does, against the same device. Neither
+     * arm can express this alone -- a section is a lumped law and a
+     * macro solves outside MNA -- so the entry carries both, and the
+     * arms stay exclusive otherwise.
+     */
+    readonly kind: "sections-core";
+    readonly sections: readonly PartSection[];
+    /** The declaration order `sections[*].terminals` index into. See `PartPinout`. */
+    readonly pinout: PartPinout;
+    /** The sampled core, resolved as a macro against the whole device. */
+    readonly core: MacroPartModel;
+};
+/**
+ * The index of the one terminal whose role matches any of `aliases`, or `null`.
+ *
+ * `null` for no match and for an ambiguous one. Two terminals answering to the same port role is a
+ * declaration this entry cannot address — a `SAD1024`'s two cascaded sections both carry an
+ * `input` if a document names them that way — and picking the first would be a guess about which
+ * half the audio enters.
+ */
+export declare function terminalWithRole(terminalRoles: readonly (string | null)[], aliases: readonly string[]): number | null;
+/**
+ * Does this device declare the terminal order a `sections` entry's indices were written against?
+ *
+ * Length must match, and every position the entry names must carry that role token. A position the
+ * entry leaves `null` is unchecked, which is what lets a part whose document numbers its pins
+ * (`pin1`, `pin2`, ... -- `terminalRoleToken` returns null for those) still be expanded.
+ */
+export declare function pinoutMatches(pinout: PartPinout, terminalRoles: readonly (string | null)[]): boolean;
+import type { FirmwareEvidence } from "./firmware-class";
+import type { TerminalProfile } from "./terminal-role";
+import type { ProxyDeclaration } from "./proxy-declaration";
+export type PartEntry = {
+    /** Matched whole and case-folded against a device's part number. */
+    readonly partIds: readonly string[];
+    /** Matched whole against the source's closed type vocabulary. */
+    readonly declaredTypes: readonly string[];
+    /**
+     * Required terminal role tokens. Every group must be satisfied by at least one
+     * alias, compared as whole tokens. Empty means this part has no pinout signature.
+     */
+    readonly terminalRoleGroups: readonly (readonly string[])[];
+    readonly model: PartModel;
+    /**
+     * **Present when this entry's model is a STAND-IN for a part it is not.** Required for any
+     * macro binding a part whose packets declare its behaviour unavailable, and read by
+     * `report-record-behaviour.ts`: a firmware-blocked part that executes a macro is a fidelity
+     * overclaim **unless** the binding declares itself a proxy and says what it fails to
+     * reproduce. Absent means the entry asserts it models the part.
+     */
+    readonly proxy?: ProxyDeclaration;
+    /**
+     * **Whether this chip's behaviour comes from a program — typed, with positive evidence.**
+     * Absent means `undetermined`, which is **not** a scope boundary. See `firmware-class.ts`: the
+     * compiler's current operative test reads the packet's *record* rather than the chip, so a
+     * failed dump search becomes "this contains firmware" with nothing demonstrating it.
+     */
+    readonly firmware?: FirmwareEvidence;
+    /**
+     * **The whole package's own supply current at no load, in amps, from its datasheet.**
+     *
+     * An `ideal-opamp` takes its rails as numbers and a clock driver's phases are ideal sources, so
+     * without this no IC draws anything from the supply: `boss-ce-2`'s battery read 2.7 mA against
+     * the 9 mA its service notes print, the missing ~6 mA being its 4558, TL022 and MN3101.
+     * `device-laws.ts` lowers it as a conductance across the package's supply pins, sized at the
+     * pedal's own rail span, so the draw is right at the rail the pedal runs on. A device that
+     * declares one section of a multi-section package draws that section's share.
+     *
+     * Absent means no datasheet figure is recorded, and the part draws nothing, as before.
+     */
+    readonly quiescentSupplyAmps?: number;
+    /**
+     * **What each terminal IS, with per-terminal evidence.** Absent means `unpopulated`, which is a
+     * correct state rather than a gap: a consumer that needs audio terminals must fall back to
+     * bridging everything and **report its result as an upper bound**.
+     */
+    readonly terminalProfile?: TerminalProfile;
+    /**
+     * **Which other parts this entry's model ACCOUNTS FOR.** Canonical part ids of devices whose
+     * behaviour is inside this model's abstraction, so a consumer can move them out of an engine-gap
+     * count **with evidence** rather than by a packet-level guess.
+     *
+     * **This is the third instance of one defect.** A macro block carries `kind id modelId
+     * parameters audioIn audioOut parameter modulation clockControl` and **no way to say what it
+     * stands for** — so whoever bound `RDD63H101` to a bucket-brigade had nowhere to write *"and
+     * this also accounts for the three DRAMs and the ladder"*, exactly as whoever wrote
+     * `undisclosed-roland-boss-dsp` had nowhere to write *"this part has no name"*, and exactly as
+     * `open` stood in for five different claims. **Prose in an identity field, a catch-all value,
+     * and a macro that cannot name its scope: three coping strategies, one missing field each.**
+     *
+     * **Deliberately on the ENTRY rather than inside `proxy`**, because subsumption and
+     * approximation are independent: `M50195` is a legitimate model of a fixed-function chip — not
+     * a proxy at all — and it still subsumes the `4164` DRAM it addresses.
+     *
+     * **WITHDRAWN ON ITS FIRST DAY, and that is the field working.** Two entries declared
+     * `subsumes` on 2026-09-11 -- `RDD63H101` claiming three DRAMs and an R2R ladder, `M50195P`
+     * claiming a `4164` -- and all nine claims passed the structural check (12-14 shared nodes) and
+     * then **all nine collapsed under the parameter mutant**. `stages: 1024` is a catalog constant
+     * and `delaySeconds` comes from the owner's own `DelayMs`; neither moves when the subsumed
+     * device's part is changed. The macros are not parameterised by what they claimed to account
+     * for, so the claims were decorative. **A shared bus looks identical either way, which is
+     * exactly what the structural check cannot see.**
+     *
+     * **The field stays; the claims go.** Any future `subsumes` entry must pass
+     * `scripts/report-subsumption-mutant.ts`: mutate the subsumed device's spec and the claiming
+     * macro's parameters must move. **THE DERIVATION IS THE EVIDENCE** -- a subsumption claim that
+     * cannot name which macro parameter the subsumed device determines is as empty as a device
+     * parameter with no source citation, which the triode registry already knows how to carry.
+     */
+    readonly subsumes?: readonly string[];
+    /**
+     * **Claims that were MADE and REFUTED, kept rather than erased.** "Declared and refuted" is a
+     * different failure from "the record said nothing", and a census that collapses them loses the
+     * distinction between a packet that never spoke and one that spoke and was wrong.
+     */
+    readonly subsumesRefuted?: readonly {
+        readonly parts: readonly string[];
+        readonly refutedBy: string;
+        readonly on: string;
+    }[];
+    /**
+     * **This part is a data converter, and what its full scale is.** Read by `converter-scale.ts`:
+     * a program runs in volts, so a DSP between an ADC and a DAC is unity only if the two full
+     * scales are equal. The real gain is `dac / adc`, and it is a fact about the two parts, not
+     * something a document should have to declare.
+     */
+    readonly converter?: ConverterDeclaration;
+};
+/**
+ * A converter's full scale, cited. `fullScaleVoltsPeakToPeak` is null when no datasheet was
+ * obtained, and `basis` then says what was searched: an unknown full scale is a named gap, never
+ * a guessed number.
+ */
+export type ConverterDeclaration = {
+    readonly direction: "adc" | "dac";
+    readonly fullScaleVoltsPeakToPeak: number | null;
+    readonly basis: string;
+};
+export type PartRegistry = {
+    readonly entries: readonly PartEntry[];
+};
+export declare const emptyRegistry: PartRegistry;
+/** Run `fn` with registry reads recorded against `owner`. Nesting is honoured; the outer set wins. */
+export declare function withRecordedReads<T>(owner: string, fn: () => T): T;
+/** What each owner consulted. Keyed by the owner string passed to `withRecordedReads`. */
+export declare function recordedReads(): ReadonlyMap<string, ReadonlySet<string>>;
+/** Forget everything recorded so far. Callers that measure one packet at a time need this. */
+export declare function clearRecordedReads(): void;
+export declare function registryEntryFor(registry: PartRegistry, identity: PartIdentity, terminalCount?: number): PartEntry | null;
+export declare function registryModelFor(registry: PartRegistry, identity: PartIdentity, terminalCount?: number): PartModel | null;
+/** Part numbers compare ignoring case and separators: `MN-3007` is `mn3007`. */
+export declare function foldPartId(value: string | undefined | null): string;
+/** Typed vocabulary values compare ignoring case and whitespace, keeping structure. */
+export declare function foldToken(value: string | undefined | null): string;
+/**
+ * The law a registered part supplies for a device whose class already names its law kind.
+ *
+ * This is rung 1 of `identify.ts`'s evidence ladder and **only** rung 1: an exact manufacturer
+ * part number, compared whole and case-folded. The other two rungs are deliberately unreachable
+ * here.
+ *
+ * - **Declared type is not consulted.** `Circuit.Pentode` is a *class*, and resolving a class to
+ *   one part's model would claim every pentode in the corpus is an EL84 — the same reason
+ *   `part-catalog.ts` leaves `declaredTypes` empty for op-amps.
+ * - **Pinout signature is not consulted.** Every pentode has the same electrodes, so a pinout
+ *   match cannot tell an EL84 from a KT66. That is exactly the case where a wrong identity is
+ *   worse than none.
+ *
+ * `lawKind` must match the law the device's class already implies, so an entry can only refine
+ * the law that class was going to get. A triode cannot be handed a pentode's fit by a catalog
+ * typo; it falls back instead.
+ *
+ * Returns `null` when nothing matches, which is a correct and expected answer — the caller keeps
+ * its device-class default. See `findGenericTubeFits`, which reports every such fallback, because
+ * a silent one is what let every amp in the corpus run a 6V6 fit.
+ */
+export declare function registryLawFor(registry: PartRegistry, partNumber: string | null, lawKind: DeviceLaw["kind"]): DeviceLaw | null;
+/**
+ * How far a part's output stops short of each supply rail, from the registry entry that names
+ * it, or `null` when the part is not in the registry or states none (the rails are then used as
+ * they are). Read from either an `ideal-opamp` law entry or the first section of a `sections`
+ * entry, because a declared `opamp` device never reaches the section lowering.
+ */
+export declare function registryOpampSwingDrop(registry: PartRegistry, partNumber: string | null): number | null;
+//# sourceMappingURL=registry.d.ts.map