@thotischner/observability-mcp 1.8.1 → 3.0.1

package/dist/postmortem/synthesizer.d.ts

@@ -0,0 +1,83 @@
+export interface AnomalySample {
+    ts: string;
+    service: string;
+    score: number;
+    method: string;
+    severity: string;
+    signal?: string;
+}
+export interface BlastRadiusNode {
+    id: string;
+    kind: string;
+    name: string;
+    /** Whether this node is the suspected root cause (the input service). */
+    root?: boolean;
+}
+export interface TraceSummary {
+    traceId: string;
+    rootName: string;
+    rootService: string;
+    durationMs: number;
+    hasError: boolean;
+}
+export interface PostmortemInput {
+    /** Suspected root-cause service (the operator's first guess). */
+    service: string;
+    /** Rolling window the incident took place in, e.g. "2h", "6h". */
+    window: string;
+    /** Tenant the incident occurred in. */
+    tenant: string;
+    /** RFC-3339 start + end of the incident window for human display. */
+    fromIso: string;
+    toIso: string;
+    /** Live anomaly samples within the window. */
+    anomalies: AnomalySample[];
+    /** Blast-radius graph at peak. */
+    blastRadius: {
+        nodes: BlastRadiusNode[];
+        edges: Array<{
+            from: string;
+            to: string;
+            relation: string;
+        }>;
+    };
+    /** Trace summaries (top by duration). */
+    traces: TraceSummary[];
+    /** Optional log-error summary lines, e.g. ["payment-service: 412 5xx in window"]. */
+    logHighlights?: string[];
+}
+export interface PostmortemReport {
+    service: string;
+    window: string;
+    fromIso: string;
+    toIso: string;
+    /** Compact synopsis the UI puts at the top of the report. */
+    synopsis: string;
+    /** Markdown body of the full report. */
+    markdown: string;
+    /** Structured form for callers that want to render their own UI. */
+    sections: {
+        timeline: Array<{
+            ts: string;
+            service: string;
+            score: number;
+            severity: string;
+            method: string;
+        }>;
+        blastRadius: {
+            nodes: BlastRadiusNode[];
+            edgeCount: number;
+        };
+        topTraces: TraceSummary[];
+        contributingSignals: Array<{
+            signal: string;
+            count: number;
+            meanScore: number;
+        }>;
+        followUps: string[];
+        logHighlights: string[];
+    };
+}
+/** Synthesise one report from already-fetched primitives. Pure
+ *  compute — no I/O. */
+export declare function synthesizePostmortem(input: PostmortemInput): PostmortemReport;

package/dist/postmortem/synthesizer.js

@@ -0,0 +1,205 @@
+// Auto-post-mortem synthesizer — Phase F19.
+//
+// Stitches together the existing observability primitives — anomaly
+// history (F15), blast-radius (F13/topology), trace summaries (F13),
+// log-derived error patterns (existing query_logs) — into a single
+// markdown report a human (or LLM) can read in one shot.
+//
+// The synthesizer is pure-ish: it accepts the upstream queries as
+// injected functions so the tool layer can compose them without the
+// synthesizer depending on the entire ConnectorRegistry API. Tests
+// inject fake data and don't need a live demo stack.
+/** Synthesise one report from already-fetched primitives. Pure
+ *  compute — no I/O. */
+export function synthesizePostmortem(input) {
+    const timeline = [...input.anomalies]
+        .sort((a, b) => a.ts.localeCompare(b.ts))
+        .map((a) => ({ ts: a.ts, service: a.service, score: a.score, severity: a.severity, method: a.method }));
+    const contributingSignals = aggregateBySignal(input.anomalies);
+    const peakScore = input.anomalies.reduce((m, a) => Math.max(m, a.score), 0);
+    const errorTraces = input.traces.filter((t) => t.hasError).length;
+    const peakNode = input.blastRadius.nodes.find((n) => n.root) ?? input.blastRadius.nodes[0];
+    const blastSize = input.blastRadius.nodes.length;
+    const followUps = inferFollowUps(input, { peakScore, errorTraces, blastSize });
+    const synopsis = synopsisFor(input, peakScore, errorTraces, blastSize);
+    const markdown = renderMarkdown({
+        input,
+        timeline,
+        contributingSignals,
+        peakNode,
+        peakScore,
+        errorTraces,
+        blastSize,
+        followUps,
+        synopsis,
+    });
+    return {
+        service: input.service,
+        window: input.window,
+        fromIso: input.fromIso,
+        toIso: input.toIso,
+        synopsis,
+        markdown,
+        sections: {
+            timeline,
+            blastRadius: { nodes: input.blastRadius.nodes, edgeCount: input.blastRadius.edges.length },
+            topTraces: input.traces.slice(0, 10),
+            contributingSignals,
+            followUps,
+            logHighlights: input.logHighlights ?? [],
+        },
+    };
+}
+function aggregateBySignal(anomalies) {
+    const groups = new Map();
+    for (const a of anomalies) {
+        const sig = a.signal ?? a.method;
+        const prev = groups.get(sig);
+        if (prev)
+            prev.push(a.score);
+        else
+            groups.set(sig, [a.score]);
+    }
+    return [...groups.entries()]
+        .map(([signal, scores]) => ({
+        signal,
+        count: scores.length,
+        meanScore: Math.round((scores.reduce((s, x) => s + x, 0) / scores.length) * 100) / 100,
+    }))
+        .sort((a, b) => b.meanScore - a.meanScore);
+}
+function inferFollowUps(input, ctx) {
+    const out = [];
+    if (input.anomalies.length === 0) {
+        out.push("No anomaly history found for this service in the window — confirm OMCP_ANOMALY_HISTORY_REMOTE_WRITE is wired and Prometheus is scraping the same TSDB.");
+        return out;
+    }
+    if (ctx.peakScore >= 0.9) {
+        out.push(`Peak anomaly score ${ctx.peakScore} is critical — review the detector's threshold for service '${input.service}' and consider whether the chosen method (${dominantMethod(input.anomalies)}) suits this signal's distribution.`);
+    }
+    if (ctx.errorTraces > 0) {
+        out.push(`${ctx.errorTraces} trace(s) carried error spans during the window — drill into the slowest via \`query_traces(service="${input.service}", errorsOnly=true)\`.`);
+    }
+    if (ctx.blastSize > 5) {
+        out.push(`Blast radius spans ${ctx.blastSize} nodes — verify that the dependency edges are still accurate (a stale topology snapshot can blow up the radius and miss the real cause).`);
+    }
+    if ((input.logHighlights ?? []).length > 0) {
+        out.push("Log highlights above point at concrete error patterns — promote the recurring ones to an alert or SLO so the next regression catches itself.");
+    }
+    if (out.length === 0) {
+        out.push("All signals look stable for this window — consider closing the incident as a transient anomaly or expanding the time window.");
+    }
+    return out;
+}
+function dominantMethod(anomalies) {
+    const c = new Map();
+    for (const a of anomalies)
+        c.set(a.method, (c.get(a.method) ?? 0) + 1);
+    return [...c.entries()].sort((a, b) => b[1] - a[1])[0]?.[0] ?? "unknown";
+}
+function synopsisFor(input, peakScore, errorTraces, blastSize) {
+    const anomalyCount = input.anomalies.length;
+    if (anomalyCount === 0) {
+        return `No anomalies recorded for service '${input.service}' between ${input.fromIso} and ${input.toIso}. Either the window was clean, or the history sink wasn't writing at the time.`;
+    }
+    return [
+        `Service '${input.service}' produced ${anomalyCount} anomaly sample(s) between ${input.fromIso} and ${input.toIso}, peaking at ${peakScore}.`,
+        `Blast radius at peak covered ${blastSize} node(s); ${errorTraces} trace(s) carried error spans.`,
+    ].join(" ");
+}
+function renderMarkdown(ctx) {
+    const { input, timeline, contributingSignals, peakNode, peakScore, errorTraces, followUps, synopsis } = ctx;
+    const lines = [];
+    lines.push(`# Post-mortem — ${input.service}`);
+    lines.push("");
+    lines.push(`> **Window:** \`${input.fromIso}\` → \`${input.toIso}\` (\`${input.window}\`)  `);
+    lines.push(`> **Tenant:** \`${input.tenant}\`  `);
+    lines.push(`> **Generated by:** observability-mcp \`generate_postmortem\``);
+    lines.push("");
+    lines.push("## Synopsis");
+    lines.push("");
+    lines.push(synopsis);
+    lines.push("");
+    lines.push("## Anomaly timeline");
+    lines.push("");
+    if (timeline.length === 0) {
+        lines.push("_No anomaly samples in this window._");
+    }
+    else {
+        lines.push("| ts | service | score | severity | method |");
+        lines.push("|---|---|---|---|---|");
+        for (const t of timeline.slice(0, 20)) {
+            lines.push(`| \`${t.ts}\` | \`${t.service}\` | ${t.score} | ${t.severity} | ${t.method} |`);
+        }
+        if (timeline.length > 20)
+            lines.push(`| … | _${timeline.length - 20} more rows_ |  |  |  |`);
+    }
+    lines.push("");
+    lines.push("## Blast radius at peak");
+    lines.push("");
+    if (peakNode) {
+        lines.push(`Root node: **\`${peakNode.name}\`** (\`${peakNode.kind}\`).`);
+    }
+    else {
+        lines.push("_Topology snapshot empty._");
+    }
+    lines.push("");
+    if (input.blastRadius.nodes.length > 0) {
+        lines.push("| node | kind |");
+        lines.push("|---|---|");
+        for (const n of input.blastRadius.nodes.slice(0, 30)) {
+            lines.push(`| \`${n.name}\`${n.root ? " *(root)*" : ""} | \`${n.kind}\` |`);
+        }
+    }
+    lines.push("");
+    lines.push(`Edges in radius: **${input.blastRadius.edges.length}**.`);
+    lines.push("");
+    lines.push("## Contributing signals (ranked)");
+    lines.push("");
+    if (contributingSignals.length === 0) {
+        lines.push("_No anomaly samples to rank._");
+    }
+    else {
+        lines.push("| signal | samples | mean score |");
+        lines.push("|---|---|---|");
+        for (const s of contributingSignals.slice(0, 10)) {
+            lines.push(`| \`${s.signal}\` | ${s.count} | ${s.meanScore} |`);
+        }
+    }
+    lines.push("");
+    lines.push("## Related traces");
+    lines.push("");
+    if (input.traces.length === 0) {
+        lines.push("_No traces returned for the window. Configure a Tempo / Jaeger source if traces are expected._");
+    }
+    else {
+        lines.push("| trace | service | duration ms | error |");
+        lines.push("|---|---|---|---|");
+        for (const t of input.traces.slice(0, 10)) {
+            lines.push(`| \`${t.traceId}\` | \`${t.rootService}\` | ${t.durationMs} | ${t.hasError ? "yes" : "no"} |`);
+        }
+        if (errorTraces > 0)
+            lines.push(`\n_${errorTraces} of the returned traces carried error spans._`);
+    }
+    lines.push("");
+    if ((input.logHighlights ?? []).length > 0) {
+        lines.push("## Log highlights");
+        lines.push("");
+        for (const l of input.logHighlights)
+            lines.push(`- ${l}`);
+        lines.push("");
+    }
+    lines.push("## Suggested follow-ups");
+    lines.push("");
+    for (const f of followUps)
+        lines.push(`- ${f}`);
+    lines.push("");
+    lines.push("---");
+    lines.push("");
+    lines.push(`*Generated by observability-mcp \`generate_postmortem\` — see \`docs/postmortems.md\` for the prompt sources.*`);
+    lines.push("");
+    // Bound the chunk to keep memory predictable; the rendered report
+    // is normally a few KB but a pathological 10k-sample timeline
+    // could approach MB without the slice() caps above.
+    return lines.join("\n");
+}

package/dist/postmortem/synthesizer.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/postmortem/synthesizer.test.js

@@ -0,0 +1,141 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { synthesizePostmortem, } from "./synthesizer.js";
+function input(overrides = {}) {
+    return {
+        service: "payment",
+        window: "1h",
+        tenant: "default",
+        fromIso: "2026-06-06T00:00:00.000Z",
+        toIso: "2026-06-06T01:00:00.000Z",
+        anomalies: [],
+        blastRadius: { nodes: [], edges: [] },
+        traces: [],
+        ...overrides,
+    };
+}
+function anomaly(ts, score, method = "mad", severity = "warn", signal) {
+    return { ts, service: "payment", score, method, severity, signal };
+}
+test("synthesizePostmortem: empty input returns synopsis + 'no anomalies' follow-up", () => {
+    const r = synthesizePostmortem(input());
+    assert.match(r.synopsis, /No anomalies recorded/);
+    assert.equal(r.sections.timeline.length, 0);
+    assert.equal(r.sections.followUps.length, 1);
+    assert.match(r.sections.followUps[0], /OMCP_ANOMALY_HISTORY_REMOTE_WRITE/);
+});
+test("synthesizePostmortem: timeline is sorted by ts ascending", () => {
+    const r = synthesizePostmortem(input({
+        anomalies: [
+            anomaly("2026-06-06T00:30:00Z", 0.5),
+            anomaly("2026-06-06T00:10:00Z", 0.4),
+            anomaly("2026-06-06T00:50:00Z", 0.9),
+        ],
+    }));
+    assert.deepEqual(r.sections.timeline.map((t) => t.ts), ["2026-06-06T00:10:00Z", "2026-06-06T00:30:00Z", "2026-06-06T00:50:00Z"]);
+});
+test("synthesizePostmortem: contributing signals aggregated by signal label + ranked by mean score desc", () => {
+    const r = synthesizePostmortem(input({
+        anomalies: [
+            anomaly("2026-06-06T00:10Z", 0.5, "mad", "warn", "request_latency"),
+            anomaly("2026-06-06T00:20Z", 0.4, "mad", "warn", "request_latency"),
+            anomaly("2026-06-06T00:30Z", 0.95, "seasonality", "critical", "error_rate"),
+        ],
+    }));
+    const sigs = r.sections.contributingSignals;
+    assert.equal(sigs.length, 2);
+    // error_rate (0.95 mean) ranks above request_latency (0.45 mean)
+    assert.equal(sigs[0].signal, "error_rate");
+    assert.equal(sigs[0].count, 1);
+    assert.equal(sigs[0].meanScore, 0.95);
+    assert.equal(sigs[1].signal, "request_latency");
+    assert.equal(sigs[1].count, 2);
+    assert.equal(sigs[1].meanScore, 0.45);
+});
+test("synthesizePostmortem: missing signal label falls back to method", () => {
+    const r = synthesizePostmortem(input({ anomalies: [anomaly("2026-06-06T00:10Z", 0.6, "correlator")] }));
+    assert.equal(r.sections.contributingSignals[0].signal, "correlator");
+});
+test("synthesizePostmortem: critical peak triggers a follow-up mentioning the threshold", () => {
+    const r = synthesizePostmortem(input({ anomalies: [anomaly("2026-06-06T00:30Z", 0.95)] }));
+    assert.ok(r.sections.followUps.some((f) => /Peak anomaly score 0\.95/.test(f)));
+});
+test("synthesizePostmortem: errors-in-traces triggers errorsOnly drill-in suggestion", () => {
+    const r = synthesizePostmortem(input({
+        anomalies: [anomaly("2026-06-06T00:10Z", 0.6)],
+        traces: [
+            { traceId: "aaa", rootName: "GET /pay", rootService: "payment", durationMs: 800, hasError: true },
+        ],
+    }));
+    assert.ok(r.sections.followUps.some((f) => /errorsOnly=true/.test(f)));
+});
+test("synthesizePostmortem: large blast radius triggers stale-topology hint", () => {
+    const nodes = Array.from({ length: 7 }, (_, i) => ({ id: `n${i}`, kind: "pod", name: `n${i}`, root: i === 0 }));
+    const r = synthesizePostmortem(input({
+        anomalies: [anomaly("2026-06-06T00:10Z", 0.6)],
+        blastRadius: { nodes, edges: [{ from: "n0", to: "n1", relation: "CALLS" }] },
+    }));
+    assert.ok(r.sections.followUps.some((f) => /7 nodes/.test(f) && /stale topology/i.test(f)));
+});
+test("synthesizePostmortem: clean window returns a 'stable, consider closing' follow-up", () => {
+    // The "all signals stable" branch fires only when:
+    //   anomalies present (not zero)
+    //   peak < 0.9
+    //   no error traces
+    //   blast radius <= 5
+    //   no log highlights
+    const r = synthesizePostmortem(input({
+        anomalies: [anomaly("2026-06-06T00:10Z", 0.3)],
+        blastRadius: { nodes: [{ id: "n0", kind: "pod", name: "n0", root: true }], edges: [] },
+    }));
+    assert.ok(r.sections.followUps.some((f) => /stable for this window/.test(f)));
+});
+test("synthesizePostmortem: markdown contains every section header in order", () => {
+    const r = synthesizePostmortem(input({
+        anomalies: [anomaly("2026-06-06T00:10Z", 0.7)],
+        blastRadius: {
+            nodes: [{ id: "p", kind: "deployment", name: "payment", root: true }],
+            edges: [{ from: "p", to: "rds", relation: "READS_FROM" }],
+        },
+        traces: [{ traceId: "t", rootName: "GET /pay", rootService: "payment", durationMs: 200, hasError: false }],
+        logHighlights: ["payment-service: 12 5xx in window"],
+    }));
+    for (const heading of [
+        "# Post-mortem — payment",
+        "## Synopsis",
+        "## Anomaly timeline",
+        "## Blast radius at peak",
+        "## Contributing signals (ranked)",
+        "## Related traces",
+        "## Log highlights",
+        "## Suggested follow-ups",
+    ]) {
+        assert.ok(r.markdown.includes(heading), `markdown missing section: ${heading}`);
+    }
+    // The order check — anomaly timeline should appear before blast radius
+    assert.ok(r.markdown.indexOf("## Anomaly timeline") < r.markdown.indexOf("## Blast radius at peak"));
+});
+test("synthesizePostmortem: timeline > 20 rows is truncated with an ellipsis row", () => {
+    const anomalies = Array.from({ length: 25 }, (_, i) => anomaly(`2026-06-06T00:${String(i).padStart(2, "0")}:00Z`, 0.5 + i * 0.01));
+    const r = synthesizePostmortem(input({ anomalies }));
+    // The structured section has all 25
+    assert.equal(r.sections.timeline.length, 25);
+    // The markdown table is capped at 20 data rows + an ellipsis row
+    // — count rows specifically inside the Anomaly timeline section
+    // (other sections also use | ` ... | tables and would inflate a
+    // global grep).
+    const md = r.markdown;
+    const timelineStart = md.indexOf("## Anomaly timeline");
+    const blastStart = md.indexOf("## Blast radius at peak");
+    const timelineSection = md.slice(timelineStart, blastStart);
+    const tableRows = timelineSection.split("\n").filter((l) => l.startsWith("| `")).length;
+    assert.equal(tableRows, 20);
+    assert.match(timelineSection, /_5 more rows_/);
+});
+test("synthesizePostmortem: report carries the input window + iso bounds back into the structured shape", () => {
+    const r = synthesizePostmortem(input({ window: "6h" }));
+    assert.equal(r.service, "payment");
+    assert.equal(r.window, "6h");
+    assert.equal(r.fromIso, "2026-06-06T00:00:00.000Z");
+    assert.equal(r.toIso, "2026-06-06T01:00:00.000Z");
+});

package/dist/products/loader.d.ts

@@ -12,8 +12,13 @@
  *     (YAML or JSON). Missing/empty file → empty catalog.
  *   - Strict validation: unknown action / unknown resource /
  *     unexpected keys reject loudly.
- *   - Hot-reload on next /api/products call (slice 2 wires the
- *     reload trigger; for now the file is read once at boot).
+ *   - Mtime-poll hot-reload: callers (e.g. each /api/products
+ *     handler) `await store.maybeReload()` before reading. If the
+ *     file mtime advanced since the last load, the store re-parses
+ *     and atomically swaps the in-memory file; parse errors keep
+ *     the previous good state and log loudly. One `stat()` call per
+ *     reload-aware request — too cheap to matter vs. the network
+ *     round-trip, no FSWatcher platform fragility (WSL / NFS).
  */
 export interface Product {
     /** Stable identifier — used in URLs, audit entries, /api/products/{id}. */
@@ -47,7 +52,30 @@ export declare function parseProductsText(text: string, origin: string): Product
 /** In-memory store with tenant- and status-aware queries. */
 export declare class ProductsStore {
     private file;
-    constructor(file?: ProductsFile);
+    /** Optional source file path. When set, `maybeReload()` polls its
+     *  mtime and re-parses on change. Mutations via upsert/delete update
+     *  `lastMtimeMs` after the caller persists, so the store does not
+     *  reload its own writes. */
+    private path?;
+    private lastMtimeMs;
+    constructor(file?: ProductsFile, opts?: {
+        path?: string;
+        initialMtimeMs?: number;
+    });
+    /** Re-read the source file if its mtime has advanced since the last
+     *  load. No-op when no path was supplied at construction. Parse or
+     *  IO errors are logged and the previous good state is kept — the
+     *  invariant is "the store always reflects a valid catalogue", so a
+     *  broken edit on disk never takes the running server down. */
+    maybeReload(): Promise<{
+        reloaded: boolean;
+    }>;
+    /** Re-stat the source file and pin the mtime cursor to its current
+     *  value. Call this after a successful write so the store does not
+     *  treat its own change as an external reload trigger. Best-effort:
+     *  if the stat fails, the next maybeReload() will simply reload the
+     *  file once and find it identical. */
+    pinMtimeAfterWrite(): Promise<void>;
     /** Return the product list. When `tenant` is set, filters to that
      *  tenant (entries without a tenant field treated as "default").
      *  When `includeStaging` is false (default), staging products are

package/dist/products/loader.js

@@ -12,10 +12,15 @@
  *     (YAML or JSON). Missing/empty file → empty catalog.
  *   - Strict validation: unknown action / unknown resource /
  *     unexpected keys reject loudly.
- *   - Hot-reload on next /api/products call (slice 2 wires the
- *     reload trigger; for now the file is read once at boot).
+ *   - Mtime-poll hot-reload: callers (e.g. each /api/products
+ *     handler) `await store.maybeReload()` before reading. If the
+ *     file mtime advanced since the last load, the store re-parses
+ *     and atomically swaps the in-memory file; parse errors keep
+ *     the previous good state and log loudly. One `stat()` call per
+ *     reload-aware request — too cheap to matter vs. the network
+ *     round-trip, no FSWatcher platform fragility (WSL / NFS).
  */
-import { readFile, writeFile, rename } from "node:fs/promises";
+import { readFile, writeFile, rename, stat } from "node:fs/promises";
 import yaml from "js-yaml";
 const EMPTY = { products: [] };
 const VALID_STATUS = new Set(["published", "staging"]);
@@ -134,8 +139,76 @@ export function parseProductsText(text, origin) {
 /** In-memory store with tenant- and status-aware queries. */
 export class ProductsStore {
     file;
-    constructor(file = EMPTY) {
+    /** Optional source file path. When set, `maybeReload()` polls its
+     *  mtime and re-parses on change. Mutations via upsert/delete update
+     *  `lastMtimeMs` after the caller persists, so the store does not
+     *  reload its own writes. */
+    path;
+    lastMtimeMs = 0;
+    constructor(file = EMPTY, opts = {}) {
         this.file = file;
+        this.path = opts.path;
+        this.lastMtimeMs = opts.initialMtimeMs ?? 0;
+    }
+    /** Re-read the source file if its mtime has advanced since the last
+     *  load. No-op when no path was supplied at construction. Parse or
+     *  IO errors are logged and the previous good state is kept — the
+     *  invariant is "the store always reflects a valid catalogue", so a
+     *  broken edit on disk never takes the running server down. */
+    async maybeReload() {
+        if (!this.path)
+            return { reloaded: false };
+        let mtimeMs;
+        try {
+            const s = await stat(this.path);
+            mtimeMs = s.mtimeMs;
+        }
+        catch (e) {
+            const code = e.code;
+            // File gone (ENOENT) — keep last good state. Re-creating the
+            // file will land in this branch's else on the next call when
+            // stat succeeds again with a fresh mtime.
+            if (code !== "ENOENT") {
+                console.warn(`[products] hot-reload stat(${this.path}) failed: ${e.message} — keeping previous catalogue`);
+            }
+            return { reloaded: false };
+        }
+        if (mtimeMs <= this.lastMtimeMs)
+            return { reloaded: false };
+        let next;
+        try {
+            next = await readProductsFile(this.path);
+        }
+        catch (e) {
+            // readProductsFile downgrades IO errors to EMPTY but lets
+            // parse errors (ProductsLoadError) propagate — so a broken
+            // YAML edit lands here, and we explicitly do NOT swap state.
+            console.warn(`[products] hot-reload of ${this.path} failed: ${e.message} — keeping previous catalogue`);
+            // Bump the mtime cursor anyway so we don't re-log the same
+            // failure on every subsequent request until the operator fixes
+            // the file (next save advances mtime past this value).
+            this.lastMtimeMs = mtimeMs;
+            return { reloaded: false };
+        }
+        this.file = next;
+        this.lastMtimeMs = mtimeMs;
+        return { reloaded: true };
+    }
+    /** Re-stat the source file and pin the mtime cursor to its current
+     *  value. Call this after a successful write so the store does not
+     *  treat its own change as an external reload trigger. Best-effort:
+     *  if the stat fails, the next maybeReload() will simply reload the
+     *  file once and find it identical. */
+    async pinMtimeAfterWrite() {
+        if (!this.path)
+            return;
+        try {
+            const s = await stat(this.path);
+            this.lastMtimeMs = s.mtimeMs;
+        }
+        catch {
+            // Silent — see method JSDoc.
+        }
     }
     /** Return the product list. When `tenant` is set, filters to that
      *  tenant (entries without a tenant field treated as "default").

package/dist/products/loader.test.js

@@ -1,6 +1,6 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
-import { parseProductsText, ProductsStore, ProductsLoadError } from "./loader.js";
+import { parseProductsText, ProductsStore, ProductsLoadError, readProductsFile } from "./loader.js";
 test("parseProductsText — empty/minimal products array", () => {
     const f = parseProductsText("products: []", "test");
     assert.deepEqual(f.products, []);
@@ -166,3 +166,92 @@ test("ProductsLoadError is the throw class", () => {
     }
     assert.fail("expected throw");
 });
+test("ProductsStore.maybeReload — picks up out-of-band edits on next call", async () => {
+    const { mkdtemp, rm, writeFile, utimes } = await import("node:fs/promises");
+    const { tmpdir } = await import("node:os");
+    const { join } = await import("node:path");
+    const dir = await mkdtemp(join(tmpdir(), "omcp-products-reload-"));
+    try {
+        const file = join(dir, "products.yaml");
+        await writeFile(file, "products:\n  - id: a\n    name: A\n", "utf8");
+        const initial = await readProductsFile(file);
+        const store = new ProductsStore(initial, { path: file });
+        await store.pinMtimeAfterWrite();
+        assert.equal(store.list().length, 1);
+        assert.equal(store.list()[0].id, "a");
+        // Simulate an out-of-band edit. Bump mtime explicitly because
+        // some filesystems (WSL → 9P) round mtime to the second, so a
+        // back-to-back write can land in the same second and look
+        // unchanged to stat().
+        await writeFile(file, "products:\n  - id: a\n    name: A\n  - id: b\n    name: B\n", "utf8");
+        const future = new Date(Date.now() + 5_000);
+        await utimes(file, future, future);
+        const { reloaded } = await store.maybeReload();
+        assert.equal(reloaded, true);
+        assert.equal(store.list().length, 2);
+        // A second call with no further edit is a no-op.
+        const r2 = await store.maybeReload();
+        assert.equal(r2.reloaded, false);
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+});
+test("ProductsStore.maybeReload — broken YAML on disk keeps previous good state", async () => {
+    const { mkdtemp, rm, writeFile, utimes } = await import("node:fs/promises");
+    const { tmpdir } = await import("node:os");
+    const { join } = await import("node:path");
+    const dir = await mkdtemp(join(tmpdir(), "omcp-products-broken-"));
+    try {
+        const file = join(dir, "products.yaml");
+        await writeFile(file, "products:\n  - id: a\n    name: A\n", "utf8");
+        const store = new ProductsStore(await readProductsFile(file), { path: file });
+        await store.pinMtimeAfterWrite();
+        // Corrupt the file with an unknown top-level key — fails the
+        // strict typo guard inside parseProductsText.
+        await writeFile(file, "products:\n  - id: a\n    name: A\n    junk: true\n", "utf8");
+        const future = new Date(Date.now() + 5_000);
+        await utimes(file, future, future);
+        const { reloaded } = await store.maybeReload();
+        // We did NOT swap state — caller sees the previous good catalogue.
+        assert.equal(reloaded, false);
+        assert.equal(store.list().length, 1);
+        assert.equal(store.list()[0].name, "A");
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+});
+test("ProductsStore.maybeReload — no path = no-op", async () => {
+    const store = new ProductsStore({ products: [{ id: "a", name: "A" }] });
+    const r = await store.maybeReload();
+    assert.equal(r.reloaded, false);
+    assert.equal(store.list().length, 1);
+});
+test("ProductsStore.pinMtimeAfterWrite — own writes do not trigger a redundant reload", async () => {
+    const { mkdtemp, rm, writeFile, utimes } = await import("node:fs/promises");
+    const { tmpdir } = await import("node:os");
+    const { join } = await import("node:path");
+    const { writeProductsFile } = await import("./loader.js");
+    const dir = await mkdtemp(join(tmpdir(), "omcp-products-pin-"));
+    try {
+        const file = join(dir, "products.yaml");
+        await writeFile(file, "products:\n  - id: a\n    name: A\n", "utf8");
+        const store = new ProductsStore(await readProductsFile(file), { path: file });
+        await store.pinMtimeAfterWrite();
+        // Simulate the server-side mutate-then-persist path.
+        store.upsert({ id: "b", name: "B" });
+        // Move mtime forward so writeProductsFile genuinely advances it
+        // past our cursor (1-second-resolution FS guard).
+        const future = new Date(Date.now() + 5_000);
+        await writeProductsFile(file, store.snapshot());
+        await utimes(file, future, future);
+        await store.pinMtimeAfterWrite();
+        const { reloaded } = await store.maybeReload();
+        assert.equal(reloaded, false, "own write must not re-trigger maybeReload");
+        assert.equal(store.list().length, 2);
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+});