@vessel-dsp/compiler 0.4.0 → 0.6.0

package/dist/netlist.js

@@ -18,7 +18,8 @@
 import { componentDevices, deviceTerminalRoles, parseInterchangeYamlWithTopology, } from "@vessel-dsp/core";
 import { load as loadYaml } from "js-yaml";
 import { StageRefusal } from "./errors.js";
-import { foldToken } from "./registry.js";
+import { emptyRegistry, foldToken, registryEntryFor } from "./registry.js";
+import { classParamNames, requiredClassParams, } from "./registry-data/index.js";
 import { findBistableLatches } from "./latch-seed.js";
 import { speakerOnePort } from "./speaker-load.js";
 import { GROUND, } from "./types.js";
@@ -632,6 +633,7 @@ export function readNetlist(source, options) {
         ? declaredNodesFromConnectivity(document, parsed.connectivity)
         : new Map();
     const nodeOf = resolveNodes(document, declaredNodes);
+    const registry = options?.registry ?? emptyRegistry;
     const warnings = [];
     /**
      * **A switch throw or winding tap alone on its node cannot route anything.**
@@ -931,7 +933,11 @@ export function readNetlist(source, options) {
                     packageDeviceId: declared.id,
                     kind: deviceKind,
                     nodes: owned.map((entry) => entry.node),
-                    parameters: parametersFor(component, deviceKind),
+                    ...applyDeviceOverride(component, deviceKind, parametersFor(component, deviceKind), {
+                        warnings,
+                        registry,
+                        deviceId: `${component.id}.${declared.id}`,
+                    }),
                     // The control belongs to the package, so only the first device carries it.
                     // A ganged part states the same control on both and the owner map already
                     // keeps the first.
@@ -946,7 +952,11 @@ export function readNetlist(source, options) {
             id: String(component.id),
             kind,
             nodes,
-            parameters: parametersFor(component, kind),
+            ...applyDeviceOverride(component, kind, parametersFor(component, kind), {
+                warnings,
+                registry,
+                deviceId: String(component.id),
+            }),
             control,
             identity: identityOf(effectiveTerminals, effectiveTerminals.map((terminal) => declaredRole(terminal))),
             isLed: componentKind === "led" ? true : undefined,
@@ -1098,7 +1108,7 @@ export function readNetlist(source, options) {
                 device: owner.id,
                 declared: componentTaper.unreadable,
                 detail: `Control ${id}: ${owner.id} declares taper "${componentTaper.unreadable}", which ` +
-                    "this stage cannot turn into one of its four laws, so the control renders " +
+                    "this stage cannot turn into one of its laws, so the control renders " +
                     "linear. An audio pot rendered linear is audible across the whole sweep.",
             });
         }
@@ -1998,6 +2008,152 @@ kind) {
         ? value
         : null;
 }
+/** Hertz per frequency unit, compared whole. `mHz` and any other spelling are refused, not guessed. */
+const frequencyUnitScale = {
+    "": 1,
+    Hz: 1,
+    hz: 1,
+    HZ: 1,
+    kHz: 1e3,
+    KHz: 1e3,
+    khz: 1e3,
+    MHz: 1e6,
+    GHz: 1e9,
+};
+/**
+ * A declared frequency, in hertz, or `null` when the component states none.
+ *
+ * **The whole value is read, and a value that is not a frequency is refused rather than skipped.**
+ * Three forms are legal and each is checked end to end:
+ *
+ * - a number, taken as hertz;
+ * - a string that is exactly a number and an optional frequency unit -- `"3 MHz"`, `"1.2 MHz"`,
+ *   `"3000000"`, `"3e6 Hz"` -- where a missing unit means hertz and the unit is compared as a closed
+ *   set (`Hz`, `kHz`, `MHz`, `GHz`), never by stripping after a delimiter;
+ * - a structured `{value, unit}`, whose `value` wins over `raw` because it already carries the
+ *   conversion (the same reason `Aol` reads `value`), with the unit from the same closed set.
+ *
+ * `parseQuantity` is not used here on purpose. It reads a number then ignores whatever follows, so
+ * `"1.2 V/us"` -- a slew rate -- would come back as 1.2: the right number for the wrong reason, which
+ * is the trap the `SR` note above describes. A frequency property that holds `"3 MHz typ"`, `"3M"` or
+ * a slew rate is a packet error, so this throws and names the component instead of dropping it.
+ *
+ * A non-positive or non-finite frequency is refused for the same reason: it states something, and
+ * what it states is not a frequency.
+ */
+export function typedFrequencyHz(component, key) {
+    const property = component.properties[key];
+    if (property === undefined || property === null) {
+        return null;
+    }
+    const refuse = (why) => {
+        throw new NetlistError(`${component.id}: ${key} ${JSON.stringify(property)} ${why}; a declared frequency must be a number, a number with Hz/kHz/MHz/GHz, or a {value, unit}`);
+    };
+    let hertz;
+    if (typeof property === "number") {
+        hertz = property;
+    }
+    else if (typeof property === "string") {
+        const text = property
+            .trim()
+            .replace(/^['"]+|['"]+$/gu, "")
+            .trim();
+        if (text === "") {
+            return null;
+        }
+        const match = /^([+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?)\s*([A-Za-z]*)$/u.exec(text);
+        const scale = match === null ? undefined : frequencyUnitScale[match[2]];
+        if (match === null || scale === undefined) {
+            return refuse("is not a number with a frequency unit");
+        }
+        hertz = Number(match[1]) * scale;
+    }
+    else if (typeof property === "object" && !Array.isArray(property)) {
+        const { value, unit } = property;
+        if (typeof value !== "number") {
+            return refuse("has no numeric value");
+        }
+        const token = typeof unit === "string" ? unit.replaceAll("'", "").trim() : "";
+        const scale = frequencyUnitScale[token];
+        if (scale === undefined) {
+            return refuse(`has unit "${token}", which is not a frequency`);
+        }
+        hertz = value * scale;
+    }
+    else {
+        return refuse("is not a number, string or structured quantity");
+    }
+    if (!Number.isFinite(hertz) || hertz <= 0) {
+        return refuse("is not a positive finite frequency");
+    }
+    return hertz;
+}
+/**
+ * The bounds of a declared diode `EmissionCoefficient` (the SPICE `N`, the ideality factor): 1, the
+ * Shockley limit nothing physical sits below, to 10, beyond which the part is not one junction. A
+ * value outside them is refused by name, never clamped.
+ */
+export const EMISSION_COEFFICIENT_MIN = 1;
+export const EMISSION_COEFFICIENT_MAX = 10;
+/**
+ * A diode's declared `EmissionCoefficient`, or `null` when the component states none.
+ *
+ * **The whole value is read, and a value that is not an emission coefficient is refused rather than
+ * skipped or clamped** -- the `typedFrequencyHz` pattern for a dimensionless number. Legal forms,
+ * each checked end to end: a bare number; a string that is exactly a number (`"1.9"`, `"1.9e0"`,
+ * nothing after it: not `"1.9 typ"`, not `"1.9n"`); and a structured `{value, unit}` whose `value`
+ * wins over `raw` and whose unit must be empty. The property is read under this one spelling only
+ * (the corpus has one); nothing here reads a part number, a name or a description.
+ *
+ * A property that is present and is not a number in `EMISSION_COEFFICIENT_MIN` to
+ * `EMISSION_COEFFICIENT_MAX` is a packet error, so this throws and names the component and the
+ * offending value. It states something, and what it states is not an ideality factor.
+ */
+export function typedEmissionCoefficient(component) {
+    const key = "EmissionCoefficient";
+    const property = component.properties[key];
+    if (property === undefined || property === null) {
+        return null;
+    }
+    const refuse = (why) => {
+        throw new NetlistError(`${component.id}: ${key} ${JSON.stringify(property)} ${why}; a declared emission coefficient must be a number from ${EMISSION_COEFFICIENT_MIN} to ${EMISSION_COEFFICIENT_MAX}, bare, as a number-only string, or as a {value, unit: ""}`, String(component.id));
+    };
+    let n;
+    if (typeof property === "number") {
+        n = property;
+    }
+    else if (typeof property === "string") {
+        const text = property
+            .trim()
+            .replace(/^['"]+|['"]+$/gu, "")
+            .trim();
+        if (text === "") {
+            return null;
+        }
+        if (!/^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$/u.test(text)) {
+            return refuse("is not a number");
+        }
+        n = Number(text);
+    }
+    else if (typeof property === "object" && !Array.isArray(property)) {
+        const { value, unit } = property;
+        if (typeof value !== "number") {
+            return refuse("has no numeric value");
+        }
+        const token = typeof unit === "string" ? unit.replaceAll("'", "").trim() : "";
+        if (token !== "") {
+            return refuse(`has unit "${token}", which is not dimensionless`);
+        }
+        n = value;
+    }
+    else {
+        return refuse("is not a number, string or structured quantity");
+    }
+    if (!Number.isFinite(n) || n < EMISSION_COEFFICIENT_MIN || n > EMISSION_COEFFICIENT_MAX) {
+        return refuse(`is not a finite number from ${EMISSION_COEFFICIENT_MIN} to ${EMISSION_COEFFICIENT_MAX}`);
+    }
+    return n;
+}
 /**
  * Parse a quantity to SI base units. A value that cannot be parsed is an error, not a
  * default -- a silently defaulted component is a silently wrong circuit.
@@ -2074,6 +2230,396 @@ export function parseQuantity(raw) {
     }
     return value * multiplier;
 }
+/**
+ * Stage 2: the explicit device-parameter override block.
+ *
+ * A `.vdsp` NAMES the part; the registry holds its parameters. A component may carry one
+ * `DeviceOverride` object in its `properties` stating measured values for this device
+ * (`kind: "measured"`, allowed on any part) or the full parameter set for a part the
+ * registry does not have (`kind: "custom"`). Parameter names are the part's OWN class-schema
+ * names (`CLASS_PARAM_SCHEMAS` for its class); values are plain SI numbers, one per parameter.
+ *
+ * Placement is a nested structured property -- not a new component field -- so no
+ * `circuit-interchange` schema version, no `Component` type, no parser/serializer and no
+ * core change was needed: nested objects round-trip through `parsePropertyValue` /
+ * `propertiesBlock` untouched. An override changes only law numbers that already flow into
+ * program blocks the way today's legacy typed keys do, so `Program`, the stamps and the
+ * consoles are untouched too.
+ *
+ * Precedence, decided under the brief: override > legacy typed key > registry > class default.
+ * Legacy reading is untouched (REMOVAL is stage 4, not this task); while it is still read,
+ * every device carrying a still-read legacy key gets the additive `legacy-device-parameter`
+ * warning, and every applied override gets the additive `registry-override-applied` notice
+ * (emitted in `compile.ts`, where the registry is in scope).
+ *
+ * Every refusal names the component, the parameter and the rule (`NetlistError` carries the
+ * component id, and `compile` turns it into an `unsupported` result at stage `netlist`).
+ */
+const DEVICE_OVERRIDE_KEY = "DeviceOverride";
+/**
+ * The schema class an override block on this device is checked against, or `null` when the
+ * device kind takes no registry-class parameters and an override block is an error.
+ *
+ * `diode` device kind covers three classes with the same five names: zener when the component
+ * declares itself one (`Type: Zener`, the only two corpus spellings, or the canonical
+ * `Circuit.ZenerDiode` source type), led when the component kind is `led`, else diode. Only
+ * the *required set* differs between them (a zener additionally requires `breakdownVolts`,
+ * because without it the law stamps an ordinary diode).
+ */
+function overrideTargetClass(component, deviceKind) {
+    switch (deviceKind) {
+        case "bjt":
+            return "bjt";
+        case "jfet":
+            return "jfet";
+        case "mosfet":
+            return "mosfet";
+        case "diode": {
+            const declaredType = propertyString(component, "Type");
+            if (declaredType === "Zener" ||
+                declaredType === "zener" ||
+                component.sourceTypeName === "Circuit.ZenerDiode") {
+                return "zener";
+            }
+            if (String(component.kind) === "led") {
+                return "led";
+            }
+            return "diode";
+        }
+        case "opamp":
+            return "opamp";
+        default:
+            return null;
+    }
+}
+/**
+ * Legacy typed device-parameter keys this stage still reads, per device kind. Only these warn:
+ * keys the compiler never reads (`SR`, `Rout`, `Rin`, `Vsat`, a diode's `IS`/`n`, ...) change
+ * nothing when deleted and belong to the migration table, not to a compile warning.
+ */
+const LEGACY_DEVICE_PARAM_KEYS = {
+    bjt: ["IS", "BF", "BR", "LeakageCurrent"],
+    jfet: [
+        "Vt0",
+        "VTO",
+        "ThresholdVoltage",
+        "thresholdVolts",
+        "Beta",
+        "BETA",
+        "Transconductance",
+        "transconductance",
+    ],
+    mosfet: [
+        "Vt0",
+        "VTO",
+        "ThresholdVoltage",
+        "thresholdVolts",
+        "Beta",
+        "BETA",
+        "Transconductance",
+        "transconductance",
+    ],
+    diode: [
+        "ReverseBreakdownVoltage",
+        "BreakdownVoltage",
+        "ZenerVoltage",
+        "SaturationCurrent",
+        "SeriesResistance",
+        "OhmicResistance",
+        "RS",
+        "Rs",
+        "EmissionCoefficient",
+    ],
+    opamp: ["Aol", "GBP"],
+};
+/**
+ * The engine field a legacy key feeds, for the superseded computation. A legacy key is
+ * superseded when the override supplies the same engine field -- compared on fields, not on
+ * spellings, so the compiler holds no legacy-name to schema-name translation table (that
+ * table lives only in the step-3 migration script).
+ */
+const LEGACY_KEY_ENGINE_FIELD = {
+    IS: "saturationCurrent",
+    BF: "beta",
+    BR: "reverseBeta",
+    LeakageCurrent: "leakageAmps",
+    Vt0: "thresholdVolts",
+    VTO: "thresholdVolts",
+    ThresholdVoltage: "thresholdVolts",
+    thresholdVolts: "thresholdVolts",
+    Beta: "transconductance",
+    BETA: "transconductance",
+    Transconductance: "transconductance",
+    transconductance: "transconductance",
+    ReverseBreakdownVoltage: "breakdownVolts",
+    BreakdownVoltage: "breakdownVolts",
+    ZenerVoltage: "breakdownVolts",
+    SaturationCurrent: "saturationCurrent",
+    SeriesResistance: "seriesResistance",
+    OhmicResistance: "seriesResistance",
+    RS: "seriesResistance",
+    Rs: "seriesResistance",
+    EmissionCoefficient: "emissionCoefficient",
+    Aol: "openLoopGain",
+    GBP: "gainBandwidthHz",
+};
+/**
+ * The engine field an override schema name writes. Every schema name already IS the engine
+ * field except the BJT's gain: the document-typed legacy key is `BF`, the engine field is
+ * `beta` (read by `device-laws.ts` and the provisional-value suppression), and the schema
+ * name is `forwardBeta`.
+ */
+function overrideEngineField(target, name) {
+    if (target === "bjt" && name === "forwardBeta") {
+        return "beta";
+    }
+    return name;
+}
+/**
+ * The class parameters an override block may actually set, by target class: the subset of
+ * the class schema that the engine reads from the document.
+ *
+ * A schema name outside this set is refused even though it is a real class parameter, because
+ * accepting it would be a silent drop: `device-laws.ts` reads a JFET's gate terms
+ * (`gateSaturationCurrent`, `gateOnsetVolts`, `gateScaleVolts`), its
+ * `channelLengthModulation` and `subthresholdVolts`, and an op-amp's output-swing pair ONLY
+ * from the registry entry, never from `device.parameters`. An override value for one of those
+ * would merge, stamp nothing, and change nothing -- the wrong-answer-that-renders this file
+ * exists to prevent. Those numbers come from registry entries (stage 3 fills them), never
+ * from a per-device override; polarity and channel stay structural for the same reason.
+ */
+const OVERRIDABLE_CLASS_PARAMS = {
+    bjt: [
+        "saturationCurrent",
+        "forwardBeta",
+        "reverseBeta",
+        "thermalVoltage",
+        "leakageAmps",
+    ],
+    jfet: ["thresholdVolts", "transconductance"],
+    mosfet: ["thresholdVolts", "transconductance"],
+    diode: [
+        "saturationCurrent",
+        "emissionCoefficient",
+        "thermalVoltage",
+        "breakdownVolts",
+        "seriesResistance",
+    ],
+    zener: [
+        "saturationCurrent",
+        "emissionCoefficient",
+        "thermalVoltage",
+        "breakdownVolts",
+        "seriesResistance",
+    ],
+    led: [
+        "saturationCurrent",
+        "emissionCoefficient",
+        "thermalVoltage",
+        "breakdownVolts",
+        "seriesResistance",
+    ],
+    opamp: ["openLoopGain", "gainBandwidthHz"],
+};
+/** A non-empty authored string, or `null` when the value is not one. */
+function nonEmptyText(value) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        return null;
+    }
+    return value.trim();
+}
+/**
+ * Check one override value: finite, and positive (or bounded) where the parameter is
+ * physically required to be. Names the component, the parameter and the rule.
+ */
+function checkOverrideValue(componentId, target, name, value) {
+    const refuse = (rule) => {
+        throw new NetlistError(`component ${componentId}: DeviceOverride parameter "${name}" ${JSON.stringify(value)} ${rule}`, componentId);
+    };
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        refuse("is not a finite SI number");
+    }
+    const n = value;
+    switch (name) {
+        case "emissionCoefficient":
+            if (n < EMISSION_COEFFICIENT_MIN || n > EMISSION_COEFFICIENT_MAX) {
+                refuse(`is not an ideality factor from ${EMISSION_COEFFICIENT_MIN} to ${EMISSION_COEFFICIENT_MAX}`);
+            }
+            return n;
+        case "leakageAmps":
+        case "breakdownVolts":
+        case "seriesResistance":
+        case "channelLengthModulation":
+        case "subthresholdVolts":
+        case "gateSaturationCurrent":
+            if (n < 0) {
+                refuse(`is negative, and a negative ${name} is not physical`);
+            }
+            return n;
+        case "thresholdVolts":
+        case "gateOnsetVolts":
+            // Sign carries the physics here (depletion negative, enhancement positive, and
+            // p-channel JFETs pinch off positive), so any finite value -- including zero --
+            // parses, exactly as the legacy `Vt0` reader accepts any quantity.
+            return n;
+        default:
+            // saturationCurrent, forwardBeta, reverseBeta, thermalVoltage, transconductance,
+            // gateScaleVolts, openLoopGain, gainBandwidthHz, volts, sourceOhms,
+            // chargePumpLossVolts: zero or negative is not a value for any of them.
+            if (!(n > 0)) {
+                refuse(`is not a positive finite number, which ${name} must be`);
+            }
+            return n;
+    }
+}
+/**
+ * Parse and validate the `DeviceOverride` block on this component, or return null when it
+ * declares none. Throws `NetlistError` (naming component, parameter and rule) on every
+ * malformed block: unknown kind, missing/malformed provenance, malformed parameter list,
+ * unknown name for the class, duplicate parameter, non-physical value, `custom` on a known
+ * part, or `custom` missing a required parameter. Override on a device kind that takes no
+ * registry-class parameters is an error, so a block on a resistor or an IC can never sit
+ * silently unread.
+ */
+function readDeviceOverride(component, deviceKind, registry) {
+    const raw = component.properties[DEVICE_OVERRIDE_KEY];
+    if (raw === undefined || raw === null) {
+        return null;
+    }
+    const componentId = String(component.id);
+    const target = overrideTargetClass(component, deviceKind);
+    if (target === null) {
+        throw new NetlistError(`component ${componentId}: DeviceOverride is not supported for ${deviceKind} devices (bjt, jfet, mosfet, diode and opamp only)`, componentId);
+    }
+    if (typeof raw !== "object" || Array.isArray(raw)) {
+        throw new NetlistError(`component ${componentId}: DeviceOverride must be an object with kind, provenance and parameters, not ${JSON.stringify(raw)}`, componentId);
+    }
+    const block = raw;
+    const kind = block.kind;
+    if (kind !== "measured" && kind !== "custom") {
+        throw new NetlistError(`component ${componentId}: DeviceOverride.kind ${JSON.stringify(kind)} is not "measured" or "custom"`, componentId);
+    }
+    const source = nonEmptyText(block.source);
+    if (source === null) {
+        throw new NetlistError(`component ${componentId}: DeviceOverride.source is missing (what was measured, or which document the numbers come from)`, componentId);
+    }
+    const method = nonEmptyText(block.method);
+    if (method === null) {
+        throw new NetlistError(`component ${componentId}: DeviceOverride.method is missing (instrument/procedure for measured, why the registry lacks the part for custom)`, componentId);
+    }
+    const dateRaw = nonEmptyText(block.date);
+    if (dateRaw === null ||
+        !/^\d{4}-\d{2}-\d{2}$/u.test(dateRaw) ||
+        Number.isNaN(Date.parse(`${dateRaw}T00:00:00Z`))) {
+        throw new NetlistError(`component ${componentId}: DeviceOverride.date ${JSON.stringify(block.date)} is not an ISO date (YYYY-MM-DD)`, componentId);
+    }
+    const by = nonEmptyText(block.by);
+    if (by === null) {
+        throw new NetlistError(`component ${componentId}: DeviceOverride.by is missing (a named person or organisation)`, componentId);
+    }
+    const conditions = block.conditions;
+    if (conditions !== undefined && typeof conditions !== "string") {
+        throw new NetlistError(`component ${componentId}: DeviceOverride.conditions must be free text, not ${JSON.stringify(conditions)}`, componentId);
+    }
+    const list = block.parameters;
+    if (!Array.isArray(list) || list.length === 0) {
+        throw new NetlistError(`component ${componentId}: DeviceOverride.parameters must be a non-empty list of {name, value}`, componentId);
+    }
+    const allowed = new Set(classParamNames(target));
+    const overridable = new Set(OVERRIDABLE_CLASS_PARAMS[target]);
+    const seen = new Set();
+    const parameters = [];
+    for (const [index, entry] of list.entries()) {
+        if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+            throw new NetlistError(`component ${componentId}: DeviceOverride.parameters[${index}] must be {name, value}, not ${JSON.stringify(entry)}`, componentId);
+        }
+        const record = entry;
+        const name = record.name;
+        if (typeof name !== "string" || !allowed.has(name)) {
+            throw new NetlistError(`component ${componentId}: DeviceOverride parameter ${JSON.stringify(name)} is not a ${target} parameter (accepted: ${[...allowed].join(", ")})`, componentId);
+        }
+        if (!overridable.has(name)) {
+            throw new NetlistError(`component ${componentId}: DeviceOverride parameter "${name}" is a ${target} parameter but the engine reads it only from the registry entry, never from the document, so an override cannot set it (overridable: ${[...overridable].join(", ")})`, componentId);
+        }
+        if (seen.has(name)) {
+            throw new NetlistError(`component ${componentId}: DeviceOverride parameter "${name}" is stated twice (one value per parameter)`, componentId);
+        }
+        seen.add(name);
+        const value = checkOverrideValue(componentId, target, name, record.value);
+        parameters.push({ name, value });
+    }
+    if (kind === "custom") {
+        const partNumber = propertyString(component, "PartNumber");
+        if (partNumber !== null &&
+            registryEntryFor(registry, { partId: partNumber, evidence: "exact-part" }) !== null) {
+            throw new NetlistError(`component ${componentId}: DeviceOverride kind "custom" on part "${partNumber}", which the registry already has (use kind "measured", or remove the block)`, componentId);
+        }
+        const missing = requiredClassParams(target).filter((name) => !seen.has(name));
+        if (missing.length > 0) {
+            throw new NetlistError(`component ${componentId}: DeviceOverride kind "custom" for class ${target} is missing required parameter(s): ${missing.join(", ")}`, componentId);
+        }
+    }
+    const provenance = {
+        kind,
+        source,
+        method,
+        date: dateRaw,
+        by,
+        ...(conditions === undefined ? {} : { conditions }),
+    };
+    return { override: { provenance, parameters }, target };
+}
+/**
+ * Merge an explicit override over this device's legacy typed parameters (override wins),
+ * and emit the additive `legacy-device-parameter` warning for every legacy key still read.
+ * No override block: legacy parameters pass through bit-identically and only the warning
+ * is new.
+ */
+function applyDeviceOverride(component, deviceKind, legacy, context) {
+    const read = readDeviceOverride(component, deviceKind, context.registry);
+    const legacyKeys = (LEGACY_DEVICE_PARAM_KEYS[deviceKind] ?? []).filter((key) => component.properties[key] !== undefined);
+    if (read === null) {
+        if (legacyKeys.length > 0) {
+            const warning = {
+                code: "legacy-device-parameter",
+                device: context.deviceId,
+                keys: legacyKeys,
+                overridden: [],
+                detail: `${context.deviceId} still types device parameters under legacy keys (${legacyKeys.join(", ")}), ` +
+                    `which the compiler still reads and the stage-4 removal will stop reading: ` +
+                    `migrate them to a DeviceOverride block (measured with provenance, or custom ` +
+                    `for a part the registry lacks).`,
+            };
+            context.warnings.push(warning);
+        }
+        return { parameters: legacy, deviceOverride: undefined };
+    }
+    const { override, target } = read;
+    const values = { ...legacy };
+    const overrideFields = new Set(override.parameters.map((parameter) => overrideEngineField(target, parameter.name)));
+    for (const parameter of override.parameters) {
+        values[overrideEngineField(target, parameter.name)] =
+            parameter.value;
+    }
+    const overridden = legacyKeys.filter((key) => {
+        const field = LEGACY_KEY_ENGINE_FIELD[key];
+        return field !== undefined && overrideFields.has(field);
+    });
+    const warning = {
+        code: "legacy-device-parameter",
+        device: context.deviceId,
+        keys: legacyKeys,
+        overridden,
+        detail: overridden.length > 0
+            ? `${context.deviceId} applies a ${override.provenance.kind} DeviceOverride that supersedes legacy keys (${overridden.join(", ")}); the override values win. ` +
+                `Remaining legacy keys (${legacyKeys.filter((key) => !overridden.includes(key)).join(", ") || "none"}) still read as before.`
+            : `${context.deviceId} applies a ${override.provenance.kind} DeviceOverride alongside legacy keys (${legacyKeys.join(", ") || "none"}); no legacy key feeds an overridden parameter, so all legacy values still read.`,
+    };
+    if (legacyKeys.length > 0) {
+        context.warnings.push(warning);
+    }
+    return { parameters: values, deviceOverride: override };
+}
 function parametersFor(component, kind) {
     // A supply rail asserts a potential at its node. Most declare one -- 84 of the
     // corpus's 90 -- and the six that do not are named support shells with nothing to
@@ -2224,10 +2770,18 @@ function parametersFor(component, kind) {
     // with the decibel conversion done -- `{raw: "92 dB", value: 39810, unit: ""}`. So the typed
     // `value` is taken as-is and nothing here converts from dB, which would double-apply it.
     //
-    // `GBP` and `SR` are deliberately not read. The gain-bandwidth product has no consumer until a
-    // dominant pole exists, and that was implemented and reverted; reading it into the stamp now
-    // would be a field nothing uses. `SR` is stated as `"1.2 V/us"`, and `parseQuantity` strips
-    // after the slash, so it would yield 1.2 for the wrong reason -- right number, lost units.
+    // `GBP`, the gain-bandwidth product, is read as a typed frequency. It was left unread while no
+    // dominant pole existed for it to feed; the pole landed 2026-08-21 and both consoles now take
+    // the product from the stamp. It is stated in several forms across the corpus -- `"3 MHz"`,
+    // `"3000000"`, `1.2 MHz`, and structured `{value, unit}` -- so it goes through
+    // `typedFrequencyHz`, which reads the unit whole and refuses what it cannot read. Nothing here
+    // falls back to a number: a packet that states none leaves the field absent, and the catalog's
+    // datasheet figure for the exact part id, else `null`, is decided in `device-laws.ts`.
+    //
+    // `SR` stays unread. It is stated as `"1.2 V/us"`, and `parseQuantity` strips after the slash,
+    // so it would yield 1.2 for the wrong reason -- right number, lost units -- and no consumer
+    // exists for a slew rate yet. `typedFrequencyHz` does not inherit that trap: it compares the
+    // whole string against a number and a frequency unit and refuses anything else.
     if (kind === "opamp") {
         // `typedNumber`, not `optionalQuantity`, and the difference is a 433x error.
         // `optionalQuantity` reads `raw` first, so `{raw: "92 dB", value: 39810, unit: ""}` parsed as
@@ -2235,7 +2789,11 @@ function parametersFor(component, kind) {
         // the conversion, so it has to win. Caught by measuring the stamped gains after the change
         // rather than by reading the code.
         const gain = typedNumber(component, "Aol", [""]);
-        return gain !== null && gain > 0 ? { openLoopGain: gain } : {};
+        const bandwidth = typedFrequencyHz(component, "GBP");
+        return {
+            ...(gain !== null && gain > 0 ? { openLoopGain: gain } : {}),
+            ...(bandwidth === null ? {} : { gainBandwidthHz: bandwidth }),
+        };
     }
     // A delay-memory shell's own delay time, which is a **packet** fact rather than a part fact.
     //
@@ -2374,6 +2932,12 @@ function parametersFor(component, kind) {
             optionalQuantity(component, "OhmicResistance") ??
             optionalQuantity(component, "RS") ??
             optionalQuantity(component, "Rs");
+        // `EmissionCoefficient` -- the junction's ideality, the slope of its knee. One packet declares
+        // it (`boss-sd-1`, 1.9 on three clipping diodes) and until this read it was discarded: the law
+        // stamped 1.752 whatever the source said, and nothing said so, so a knee that a packet states
+        // was a knee the engine never had. Typed and refused when unreadable, like `GBP`; absent stays
+        // absent, so `deviceLaw` keeps ownership of what an undeclared coefficient means.
+        const emission = typedEmissionCoefficient(component);
         return {
             ...(breakdown !== null && breakdown > 0
                 ? { breakdownVolts: breakdown }
@@ -2384,6 +2948,7 @@ function parametersFor(component, kind) {
             ...(seriesResistance !== null && seriesResistance > 0
                 ? { seriesResistance }
                 : {}),
+            ...(emission === null ? {} : { emissionCoefficient: emission }),
         };
     }
     // A bipolar transistor's device type and SPICE parameters, which this stage used to
@@ -3302,6 +3867,11 @@ function selectedOption(component, stated) {
  * Deliberately absent: `W`, `W20`, `G`, `D`, `L`, `BH`, `Stepped`, `Trim`,
  * `Boss-G-taper` and the other manufacturer-specific curves. We do not know their
  * shapes, and guessing one would be inventing a device law from a letter.
+ *
+ * `s-curve` is the one S-shaped law present, and it is the *law's name*, not Alpha's letter: a
+ * pot marked `W` or `W20` stays absent, because makers disagree on W and a letter selects a
+ * curve only with its maker. A document that has established its pot's S-curve is Alpha W(4B)
+ * says so by writing `s-curve`.
  */
 const taperSpellings = new Map([
     ["linear", "linear"],
@@ -3319,6 +3889,9 @@ const taperSpellings = new Map([
     ["negativelog", "reverse-logarithmic"],
     ["c", "reverse-logarithmic"],
     ["reverselinear", "reverse-linear"],
+    // Alpha W(4B). `foldTaper` strips `-`, `_` and whitespace, so this one key is `s-curve`,
+    // `S-Curve`, `S Curve` and `scurve`; a hyphenated key would be unreachable.
+    ["scurve", "s-curve"],
 ]);
 /**
  * Values whose meaning is "the source does not state a taper".
@@ -3336,12 +3909,11 @@ const taperUnknownSpellings = new Set([
 /**
  * Tapers `@vessel-dsp/core`'s format supports and this runtime has no curve for.
  *
- * `PotentiometerTaper` carries seven values; `TaperKind` -- the executable law -- carries four.
- * A document declaring one of these three has stated a real taper that the render cannot produce,
+ * `PotentiometerTaper` carries seven values; `TaperKind` -- the executable law -- carries five.
+ * A document declaring one of these two has stated a real taper that the render cannot produce,
  * which is a different failure from an unreadable marking and is worth saying differently.
  */
 const taperWithoutLaw = new Set([
-    "scurve",
     "stepped",
     "custom",
 ]);
@@ -3370,7 +3942,7 @@ function taperKind(value) {
  *   have read;
  * - the value states anything else -> linear, and **name it**, whether it is a part marking whose
  *   curve is not derivable here (`W20`, `Boss-G-taper`) or a taper the format supports and this
- *   runtime has no law for (`s-curve`, `stepped`).
+ *   runtime has no law for (`stepped`, `custom`).
  */
 function declaredTaper(component) {
     // `Sweep` is what a variable-resistor calls its taper. Both are closed vocabularies