@ksp-gonogo/sitrep-sdk 0.0.1 → 0.2.0-rc.12

package/dist/flight/BufferedDataSource.js

@@ -0,0 +1,790 @@
+import { PerfBudget } from "../perf/PerfBudget.js";
+import { DataSourceWrapper } from "./DataSourceWrapper.js";
+import { debugFlight } from "./debugFlight.js";
+import { getDerivedKeys } from "./derive.js";
+import { exportFlightToFixture } from "./fixtureIO.js";
+import { getKeepCount } from "./flightAutoDelete.js";
+import { FlightDetector } from "./flightDetector.js";
+import { KeyedListenerSet, ListenerSet } from "./ListenerSet.js";
+/**
+ * Soft cap on samples flowing into the buffered layer. A polling telemetry
+ * source runs at 4 Hz across ~170 keys (worst-case 680/sec when every key
+ * changes each tick), plus a handful of derived keys and a brief replay burst
+ * on subscribe. A mid-flight refresh routinely comes close to 1500, so the cap
+ * sits at 3000: still tight enough to catch a true regression (duplicated
+ * samples, a runaway WS rate) without false-alarming on normal load.
+ */
+const BUFFERED_SAMPLE_BUDGET = new PerfBudget({
+    name: "BufferedDataSource samples in/sec",
+    threshold: 3000,
+    windowMs: 1000,
+    unit: "samples",
+});
+function hasExecuteScript(source) {
+    return (!!source &&
+        typeof source.executeScript === "function");
+}
+/**
+ * Match a recovery/crash event to a FlightRecord by vessel name, prefer
+ * the most-recent (highest `launchedAt`). KSP may auto-name vessels with
+ * collisions so we don't trust the first match, we scan and pick the
+ * latest. Returns null if no flight in the list bears the given name.
+ */
+function pickMostRecentFlightByName(flights, vesselName) {
+    let best = null;
+    for (const f of flights) {
+        if (f.vesselName !== vesselName)
+            continue;
+        if (!best || f.launchedAt > best.launchedAt)
+            best = f;
+    }
+    return best;
+}
+function parseCrewNames(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const entries = raw;
+    const names = [];
+    for (const entry of entries) {
+        if (entry && typeof entry === "object" && !Array.isArray(entry)) {
+            const e = entry;
+            if (typeof e.name === "string")
+                names.push(e.name);
+        }
+    }
+    return names;
+}
+function parseStringArray(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    return raw.filter((x) => typeof x === "string");
+}
+const KEY_AS_LABEL = (key) => ({ label: key, group: "Other" });
+/**
+ * Wraps a live {@link DataSource}, saves every sample into a {@link FlightStore}
+ * under the flight it belongs to, and offers both live subscriptions and range
+ * queries over what it has saved.
+ *
+ * A subscription fires on new samples only, not on subscribing; read history
+ * with `queryRange`. After a reload it picks up the flights it saved, rather
+ * than starting them again.
+ *
+ * @category Flight recording
+ */
+export class BufferedDataSource extends DataSourceWrapper {
+    store;
+    detector = new FlightDetector();
+    inMemoryLimit;
+    now;
+    enrichKey;
+    latestName = null;
+    /** Latest known sample (t + v) per raw key, used by the derivation engine. */
+    lastRawSample = new Map();
+    /** Last inputs array passed to each derived fn, for the `previous` argument. */
+    derivedPrevious = new Map();
+    /**
+     * Last emitted value per key (raw + derived). Replayed synchronously on
+     * `subscribe()` so late subscribers (e.g. widgets that mount after the
+     * upstream WS push has already landed) see the current reading instead of
+     * waiting for the next sample.
+     */
+    lastEmittedValue = new Map();
+    buffers = new Map();
+    keySubscribers = new KeyedListenerSet();
+    statusSubscribers = new ListenerSet();
+    flightSubscribers = new ListenerSet();
+    // Fires on every list-shape mutation (add via detection, delete, clear,
+    // star toggle, prune, chapter add/update/remove). FlightsManager subscribes
+    // to it to auto-refresh, and the peer host re-broadcasts so a mutation
+    // initiated on a station bubbles back to the main screen's open modal.
+    flightListSubscribers = new ListenerSet();
+    upstreamUnsubs = [];
+    upstreamStatusUnsub = null;
+    lastEmittedCurrent = null;
+    /**
+     * Keys we've subscribed to upstream because of `connect()`, i.e. every
+     * key the wrapped source advertises in `schema()`. Tracked so demand
+     * subscribes can skip them.
+     */
+    upfrontKeys = new Set();
+    /**
+     * Schema entries from feeders other than the wrapped source (e.g. a
+     * centralised compute fanout). Surfaced through `schema()` so the picker shows them and
+     * exports include them. Populated via `registerExternalKeys`.
+     */
+    externalSchema = new Map();
+    /**
+     * Indexed/dynamic keys (e.g. `b.name[1]`) aren't in the upstream
+     * schema, so they don't get subscribed at connect-time. When a widget
+     * calls subscribe() for one of these, we forward the subscribe to the
+     * upstream and ref-count callers so we can tear it down once the last
+     * widget leaves. Without this the upstream WS never carries the key
+     * and the widget waits forever.
+     */
+    demandSubs = new Map();
+    /**
+     * Trust gate state. Tracks TWO independent signals, telemetry is
+     * trusted only when BOTH are good:
+     *
+     * 1. **The telemetry antenna** via `p.paused`. `0` = active + powered;
+     *    `1` = game paused (frozen values still real). Anything else
+     *    (2/3/4/5) means the antenna is gone / unpowered / off and
+     *    vessel-required keys collapse to the literal value `2`,
+     *    verified live 2026-05-18.
+     * 2. **Vanilla CommNet** via `comm.connected`. Mission-control
+     *    link; independent of the telemetry antenna. Widgets that drive
+     *    the vessel need this too, even with a live telemetry link: no
+     *    CommNet means the operator shouldn't be acting on the data.
+     *
+     * Each signal has its own "ever confirmed good?" guard so cold-start
+     * `false` / non-zero values don't freeze widgets the moment a station
+     * connects. The combined gate activates when EITHER signal has been
+     * confirmed good and is now bad.
+     *
+     * Defaults are `true` so sources that aren't signal-affected aren't held
+     * back, and so a wrapped source that hasn't reported either key yet
+     * doesn't freeze every widget on cold-start.
+     */
+    commGate = true;
+    hasConfirmedComm = false;
+    pPausedGate = true;
+    hasConfirmedPPaused = false;
+    // Idempotence keys for outcome annotation. The upstream
+    // recovery.lastSummary / crash.lastCrash are sticky, they emit the same
+    // payload on every WS tick until a fresh capture replaces them. Track
+    // the snapshot's capture-time so we only annotate the FlightRecord
+    // when a genuinely new outcome arrives.
+    lastAppliedRecoveryAtUT = null;
+    lastAppliedCrashAtUT = null;
+    constructor(opts) {
+        super(opts.source, {
+            id: opts.id ?? "data",
+            name: opts.name ?? `Buffered ${opts.source.name}`,
+        });
+        this.store = opts.store;
+        this.inMemoryLimit = opts.inMemoryLimit ?? 500;
+        this.now = opts.now ?? Date.now;
+        this.enrichKey = opts.enrichKey ?? KEY_AS_LABEL;
+    }
+    /** Alias for `this.real` for readability inside this wrapper. */
+    get source() {
+        return this.real;
+    }
+    /**
+     * Sets up the wrapper's subscriptions to the wrapped source. Does NOT
+     * call `source.connect()`: the wrapped source's connection lifecycle
+     * belongs to whoever registered it. Typically both sources are
+     * registered independently and the caller's "connect all registered
+     * sources" loop connects each exactly once.
+     */
+    async connect() {
+        // Hydrate detector with any flights that already exist in the store so we resume rather than duplicate across reloads.
+        const known = await this.store.listFlights();
+        this.detector.hydrate(known);
+        // Honour the user's auto-delete preference at startup. Silent, the
+        // pref opts the user in to this behaviour; surfacing a toast each time
+        // would become noise.
+        const keepCount = getKeepCount();
+        if (keepCount > 0) {
+            await this.pruneFlightsKeepLatest({ keepCount });
+        }
+        // Subscribe to every key the upstream exposes. We don't filter, the
+        // graph widget may want any of them. The upstream schema is static so
+        // this is a fixed cost at connect time. Indexed keys (e.g.
+        // `b.name[1]`) live outside the schema; they're picked up via demand
+        // subscribes from `subscribe()` below.
+        for (const { key } of this.source.schema()) {
+            this.upfrontKeys.add(key);
+            const unsub = this.source.subscribe(key, (value) => {
+                this.handleSample(key, value);
+            });
+            this.upstreamUnsubs.push(unsub);
+        }
+        this.upstreamStatusUnsub = this.source.onStatusChange((status) => {
+            this.statusSubscribers.fire(status);
+        });
+    }
+    /**
+     * Tears down the wrapper's subscriptions. The wrapped source is NOT
+     * disconnected here: same reasoning as `connect`.
+     */
+    disconnect() {
+        for (const u of this.upstreamUnsubs)
+            u();
+        this.upstreamUnsubs = [];
+        for (const d of this.demandSubs.values())
+            d.unsub();
+        this.demandSubs.clear();
+        this.upfrontKeys.clear();
+        this.upstreamStatusUnsub?.();
+        this.upstreamStatusUnsub = null;
+    }
+    schema() {
+        const raw = this.source.schema().map((dk) => ({
+            ...dk,
+            ...this.enrichKey(dk.key),
+        }));
+        const derived = getDerivedKeys().map((def) => ({
+            key: def.id,
+            ...def.meta,
+        }));
+        const external = [...this.externalSchema.values()];
+        return [...raw, ...derived, ...external];
+    }
+    subscribe(key, cb) {
+        const removeLocal = this.keySubscribers.add(key, cb);
+        // For keys NOT covered by the upfront schema sub (indexed keys like
+        // `b.name[1]`), demand-subscribe upstream so values actually flow.
+        // Reference-counted so multiple widgets share a single upstream sub.
+        //
+        // Schema-aware guard: a key that's part of the upstream's static
+        // schema will be subscribed by `connect()` regardless of whether
+        // that has happened yet. If a subscriber arrives BEFORE `connect`
+        // (e.g. PeerBroadcastingDataSource wraps us at module load and
+        // subscribes to every schema key in its constructor), we must NOT
+        // also create a demand-sub here: when `connect` runs, both the
+        // demand-sub AND the upfront-sub would deliver each upstream sample,
+        // doubling every fanout. The check against `source.schema()` covers
+        // the pre-connect window; `upfrontKeys.has(key)` covers post-connect.
+        const isSchemaKey = this.upfrontKeys.has(key) ||
+            this.source.schema().some((k) => k.key === key);
+        if (!isSchemaKey) {
+            const existing = this.demandSubs.get(key);
+            if (existing) {
+                existing.count += 1;
+            }
+            else {
+                const unsub = this.source.subscribe(key, (value) => {
+                    this.handleSample(key, value);
+                });
+                this.demandSubs.set(key, { count: 1, unsub });
+            }
+        }
+        // Replay the last-known value so late subscribers aren't stuck on `undefined` until the next sample arrives.
+        if (this.lastEmittedValue.has(key)) {
+            cb(this.lastEmittedValue.get(key));
+        }
+        return () => {
+            removeLocal();
+            const demand = this.demandSubs.get(key);
+            if (demand) {
+                demand.count -= 1;
+                if (demand.count <= 0) {
+                    demand.unsub();
+                    this.demandSubs.delete(key);
+                }
+            }
+        };
+    }
+    onStatusChange(cb) {
+        return this.statusSubscribers.add(cb);
+    }
+    // Conditional getter so `hasExecuteScript(buffered)` reflects whether the wrapped source actually supports executeScript, matching the PeerBroadcastingDataSource pattern.
+    get executeScript() {
+        if (!hasExecuteScript(this.source))
+            return undefined;
+        return this.source.executeScript.bind(this.source);
+    }
+    /**
+     * Columnar range query. Always hits the store, so pending writes are
+     * flushed first. Defaults `flightId` to the current flight when omitted.
+     */
+    async queryRange(key, tStart, tEnd, flightId) {
+        const id = flightId ?? this.detector.getCurrent()?.id;
+        if (!id)
+            return { t: [], v: [] };
+        return this.store.queryRange(id, key, tStart, tEnd);
+    }
+    /**
+     * Latest single emitted value for a key, or undefined if none seen yet.
+     * Synchronous: used where widgets need a snapshot without subscribing
+     * (e.g. resolving telemetry args at script dispatch time).
+     */
+    getLatestValue(key) {
+        return this.lastEmittedValue.get(key);
+    }
+    /**
+     * Latest N samples for a key from the in-memory ring buffer. Synchronous,
+     * useful for the graph widget's first paint before any async query
+     * completes. May return fewer samples than requested, including zero.
+     */
+    getLatest(key, n = this.inMemoryLimit) {
+        const buf = this.buffers.get(key);
+        if (!buf || buf.length === 0)
+            return { t: [], v: [] };
+        const start = Math.max(0, buf.length - n);
+        const slice = buf.slice(start);
+        return {
+            t: slice.map((r) => r.t),
+            v: slice.map((r) => r.v),
+        };
+    }
+    /**
+     * Subscribe to a fixed set of keys and receive a single callback with an
+     * array of all current values whenever any of them changes. Keeps the
+     * coalescing and relabelling inside the data layer, consumers treat a
+     * group of related keys (e.g. per-stage fuel masses) as one value with
+     * one hook call.
+     *
+     * `values[i]` is `undefined` until `keys[i]` has emitted at least once.
+     * On subscribe, the last-known value for each key is replayed via
+     * `subscribe()`, so the callback typically fires once per already-seen
+     * key during setup and then once per change afterwards.
+     */
+    subscribeCollection(keys, cb) {
+        const snapshot = new Array(keys.length).fill(undefined);
+        const unsubs = [];
+        keys.forEach((key, i) => {
+            unsubs.push(this.subscribe(key, (value) => {
+                snapshot[i] = value;
+                cb(snapshot.slice());
+            }));
+        });
+        return () => {
+            unsubs.forEach((u) => {
+                u();
+            });
+        };
+    }
+    // ── External-source ingestion ────────────────────────────────────────────
+    //
+    // The wrapped source drives FlightDetector + signal-loss gating and is the
+    // canonical sample feed. But we also want samples from other feeders (a
+    // centralised compute fanout, say) to land in the same flight record so they
+    // replay alongside it. These methods are the public seam for that: they
+    // bypass the gate + detector but feed the store + buffer + subscriber fanout
+    // exactly like a sample from the wrapped source.
+    //
+    // Keys must be globally unique across all feeders. A feeder that namespaces
+    // its keys under its own prefix cannot collide by construction.
+    /**
+     * Schema entries from other feeders, surfaced through `schema()` so the
+     * data picker shows them and `exportFlight` captures their samples.
+     * Caller (typically the app shell, after wiring that feeder) calls this
+     * once per known schema; calling again for the same key replaces.
+     */
+    registerExternalKeys(keys) {
+        for (const k of keys)
+            this.externalSchema.set(k.key, k);
+    }
+    /**
+     * Append a sample from another feeder. Same fanout chain as samples from
+     * the wrapped source (store, in-memory buffer, live subscribers,
+     * derived keys), minus the FlightDetector tick (driven by `v.missionTime`
+     * exclusively) and the signal-loss gate (a feeder running aboard the vessel
+     * isn't comm-affected).
+     *
+     * If no flight is established yet (the wrapped source's warmup hasn't
+     * completed), the sample is fanned out live but NOT persisted, same shape
+     * as pre-flight samples from the wrapped source.
+     */
+    appendExternalSample(key, value) {
+        const t = this.now();
+        this.lastRawSample.set(key, { t, v: value });
+        const current = this.detector.getCurrent();
+        if (current) {
+            void this.store.appendSample(current.id, key, t, value);
+            this.pushToBuffer(key, t, value);
+        }
+        this.lastEmittedValue.set(key, value);
+        this.keySubscribers.fire(key, value);
+        // Derived keys can opt in by listing an external key as one of their inputs: same machinery as derivations driven by the wrapped source.
+        this.runDerivedKeys(key, current?.id ?? null);
+    }
+    onFlightChange(cb) {
+        return this.flightSubscribers.add(cb);
+    }
+    /**
+     * Fires whenever the persisted flight list could have changed shape,
+     * a flight is added, deleted, starred, pruned, or its chapters changed.
+     * Sample-driven updates to the *current* flight are not signalled here;
+     * those go through `onFlightChange`.
+     */
+    onFlightListChange(cb) {
+        return this.flightListSubscribers.add(cb);
+    }
+    listFlights() {
+        return this.store.listFlights();
+    }
+    getFlight(id) {
+        return this.store.getFlight(id);
+    }
+    /**
+     * Export a recorded flight as a portable `FlightFixture`, every sample
+     * across every schema-known key, packaged with the flight metadata.
+     * Suitable for `JSON.stringify()` and round-tripping through the replay
+     * pipeline (or out to a `.json` file on disk). Persisted chapters on
+     * the FlightRecord are carried into the fixture's `chapters` array.
+     */
+    async exportFlight(id) {
+        const schema = this.schema();
+        const fixture = await exportFlightToFixture(this.store, id, {
+            keys: schema.map((k) => k.key),
+            schema,
+        });
+        if (!fixture.flight.chapters || fixture.flight.chapters.length === 0) {
+            return fixture;
+        }
+        return { ...fixture, chapters: fixture.flight.chapters };
+    }
+    // ── Chapters (markers on a recorded flight) ──────────────────────────────
+    /**
+     * Add a new chapter to the flight and persist. Returns the upserted
+     * FlightRecord so callers can refresh their view immediately.
+     */
+    async addChapter(flightId, chapter) {
+        const flight = await this.store.getFlight(flightId);
+        if (!flight)
+            return null;
+        const id = chapter.id ??
+            (typeof crypto !== "undefined" && crypto.randomUUID
+                ? crypto.randomUUID()
+                : `ch-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
+        const next = {
+            id,
+            label: chapter.label,
+            startMs: chapter.startMs,
+            endMs: chapter.endMs,
+        };
+        const updated = {
+            ...flight,
+            chapters: [...(flight.chapters ?? []), next],
+        };
+        await this.store.upsertFlight(updated);
+        if (this.detector.getCurrent()?.id === flightId)
+            this.emitFlightChange();
+        this.flightListSubscribers.fire();
+        return updated;
+    }
+    async updateChapter(flightId, chapterId, patch) {
+        const flight = await this.store.getFlight(flightId);
+        if (!flight)
+            return null;
+        const chapters = (flight.chapters ?? []).map((c) => c.id === chapterId ? { ...c, ...patch } : c);
+        const updated = { ...flight, chapters };
+        await this.store.upsertFlight(updated);
+        if (this.detector.getCurrent()?.id === flightId)
+            this.emitFlightChange();
+        this.flightListSubscribers.fire();
+        return updated;
+    }
+    async removeChapter(flightId, chapterId) {
+        const flight = await this.store.getFlight(flightId);
+        if (!flight)
+            return null;
+        const chapters = (flight.chapters ?? []).filter((c) => c.id !== chapterId);
+        const updated = { ...flight, chapters };
+        await this.store.upsertFlight(updated);
+        if (this.detector.getCurrent()?.id === flightId)
+            this.emitFlightChange();
+        this.flightListSubscribers.fire();
+        return updated;
+    }
+    getCurrentFlight() {
+        return this.detector.getCurrent();
+    }
+    async deleteFlight(id) {
+        const wasCurrent = this.detector.getCurrent()?.id === id;
+        this.detector.forget(id);
+        await this.store.deleteFlight(id);
+        if (wasCurrent)
+            this.emitFlightChange();
+        this.flightListSubscribers.fire();
+    }
+    /**
+     * Pin a flight so it's exempt from the auto-delete cleanup. Per-row delete
+     * and "Clear all" still remove starred flights, this only protects against
+     * the silent age-based prune.
+     */
+    async setFlightStarred(id, starred) {
+        const flight = await this.store.getFlight(id);
+        if (!flight)
+            return;
+        if (Boolean(flight.starred) === starred)
+            return;
+        const updated = { ...flight, starred };
+        await this.store.upsertFlight(updated);
+        if (this.detector.getCurrent()?.id === id)
+            this.emitFlightChange();
+        this.flightListSubscribers.fire();
+    }
+    /**
+     * Keep the `keepCount` most recently launched flights (by `launchedAt`),
+     * deleting the rest. Starred flights and the current flight are exempt:
+     * they are never evicted and they don't count toward the cap. Returns the
+     * ids that were actually removed.
+     */
+    async pruneFlightsKeepLatest(opts) {
+        if (opts.keepCount <= 0)
+            return [];
+        const all = await this.store.listFlights();
+        const sorted = [...all].sort((a, b) => b.launchedAt - a.launchedAt);
+        const currentId = this.detector.getCurrent()?.id ?? null;
+        const victims = [];
+        let kept = 0;
+        for (const f of sorted) {
+            if (f.starred || f.id === currentId)
+                continue;
+            kept += 1;
+            if (kept > opts.keepCount)
+                victims.push(f);
+        }
+        for (const f of victims) {
+            await this.deleteFlight(f.id);
+        }
+        return victims.map((f) => f.id);
+    }
+    async clearAllFlights() {
+        this.detector.forgetAll();
+        await this.store.clearAllFlights();
+        this.buffers.clear();
+        this.lastRawSample.clear();
+        this.derivedPrevious.clear();
+        this.lastEmittedValue.clear();
+        this.emitFlightChange();
+        this.flightListSubscribers.fire();
+    }
+    handleSample(key, value) {
+        BUFFERED_SAMPLE_BUDGET.record();
+        // Trust-gate trackers: BOTH `comm.connected` (vanilla CommNet) and
+        // `p.paused` (the telemetry antenna) must be good for the source to
+        // be trusted. Cold-start guards on each: only a confirmed-good
+        // then bad transition activates that signal's half of the gate.
+        if (key === "comm.connected") {
+            if (value === true) {
+                this.commGate = true;
+                this.hasConfirmedComm = true;
+            }
+            if (value === false && this.hasConfirmedComm) {
+                this.commGate = false;
+            }
+        }
+        if (key === "p.paused") {
+            if (value === 0 || value === 1) {
+                this.pPausedGate = true;
+                this.hasConfirmedPPaused = true;
+            }
+            if (typeof value === "number" &&
+                this.hasConfirmedPPaused &&
+                value !== 0 &&
+                value !== 1) {
+                this.pPausedGate = false;
+            }
+        }
+        // Antenna-down gate. When the wrapped source is
+        // signal-affected and we've confirmed a prior live
+        // link that has since dropped, drop ONLY the specific keys that
+        // collapse to the literal value `2` in this state. Everything
+        // else stays: tracking-station-observable (vessel position +
+        // basic orbital elements + resource quantities + crew + atmosphere
+        // readings) and KSC-global state remain trustworthy whether or
+        // not the telemetry antenna is up.
+        //
+        // Rather than try to enumerate the honest set (a moving target), we enumerate the broken set.
+        //
+        // Special-cases handled outside the blocklist:
+        //  - `p.paused` itself: returns the literal `2` here (it IS the
+        //    "no power" status code), but must always flow so we can
+        //    detect the gate-lift event. Excluded from the blocklist.
+        //  - `comm.controlState`: returns `2` here but legitimately:
+        //    `2` means "full control" in the vanilla CommNet enum and
+        //    CommNet is independent of the telemetry antenna. Flows.
+        const isAntennaOnlyKey = key.startsWith("land.") ||
+            key.startsWith("therm.") ||
+            (key.startsWith("v.") && key.endsWith("Value")) ||
+            key === "f.throttle" ||
+            key === "v.currentStage" ||
+            key === "dv.stageCount";
+        const signalConnected = this.commGate && this.pPausedGate;
+        const hasConfirmedConnection = this.hasConfirmedComm || this.hasConfirmedPPaused;
+        if (this.source.affectedBySignalLoss &&
+            hasConfirmedConnection &&
+            !signalConnected &&
+            isAntennaOnlyKey) {
+            return;
+        }
+        // Cache the identity inputs regardless: the detector needs both, and they
+        // may arrive in separate callbacks within the same WS message. Only the
+        // name is cached, since `v.missionTime` drives the detector directly.
+        if (key === "v.name" && typeof value === "string") {
+            this.latestName = value;
+        }
+        // Recovery / crash snapshots from the GonogoTelemetry plugin,
+        // annotate the matching flight record with the final outcome. Idempotent
+        // per snapshot ut (the snapshots are sticky upstream; we
+        // don't want to overwrite an outcome with the same outcome every tick).
+        if (key === "recovery.lastSummary" && value && typeof value === "object") {
+            this.applyRecoveryOutcome(value);
+        }
+        if (key === "crash.lastCrash" && value && typeof value === "object") {
+            this.applyCrashOutcome(value);
+        }
+        const t = this.now();
+        // Track latest raw sample for the derivation engine.
+        this.lastRawSample.set(key, { t, v: value });
+        // Run the detector off v.missionTime as the driver. It ticks every frame
+        // with a numeric value, and by the time it arrives in a given WS message
+        // v.name has already been processed.
+        if (key === "v.missionTime" &&
+            this.latestName !== null &&
+            typeof value === "number") {
+            const before = this.detector.getCurrent();
+            const decision = this.detector.observe({
+                vesselName: this.latestName,
+                missionTime: value,
+                now: t,
+            });
+            void this.store.upsertFlight(decision.flight);
+            if (!before || before.id !== decision.flight.id) {
+                this.emitFlightChange();
+            }
+            // Newly minted flight grows the persisted list; let any open
+            // FlightsManager refresh without waiting for a manual reload.
+            // Resumes and appends don't change shape (the record was already
+            // there or was already current).
+            if (decision.kind === "new") {
+                this.flightListSubscribers.fire();
+            }
+        }
+        const current = this.detector.getCurrent();
+        // Append to store + in-memory buffer only if we've identified a flight.
+        // Samples arriving before v.name/v.missionTime have landed are dropped,
+        // a short warmup on first connect.
+        if (current) {
+            void this.store.appendSample(current.id, key, t, value);
+            this.pushToBuffer(key, t, value);
+        }
+        else {
+            debugFlight("drop-pre-flight", { key });
+        }
+        // Fan out to live subscribers regardless of whether we have a flight, so they get live values during warmup.
+        this.lastEmittedValue.set(key, value);
+        this.keySubscribers.fire(key, value);
+        // Run derived keys that depend on this raw key.
+        this.runDerivedKeys(key, current?.id ?? null);
+    }
+    /**
+     * Annotate the FlightRecord matching the recovered vessel with a
+     * recovery outcome. Matches by `vesselName` against listFlights ordered
+     * by most-recent: the recovered vessel is almost always the most
+     * recent flight, but if names collide (rare; KSP auto-assigns names),
+     * the most-recent match wins.
+     *
+     * Idempotent per `capturedAtUT`: a sticky `recovery.lastSummary`
+     * snapshot keeps emitting until replaced, but the FlightRecord is
+     * only updated once per snapshot.
+     */
+    applyRecoveryOutcome(payload) {
+        const capturedAt = typeof payload.capturedAtUT === "number" ? payload.capturedAtUT : 0;
+        if (capturedAt === this.lastAppliedRecoveryAtUT)
+            return;
+        const vesselName = typeof payload.vesselName === "string" ? payload.vesselName : "";
+        if (!vesselName)
+            return;
+        this.lastAppliedRecoveryAtUT = capturedAt;
+        void this.store.listFlights().then((flights) => {
+            const match = pickMostRecentFlightByName(flights, vesselName);
+            if (!match)
+                return;
+            const outcome = {
+                kind: "recovered",
+                recordedAt: this.now(),
+                recoveryLocation: typeof payload.recoveryLocation === "string"
+                    ? payload.recoveryLocation
+                    : "",
+                recoveryFactor: typeof payload.recoveryFactor === "string"
+                    ? payload.recoveryFactor
+                    : "",
+                fundsEarned: typeof payload.fundsEarned === "number" ? payload.fundsEarned : 0,
+                scienceEarned: typeof payload.scienceEarned === "number" ? payload.scienceEarned : 0,
+                reputationEarned: typeof payload.reputationEarned === "number"
+                    ? payload.reputationEarned
+                    : 0,
+                crew: parseCrewNames(payload.crewBreakdown),
+            };
+            void this.store.upsertFlight({ ...match, outcome });
+            this.flightListSubscribers.fire();
+        });
+    }
+    applyCrashOutcome(payload) {
+        const ut = typeof payload.ut === "number" ? payload.ut : 0;
+        if (ut === this.lastAppliedCrashAtUT)
+            return;
+        const vesselName = typeof payload.vesselName === "string" ? payload.vesselName : "";
+        if (!vesselName)
+            return;
+        this.lastAppliedCrashAtUT = ut;
+        void this.store.listFlights().then((flights) => {
+            const match = pickMostRecentFlightByName(flights, vesselName);
+            if (!match)
+                return;
+            const partsLost = Array.isArray(payload.partsLost)
+                ? payload.partsLost.length
+                : 0;
+            const outcome = {
+                kind: "crashed",
+                recordedAt: this.now(),
+                body: typeof payload.body === "string" ? payload.body : "",
+                situation: typeof payload.situation === "string" ? payload.situation : "",
+                what: typeof payload.what === "string" ? payload.what : "",
+                partsLostCount: partsLost,
+                kerbalsKilled: parseStringArray(payload.kerbalsKilled),
+            };
+            void this.store.upsertFlight({ ...match, outcome });
+            this.flightListSubscribers.fire();
+        });
+    }
+    runDerivedKeys(changedKey, flightId) {
+        for (const def of getDerivedKeys()) {
+            if (!def.inputs.includes(changedKey))
+                continue;
+            // All inputs must have been seen at least once before we fire.
+            const inputSamples = [];
+            let allSeen = true;
+            for (const inputKey of def.inputs) {
+                const s = this.lastRawSample.get(inputKey);
+                if (!s) {
+                    allSeen = false;
+                    break;
+                }
+                inputSamples.push(s);
+            }
+            if (!allSeen)
+                continue;
+            const previous = this.derivedPrevious.get(def.id) ?? null;
+            const result = def.fn(inputSamples, previous);
+            this.derivedPrevious.set(def.id, inputSamples);
+            if (result === undefined)
+                continue;
+            const derivedT = this.now();
+            if (flightId) {
+                void this.store.appendSample(flightId, def.id, derivedT, result);
+                this.pushToBuffer(def.id, derivedT, result);
+            }
+            this.lastEmittedValue.set(def.id, result);
+            this.keySubscribers.fire(def.id, result);
+        }
+    }
+    pushToBuffer(key, t, v) {
+        let buf = this.buffers.get(key);
+        if (!buf) {
+            buf = [];
+            this.buffers.set(key, buf);
+        }
+        buf.push({ t, v });
+        if (buf.length > this.inMemoryLimit) {
+            // Trim from the front in chunks of 1, cheap enough at 4Hz; move to a circular buffer if this ever shows up in profiling.
+            buf.shift();
+        }
+    }
+    emitFlightChange() {
+        const next = this.detector.getCurrent();
+        if (next === this.lastEmittedCurrent)
+            return;
+        this.lastEmittedCurrent = next;
+        // Reset derivation state across flight boundaries so rates don't straddle two flights.
+        this.derivedPrevious.clear();
+        this.flightSubscribers.fire(next);
+    }
+}
+//# sourceMappingURL=BufferedDataSource.js.map