@vessel-dsp/compiler 0.0.0-stage → 0.3.0

package/dist/compile.js

@@ -0,0 +1,348 @@
+// The pipeline: `.vdsp` source text -> a program, or an explanation of the refusal.
+//
+// Seven stages, composed. The registry is a parameter rather than an import, so the
+// compiler holds no knowledge of any specific part -- and compiling with an empty
+// registry is a legitimate configuration that measures what works with no part
+// knowledge at all.
+import { attachDeviceLaws, composeMacroBlocks, findElectricallyIsolatedIcs, findIcsNotExecuted, findUnimplementedDeviceLaws, JFET_DEFAULT_THRESHOLD_VOLTS, JFET_DEFAULT_TRANSCONDUCTANCE, SILICON_FORWARD_BETA, SILICON_SATURATION_CURRENT, } from "./device-laws.js";
+import { findMultiDeviceShells, findUnreadableTerminalRoles, } from "./unreadable-terminal-role.js";
+import { findUnexecutedRegions } from "./unexecuted-region.js";
+import { deriveBypass } from "./bypass.js";
+import { applyConverterScale } from "./converter-scale.js";
+import { couple } from "./couple.js";
+import { emit } from "./emit.js";
+import { StageRefusal } from "./errors.js";
+import { findInertControls } from "./inert-controls.js";
+import { link } from "./link.js";
+import { lower } from "./lower.js";
+import { readNetlist } from "./netlist.js";
+import { partition } from "./partition.js";
+import { emptyRegistry, registryLawFor } from "./registry.js";
+import { findDanglingActiveTerminals, synthesizeOpampImplicitBias, } from "./dangling-active-terminal.js";
+import { findOverDrivenNodes } from "./over-driven-node.js";
+import { findSupplyShorts } from "./supply-short.js";
+import { findUnreachableOutput } from "./unreachable-output.js";
+import { findPowerDomainControls } from "./power-domain-control.js";
+import { findUnimplementedControlRoles } from "./unimplemented-control-role.js";
+import { findUnverifiedPinoutBindings } from "./unverified-pinout.js";
+import { findGenericTubeFits } from "./generic-tube-fit.js";
+import { findGroundedClockSupplies } from "./grounded-clock-supply.js";
+import { findNonExecutableClockDrivers } from "./non-executable-clock-drivers.js";
+import { GROUND } from "./types.js";
+import { findUnboundedOpamps } from "./unbounded-operating-point.js";
+/**
+ * Compile, or explain the refusal. This never throws for a document it cannot use.
+ *
+ * A stage raises a `StageRefusal` when the *source* does not support a program, and
+ * that becomes a result rather than an exception: one malformed packet must not take
+ * down a batch, and "could not read the document" is an answer a caller can act on.
+ *
+ * Anything else propagates. A compiler bug reported as an unsupported pedal would be
+ * a wrong answer about someone's circuit, so the catch is deliberately narrow.
+ */
+export function compile(source, options = { registry: emptyRegistry }) {
+    try {
+        return run(source, options);
+    }
+    catch (error) {
+        if (!(error instanceof StageRefusal)) {
+            throw error;
+        }
+        return {
+            status: "unsupported",
+            reasons: [
+                { stage: error.stage, device: error.device, reason: error.message },
+            ],
+        };
+    }
+}
+function run(source, options) {
+    const netlist = readNetlist(source, {
+        inputJack: options.inputJack,
+        outputJack: options.outputJack,
+    });
+    const lawed = attachDeviceLaws(netlist, options.registry ?? emptyRegistry);
+    // Decision 1: an unmodellable device makes the whole pedal/amp unsupported, and
+    // the refusal names every component and reason rather than the first one.
+    const unsupported = lawed.resolutions.filter((resolution) => resolution.outcome === "unsupported");
+    if (unsupported.length > 0) {
+        return {
+            status: "unsupported",
+            reasons: unsupported.map((resolution) => ({
+                stage: "device-laws",
+                device: resolution.device,
+                reason: resolution.outcome === "unsupported" ? resolution.reason : "",
+            })),
+        };
+    }
+    const partitioning = partition(lawed);
+    const lowered = lower(partitioning, lawed);
+    // Stage 5.5: a macro's `coupled`/`parameter` ports reference other blocks, so wiring them
+    // happens once every region has one, not while `lower` is still producing them one at a time.
+    // `couple` also corrects the dependency graph's audio-out edge (clause 3, the region
+    // schedule) -- `link` must sort against that corrected graph, not stage 4's original one, or
+    // a coupled seam's downstream side would be free to run before the macro that feeds it.
+    const coupled = couple(lowered, partitioning, lawed);
+    const bypass = deriveBypass(netlist);
+    // Stage 5.75 (board-p3 row 4): the three decomposed models execute as
+    // catalog-parameterized compositions. Unconditional since board-p3 row 7 deleted the
+    // dispatched kernels: there is no second route to emit, and both runtimes refuse a
+    // `macro` block by name rather than execute one.
+    const composed = composeMacroBlocks(coupled.blocks);
+    const linked = link(composed, { ...partitioning, dependencies: coupled.dependencies }, netlist.controls, netlist.ports, netlist.portImpedanceOhms, netlist.portDeclaredFullScaleVolts, bypass);
+    // Stage 6.5: an op-amp the topology leaves genuinely undefined (no DC path back to its
+    // inverting input, or none from its non-inverting input to any reference) gets an implicit
+    // bias so its operating point is bounded rather than left to whatever `gmin` alone settles
+    // into -- see `dangling-active-terminal.ts`'s "implicit op-amp DC-bias synthesis" section.
+    // Every later Program-consuming stage below reads the bridged program, because that is the
+    // one the runtime will actually execute.
+    // Stage 6.75: a composed program between two converters takes their full-scale ratio as its
+    // level, or says why it cannot. Read from the catalog by exact part id and found by
+    // connectivity, so nothing about it is declared in the document.
+    const scaled = applyConverterScale(synthesizeOpampImplicitBias(linked), netlist, options.registry ?? emptyRegistry);
+    const program = scaled.program;
+    // A program with no blocks has nothing to execute, so calling it `ok` reports a
+    // compiled pedal that can only ever render silence. `boss-ps-2` reaches here: its
+    // jacks and ground are wired and its 223 electrically active parts declare no
+    // terminals, so every one is correctly dropped and nothing is left to solve.
+    if (program.blocks.length === 0) {
+        return {
+            status: "unsupported",
+            reasons: [
+                {
+                    stage: "link",
+                    device: null,
+                    reason: "no component contributes to the signal path, so the program has nothing to execute",
+                },
+            ],
+        };
+    }
+    // Strict Admission: Floating wipers or completely disconnected devices are genuine structural
+    // defects in the source capture that must be refused. Controls in unscheduled blocks (e.g.
+    // unselected channels or scope exclusions documented in packet boundary) remain warnings.
+    const inertControls = findInertControls(netlist, program);
+    const structuralDefects = inertControls.filter((w) => w.isStructuralDefect);
+    if (structuralDefects.length > 0) {
+        return {
+            status: "unsupported",
+            reasons: structuralDefects.map((w) => ({
+                stage: "link",
+                device: (w.devices && w.devices.length > 0) ? w.devices[0] : null,
+                reason: w.detail,
+            })),
+        };
+    }
+    // Warnings are computed only for a program that exists and whose controls are connected.
+    return {
+        status: "ok",
+        program,
+        warnings: [
+            ...(netlist.warnings ?? []),
+            ...inertControls.filter((w) => !w.isStructuralDefect),
+            ...findUnboundedOpamps(netlist),
+            ...findSupplyShorts(netlist),
+            ...findOverDrivenNodes(program),
+            ...findDanglingActiveTerminals(program),
+            ...findGroundedClockSupplies(program),
+            ...findNonExecutableClockDrivers(netlist, options.registry ?? emptyRegistry),
+            ...findGenericTubeFits(netlist, options.registry ?? emptyRegistry),
+            ...findUnverifiedPinoutBindings(netlist, options.registry ?? emptyRegistry),
+            ...findPowerDomainControls(netlist, program.controls ?? [], [netlist.ports.input, netlist.ports.output].filter((node) => typeof node === "number")),
+            ...findUnimplementedControlRoles(program.controls ?? []),
+            ...findElectricallyIsolatedIcs(netlist),
+            ...findIcsNotExecuted(lawed, netlist, options.registry ?? emptyRegistry),
+            ...findUnreadableTerminalRoles(lawed),
+            ...findMultiDeviceShells(lawed),
+            ...findUnimplementedDeviceLaws(lawed),
+            ...findUnreachableOutput(program, netlist),
+            ...findUnexecutedRegions(program),
+            ...findDeclaredDelays(program),
+            ...findUnmodelledModulation(program),
+            ...findRailsWithoutVoltage(netlist),
+            ...findFetLawDefaults(netlist, options.registry ?? emptyRegistry),
+            ...findBjtLawDefaults(netlist),
+            ...findOpampLawDefaults(lawed),
+            ...scaled.warnings,
+        ],
+    };
+}
+/**
+ * Delay macros whose modulation input the part declares and the document wires, but which
+ * admission refused -- so the delay is a constant and whatever sweeps it in the real pedal does
+ * not reach it.
+ *
+ * This is the difference between a flanger and a fixed comb filter, and the two compiled to
+ * indistinguishable programs. The refusal itself is correct -- gate 1b measured that an
+ * LFO-swept clock is a signal rather than a control-rate parameter -- but a correct refusal that
+ * nobody is told about renders a pedal doing none of what it is named for.
+ */
+function findUnmodelledModulation(program) {
+    return program.blocks.flatMap((block) => (block.kind === "macro" || block.kind === "composed") &&
+        typeof block.modulationRefusal === "string"
+        ? [
+            {
+                code: "modulation-not-modelled",
+                device: null,
+                detail: `${block.id} declares a modulation input this document wires, but ` +
+                    `${block.modulationRefusal}. ` +
+                    // The consequence is not the same in both cases, and saying the wrong
+                    // one discredits the warning: a delay that derives from its own clock
+                    // network still works, it just cannot be swept.
+                    (block.clockControl != null || block.delayProvenance === "derived"
+                        ? "Its delay still follows its own clock network, but nothing in the " +
+                            "circuit can sweep it."
+                        : "Its delay is therefore a constant, and whatever sweeps it in the " +
+                            "real pedal does not reach it."),
+            },
+        ]
+        : []);
+}
+/**
+ * Delay macros whose delay time was typed into the source instead of derived from the clock
+ * network they are wired to.
+ *
+ * A derived delay is a consequence of the packet's own R and C: change either and it moves, and
+ * a wrong value shows up as a wrong delay. A declared `DelayMs` renders exactly what it says and
+ * is therefore unfalsifiable by any render -- which is precisely why it must not pass silently.
+ * The two were indistinguishable in the program until now, so a reader could not tell a
+ * simulated delay from a reported one.
+ */
+function findDeclaredDelays(program) {
+    return program.blocks.flatMap((block) => (block.kind === "macro" || block.kind === "composed") &&
+        block.delayProvenance === "declared"
+        ? [
+            {
+                code: "declared-delay-not-derived",
+                device: null,
+                detail: `${block.id} runs ${block.modelId} at ` +
+                    `${((block.parameters.delaySeconds ?? 0) * 1000).toFixed(1)} ms taken from the ` +
+                    `source's declared DelayMs, not derived from a clock network: ` +
+                    `${block.delayDeclaredReason ?? "no reason recorded"}. That number renders ` +
+                    `whatever it says, so it is not evidence about this circuit's delay time.`,
+            },
+        ]
+        : []);
+}
+/** Voltage-less rails that something is connected to. See `RailWithoutVoltageWarning`. */
+function findRailsWithoutVoltage(netlist) {
+    const loaded = new Map();
+    for (const device of netlist.devices) {
+        for (const node of new Set(device.nodes))
+            loaded.set(node, (loaded.get(node) ?? 0) + 1);
+    }
+    return netlist.devices.flatMap((device) => {
+        if (device.kind !== "rail")
+            return [];
+        const volts = device.parameters.volts;
+        if (volts !== undefined && Number.isFinite(volts))
+            return [];
+        const attached = [...new Set(device.nodes)].filter((node) => node !== GROUND && (loaded.get(node) ?? 0) > 1);
+        if (attached.length === 0)
+            return [];
+        return [
+            {
+                code: "rail-without-voltage",
+                device: device.id,
+                detail: `${device.id} declares no voltage, so it asserts nothing and lowers open; ` +
+                    `${attached.length === 1 ? `node ${attached[0]} has` : `nodes ${attached.join(", ")} have`} ` +
+                    "other devices attached, and they see only gmin to ground. A supply the sheet draws " +
+                    "there solves at 0 V.",
+            },
+        ];
+    });
+}
+/** JFETs stamped with the fet law's own defaults. See `FetLawDefaultWarning`. */
+function findFetLawDefaults(netlist, registry) {
+    const defaulted = netlist.devices.filter((device) => device.kind === "jfet" &&
+        (device.parameters.thresholdVolts === undefined ||
+            device.parameters.transconductance === undefined) &&
+        // A registered part runs on its catalog entry, not the class default --
+        // naming it here would claim the opposite. Exact part id only, the same
+        // rung `device-laws.ts` refines on.
+        registryLawFor(registry, device.identity.partNumber, "fet") === null);
+    if (defaulted.length === 0)
+        return [];
+    const listed = defaulted.map((device) => {
+        const missing = [
+            device.parameters.thresholdVolts === undefined ? "Vt0" : null,
+            device.parameters.transconductance === undefined ? "Beta" : null,
+        ].filter((name) => name !== null);
+        const part = device.identity.partNumber;
+        return `${device.id}${part === null ? "" : ` (${part})`} without ${missing.join("/")}`;
+    });
+    return [
+        {
+            code: "fet-law-default-parameters",
+            device: null,
+            devices: defaulted.map((device) => device.id),
+            detail: `${defaulted.length} JFET(s) run on the fet law's own defaults ` +
+                `(Vt0 ${JFET_DEFAULT_THRESHOLD_VOLTS} V, Beta ${JFET_DEFAULT_TRANSCONDUCTANCE * 1e3} mS), ` +
+                `which are not any part's values: ${listed.join("; ")}. Harmless for a switch that is ` +
+                "fully on or off; decisive for one biased near its knee.",
+        },
+    ];
+}
+/** BJTs stamped with the bjt law's own defaults. See `BjtLawDefaultWarning`. */
+function findBjtLawDefaults(netlist) {
+    const defaulted = netlist.devices.filter((device) => device.kind === "bjt" &&
+        (device.parameters.saturationCurrent === undefined ||
+            device.parameters.beta === undefined));
+    if (defaulted.length === 0)
+        return [];
+    const listed = defaulted.map((device) => {
+        const missing = [
+            device.parameters.saturationCurrent === undefined ? "IS" : null,
+            device.parameters.beta === undefined ? "BF" : null,
+        ].filter((name) => name !== null);
+        const part = device.identity.partNumber;
+        return `${device.id}${part === null ? "" : ` (${part})`} without ${missing.join("/")}`;
+    });
+    return [
+        {
+            code: "bjt-law-default-parameters",
+            device: null,
+            devices: defaulted.map((device) => device.id),
+            detail: `${defaulted.length} BJT(s) run on the bjt law's own defaults ` +
+                `(IS ${SILICON_SATURATION_CURRENT} A, BF ${SILICON_FORWARD_BETA}), ` +
+                `which are not any part's values: ${listed.join("; ")}. Harmless for a saturated ` +
+                "switch; decisive for a biased stage.",
+        },
+    ];
+}
+/** Op-amps that state no output-swing drop. See `OpampLawDefaultWarning`. */
+function findOpampLawDefaults(lawed) {
+    const byId = new Map(lawed.netlist.devices.map((device) => [device.id, device]));
+    const stated = new Map();
+    for (const resolution of lawed.resolutions) {
+        if (resolution.outcome !== "law" || resolution.law.kind !== "ideal-opamp")
+            continue;
+        // A section of a package is lowered as `<device>#<index>`; the warning names the device.
+        const id = resolution.device.replace(/#\d+$/, "");
+        stated.set(id, (stated.get(id) ?? true) && resolution.law.outputSwingDropVolts !== undefined);
+    }
+    const defaulted = [...stated].flatMap(([id, has]) => (has ? [] : [id]));
+    if (defaulted.length === 0)
+        return [];
+    const listed = defaulted.map((id) => {
+        const part = byId.get(id)?.identity.partNumber ?? null;
+        return `${id}${part === null ? "" : ` (${part})`}`;
+    });
+    return [
+        {
+            code: "opamp-law-default-parameters",
+            device: null,
+            devices: defaulted,
+            detail: `${defaulted.length} op-amp(s) swing the full supply because the part states no ` +
+                `output-swing drop: ${listed.join("; ")}. Harmless for a stage that never nears ` +
+                "the rails; decisive for a comparator, an LFO or a clipper.",
+        },
+    ];
+}
+export function compileToArtifact(source, options) {
+    const result = compile(source, options);
+    return {
+        result,
+        artifact: result.status === "ok" ? emit(result.program) : null,
+    };
+}
+//# sourceMappingURL=compile.js.map

package/dist/compile.js.map

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

package/dist/converter-scale.d.ts

@@ -0,0 +1,14 @@
+import { type PartRegistry } from "./registry";
+import type { ConverterScaleNotModelledWarning, Netlist, Program } from "./types";
+/**
+ * Scale every composed block that sits between two cited converters, and name every one that
+ * touches a converter but cannot be scaled.
+ *
+ * A block no converter touches is left alone and raises nothing: a bucket-brigade composition
+ * is analog end to end and has no full scale to be wrong about.
+ */
+export declare function applyConverterScale(program: Program, netlist: Netlist, registry: PartRegistry): {
+    readonly program: Program;
+    readonly warnings: readonly ConverterScaleNotModelledWarning[];
+};
+//# sourceMappingURL=converter-scale.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"converter-scale.d.ts","sourceRoot":"","sources":["../src/converter-scale.ts"],"names":[],"mappings":"AAkBA,OAAO,EAGN,KAAK,YAAY,EACjB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EACX,gCAAgC,EAEhC,OAAO,EAEP,OAAO,EACP,MAAM,SAAS,CAAC;AA4BjB;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAClC,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,YAAY,GACpB;IAAE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,SAAS,gCAAgC,EAAE,CAAA;CAAE,CAoG/F"}

package/dist/converter-scale.js

@@ -0,0 +1,133 @@
+// Converter full scale: the gain a program between an ADC and a DAC actually has.
+//
+// A composed program runs in volts: its input is the solved voltage at its input node and its
+// output drives its output node in volts. That is exact only when the chip's converters have
+// equal full scales. In the pedal the ADC maps its full scale to digital 1.0 and the DAC maps
+// digital 1.0 back to its own, so the program's volts-to-volts gain is `dac / adc` times
+// whatever the firmware does. The firmware is the program; the ratio is a fact about two parts.
+//
+// **Connectivity, not names.** A converter is the one on the block's input or output node, found
+// by the node the circuit shares with it, and it is a converter because its exact part id has a
+// `converter` entry in the catalog. Nothing is declared in the document.
+//
+// **Unity and a warning, never a guess, when a side is unknown.** The ratio is applied only when
+// both sides are wired and both full scales are cited. Otherwise the program stays unity in volts,
+// which is a level assumption the reader must be told about: `boss-dd-5` sits ~7.5 dB below
+// its own deck for exactly this reason.
+import { canonicalPartId } from "./part-number.js";
+import { foldPartId, } from "./registry.js";
+/** The catalog's converter declaration for a device's exact part id, or null. */
+function converterOf(device, registry) {
+    const partNumber = device.identity.partNumber;
+    if (partNumber === null)
+        return null;
+    const canonical = foldPartId(canonicalPartId(partNumber));
+    for (const entry of registry.entries) {
+        if (entry.converter !== undefined &&
+            entry.partIds.some((id) => foldPartId(canonicalPartId(id)) === canonical)) {
+            return entry.converter;
+        }
+    }
+    return null;
+}
+function describe(converter) {
+    const fullScale = converter.declaration.fullScaleVoltsPeakToPeak;
+    return (`${converter.device.id} ${converter.device.identity.partNumber} ` +
+        (fullScale === null ? "(full scale not cited)" : `(${fullScale} Vp-p full scale)`));
+}
+/**
+ * Scale every composed block that sits between two cited converters, and name every one that
+ * touches a converter but cannot be scaled.
+ *
+ * A block no converter touches is left alone and raises nothing: a bucket-brigade composition
+ * is analog end to end and has no full scale to be wrong about.
+ */
+export function applyConverterScale(program, netlist, registry) {
+    const converters = netlist.devices.flatMap((device) => {
+        const declaration = converterOf(device, registry);
+        return declaration === null ? [] : [{ device, declaration }];
+    });
+    if (converters.length === 0)
+        return { program, warnings: [] };
+    // Ports and stamps address MNA rows, not source nodes, so both are translated through the
+    // owning block's `nodeIds` before they can be compared with a converter's terminals.
+    const sourceNode = new Map();
+    const outputNodeOf = new Map();
+    for (const block of program.blocks) {
+        if (block.kind !== "mna")
+            continue;
+        sourceNode.set(block.id, block.nodeIds);
+        for (const stamp of block.stamps) {
+            const node = block.nodeIds[stamp.kind === "macro-audio-source" ? stamp.node : -1];
+            if (stamp.kind === "macro-audio-source" && node !== undefined) {
+                outputNodeOf.set(stamp.macroId, node);
+            }
+        }
+    }
+    const on = (node, direction) => node === undefined
+        ? []
+        : converters.filter((converter) => converter.declaration.direction === direction &&
+            converter.device.nodes.includes(node));
+    const warnings = [];
+    const blocks = program.blocks.map((block) => {
+        if (block.kind !== "composed")
+            return block;
+        const adcs = on(block.audioIn === null
+            ? undefined
+            : sourceNode.get(block.audioIn.block)?.[block.audioIn.node], "adc");
+        const dacs = on(outputNodeOf.get(block.id), "dac");
+        // A reprogrammable chip's program sits behind converters by construction, so in a document
+        // that has them its volts-in, volts-out assumption is named even where neither is wired to it.
+        if (adcs.length === 0 && dacs.length === 0 && block.modelSource !== "declared")
+            return block;
+        const adc = adcs.length === 1 ? adcs[0] : undefined;
+        const dac = dacs.length === 1 ? dacs[0] : undefined;
+        const adcScale = adc?.declaration.fullScaleVoltsPeakToPeak ?? null;
+        const dacScale = dac?.declaration.fullScaleVoltsPeakToPeak ?? null;
+        if (adcScale !== null && dacScale !== null) {
+            const gain = dacScale / adcScale;
+            return {
+                ...block,
+                positions: block.positions.map((position) => ({
+                    ...position,
+                    ops: [
+                        ...position.ops,
+                        {
+                            op: "mix",
+                            terms: [{ source: { kind: "temp", index: position.out }, gain }],
+                            out: position.ops.length,
+                        },
+                    ],
+                    out: position.ops.length,
+                })),
+            };
+        }
+        const side = (found, direction, node) => {
+            if (found.length === 1)
+                return `its ${node} is ${describe(found[0])}`;
+            if (found.length > 1) {
+                return `its ${node} touches ${found.length} ${direction.toUpperCase()}s (${found.map((c) => c.device.id).join(", ")}), so which one converts is not decidable`;
+            }
+            const elsewhere = converters.filter((c) => c.declaration.direction === direction);
+            return (`its ${node} reaches no ${direction.toUpperCase()}` +
+                (elsewhere.length > 0
+                    ? `; ${elsewhere.map(describe).join(" and ")} ${elsewhere.length === 1 ? "is" : "are"} in the document, not wired to it`
+                    : ""));
+        };
+        warnings.push({
+            code: "converter-scale-not-modelled",
+            device: null,
+            detail: `${block.id} runs in volts, unity from input to output, but ` +
+                `${side(adcs, "adc", "input")}, and ${side(dacs, "dac", "output")}. ` +
+                "The pedal's gain there is the DAC's full scale over the ADC's, so the level of " +
+                "everything this program outputs is unmodelled by that ratio." +
+                [...adcs, ...dacs, ...converters]
+                    .filter((c, i, all) => all.indexOf(c) === i && c.declaration.fullScaleVoltsPeakToPeak === null)
+                    .map((c) => ` ${c.device.identity.partNumber}: ${c.declaration.basis}`)
+                    .join(""),
+        });
+        return block;
+    });
+    return { program: { ...program, blocks }, warnings };
+}
+//# sourceMappingURL=converter-scale.js.map

package/dist/converter-scale.js.map

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

package/dist/couple.d.ts

@@ -0,0 +1,28 @@
+import type { Block, LawedNetlist, Partitioning, Stamp } from "./types";
+export type Coupled = {
+    readonly blocks: readonly Block[];
+    /**
+     * `partitioning.dependencies`, corrected for every macro's audio-out edge -- see this
+     * file's header. This is what `link.ts` must sort against instead of the stage-4 graph,
+     * so a coupled seam's two sides land in the right order within a sample rather than the
+     * downstream side reading last sample's write-back by accident.
+     */
+    readonly dependencies: Partitioning["dependencies"];
+};
+export declare function couple(blocks: readonly Block[], partitioning: Partitioning, lawed: LawedNetlist): Coupled;
+/**
+ * A new stamp, added to a block whose `linear`/`controlFree` are re-derived rather than
+ * assumed unchanged -- the same rule `lowerRegion` itself follows, so a stamp this stage adds
+ * cannot silently leave a block claiming a solver cost or a control independence its own
+ * stamps contradict.
+ *
+ * Exported for `dangling-active-terminal.ts`'s implicit op-amp bias synthesis, which adds a
+ * stamp to an already-linked block for the same reason this stage does: a block's derived
+ * fields must never describe a stamps array it does not have.
+ */
+export declare function withStamp(block: Extract<Block, {
+    readonly kind: "mna";
+}>, stamp: Stamp): Extract<Block, {
+    readonly kind: "mna";
+}>;
+//# sourceMappingURL=couple.d.ts.map

package/dist/couple.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"couple.d.ts","sourceRoot":"","sources":["../src/couple.ts"],"names":[],"mappings":"AAoHA,OAAO,KAAK,EAAE,KAAK,EAAE,YAAY,EAAU,YAAY,EAAU,KAAK,EAAE,MAAM,SAAS,CAAC;AAGxF,MAAM,MAAM,OAAO,GAAG;IACrB,QAAQ,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,CAAC;IAClC;;;;;OAKG;IACH,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC,cAAc,CAAC,CAAC;CACpD,CAAC;AA6BF,wBAAgB,MAAM,CACrB,MAAM,EAAE,SAAS,KAAK,EAAE,EACxB,YAAY,EAAE,YAAY,EAC1B,KAAK,EAAE,YAAY,GACjB,OAAO,CAgaT;AAcD;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CACxB,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAA;CAAE,CAAC,EAC/C,KAAK,EAAE,KAAK,GACV,OAAO,CAAC,KAAK,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAA;CAAE,CAAC,CAgC1C"}