@vessel-dsp/compiler 0.0.0-stage → 0.3.0

package/dist/link.js

@@ -0,0 +1,270 @@
+// Stage 6: order the blocks and assemble the program.
+//
+// Execution order comes from the partition dependency graph: a macro model whose
+// parameters are set by an analog region must run after it. Topological, and a cycle
+// is an error rather than an arbitrary tie-break.
+//
+// **`order` is what executes, and it is not every block.** A block that cannot reach the
+// output is left out of it, which is the build order's "do not execute an operator that
+// cannot reach the output" -- see `executionOrder`. The blocks themselves all stay in the
+// program.
+//
+// The program carries its controls -- including each one's taper -- because taper is
+// emitted rather than evaluated at compile time. It deliberately carries **no sample
+// rate**: a program is valid at any rate and is given one at initialization.
+import { StageRefusal } from "./errors.js";
+import { portFullScaleVolts } from "./port-full-scale.js";
+import { stageCoverage } from "./stage-coverage.js";
+import { supplyReference } from "./supply-reference.js";
+export class LinkError extends StageRefusal {
+    constructor(message) {
+        super("link", null, message);
+    }
+}
+export function link(blocks, partitioning, controls, ports, 
+// Defaulted, because "the source declares no port impedance" is the state of almost every
+// document -- zero corpus input jacks declare one -- so a caller with nothing to say says nothing.
+portImpedanceOhms = {
+    input: null,
+    output: null,
+}, 
+// Likewise defaulted, and likewise a stage-1 read: `V0dBFS` is a declaration on the port's own
+// jack, which only stage 1 can see.
+portDeclaredFullScaleVolts = {
+    input: null,
+    output: null,
+}, bypass = { declared: "none" }) {
+    const order = executionOrder(blocks, partitioning);
+    const live = new Set(order);
+    const executed = blocks.filter((block) => live.has(block.id));
+    return {
+        formatVersion: 6,
+        // Read off `order`'s blocks, not `blocks` -- see `requiredOperators`'s own comment for
+        // why a pruned block's operator is not "required to execute a program" at all. The
+        // same exclusion applies to `requiredModels` and to `costPredictors`, for the same
+        // reason: a block that never runs cannot be a cost this program's execution needs to be
+        // admitted against, and cannot be an algorithm a runtime needs to gain to execute it.
+        requiredOperators: requiredOperators(executed),
+        requiredModels: requiredModels(executed),
+        costPredictors: costPredictors(executed, order.length),
+        blocks,
+        order,
+        controls,
+        ports,
+        // From `blocks`, not `executed`, and the difference is deliberate: the three fields
+        // above describe what executing this program costs and needs, so a pruned block cannot
+        // contribute to them. Which terminal the circuit calls ground is a property of the
+        // circuit as declared -- a positive-ground fuzz whose supply island happens not to
+        // reach the output port is still a positive-ground fuzz, and a chain sharing one
+        // physical supply has to know that.
+        supplyReference: supplyReference(blocks),
+        // From `blocks` and `ports` together: the bound is a property of the rails feeding the
+        // circuit and of which node the port landed on, both of which are already decided by
+        // the time this runs.
+        portFullScaleVolts: portFullScaleVolts(blocks, ports),
+        // **The port's declared 0 dBFS reference, kept apart from the derived ceiling above.**
+        //
+        // They are different quantities and folding them together is a level error, measured
+        // rather than argued: a pedal's derived output is its 9 V supply -- the largest voltage
+        // that node can reach -- while a declared input `V0dBFS` is 0.1 to 1 V, the voltage that
+        // *means* full scale. Substituting one for the other made 4,994 of the 13,806 ordered
+        // pedal-to-pedal seams scale by a median of 9x (+19 dB) and up to 240x (+47.6 dB), by
+        // dividing a ceiling by a reference.
+        //
+        // So a consumer picks the one its question needs. A render converting into a +/-1 file
+        // wants the reference where a source states one and the ceiling otherwise -- either is a
+        // valid conversion. `chainScaleFactor` compares two ports and needs like with like, so it
+        // still reads `portFullScaleVolts`; moving it to reference-to-reference would start
+        // scaling 850 seams at a median of +9.5 dB and belongs in its own change with its own
+        // listening pass.
+        portReferenceVolts: portDeclaredFullScaleVolts,
+        stageCoverage: stageCoverage(blocks, ports),
+        // A port property, decided in stage 1 where the jack's own declaration is readable.
+        portImpedanceOhms,
+        bypass,
+    };
+}
+/**
+ * The rate-independent cost facts the executed blocks can honestly declare — see
+ * `CostPredictors`'s own doc for what this deliberately omits and why.
+ */
+function costPredictors(executed, executedBlockCount) {
+    let stateCount = 0;
+    const solvedBlocks = [];
+    const macroBlocks = [];
+    for (const block of executed) {
+        if (block.kind === "macro" || block.kind === "composed") {
+            // Declared, not priced -- see `CostPredictors.macroBlocks`. Its absence is what let
+            // a macro's per-sample work cost zero at the admission gate. A composed block
+            // prices at its `modelId` exactly like the macro it replaces (board-p3 row 4,
+            // first slice): equal budget while the bit-identical gate holds; op-level
+            // costing follows with the catalog migration.
+            macroBlocks.push({ blockId: block.id, modelId: block.modelId });
+            continue;
+        }
+        stateCount += block.stateCount;
+        solvedBlocks.push({
+            blockId: block.id,
+            unknownCount: block.nodeCount + block.auxCount,
+            linear: block.linear,
+        });
+    }
+    return { executedBlockCount, stateCount, solvedBlocks, macroBlocks };
+}
+/**
+ * The blocks to execute, in dependency order: those that can reach the output.
+ *
+ * **Why any block cannot.** Stage 4 groups devices into regions by shared non-ground node,
+ * so two analog regions share nothing but ground — they are separate subcircuits, not
+ * halves of one system. The runtime solves each independently and takes its output sample
+ * from the block owning the output jack. A region owning neither the output nor an edge into
+ * something that does therefore has its entire solution discarded, every sample. Measured
+ * across the corpus: 141 of 191 regions own neither port, and 84% of the nodes solved per
+ * sample are thrown away. `boss-ds-1` is the extreme, and is exactly why it is both the
+ * slowest packet and a silent one.
+ *
+ * **Why the dependency graph is needed rather than the port fields alone.** A macro model's
+ * parameters can be set by an analog region it shares a node with — a BBD's delay time comes
+ * from its clock network — so a region with no port of its own can still be load-bearing.
+ * Reachability computed from `inputNode`/`outputNode` alone would delete the input shell and
+ * the clock network of the `hybridDelayPedal` fixture, which is a silent wrong answer rather
+ * than a slow one. Hence the traversal: if a live block depends on a producer, the producer
+ * is live too.
+ *
+ * **Why a macro block is seeded live unconditionally**, which is the conservative half of
+ * this rule and the reason it is safe to land before the operator format is finished. The
+ * `macro` variant carries no `inputNode` or `outputNode` at all, so the compiler cannot show
+ * that a macro fails to reach the output — the ports that would answer do not exist. The two
+ * errors are not symmetric: keeping a dead block costs solve time that shows up in a
+ * measurement, while dropping a live one is audio that is quietly missing a stage. So an
+ * unprovable case stays.
+ *
+ * **Why `order` and not `blocks`.** Pruning the block list would delete the structural
+ * record `report-compiler-fidelity.ts` reads — the compiler's own correctness gate while
+ * stamps exist — turning a scheduling change into a fidelity regression, and would also
+ * discard the circuit a later step still has to eliminate or factor. Leaving the blocks and
+ * shortening the execution list is the whole of the change the runtime needs: it already
+ * iterates `order`.
+ *
+ * The cycle refusal is deliberately computed over *every* block, before this filter: a
+ * cyclic dependency is a compiler defect whether or not the blocks in it are audible.
+ */
+function executionOrder(blocks, partitioning) {
+    const live = blocksReachingOutput(blocks, partitioning);
+    return topologicalOrder(blocks, partitioning).filter((id) => live.has(id));
+}
+function blocksReachingOutput(blocks, partitioning) {
+    const live = new Set();
+    const pending = [];
+    for (const block of blocks) {
+        // A composed block stays live like a macro: its readers are stamps, so its
+        // reachability is as unprovable as a macro's, and the error asymmetry is
+        // the same -- a kept dead block costs time, a dropped live one loses audio.
+        if (block.kind === "macro" ||
+            block.kind === "composed" ||
+            block.outputNode !== null) {
+            live.add(block.id);
+            pending.push(block.id);
+        }
+    }
+    while (pending.length > 0) {
+        const id = pending.pop();
+        for (const producer of partitioning.dependencies[id] ?? []) {
+            if (!live.has(producer)) {
+                live.add(producer);
+                pending.push(producer);
+            }
+        }
+    }
+    return live;
+}
+/**
+ * The operators the *executed* blocks actually use, sorted and deduplicated.
+ *
+ * Read off the stamps rather than assumed from the device kinds, because the two are not
+ * the same list: a pot lowers to two `controlled-conductance` stamps, a jack's engage
+ * contact to a `conductance`, and a device whose law is `open` stamps nothing at all. What
+ * a runtime must implement is what is in the program, not what was in the document.
+ *
+ * **Callers pass only the live blocks (`order`'s), not every retained one.** `Program`'s own
+ * doc comment calls this "every operator this program needs a runtime to implement... to
+ * execute a program," and a block `executionOrder` prunes never executes under any runtime --
+ * so its operators cannot be needed to execute the program regardless of what a consumer
+ * implements. Declaring them anyway is not safe conservatism either: the console/ROM
+ * principle's refusal exists to prevent *silence*, and a pruned block is silent (never runs)
+ * under every runtime already, so requiring its operator cannot prevent silence and can only
+ * cause a constrained second runtime (e.g. ESP32, implementing a subset) to refuse a pedal it
+ * could actually play. Measured on the corpus before this changed: 4 of 52 compiling packets
+ * (`boss-ds-1`, `analog-man-prince-of-tone` -- both zero live blocks -- plus `boss-od-3` and
+ * `boss-sd-1`, each carrying a `selector` only in a region that never reaches the output) had
+ * exactly this gap. A consumer that wants every retained block's operators regardless of
+ * liveness (a fidelity/structural tool, say) can compute it itself from `Program.blocks`,
+ * which still carries every block -- only this declared, "must implement" set narrows.
+ *
+ * Sorted so the declaration is a function of the set and not of stamp order — otherwise two
+ * identical circuits drawn in a different order would emit different bytes and different
+ * digests.
+ */
+function requiredOperators(blocks) {
+    const kinds = new Set();
+    for (const block of blocks) {
+        if (block.kind !== "mna") {
+            continue;
+        }
+        for (const stamp of block.stamps) {
+            kinds.add(stamp.kind);
+        }
+    }
+    return [...kinds].sort();
+}
+/**
+ * The DSP algorithms the executed macro blocks name — `requiredOperators`'s counterpart for
+ * the half of the instruction set that is not a stamp. See `Program.requiredModels` for why
+ * this is a second set rather than more entries in the first.
+ *
+ * Live blocks only and sorted, for the two reasons `requiredOperators` records: a pruned
+ * block cannot be an algorithm a runtime needs to gain, and an unsorted declaration would
+ * make the emitted bytes a function of block order rather than of the set.
+ *
+ * **No validation here, deliberately.** This compiler cannot know which algorithms the
+ * runtime that will execute the program implements, and inventing an allowlist here would
+ * either duplicate one runtime's list into a portable artifact or refuse a program a second,
+ * richer runtime could play. Declaring truthfully is the whole contribution; refusing is the
+ * runtime's job, by name, at load.
+ */
+function requiredModels(blocks) {
+    const models = new Set();
+    for (const block of blocks) {
+        if (block.kind !== "macro" && block.kind !== "composed") {
+            continue;
+        }
+        // A composition whose ops came from the source needs no algorithm from the runtime:
+        // it brought its own. Declaring its chip's part number here would make every
+        // reprogrammable pedal refuse at load on a name no runtime could ever register,
+        // which is the opposite of what this set is for.
+        if (block.kind === "composed" && block.modelSource === "declared") {
+            continue;
+        }
+        models.add(block.modelId);
+    }
+    return [...models].sort();
+}
+function topologicalOrder(blocks, partitioning) {
+    const ids = blocks.map((block) => block.id);
+    const remaining = new Set(ids);
+    const ordered = [];
+    while (remaining.size > 0) {
+        const ready = [...remaining].filter((id) => (partitioning.dependencies[id] ?? []).every((dependency) => !remaining.has(dependency)));
+        if (ready.length === 0) {
+            throw new LinkError(`cyclic region dependencies among ${[...remaining].join(", ")}`);
+        }
+        // Stable: preserve the order blocks were produced in.
+        ready.sort((a, b) => ids.indexOf(a) - ids.indexOf(b));
+        for (const id of ready) {
+            ordered.push(id);
+            remaining.delete(id);
+        }
+    }
+    return ordered;
+}
+//# sourceMappingURL=link.js.map

package/dist/link.js.map

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

package/dist/lower.d.ts

@@ -0,0 +1,79 @@
+import { type BistableLatch } from "./latch-seed";
+export { stampNeedsNewton } from "./stamp-partition";
+import type { Block, Device, LawedNetlist, NodeId, OperatingPointSeed, Partitioning, Region, Stamp } from "./types";
+export { opampInvertingInputNodes, opampInputDistances, opampOutputAcDistances, opampOutputDistances, potTerminals, quietDistances, } from "./pot-orientation";
+export { LoweringError } from "./errors";
+export { stampControl } from "./stamp-partition";
+export declare function lowerRegion(region: Region, lawed: LawedNetlist, inputNode: number, outputNode: number, 
+/**
+ * Computed once by `lower` rather than per region: the rule is a pairwise scan over
+ * transistors, and `boss-ds-1` lowers 82 regions from one netlist.
+ */
+latchSeeds?: readonly OperatingPointSeed[], latches?: readonly BistableLatch[], 
+/**
+ * Computed once by `lower`, for the same reason `latchSeeds` is: the graph a pot's
+ * orientation reads (`quietDistances`) does not change between `boss-ds-1`'s 82 regions
+ * either. Empty by default so a direct call site not passing one gets today's
+ * declaration-order behaviour for every pot -- never a wrong answer, only an unresolved one.
+ */
+quietDistance?: ReadonlyMap<NodeId, number>, 
+/**
+ * The narrower, scoped fallback `potTerminals` only consults when `quietDistance` leaves a
+ * pot fully unreachable -- see `opampInputDistances`. Empty by default for the same reason
+ * `quietDistance` is: an unresolved pot, never a wrong one.
+ */
+opampInputDistance?: ReadonlyMap<NodeId, number>, 
+/**
+ * Companion of `opampInputDistance` for the negative-feedback gain-stage tie in
+ * `potTerminals`: a pot that the input-distance evidence cannot break reads which end
+ * sits on an op-amp's declared output instead. Empty by default for the same reason.
+ */
+opampOutputDistance?: ReadonlyMap<NodeId, number>, 
+/**
+ * Nodes that are a declared op-amp inverting input, and the AC (DC + capacitors) distance to
+ * an op-amp's declared output: the two signals `potTerminals` reads for the one finite-tie
+ * shape the DC maps cannot break -- a non-inverting gain pot whose wiper sits on the
+ * inverting input. Empty by default for the same reason as the other maps.
+ */
+invertingInputNodes?: ReadonlySet<NodeId>, acOutputDistance?: ReadonlyMap<NodeId, number>): Block;
+/**
+ * A block's row index for a source `NodeId`, or `null` when the node is not one of this
+ * block's own.
+ *
+ * The forward direction of `Block.nodeIds`. `null` rather than a throw because the two
+ * callers that need it are asking a question whose honest answer can be "not this block":
+ * `couple.ts` locating a macro's port node, and a report matching a declared source net
+ * against whichever region owns it.
+ */
+export declare function blockNodeIndex(block: Extract<Block, {
+    readonly kind: "mna";
+}>, node: NodeId): number | null;
+/**
+ * A stamp read back in the document's node ids rather than its block's rows.
+ *
+ * The inverse of what `lowerRegion` did on the way out, for consumers that have to state a
+ * stamp's topology in the terms the source authored -- a report naming the net a device
+ * sits on, or an assertion written against a fixture's declared node numbers.
+ */
+export declare function stampInSourceNodes(block: Extract<Block, {
+    readonly kind: "mna";
+}>, stamp: Stamp): Stamp;
+export declare function lower(partitioning: Partitioning, lawed: LawedNetlist): readonly Block[];
+/**
+ * Slots a reactive element's companion model needs: the voltage across it and the current
+ * through it, which is what a trapezoidal companion carries between samples.
+ *
+ * The program declares state in slots and each stamp declares the offset its own state
+ * begins at, so both are the same unit and no executor has to know a hidden convention.
+ */
+export declare const STATE_SLOTS_PER_REACTIVE_ELEMENT = 2;
+/**
+ * Which rung decided an optocoupler's wiring, so a warning can name the devices that reached the
+ * weaker ones without restating either test.
+ *
+ * The alternative -- a predicate in the warning module that mirrors this vocabulary -- is how a
+ * silent switch mis-wiring was introduced in this compiler once already: the mirror drifted from
+ * the resolver and the warning went quiet about the case it existed for.
+ */
+export declare function optocouplerBinding(device: Device): "declared" | "named" | "declaration-order";
+//# sourceMappingURL=lower.d.ts.map

package/dist/lower.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lower.d.ts","sourceRoot":"","sources":["../src/lower.ts"],"names":[],"mappings":"AAqBA,OAAO,EAGN,KAAK,aAAa,EAClB,MAAM,cAAc,CAAC;AAUtB,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EACX,KAAK,EACL,MAAM,EACN,YAAY,EACZ,MAAM,EACN,kBAAkB,EAClB,YAAY,EACZ,MAAM,EACN,KAAK,EACL,MAAM,SAAS,CAAC;AAkBjB,OAAO,EACN,wBAAwB,EACxB,mBAAmB,EACnB,sBAAsB,EACtB,oBAAoB,EACpB,YAAY,EACZ,cAAc,GACd,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAIzC,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD,wBAAgB,WAAW,CAC1B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,YAAY,EACnB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM;AAClB;;;GAGG;AACH,UAAU,GAAE,SAAS,kBAAkB,EAAO,EAC9C,OAAO,GAAE,SAAS,aAAa,EAAO;AACtC;;;;;GAKG;AACH,aAAa,GAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAa;AACtD;;;;GAIG;AACH,kBAAkB,GAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAa;AAC3D;;;;GAIG;AACH,mBAAmB,GAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAa;AAC5D;;;;;GAKG;AACH,mBAAmB,GAAE,WAAW,CAAC,MAAM,CAAa,EACpD,gBAAgB,GAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAa,GACvD,KAAK,CAmtCP;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC7B,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAA;CAAE,CAAC,EAC/C,IAAI,EAAE,MAAM,GACV,MAAM,GAAG,IAAI,CAGf;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CACjC,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAA;CAAE,CAAC,EAC/C,KAAK,EAAE,KAAK,GACV,KAAK,CAEP;AAGD,wBAAgB,KAAK,CACpB,YAAY,EAAE,YAAY,EAC1B,KAAK,EAAE,YAAY,GACjB,SAAS,KAAK,EAAE,CAwBlB;AA2TD;;;;;;GAMG;AACH,eAAO,MAAM,gCAAgC,IAAI,CAAC;AAqYlD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CACjC,MAAM,EAAE,MAAM,GACZ,UAAU,GAAG,OAAO,GAAG,mBAAmB,CAK5C"}