@vessel-dsp/compiler 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,315 @@
-# 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.1.0 is not yet on npm. Until the release is published, use the package from this repository's workspace rather than an install command that will 404.
+
+```bash
+# once published:
+bun add @vessel-dsp/compiler
+```
+
+## 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.
+
+```ts
+import { readFileSync } from "node:fs";
+import { compile, pedalPartCatalog } from "@vessel-dsp/compiler";
+
+const source = readFileSync("big-muff-pi.vdsp", "utf8");
+const result = compile(source, { registry: pedalPartCatalog });
+
+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.
+
+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`.
+
+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 `boss-dd-3t.vdsp` with `pedalPartCatalog`:
+
+```text
+[{ "stage": "device-laws", "device": "U1",
+   "reason": "integrated circuit has no model: its part number
+   \"undisclosed-roland-boss-dsp\" 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.
+- `{ 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.
+
+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. `decode(text)` parses an artifact back into a `Program`.
+
+`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` (always 1), `requiredOperators`, `requiredModels`, `costPredictors`, `blocks`, `order`, `controls`, `ports`, `supplyReference`, `portReferenceVolts`, `portFullScaleVolts`, `stageCoverage`, `portImpedanceOhms`.
+
+`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. `supplyReference` is `negative-ground`, `positive-ground`, `dual-rail`, or `unpowered`, derived from `dc-source` signs. `stageCoverage` is `instrument`, `preamp`, `speaker-electrical`, or `miked`.
+
+`big-muff-pi.vdsp` with `pedalPartCatalog` compiles to 1 block (`order: ["analog:0"]`) with stamp kinds `dc-source` 1, `bjt` 4, `conductance` 22, `capacitor` 13, `controlled-conductance` 6, `diode` 4, `input-source` 1. Controls are `IN`, `OUT`, `SUSTAIN`, `TONE`, `VOLUME`, each 0..1 with default 0.5.
+
+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.
+
+Measured over the same 121 packets with `pedalPartCatalog`: 54 packets resolve at least one supply. Refusals by entry: `derived-rail` 60, `no-power-section` 42, `no-stamp-for-rail` 17, `mains-ac-source` 7, `unknown-source-kind` 4, plus 2 packets that do not compile at all. `big-muff-pi` resolves `VPLUS_RAIL` with role `main-supply`.
+
+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.
+
+## Public exports
+
+### Compile
+
+| 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 }`. |
+| `CompileOptions` | `{ registry, inputJack, outputJack }`. |
+| `CompileResult` | `CompileSuccess` or `CompileFailure`. |
+| `CompileSuccess` | `{ status: "ok", program, warnings }`. |
+| `CompileFailure` | `{ status: "unsupported", reasons }`. |
+| `CompileRefusal` | `{ stage, device, reason }`. |
+| `CompilerStage` | `netlist`, `partition`, `lower`, or `link`. |
+| `StageRefusal` | Stage error that becomes a result instead of a throw. |
+| `LoweringError` | A device declared with a terminal count lowering cannot stamp. |
+| `NetlistError` | Netlist stage refusal. |
+| `PartitionError` | Partition stage refusal. |
+| `LinkError` | Link stage refusal. |
+
+### Artifacts
+
+| Name | What it is |
+| --- | --- |
+| `emit` | Render a `Program` to its serializable `Artifact`. |
+| `decode` | Parse an artifact back into a `Program`. |
+| `Artifact` | The serializable form of a compiled program. |
+
+### Netlist
+
+| Name | What it is |
+| --- | --- |
+| `readNetlist` | First stage only: source text to a law free `Netlist`. |
+| `ReadNetlistOptions` | `{ inputJack, outputJack }` overrides. |
+| `Netlist` | Devices, controls, ports, and port metadata before laws attach. |
+| `Device` | One lowered device with kind, identity, terminals, and parameters. |
+| `DeviceId` | Component id string. |
+| `DeviceKind` | What a device is electrically (resistor through power-amp, plus sources, rails, gates, BBD, compandor). |
+| `DeviceIdentity` | Evidence a part is recognised by, in stage 2 order. |
+| `DeviceLaw` | A lumped constitutive relation the solver can stamp. |
+| `DeviceResolution` | Per device law outcome, including unsupported with reason. |
+| `LawedNetlist` | Netlist plus per device resolutions. |
+| `parseQuantity` | Parse a quantity to SI base units (`10k` to 10000). |
+| `dcConductingKinds` | DC conducting device kinds, for asking whether a node potential is generated. |
+| `deviceCountByNode` | How many devices touch each node. |
+| `DeclaredWinding` | One declared coil: role, name, terminals in coil order. |
+| `DeclaredWindingImpedance` | One rated coil impedance in ohms. |
+
+### Registries
+
+| Name | What it is |
+| --- | --- |
+| `emptyRegistry` | No part knowledge; measures what device class laws alone cover. |
+| `pedalPartCatalog` | The catalog corpus facing scripts inject. |
+| `PartRegistry` | `{ entries }` consulted by stage 2. |
+| `PartEntry` | One catalog entry binding identity to a model. |
+| `PartModel` | Law, sections, or macro model a part supplies. |
+| `PartSection` | One section of a multi section part with its terminals. |
+| `PartPinout` | Terminal order a sections model indices assume. |
+| `PartIdentity` | A resolved part identity. |
+| `MacroPartModel` | Macro model a registered part supplies. |
+| `MacroPortRoles` | Where a macro ports sit, named by terminal role. |
+| `MacroBarePinPositions` | Physical terminal positions for pin numbered documents. |
+| `registryEntryFor` | Entry lookup for a device. |
+| `registryModelFor` | Model lookup for a device. |
+| `registryLawFor` | The law a registered part supplies for a device. |
+| `terminalWithRole` | Index of the terminal whose role matches, or null. |
+| `pinoutMatches` | Whether a device declares the order an entry was written against. |
+| `foldPartId` | Fold case and separators (`MN-3007` is `mn3007`). |
+| `foldToken` | Fold case and whitespace for typed vocabulary values. |
+| `recordedReads` | What each owner consulted. |
+| `withRecordedReads` | Run a function with registry reads recorded. |
+| `clearRecordedReads` | Forget everything recorded so far. |
+
+### Supply stamps
+
+| Name | What it is |
+| --- | --- |
+| `resolveSupplyStamps` | Join document power domains to compiled `dc-source` stamps. |
+| `SupplyAddress` | `{ blockIndex, sourceIndex }` naming one `dc-source` stamp. |
+| `ResolvedSupply` | Address plus rail id, role, and nominal volts. |
+| `RefusedSupply` | Unmapped rail with reason and human readable detail. |
+| `SupplyResolution` | `{ supplies, refused }`. |
+| `SupplyRefusalReason` | Closed union of eight refusal reasons. |
+
+### Partition, lower, link, couple
+
+| Name | What it is |
+| --- | --- |
+| `partition` | Split the lawed netlist into regions. |
+| `Partitioning` | Regions plus dependencies. |
+| `Region` | One coupled subgraph with its kind. |
+| `RegionKind` | `linear`, `nonlinear`, or `macro`. |
+| `lower` | Turn regions into MNA stamp blocks. |
+| `lowerRegion` | Lower one region. |
+| `link` | Order blocks and attach program metadata. |
+| `couple` | Wire coupled and parameter ports after every region exists. |
+| `Coupled` | Coupled seam record. |
+| `blockNodeIndex` | A block row index for a source node id, or null. |
+
+### Stamps, blocks, program
+
+| Name | What it is |
+| --- | --- |
+| `Program` | The compiled ROM: operators, models, blocks, order, controls, ports, supply reference, scales, coverage. |
+| `Block` | One `mna` solve block or one `macro` DSP block. |
+| `Stamp` | One MNA contribution (conductance through switch families). |
+| `OperatorKind` | A stamp kind a runtime must implement. |
+| `StampPartition` | Compile time linear, control, constant, and dynamic partition. |
+| `SparseSchedule` | Compile time static sparse elimination schedule. |
+| `stampControl` | Control a stamp reads, or null. |
+| `stampNeedsNewton` | Whether a stamp needs the Newton loop. |
+| `stampNodes` | Every node a stamp names. |
+| `stampInSourceNodes` | A stamp read back in document node ids. |
+| `withStamp` | Add a stamp with linear and controlFree re-derived. |
+| `Ports` | Input and output node ids. |
+| `CostPredictors` | Rate independent cost facts for admission. |
+| `OperatingPointSeed` | A nodeset style hint for the DC solve start. |
+| `NodeId` | Electrical node number. |
+| `GROUND` | Node 0. |
+| `ModulationPort` | Solved node read every sample to scale a delay macro. |
+| `ParameterPort` | Scalar another operator derives. |
+| `MacroModel` | A region the compiler does not solve. |
+| `MacroClockControl` | Clock control mapping for a macro block. |
+| `SUPPLY_SOURCE_OHMS` | Default series impedance of a pedal supply in ohms (1). |
+| `STATE_SLOTS_PER_REACTIVE_ELEMENT` | State slots a reactive element companion model needs. |
+| `THERMAL_VOLTAGE` | Room temperature thermal voltage for the diode law. |
+| `SILICON_SATURATION_CURRENT` | Default silicon saturation current. |
+| `SILICON_FORWARD_BETA` | Default silicon forward beta (100). |
+| `SWITCH_ON_OHMS` | Closed switch resistance. |
+| `SWITCH_OFF_OHMS` | Open switch resistance. |
+
+### Controls and tapers
+
+| Name | What it is |
+| --- | --- |
+| `Control` | Compiled control with id, taper, default position, role, label. |
+| `ControlId` | Control id string. |
+| `TaperKind` | `linear`, `logarithmic`, `reverse-logarithmic`, or `reverse-linear`. |
+
+### Clocks, timing, delay lines
+
+| Name | What it is |
+| --- | --- |
+| `deriveBbdDelayFromNetlist` | Derive BBD delay from the clock network. |
+| `derivePt2399DelayFromNetlist` | Derive PT2399 delay from the VCO resistor network. |
+| `deriveM50195DelayFromNetlist` | Derive M50195P delay from the oscillator network. |
+| `pt2399DelayFromOhms` | PT2399 delay formula from VCO resistance. |
+| `identifyClockFamily` | Clock driver family for a device. |
+| `ClockDriverFamily` | BBD clock family. |
+| `clockTimingNodes` | Nodes a clock driver timing network hangs on. |
+| `activeTimingDrivers` | Devices actively steering a timing network. |
+| `ACTIVE_TIMING_KINDS` | Device kinds that can drive a timing node. |
+| `findClockDriverDevice` | Locate the clock driver device. |
+| `resolveClockModulationSource` | Node an LFO reaches a modulated BBD clock on. |
+| `ClockModulationSource` | That modulation source. |
+| `BbdClockDerivationOutcome` | BBD clock derivation result. |
+
+### Device helpers
+
+| Name | What it is |
+| --- | --- |
+| `attachDeviceLaws` | Stage 2: attach laws to every netlist device. |
+| `declaredRegulatorTerminals` | Output and reference terminals of a regulator model. |
+| `isElectricallyIsolated` | Whether every device node is private to itself. |
+| `opampInputDistances` | Op-amp input network distances. |
+| `quietDistances` | Quiet network distances. |
+| `optocouplerBinding` | Which rung decided an optocoupler wiring. |
+| `otaPackageOrderAssumed` | Whether an OTA used DIP-8 package order. |
+| `potTerminals` | Potentiometer terminal roles. |
+| `synthesizeOpampImplicitBias` | Add implicit DC bias where topology leaves it undefined. |
+| `stageCoverage` | Amplification stage coverage read from lowered stamps. |
+
+### Diagnostics (warnings and their finders)
+
+| Name | What it is |
+| --- | --- |
+| `CompileWarning` | Union of every warning shape. |
+| `findInertControls` | A pot whose wiper touches nothing is a fixed resistor. |
+| `InertControlWarning` | Why a control cannot move the circuit. |
+| `ControlPositionDisagreesWarning` | Panel and component disagree about a control setting. |
+| `findUnboundedOpamps` | Op-amps with no DC feedback path. |
+| `UnboundedOpampWarning` | Op-amp on the signal path with no DC feedback. |
+| `findSupplyShorts` | Diodes forward across a supply. |
+| `SupplyShortWarning` | A diode wired forward across a supply. |
+| `findOverDrivenNodes` | Nodes driven by more than one ideal source. |
+| `OverDrivenNodeWarning` | Over-determined node. |
+| `findDanglingActiveTerminals` | Active terminals on untouched nodes. |
+| `DanglingActiveTerminalWarning` | Active device terminal that cannot conduct. |
+| `findGroundedClockSupplies` | Clock drivers with supply at ground. |
+| `ClockDriverSupplyAtGroundWarning` | Clock driver rendering no clock at all. |
+| `findUnimplementedDeviceLaws` | Devices with no law, told by name. |
+| `UnimplementedDeviceLawWarning` | Device class with no law. |
+| `UnimplementedControlRoleWarning` | Control role with no law: accepted, lowered, ignored. |
+| `findUnreachableOutput` | Outputs reachable by nothing. |
+| `OutputPortUnreachableWarning` | Program executing no blocks. |
+| `OutputPortNotTransformerCoupledWarning` | Output measured before the power stage. |
+| `NoOutputTransformerWarning` | Amp shaped document with no output transformer. |
+| `findUnexecutedRegions` | Regions the program never executes. |
+| `UnexecutedActiveRegionWarning` | Active region never executed. |
+| `findIcsNotExecuted` | Declared ICs the program does not execute. |
+| `IcNotExecutedWarning` | Declared but unexecuted IC. |
+| `findElectricallyIsolatedIcs` | Identification devices with all private nodes. |
+| `ElectricallyIsolatedIcWarning` | Isolated device given an open law. |
+| `OpenIcReason` | Why a device got an open law. |
+| `findPowerDomainControls` | Power hardware exposed as sweepable controls. |
+| `PowerDomainControlWarning` | Power domain hardware outside the audio graph. |
+| `findNonExecutableClockDrivers` | Clock drivers bypassed by the MNA solver. (finder; warning type `NonExecutableClockDriverWarning`) |
+| `NonExecutableClockDriverWarning` | Clock behavior not modelled. |
+| `NonExecutableSupportShellWarning` | Support shell preserved but not executed. |
+| `findGenericTubeFits` | Tubes lowered with device class fits. (finder; types below) |
+| `GenericTubeFitWarning` | Tube lowered without a catalog match. |
+| `GenericSpeakerProfileWarning` | Speaker load with a generic driver profile. |
+| `findUnverifiedPinoutBindings` | Parts wired by declaration order. (finder; type below) |
+| `UnverifiedPinoutBindingWarning` | Terminals placed by order, not assertion. |
+| `UnreadableTerminalRoleWarning` | Terminals wired by order after an unplaceable spelling. |
+| `UnroutableThrowWarning` | Switch throw alone on its node. |
+| `InterfaceOrSourceOnlyWarning` | Interface or source only component. |
+| `UnconnectedBehaviorComponentWarning` | Behavior component with no connection to the audio graph. |
+| `NotPopulatedWarning` | DNP position with nothing fitted. |
+| `NotPopulatedWithoutValueWarning` | DNP component with no value. |
+| `LedgerDivergenceWarning` | Nodes ledger and terminal refs disagree. |
+| `DeclaredDelayWarning` | Delay typed into the source, not derived. |
+| `ModulationNotModelledWarning` | Wired modulation input admission refused. |
+| `TaperNotExecutableWarning` | Taper that renders linear. |

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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"}