@map-audio/pam-mcp-server 1.18.1 → 1.22.0

package/dist/fingerprint.d.ts

@@ -0,0 +1,70 @@
+export type Fingerprint = {
+    name: string;
+    bpm: number;
+    /** Cells carrying at least one note. */
+    cells: number;
+    /** Per-cell param suffixes moved off their manifest default, unioned. */
+    params: string[];
+    /** Effect slugs enabled on at least one cell. */
+    fx: string[];
+    /** Distinct FX chain orders, as "filter>eq>..." signatures. */
+    chains: string[];
+    /** Modulation source counts and the param families they target. */
+    mod: {
+        lfo: number;
+        env: number;
+        vary: number;
+        seq: number;
+        targets: string[];
+    };
+    /** Per-cell onset sets, quantized to 16ths of a bar: "c1:0,4,8,12". */
+    groove: string[];
+    /** Distinct transposition values in use (pitchShift + arpeg + pitch lanes). */
+    pitch: number[];
+    /** Sample identity, normalized so takes of one source collapse together. */
+    sources: string[];
+    /** Drum-synth engine indices in use. */
+    engines: number[];
+};
+export declare function buildFingerprint(state: Record<string, unknown>, defaults: Record<string, number>, effectNames: readonly string[], name?: string): Fingerprint;
+/** Dimension weights. Groove and params dominate because they are what a
+ *  listener names first when two presets "sound the same". */
+declare const WEIGHTS: {
+    params: number;
+    groove: number;
+    mod: number;
+    sources: number;
+    fx: number;
+    chains: number;
+    pitch: number;
+};
+export type Similarity = {
+    overall: number;
+    byDimension: Record<keyof typeof WEIGHTS, number>;
+};
+export declare function similarity(a: Fingerprint, b: Fingerprint): Similarity;
+/** Leave-one-out novelty distribution of the corpus against itself. Absolute
+ *  novelty numbers mean nothing on their own — a perfectly good preset scores
+ *  ~0.55 because every PAM preset shares an instrument. The only useful
+ *  question is "distinct compared to what already shipped", so verdicts are
+ *  phrased against these percentiles rather than invented thresholds. */
+export type NoveltyBaseline = {
+    p10: number;
+    p50: number;
+    p90: number;
+    floor: number;
+};
+export type NeighbourReport = {
+    novelty: number;
+    percentileVsCorpus: number | null;
+    nearest: {
+        name: string;
+        similarity: number;
+        duplicatedDimensions: string[];
+    }[];
+    verdict: string;
+};
+/** Score a candidate against a corpus. novelty = 1 - closest match, so 0 means
+ *  "this already exists" and 1 means "nothing like it has shipped". */
+export declare function scoreNovelty(candidate: Fingerprint, corpus: Fingerprint[], topN?: number, baseline?: NoveltyBaseline): NeighbourReport;
+export {};

package/dist/fingerprint.js

@@ -0,0 +1,240 @@
+// Preset fingerprinting — the shared algorithm behind the corpus index
+// (scripts/derive-corpus-fingerprints.ts) and the preset_novelty tool.
+//
+// WHY: nothing in the design pipeline ever compared a new preset against the
+// ones already shipped, so every session started from the same prior and landed
+// on the same centroid preset. A fingerprint plus a distance makes "does this
+// already exist?" a number instead of a judgement call.
+//
+// The dimensions are deliberately structural rather than acoustic — they read
+// straight off preset state, so novelty can be scored with no render, no audio
+// and no plugin connection.
+const asArray = (v) => {
+    if (Array.isArray(v))
+        return v;
+    if (typeof v === "string") {
+        try {
+            const p = JSON.parse(v);
+            return Array.isArray(p) ? p : [];
+        }
+        catch {
+            return [];
+        }
+    }
+    return [];
+};
+const asRecord = (v) => {
+    if (typeof v === "string") {
+        try {
+            const p = JSON.parse(v);
+            return p && typeof p === "object" ? p : {};
+        }
+        catch {
+            return {};
+        }
+    }
+    return v && typeof v === "object" ? v : {};
+};
+/** Strip take numbers, bpm tags and separators so "Kick_03_120bpm" and
+ *  "kick-05" read as the same source. Two presets built from the same folder
+ *  should look similar even when the exact files differ. */
+const normalizeSource = (path) => path
+    .split(/[\\/]/)
+    .pop()
+    .replace(/\.[a-z0-9]+$/i, "")
+    .toLowerCase()
+    .replace(/\d+\s*bpm/g, "")
+    .replace(/[\d_\-\s]+/g, "")
+    .slice(0, 24);
+/** Param suffix from a modulation link's target, so cell3_filterCutoff and
+ *  cell7_filterCutoff count as the same kind of move. */
+const targetFamily = (paramId) => typeof paramId === "string" ? paramId.replace(/^cell\d+_/, "").replace(/^macro_/, "macro:") : null;
+export function buildFingerprint(state, defaults, effectNames, name = "candidate") {
+    const params = new Set();
+    const fx = new Set();
+    const chains = new Set();
+    const groove = [];
+    const pitch = new Set();
+    const engines = new Set();
+    let cells = 0;
+    for (let c = 1; c <= 8; c += 1) {
+        const seq = asArray(state[`cell${c}_midiSequence`]);
+        if (seq.length === 0)
+            continue;
+        cells += 1;
+        // The per-effect enable flags are state-only — they are NOT manifest
+        // parameters, so they never reach the defaults map below and have to be
+        // read directly. Missing this silently produced an empty fx set on every
+        // preset in the corpus index.
+        for (const slug of effectNames) {
+            if (state[`cell${c}_${slug}Enabled`])
+                fx.add(slug);
+        }
+        for (const [key, value] of Object.entries(state)) {
+            if (!key.startsWith(`cell${c}_`) || typeof value !== "number")
+                continue;
+            const suffix = key.slice(`cell${c}_`.length);
+            const def = defaults[suffix];
+            // A param at its default was never a decision. Only moved params
+            // describe the preset.
+            if (def === undefined || value === def)
+                continue;
+            params.add(suffix);
+        }
+        const order = asArray(state[`cell${c}_effectOrder`]).filter((s) => typeof s === "string");
+        if (order.length)
+            chains.add(order.join(">"));
+        // Onsets quantized to 16ths of a bar. `time` is in beats, so ×4 is a 16th
+        // grid; folding mod 16 compares the groove rather than the bar count.
+        const steps = new Set();
+        for (const ev of seq) {
+            const t = ev.time;
+            if (typeof t === "number")
+                steps.add(Math.round(t * 4) % 16);
+        }
+        if (steps.size)
+            groove.push(`c${c}:${[...steps].sort((a, b) => a - b).join(",")}`);
+        const ps = state[`cell${c}_pitchShift`];
+        if (typeof ps === "number" && ps !== 0)
+            pitch.add(ps);
+        const ar = state[`cell${c}_arpeg`];
+        if (typeof ar === "number" && ar !== 0)
+            pitch.add(ar);
+        for (const ev of asArray(state[`cell${c}_pitchSequence`])) {
+            const v = ev.value;
+            if (typeof v === "number" && v !== 0)
+                pitch.add(v);
+        }
+        const eng = state[`cell${c}_synthEngine`];
+        if (typeof eng === "number" && eng > 0)
+            engines.add(eng);
+    }
+    const modTargets = new Set();
+    const countLinks = (key) => {
+        const links = asArray(state[key]);
+        for (const l of links) {
+            const fam = targetFamily(l.paramId);
+            if (fam)
+                modTargets.add(fam);
+        }
+        return links.length;
+    };
+    const sources = new Set();
+    const cellMap = asRecord(state.cells);
+    for (const entry of Object.values(cellMap)) {
+        const fp = entry.filePath;
+        if (typeof fp === "string" && fp.length > 2)
+            sources.add(normalizeSource(fp));
+    }
+    const bpmRaw = asRecord(state.transport).bpm ?? state.bpm;
+    return {
+        name,
+        bpm: typeof bpmRaw === "number" ? bpmRaw : 0,
+        cells,
+        params: [...params].sort(),
+        fx: [...fx].sort(),
+        chains: [...chains].sort(),
+        mod: {
+            lfo: countLinks("lfos"),
+            env: countLinks("envelopes"),
+            vary: countLinks("vary"),
+            seq: countLinks("paramSeqs"),
+            targets: [...modTargets].sort(),
+        },
+        groove: groove.sort(),
+        pitch: [...pitch].sort((a, b) => a - b),
+        sources: [...sources].sort(),
+        engines: [...engines].sort((a, b) => a - b),
+    };
+}
+const jaccard = (a, b) => {
+    if (a.length === 0 && b.length === 0)
+        return 1;
+    const setB = new Set(b);
+    let shared = 0;
+    for (const x of new Set(a))
+        if (setB.has(x))
+            shared += 1;
+    const union = new Set([...a, ...b]).size;
+    return union === 0 ? 1 : shared / union;
+};
+/** Groove similarity ignores which cell a rhythm sat on — the same pattern
+ *  moved from cell 3 to cell 5 is still the same pattern. */
+const grooveSimilarity = (a, b) => jaccard(a.map((g) => g.split(":")[1] ?? ""), b.map((g) => g.split(":")[1] ?? ""));
+const modSimilarity = (a, b) => {
+    const density = (m) => m.lfo + m.env + m.vary + m.seq;
+    const da = density(a);
+    const db = density(b);
+    const scale = Math.max(da, db) || 1;
+    const densityMatch = 1 - Math.abs(da - db) / scale;
+    // What is modulated matters more than how much of it there is.
+    return 0.35 * densityMatch + 0.65 * jaccard(a.targets, b.targets);
+};
+/** Dimension weights. Groove and params dominate because they are what a
+ *  listener names first when two presets "sound the same". */
+const WEIGHTS = { params: 0.24, groove: 0.24, mod: 0.18, sources: 0.16, fx: 0.08, chains: 0.05, pitch: 0.05 };
+export function similarity(a, b) {
+    const byDimension = {
+        params: jaccard(a.params, b.params),
+        groove: grooveSimilarity(a.groove, b.groove),
+        mod: modSimilarity(a.mod, b.mod),
+        sources: jaccard(a.sources, b.sources),
+        fx: jaccard(a.fx, b.fx),
+        chains: jaccard(a.chains, b.chains),
+        pitch: jaccard(a.pitch.map(String), b.pitch.map(String)),
+    };
+    let overall = 0;
+    for (const [dim, w] of Object.entries(WEIGHTS)) {
+        overall += w * byDimension[dim];
+    }
+    return { overall, byDimension };
+}
+/** Score a candidate against a corpus. novelty = 1 - closest match, so 0 means
+ *  "this already exists" and 1 means "nothing like it has shipped". */
+export function scoreNovelty(candidate, corpus, topN = 5, baseline) {
+    const scored = corpus
+        .map((other) => ({ other, sim: similarity(candidate, other) }))
+        .sort((x, y) => y.sim.overall - x.sim.overall)
+        .slice(0, topN);
+    const nearest = scored.map(({ other, sim }) => ({
+        name: other.name,
+        similarity: Math.round(sim.overall * 1000) / 1000,
+        // Dimensions where the candidate is essentially a copy. These are the
+        // actionable part of the report — they name what to change.
+        duplicatedDimensions: Object.entries(sim.byDimension)
+            .filter(([, v]) => v >= 0.7)
+            .sort((a, b) => b[1] - a[1])
+            .map(([k, v]) => `${k} ${Math.round(v * 100)}%`),
+    }));
+    const top = scored[0]?.sim.overall ?? 0;
+    const novelty = Math.round((1 - top) * 1000) / 1000;
+    let verdict;
+    let percentileVsCorpus = null;
+    if (baseline) {
+        // Linear interpolation across the three known percentiles is enough for a
+        // verdict — this is a calibration aid, not a statistic.
+        if (novelty <= baseline.p10)
+            percentileVsCorpus = Math.max(0, Math.round((10 * novelty) / baseline.p10));
+        else if (novelty <= baseline.p50)
+            percentileVsCorpus = Math.round(10 + (40 * (novelty - baseline.p10)) / (baseline.p50 - baseline.p10));
+        else if (novelty <= baseline.p90)
+            percentileVsCorpus = Math.round(50 + (40 * (novelty - baseline.p50)) / (baseline.p90 - baseline.p50));
+        else
+            percentileVsCorpus = Math.min(100, Math.round(90 + (10 * (novelty - baseline.p90)) / (1 - baseline.p90)));
+        verdict =
+            novelty < baseline.floor
+                ? `More derivative than ANY pair in the shipped corpus (the closest shipped pair scores ${baseline.floor}). Redesign the duplicated dimensions before saving.`
+                : novelty < baseline.p10
+                    ? "More derivative than 90% of shipped presets. Change at least one duplicated dimension."
+                    : novelty < baseline.p50
+                        ? "Below the corpus median for distinctness. Acceptable, but the duplicated dimensions are where it blends in."
+                        : novelty < baseline.p90
+                            ? "Distinct at or above the corpus median."
+                            : "More distinct than 90% of shipped presets.";
+    }
+    else {
+        verdict = `Nearest-neighbour similarity ${Math.round(top * 100)}%. No corpus baseline supplied, so this number is only comparable against other runs.`;
+    }
+    return { novelty, percentileVsCorpus, nearest, verdict };
+}
+//# sourceMappingURL=fingerprint.js.map

package/dist/fingerprint.js.map

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

package/dist/generated/variationSnapshot.d.ts

@@ -0,0 +1,31 @@
+export interface VariationSnapshotContract {
+    /** Session keys a variation must not carry (shared/variationSessionKeys.json). */
+    sessionKeys: readonly string[];
+    /** Visual audio-react paramIds — they persist ACROSS variations, so they are
+     *  stripped from every snapshot rather than captured per slot. */
+    visualParamIds: readonly string[];
+    /** Number of shared LFO generators (NUM_LFOS). */
+    lfoGeneratorCount: number;
+}
+export interface VariationSnapshotOptions {
+    /** FX-router products ship without Vary — never serialize its matrix state. */
+    isFxProduct?: boolean;
+}
+/**
+ * Force each `lfo{g}_enabled` flag to match whether that generator still has a
+ * live link.
+ *
+ * A generator whose links were all removed or disabled must not persist as
+ * enabled: on load it would re-arm a generator driving nothing, and the next
+ * link added to that slot would inherit an on state the user never set.
+ */
+export declare function reconcileLfoGeneratorEnabledState(snapshot: Record<string, unknown>, lfoGeneratorCount: number): void;
+/**
+ * Shape a variation snapshot from plugin state.
+ *
+ * Order matters and is part of the contract: strip session keys, drop the
+ * active-preset path, strip visual params, narrow for FX products, then
+ * reconcile the LFO generator flags LAST — the reconcile reads `lfos`, which
+ * the earlier steps may have removed.
+ */
+export declare function buildVariationSnapshotBase(state: Record<string, unknown>, contract: VariationSnapshotContract, options?: VariationSnapshotOptions): Record<string, unknown>;

package/dist/generated/variationSnapshot.js

@@ -0,0 +1,62 @@
+// GENERATED COPY of shared/variationSnapshot.ts — do not edit here.
+// Regenerate: node scripts/generate-variation-session-keys.mjs
+// The variation-snapshot shaping both save paths run.
+//
+// The UI (interface/src/interop.ts) and MCP (packages/mcp-server) both shape
+// through here, because two implementations drift: the MCP side was missing 16
+// session keys, the visual-param strip and the LFO-generator reconcile, so a
+// variation saved over MCP was not the same bytes as one saved from the window.
+//
+// This is the PURE half. It takes state plus the contract data and returns the
+// shaped snapshot, so both callers produce identical bytes for identical input
+// (pinned by interface/test/variationSnapshotParity.test.ts).
+//
+// The IMPURE half stays per-caller and is genuinely different: the UI can await
+// `refreshLoadedPluginStateBlobs()` and stamp hosted-plugin identity/bypass from
+// `pluginHostStore`; the headless bridge cannot reach either, and says so on the
+// save result instead of writing a silently lossy slot.
+//
+// GENERATED COPY: packages/mcp-server/src/generated/variationSnapshot.ts is
+// produced from this file by scripts/generate-variation-session-keys.mjs.
+// Edit THIS file; the drift check fails if the copy is stale.
+/**
+ * Force each `lfo{g}_enabled` flag to match whether that generator still has a
+ * live link.
+ *
+ * A generator whose links were all removed or disabled must not persist as
+ * enabled: on load it would re-arm a generator driving nothing, and the next
+ * link added to that slot would inherit an on state the user never set.
+ */
+export function reconcileLfoGeneratorEnabledState(snapshot, lfoGeneratorCount) {
+    if (!Array.isArray(snapshot.lfos))
+        return;
+    const lfos = snapshot.lfos;
+    for (let generatorIndex = 1; generatorIndex <= lfoGeneratorCount; generatorIndex++) {
+        const hasEnabledLinks = lfos.some((lfo) => lfo?.lfoGeneratorIndex === generatorIndex &&
+            (lfo?.enabled ?? 1) === 1 &&
+            typeof lfo?.paramId === 'string' &&
+            lfo.paramId.length > 0);
+        snapshot[`lfo${generatorIndex}_enabled`] = hasEnabledLinks ? 1 : 0;
+    }
+}
+/**
+ * Shape a variation snapshot from plugin state.
+ *
+ * Order matters and is part of the contract: strip session keys, drop the
+ * active-preset path, strip visual params, narrow for FX products, then
+ * reconcile the LFO generator flags LAST — the reconcile reads `lfos`, which
+ * the earlier steps may have removed.
+ */
+export function buildVariationSnapshotBase(state, contract, options = {}) {
+    const snapshot = { ...state };
+    for (const key of contract.sessionKeys)
+        delete snapshot[key];
+    delete snapshot.activePresetPath;
+    for (const paramId of contract.visualParamIds)
+        delete snapshot[paramId];
+    if (options.isFxProduct)
+        delete snapshot.vary;
+    reconcileLfoGeneratorEnabledState(snapshot, contract.lfoGeneratorCount);
+    return snapshot;
+}
+//# sourceMappingURL=variationSnapshot.js.map

package/dist/generated/variationSnapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"variationSnapshot.js","sourceRoot":"","sources":["../../src/generated/variationSnapshot.ts"],"names":[],"mappings":"AAAA,oEAAoE;AACpE,+DAA+D;AAC/D,sDAAsD;AACtD,EAAE;AACF,6EAA6E;AAC7E,+EAA+E;AAC/E,6EAA6E;AAC7E,gFAAgF;AAChF,EAAE;AACF,+EAA+E;AAC/E,+EAA+E;AAC/E,8DAA8D;AAC9D,EAAE;AACF,gFAAgF;AAChF,iFAAiF;AACjF,iFAAiF;AACjF,wDAAwD;AACxD,EAAE;AACF,4EAA4E;AAC5E,0EAA0E;AAC1E,8DAA8D;AAuB9D;;;;;;;GAOG;AACH,MAAM,UAAU,iCAAiC,CAC/C,QAAiC,EACjC,iBAAyB;IAEzB,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAM;IACzC,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAiB,CAAA;IAEvC,KAAK,IAAI,cAAc,GAAG,CAAC,EAAE,cAAc,IAAI,iBAAiB,EAAE,cAAc,EAAE,EAAE,CAAC;QACnF,MAAM,eAAe,GAAG,IAAI,CAAC,IAAI,CAC/B,CAAC,GAAG,EAAE,EAAE,CACN,GAAG,EAAE,iBAAiB,KAAK,cAAc;YACzC,CAAC,GAAG,EAAE,OAAO,IAAI,CAAC,CAAC,KAAK,CAAC;YACzB,OAAO,GAAG,EAAE,OAAO,KAAK,QAAQ;YAChC,GAAG,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CACzB,CAAA;QACD,QAAQ,CAAC,MAAM,cAAc,UAAU,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IACpE,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,0BAA0B,CACxC,KAA8B,EAC9B,QAAmC,EACnC,UAAoC,EAAE;IAEtC,MAAM,QAAQ,GAA4B,EAAE,GAAG,KAAK,EAAE,CAAA;IAEtD,KAAK,MAAM,GAAG,IAAI,QAAQ,CAAC,WAAW;QAAE,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAA;IAC5D,OAAO,QAAQ,CAAC,gBAAgB,CAAA;IAChC,KAAK,MAAM,OAAO,IAAI,QAAQ,CAAC,cAAc;QAAE,OAAO,QAAQ,CAAC,OAAO,CAAC,CAAA;IACvE,IAAI,OAAO,CAAC,WAAW;QAAE,OAAO,QAAQ,CAAC,IAAI,CAAA;IAE7C,iCAAiC,CAAC,QAAQ,EAAE,QAAQ,CAAC,iBAAiB,CAAC,CAAA;IACvE,OAAO,QAAQ,CAAA;AACjB,CAAC"}