@vessel-dsp/compiler 0.0.0-stage → 0.3.0

package/README.md

@@ -1,3 +1,119 @@
-# Temporary Holding Version
+# @vessel-dsp/compiler
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Headless circuit compiler turning `.vdsp` / `CircuitDocument` schematic data into compiled simulation `Program` ROMs for VesselDSP. Pure TypeScript, deterministic, rate independent, headless. It depends on `@vessel-dsp/core` and `js-yaml` only.
+
+## Install
+
+`@vessel-dsp/compiler` 0.3.0 is on npm:
+
+```bash
+bun add @vessel-dsp/compiler
+```
+
+Subpath exports: `.` (compile, registries, the supply-stamp join, and every `Program` type), `./diagnostics` (the report-only reach into stages for instruments), and `./fixtures` (the synthetic circuits the engine is graded on, with hand-computed expectations).
+
+## Minimal example
+
+Compile takes `.vdsp` source text and an optional part registry. It returns a result, never a throw, for a document it cannot use. The fixtures below ship with the package under `./fixtures`, so this runs as written:
+
+```ts
+import { compile, emptyRegistry } from "@vessel-dsp/compiler";
+import { resistorDivider } from "@vessel-dsp/compiler/fixtures";
+
+const result = compile(resistorDivider, { registry: emptyRegistry });
+
+if (result.status === "ok") {
+  console.log("Compiled program blocks:", result.program.blocks.length);
+  console.log("Warnings:", result.warnings.length);
+} else {
+  console.error("Compilation refused:", result.reasons);
+}
+```
+
+```text
+Compiled program blocks: 1
+Warnings: 0
+```
+
+## Which registry to pass
+
+`compile(source, options)` defaults to `emptyRegistry` when no registry is given. The empty registry models only device class laws (resistor, capacitor, plain op-amp stages) and refuses parts that need catalog identity. `pedalPartCatalog` is the corpus facing catalog injected by scripts and tests.
+
+Over the eight fixtures used in the guides (`resistorDivider`, `rcLowPass`, `diodeClipper`, `invertingAmplifier`, `potDivider`, `commonEmitterAmplifier`, `emitterFollower`, `triodeGainStage`), both registries compile 8 of 8. Measured over the 121 top level packets in the artifacts corpus (read only, not committed):
+
+- `emptyRegistry`: 74 of 121 compile.
+- `pedalPartCatalog`: 119 of 121 compile. The two refusals are `boss-dd-3t.vdsp` and `boss-dd-5.vdsp`, both undisclosed DSP parts.
+
+Use `pedalPartCatalog` for real pedal packets. Use `emptyRegistry` only to measure what works with no part knowledge, or for synthetic device class probes.
+
+One refusal shape, for the `unknownChip` fixture with `emptyRegistry`:
+
+```text
+[{ "stage": "device-laws", "device": "U1",
+   "reason": "integrated circuit has no model: its part number
+   \"UNKNOWN-PART-XYZ\" matched no registry entry, and a declared
+   class may not supply a macro for a part whose identity is unresolved" }]
+```
+
+## Result shape
+
+`compile` returns `CompileResult`:
+
+- `{ status: "ok", program, warnings }`. Warnings never block a program. A pedal with a dead knob is still worth hearing, but it must not be silent about it. Each warning carries a closed `code` callers can switch on, plus human readable `detail`.
+- `{ status: "unsupported", reasons }`. Each reason is a `CompileRefusal` with `stage` (`netlist`, `device-laws`, `partition`, `lower`, or `link`), `device` (component id or null), and a human readable `reason`. `device-laws` means a part could not be modelled; any other stage means the document itself does not support a program. A floating wiper that disconnects the circuit refuses at the `link` stage instead of warning.
+
+Only a `StageRefusal` becomes a result. Anything else (a compiler bug) propagates as a throw, because a bug reported as an unsupported pedal would be a wrong answer about someone's circuit.
+
+`compileToArtifact(source, options)` runs `compile` and pairs it with `emit`: `{ result, artifact }` where `artifact` is null unless the result is ok. `emit` renders the deterministic serializable form (`{ text, digest }`). There is no public `decode` in 0.2.0: program JSON is consumed by the consoles.
+
+`readNetlist(source, options?)` runs the first stage only: document text to a law free `Netlist` with `inputJack`/`outputJack` overrides and `parseQuantity` for SI values (`10k` to 10000).
+
+## The Program
+
+A `Program` is rate independent: it carries no sample rate. The runtime supplies the rate at `prepare()`. Top level keys:
+
+`formatVersion` (6 in 0.2.0), `requiredOperators`, `requiredModels`, `costPredictors`, `blocks`, `order`, `controls`, `ports`, `supplyReference`, `portReferenceVolts`, `portFullScaleVolts`, `stageCoverage`, `portImpedanceOhms`, `bypass`.
+
+Compiled `Program`s carry `formatVersion` 6. Named I/O ports and the `bufferProgram` bypass are deferred to a later `formatVersion`; from here any change to `Program`, the `Stamp` union, `ProgramJson.cpp` or `Program.h` is a package minor bump.
+
+`requiredOperators` lists every stamp operator the executed blocks present, sorted, so a runtime can refuse by name at load. `requiredModels` lists every macro DSP model id the same way. `order` is the block execution order and may omit blocks `blocks` retains. `supplyReference` is `negative-ground`, `positive-ground`, `dual-rail`, or `unpowered`, derived from `dc-source` signs. `stageCoverage` is `instrument`, `preamp`, `speaker-electrical`, or `miked`. `portFullScaleVolts` (a ceiling derived from the rails) and `portReferenceVolts` (the 0 dBFS voltage the jack declares) are different quantities; either entry may be `null`.
+
+`commonEmitterAmplifier` with `emptyRegistry` compiles to 1 block (`order: ["analog:0"]`) with stamp kinds `dc-source` 1, `capacitor` 2, `conductance` 5, `bjt` 1, `input-source` 1. The `potDivider` fixture declares one control, `Level` (`taper: linear`, default 0.5, continuous so `positions: null`, role `output-level`, label `VOLUME`).
+
+Each `mna` block carries `nodeIds` (row to source node map), `auxCount`, `stamps`, `stampPartition`, `sparseSchedule`, `stateCount`, `linear`, `controlFree`, `eliminate`, input/output nodes, and operating point seeds. A `macro` block carries a DSP `modelId` with parameters instead of stamps.
+
+## Supply stamps
+
+`resolveSupplyStamps(source, program)` joins the document power domains to the compiled `dc-source` stamps. It takes the same source text the program was compiled from and returns `{ supplies, refused }`. Only rails in an external DC domain with `derivation: direct` and `role: main-supply` are candidates; derived rails (divider, regulator, inverter, doubler, isolated) keep their compiled values.
+
+The closed refusal reasons are `no-power-section`, `mains-ac-source`, `unknown-source-kind`, `source-kind-conflict`, `derived-rail`, `rail-not-main-supply`, `no-stamp-for-rail`, `ambiguous-stamp`. Callers switch on `reason`; `detail` is prose for a human report. Mains fed amp B+ rails are refused by design: a battery profile must never be applied downstream of a rectifier.
+
+See the Compiler guide for a worked `resolveSupplyStamps` example, and the [runtime supply-control design note](https://github.com/vessel-dsp/core/blob/main/docs/design/runtime-supply-control.md) for the full design.
+
+## Public exports
+
+Values on `.`:
+
+| Name | What it is |
+| --- | --- |
+| `compile` | Compile, or explain the refusal. Never throws for a document it cannot use. |
+| `compileToArtifact` | `compile` plus `emit`, paired as `{ result, artifact }`. |
+| `emit` | Render a `Program` to its serializable `{ text, digest }` artifact. |
+| `readNetlist` | First stage only: source text to a law free netlist. |
+| `parseQuantity` | Parse a quantity to SI base units (`10k` to 10000). |
+| `emptyRegistry` | No part knowledge; measures what device class laws alone cover. |
+| `pedalPartCatalog` | The catalog corpus facing scripts inject. |
+| `foldPartId` | Fold case and separators (`MN-3007` is `mn3007`). |
+| `foldToken` | Fold case and whitespace for typed vocabulary values. |
+| `registryEntryFor` | Entry lookup for a device. |
+| `registryLawFor` | The law a registered part supplies for a device. |
+| `canonicalPartId` | Canonical part identity spelling. |
+| `zenerCatalogPartIds` | Part ids the catalog treats as zeners. |
+| `resolveSupplyStamps` | Join document power domains to compiled `dc-source` stamps. |
+| `attachDeviceLaws` | Stage 2: attach laws to every netlist device. |
+
+Types on `.` (import with `import type`): `CompileOptions`, `CompileResult`, `CompileSuccess`, `CompileFailure`, `CompileRefusal`, every `Program`/`Block`/`Stamp`/`Control`/cost type (`Program`, `Block`, `Stamp`, `OperatorKind`, `Control`, `ControlId`, `TaperKind`, `Ports`, `CostPredictors`, `NodeId`, `GROUND`, and the rest in `types.ts`), and the supply-join types (`SupplyAddress`, `ResolvedSupply`, `RefusedSupply`, `SupplyResolution`, `SupplyRefusalReason`).
+
+`./diagnostics` (report-only reach into stages for instruments, not consumer API): `blockRow`, `describeRow`, `nodeAt`, `stampNodes`, `stampInSourceNodes`, `perSample`, `SILICON_FORWARD_BETA`, `SILICON_SATURATION_CURRENT`, `THERMAL_VOLTAGE`, `findBistableLatches`, `OPEN_RULES`, `connectedToBothPorts`, `isPacketDisconnected`, `outputDependence`, `validateProxy`, `recordedReads`, `withRecordedReads`, `clearRecordedReads`, `speakerImpedance`, `speakerImpedanceMagnitude`, `speakerOnePort`, `clockTimingNodes`, `deriveBbdDelayFromNetlist`, `findClockDriverDevice`, plus the accompanying types (`PerSample`, `BistableLatch`, `NetGraph`, `FirmwareClass`, and the violation types).
+
+`./fixtures` (248 exports: synthetic circuits, hand-computed expectations, and their registries): `resistorDivider`, `rcLowPass`, `diodeClipper`, `invertingAmplifier`, `potDivider`, `commonEmitterAmplifier`, `emitterFollower`, `triodeGainStage`, `unknownChip`, `dividerGain`, `potGainAt`, `fixtureRegistry`, and the rest. These are the only circuits whose answers are known independently of the instruments, which is what makes them shippable.

package/dist/bake.d.ts

@@ -0,0 +1,38 @@
+import type { Block } from "./types";
+/** Why a block's realisation may not be baked, naming the block and the failing flag. */
+export type BakeRefusal = {
+    readonly block: string;
+    readonly reason: string;
+};
+export type BakeDecision = {
+    readonly outcome: "may-bake";
+} | {
+    readonly outcome: "refused";
+    readonly refusal: BakeRefusal;
+};
+/**
+ * May this block's realisation be derived once and reused across samples?
+ *
+ * Only when `linear && controlFree` both hold. Checked in that order because a `linear`
+ * failure is the more fundamental one -- a nonlinear block has no fixed realisation to derive
+ * at all, `linear && controlFree` or not -- so naming it first is the more useful refusal even
+ * though a real block can fail either independently (see `bake.test.ts`'s four-quadrant cases,
+ * matching `lower.test.ts`'s own `resistorDivider`/`potDivider`/`switchedDivider`/
+ * `diodeClipper` fixtures for `linear`/`controlFree`'s own precedent).
+ */
+export declare function bakeDecisionFor(block: Extract<Block, {
+    readonly kind: "mna";
+}>, 
+/**
+ * Whether every supply this block references holds still across the samples the realisation
+ * would be reused over.
+ *
+ * `true` for every block the compiler builds today — a rail is ground or a node inside this
+ * block's own matrix, and sag inside the matrix is already exact in a linear realisation.
+ * The reducer must pass `false` the day a rail is driven from outside the block, whichever
+ * shape that plumbing takes.
+ */
+supply?: {
+    readonly static: boolean;
+}): BakeDecision;
+//# sourceMappingURL=bake.d.ts.map

package/dist/bake.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bake.d.ts","sourceRoot":"","sources":["../src/bake.ts"],"names":[],"mappings":"AAmDA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAErC,yFAAyF;AACzF,MAAM,MAAM,WAAW,GAAG;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,YAAY,GACrB;IAAE,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAA;CAAE,GAChC;IAAE,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAA;CAAE,CAAC;AAElE;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC9B,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAA;CAAE,CAAC;AAC/C;;;;;;;;GAQG;AACH,MAAM,GAAE;IAAE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;CAAqB,GACrD,YAAY,CA6Bd"}

package/dist/bake.js

@@ -0,0 +1,101 @@
+// Spec clause 5: `linear && controlFree`, jointly, as the precondition for baking a
+// realisation -- and NOTHING ELSE. No new field: `Block.linear` and `Block.controlFree`
+// already exist (`src/compiler/types.ts`, computed in `lower.ts` from the exhaustive,
+// `never`-bound `stampNeedsNewton`/`stampControl` classifiers), and this file is the
+// instruction to read them as a conjunction rather than separately, at the one place a
+// reduction may ever be baked and reused across samples.
+//
+// **This gate has no caller today, and that is honest rather than incomplete.** Nothing in
+// this compiler reduces an `mna` block into a state-space realisation -- that is step 5's own
+// future work, and it does not exist yet (build-order steps 4 and 5 are unbuilt; clause 4,
+// declared output nodes, has nothing to govern until something reduces). `bakeDecisionFor`
+// is the precondition function that future stage MUST call before it bakes anything, and it
+// is written, tested and wired into the plan's documentation now rather than left implicit,
+// so the precondition cannot be forgotten the day someone builds the reducer. The insertion
+// point is between `lower`/`couple` and `link` in `compile.ts`'s pipeline -- after a block's
+// stamps are final and its `linear`/`controlFree` flags are settled, before anything is
+// scheduled to run.
+//
+// **Why the conjunction, not either flag alone.** `linear-core-state-space-gate` measured
+// H0 (a linear reduction is exact) fully holding, and H2 ("linear is sufficient on its own")
+// false: its `load-shift` mutation -- a realisation derived at one load, evaluated at
+// another -- errs 80% of the signal (`4.19e-02` against a `5.23e-02` reference), because a
+// pot sits *inside* the matrix a realisation is derived from, so a knob move is exactly the
+// kind of topology change a baked realisation cannot track without re-deriving. `linear`
+// alone would have let that 80% error ship silently -- see `bake.test.ts`'s reproduction of
+// this shape on `potDivider`, and `pipeline.test.ts` for the same shape measured end to end.
+//
+// **The supply gap, closed 2026-09-02 as a third condition rather than a fourth flag.** A block
+// can be `linear && controlFree` and still reference a rail that moves with the audio, because
+// `controlFree` is about controls and says nothing about supply state. This used to be recorded
+// here as an undecided gap waiting on the rail-port design. It is not: the gate can refuse the
+// case without knowing how a moving rail will eventually be *plumbed*, and refusing it is what
+// the reducer needs.
+//
+// **Why the caller supplies the answer instead of the block carrying a flag.** A rail that moves
+// cannot cross a block boundary today -- every supply a block references is either ground or a
+// node inside its own matrix, and a rail sagging *inside* a linear block is already exact in the
+// realisation, because the sag is part of the linear system being derived. So a `supplyStatic`
+// field on `Block` would be a constant `true` with no way to test it, and this repository's
+// evidence rule asks for a check that can fail for the reason claimed. Taking it as an argument
+// makes the future reducer state the answer at the point it bakes, keeps the Program contract
+// (and its C++ mirror) unchanged, and is testable today by passing `false`.
+//
+// **What is still open is the port design, and it is deliberately not decided here.** Whether a
+// dynamic rail becomes a fourth port kind or folds into `coupled` is an architecture question
+// whose evidence does not exist yet -- `thoughts/shared/experiments/power-domain-rail-sag-contract/`
+// was written to produce exactly that evidence (sign convention, multi-rail summing, the DK
+// rail-in/current-out contract) and has never been run. This gate is correct under either answer:
+// whichever one lands sets `supply.static` to `false` for a block whose rail is driven from
+// outside it.
+/**
+ * May this block's realisation be derived once and reused across samples?
+ *
+ * Only when `linear && controlFree` both hold. Checked in that order because a `linear`
+ * failure is the more fundamental one -- a nonlinear block has no fixed realisation to derive
+ * at all, `linear && controlFree` or not -- so naming it first is the more useful refusal even
+ * though a real block can fail either independently (see `bake.test.ts`'s four-quadrant cases,
+ * matching `lower.test.ts`'s own `resistorDivider`/`potDivider`/`switchedDivider`/
+ * `diodeClipper` fixtures for `linear`/`controlFree`'s own precedent).
+ */
+export function bakeDecisionFor(block, 
+/**
+ * Whether every supply this block references holds still across the samples the realisation
+ * would be reused over.
+ *
+ * `true` for every block the compiler builds today — a rail is ground or a node inside this
+ * block's own matrix, and sag inside the matrix is already exact in a linear realisation.
+ * The reducer must pass `false` the day a rail is driven from outside the block, whichever
+ * shape that plumbing takes.
+ */
+supply = { static: true }) {
+    if (!block.linear) {
+        return {
+            outcome: "refused",
+            refusal: {
+                block: block.id,
+                reason: `block "${block.id}" is not linear, so it has no fixed realisation to derive at all -- it must keep iterating Newton every sample`,
+            },
+        };
+    }
+    if (!block.controlFree) {
+        return {
+            outcome: "refused",
+            refusal: {
+                block: block.id,
+                reason: `block "${block.id}" is linear but not control-free, so a realisation baked at one control position would be wrong at another -- linear-core-state-space-gate measured this at 80% of the signal (load-shift). Refuse to bake and keep solving the per-sample stamps until re-derivation on control change or knob-grid tabulation exists`,
+            },
+        };
+    }
+    if (!supply.static) {
+        return {
+            outcome: "refused",
+            refusal: {
+                block: block.id,
+                reason: `block "${block.id}" is linear and control-free but references a supply that moves with the audio, and a realisation derived at one rail voltage is wrong at another for the same reason a pot position is -- the rail sits inside the matrix the realisation is derived from. Refuse to bake until the rail is an input the realisation can be re-derived against`,
+            },
+        };
+    }
+    return { outcome: "may-bake" };
+}
+//# sourceMappingURL=bake.js.map

package/dist/bake.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bake.js","sourceRoot":"","sources":["../src/bake.ts"],"names":[],"mappings":"AAAA,oFAAoF;AACpF,wFAAwF;AACxF,sFAAsF;AACtF,qFAAqF;AACrF,uFAAuF;AACvF,yDAAyD;AACzD,EAAE;AACF,2FAA2F;AAC3F,8FAA8F;AAC9F,2FAA2F;AAC3F,2FAA2F;AAC3F,4FAA4F;AAC5F,4FAA4F;AAC5F,4FAA4F;AAC5F,6FAA6F;AAC7F,wFAAwF;AACxF,oBAAoB;AACpB,EAAE;AACF,0FAA0F;AAC1F,6FAA6F;AAC7F,sFAAsF;AACtF,2FAA2F;AAC3F,4FAA4F;AAC5F,yFAAyF;AACzF,4FAA4F;AAC5F,6FAA6F;AAC7F,EAAE;AACF,gGAAgG;AAChG,+FAA+F;AAC/F,gGAAgG;AAChG,+FAA+F;AAC/F,+FAA+F;AAC/F,qBAAqB;AACrB,EAAE;AACF,iGAAiG;AACjG,+FAA+F;AAC/F,iGAAiG;AACjG,+FAA+F;AAC/F,4FAA4F;AAC5F,gGAAgG;AAChG,8FAA8F;AAC9F,4EAA4E;AAC5E,EAAE;AACF,gGAAgG;AAChG,8FAA8F;AAC9F,qGAAqG;AACrG,4FAA4F;AAC5F,kGAAkG;AAClG,4FAA4F;AAC5F,cAAc;AAcd;;;;;;;;;GASG;AACH,MAAM,UAAU,eAAe,CAC9B,KAA+C;AAC/C;;;;;;;;GAQG;AACH,SAAuC,EAAE,MAAM,EAAE,IAAI,EAAE;IAEvD,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;QACnB,OAAO;YACN,OAAO,EAAE,SAAS;YAClB,OAAO,EAAE;gBACR,KAAK,EAAE,KAAK,CAAC,EAAE;gBACf,MAAM,EAAE,UAAU,KAAK,CAAC,EAAE,gHAAgH;aAC1I;SACD,CAAC;IACH,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC;QACxB,OAAO;YACN,OAAO,EAAE,SAAS;YAClB,OAAO,EAAE;gBACR,KAAK,EAAE,KAAK,CAAC,EAAE;gBACf,MAAM,EAAE,UAAU,KAAK,CAAC,EAAE,wTAAwT;aAClV;SACD,CAAC;IACH,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;QACpB,OAAO;YACN,OAAO,EAAE,SAAS;YAClB,OAAO,EAAE;gBACR,KAAK,EAAE,KAAK,CAAC,EAAE;gBACf,MAAM,EAAE,UAAU,KAAK,CAAC,EAAE,iVAAiV;aAC3W;SACD,CAAC;IACH,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC;AAChC,CAAC"}

package/dist/bbd-clock.d.ts

@@ -0,0 +1,171 @@
+import type { ControlId, Device, DeviceKind, Netlist, NodeId, TaperKind } from "./types";
+import type { PartRegistry } from "./registry";
+export type ClockDriverFamily = "CD4047" | "MN3101" | "MN3102" | "unknown";
+export type BbdClockDerivationOutcome = {
+    readonly outcome: "derived";
+    readonly delaySeconds: number;
+    readonly rOhms: number;
+    readonly cFarads: number;
+    readonly fClockHz: number;
+    readonly family: ClockDriverFamily;
+    readonly stages: number;
+    readonly formulaConstant: number;
+    readonly offsetSeconds: number;
+    readonly controlId: ControlId | null;
+    readonly taper: TaperKind;
+    readonly ohmsAtControlMin: number;
+    readonly ohmsAtControlMax: number;
+} | {
+    readonly outcome: "no-clock-driver";
+} | {
+    readonly outcome: "refused";
+    readonly reason: string;
+};
+/**
+ * Device kinds that can *drive* a timing node rather than merely set it.
+ *
+ * A resistor, a capacitor and a potentiometer are the timing network — a pot is a knob, which is
+ * control-rate and already carried as `controlId`. Anything on this list sitting on the timing
+ * network is steering it at signal rate, which is how an LFO reaches a BBD clock.
+ *
+ * `diode` is deliberately absent: `mxr-carbon-copy` clamps its CD4047 timing node with `D5` to
+ * ground, and a clamp is not a modulator. `ic` is absent because the clock driver is itself an
+ * `ic` on its own timing pins.
+ */
+export declare const ACTIVE_TIMING_KINDS: ReadonlySet<DeviceKind>;
+/**
+ * Devices actively steering this clock driver's timing network, by id.
+ *
+ * The discrimination this exists for, measured 2026-08-29 across the corpus: `mxr-carbon-copy`
+ * and `boss-dm-2` carry only resistors, capacitors and pots on their timing nodes, so their
+ * derived delays are a property of the circuit. `boss-ce-5` carries **`Q8`'s emitter directly
+ * on oscillator node 42**, so the frequency is set by that transistor's current and the R·C
+ * arithmetic reads a resistor that is not what times the oscillator.
+ */
+export declare function activeTimingDrivers(clockDevice: Device, netlist: Netlist, registry: PartRegistry): readonly string[];
+export type ClockModulationSource = {
+    readonly outcome: "resolved";
+    readonly steeredBy: string;
+    readonly node: NodeId;
+} | {
+    readonly outcome: "none";
+} | {
+    readonly outcome: "refused";
+    readonly reason: string;
+};
+/**
+ * The node an LFO reaches a modulated BBD clock on: the steering device's **control** terminal.
+ *
+ * **Not the timing node.** That is the point of this function. The timing node carries the
+ * oscillator's own waveform at the clock rate — for a chorus, ~100 kHz, far above anything a
+ * 48 kHz host can sample — so reading it as a modulation source would alias garbage into the
+ * delay length. The control terminal carries the LFO and nothing else: on `boss-ce-2` that is
+ * `Q5`'s base, which the DEPTH pot reaches through `Q4` and `D1`.
+ *
+ * Deliberately strict. Exactly one steering device with one resolvable control terminal, and
+ * that terminal may not sit on ground or on the timing network itself. Anything else refuses by
+ * name and leaves the delay static, because a guess here is a sweep of the wrong thing.
+ */
+export declare function resolveClockModulationSource(bbdDevice: Device, netlist: Netlist, registry: PartRegistry): ClockModulationSource;
+/**
+ * The nodes a clock driver's own timing network hangs on, by family.
+ *
+ * Exported because `scripts/report-bbd-architecture.ts` asks the same question and answered it
+ * with a private copy of the role vocabulary, which **under-reported immediately**: an MN3102
+ * spelling its pins `oscillatorinput`/`oscillatoroutput`/`clockcontrol` (`boss-bf-2`) matched
+ * none of the canonical `ox1`/`ox2`/`ox3` tokens, so a driver the compiler finds read as absent
+ * in the report. One enumerator, shared, is the same conclusion `stampNodes` reached.
+ *
+ * Role tokens are compared as whole values after folding, never by substring, and the MN310x
+ * branch admits the registry's own alias spellings through `oscillatorRoleTokens`.
+ */
+export declare function clockTimingNodes(device: Device, registry: PartRegistry): ReadonlySet<NodeId>;
+export declare function identifyClockFamily(device: Device): ClockDriverFamily;
+export declare function findClockDriverDevice(netlist: Netlist): Device | null;
+export declare function deriveBbdDelayFromNetlist(bbdDevice: Device, netlist: Netlist, stages: number, registry: PartRegistry): BbdClockDerivationOutcome;
+/**
+ * Open-OX2 clock law (CE-2 first slice, 2026-09-28).
+ *
+ * The form the MN3101 datasheet never drew: OX2 left open (N.C.) and a single
+ * relaxation loop across the OX1→OX3 inverter pair — a timing capacitor
+ * between OX3 and OX1 charged through a pull-up on OX1 and discharged by a
+ * transistor the OX3 side drives, with the LFO setting the restart level
+ * through a diode. `boss-ce-2` v1.25 is the corpus case.
+ *
+ * Family constants (per-packet R and C come from the netlist):
+ * - `OPEN_OX2_VDD_VOLTS`: the driver's supply span, 9 V nominal from the
+ *   packet's own supply port (the filtered rail measures 8.967 V, 0.4%,
+ *   disclosed and immaterial beside the threshold sensitivity).
+ * - `OPEN_OX2_VTH_VOLTS`: solved 2026-09-28 for 110 kHz at the measured
+ *   Depth-0 divider level 1.565 V against a scope specimen (DIYstompboxes
+ *   2011, one rough forum reading, disclosed), inside the 3.4–5.6 V window
+ *   the MN3101 p.60 example table allows. Re-solve, never tune: procedure in
+ *   `docs/todo-archive/2026-09-28-ce2-clock-law-analysis.md`.
+ * - `OPEN_OX2_VF_VOLTS`: generic-diode forward drop, disclosed typical.
+ * - `OPEN_OX2_FLOOR_VOLTS`: yank-minus-kick bottom under datasheet OX3 drive
+ *   (R_OH ≈ 667 Ω / R_OL ≈ 500 Ω from the I_OH2/I_OL2 minimums): a ~7 V OX3
+ *   step kicks ~6.2 V through 47 pF against cited diode maxima, landing near
+ *   −5.3 V — below the D1 floor at every measured divider level, so the D1
+ *   branch binds everywhere. Same max() form as the analysis, not a deletion.
+ */
+export declare const OPEN_OX2_VDD_VOLTS = 9;
+export declare const OPEN_OX2_VTH_VOLTS = 4.757;
+export declare const OPEN_OX2_VF_VOLTS = 0.65;
+export declare const OPEN_OX2_FLOOR_VOLTS = -5.35;
+export type OpenOx2ClockLawOutcome = {
+    readonly outcome: "recognized";
+    readonly slowNode: NodeId;
+    readonly steeredBy: string;
+    readonly rOhms: number;
+    readonly cFarads: number;
+} | {
+    readonly outcome: "absent";
+    readonly reason: string;
+};
+/**
+ * Recognise the open-OX2 relaxation form by connectivity, never by names or
+ * prose: an MN3101-family driver with OX2 touched by nothing but its own pin,
+ * one capacitor bridging OX3 to OX1, one pull-up resistor from OX1 to the
+ * driver's own supply pin, one resistor from OX3 into a grounded-emitter
+ * transistor's base, that transistor's collector on a pulled-up discharge
+ * node back into OX1 through a diode, and one diode from OX1 into a
+ * divider-fed slow node.
+ *
+ * Anything else is `absent` with the failed check named, and the caller falls
+ * back to the existing star/gate derivation untouched. In particular the
+ * pre-rewire collapse (capacitor on OX1–OX2), a transistor sitting directly
+ * on a timing node (the modulated refusal owns that), and the MN3102 two-leg
+ * form (a different oscillator; no corpus case) all read absent here.
+ */
+export declare function deriveOpenOx2ClockLaw(netlist: Netlist, registry: PartRegistry): OpenOx2ClockLawOutcome;
+/**
+ * Princeton Technology PT2399 delay time from external VCO resistance R (in Ohms).
+ *
+ * Princeton PT2399 datasheet, TABLE 1: RESISTOR/DELAY TIME VALUES (V1.4, Oct 2005;
+ * the same 28-row table is reprinted in V1.1, V1.2 and V1.6; the packet-local V1.9,
+ * Mar 2022, drops the table but still says "Please refer to Table 1 for the
+ * Resistor/Delay Time values"). Note 1 under the table states R in Ohms, so the
+ * last row's "0.5" is 0.5 Ohms (pin 6 effectively grounded, 31.3 ms), not 0.5 kOhms.
+ *
+ * The table is linear in R: with pin 6 held at 2.5 V, the page
+ * https://electrosmash.mas-effects.com/pt2399-analysis gives
+ * I_pin6 (mA) = 28.65 / (Delay_ms - 29.70), i.e. Delay_ms = 29.70 + 11.46 * R_kOhms,
+ * which reproduces all 28 cited rows within 4 ms (worst row: 27.6 kOhms, 346.0 ms
+ * predicted vs 342 ms cited). That linear form is what this returns.
+ *
+ * Deliberately no clamp and no hard maximum: the cited source states none. Quality
+ * degrades past about 350 ms (the table's own THD reaches 1.0% at 342 ms), but the
+ * delay keeps growing with R, so this extrapolates the line rather than clipping it.
+ */
+export declare function pt2399DelayFromOhms(rOhms: number): number;
+/**
+ * Derives delaySeconds and dynamic control mapping for PT2399 digital delay chips
+ * by tracing the series resistor/potentiometer network connected to VCO Pin 6.
+ */
+export declare function derivePt2399DelayFromNetlist(device: Device, netlist: Netlist): BbdClockDerivationOutcome;
+/**
+ * Derives delaySeconds and dynamic control mapping for Mitsubishi M50195P digital echo LSI
+ * by tracing the inverter oscillator timing network connected to CLK1.
+ */
+export declare function deriveM50195DelayFromNetlist(device: Device, netlist: Netlist): BbdClockDerivationOutcome;
+//# sourceMappingURL=bbd-clock.d.ts.map

package/dist/bbd-clock.d.ts.map

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