@trillboards/edge-sdk 0.2.14 → 0.2.16

package/dist/VlmAdmissionGate.js.map

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

package/dist/VlmCandidateBuffer.d.ts

@@ -0,0 +1,247 @@
+/**
+ * VlmCandidateBuffer — the bounded hold between the cascade and the admission
+ * gate, for frames the cascade has ALREADY decided are interesting.
+ *
+ * WHY THIS EXISTS, AND WHY IT IS NOT THE QUEUE THE GATE REFUSES.
+ * `VlmAdmissionGate` drops rather than queues, and its reason is correct as
+ * stated: "by the time a queued frame reached the model the scene has moved
+ * on." That is a statement about AMBIENT SAMPLING, where every frame is
+ * interchangeable and the newest one is strictly the best one, so holding an
+ * old frame is pure loss.
+ *
+ * Alerting is the other case, and alerting is the product. By the time a frame
+ * reaches this buffer the motion cascade has already spent its decode and its
+ * detector and concluded THIS frame is different from the scene it had — a
+ * person walked in, something fell, an aisle that was empty is not. Those
+ * frames are not interchangeable with the next one: at a 30 s scan cadence the
+ * next look is a different event, and on a saturated recorder it may be
+ * thirteen minutes away. Dropping the one frame that carried the event and
+ * later analysing an empty aisle is not "staying fresh"; it is answering a
+ * question nobody asked while the one that mattered went unrecorded.
+ *
+ * So the buffer holds CANDIDATES ONLY. A frame the cascade classified as
+ * no-change must never enter — that would rebuild exactly the undifferentiated
+ * backlog the gate exists to prevent, and the caller is responsible for that
+ * invariant because only the caller has the cascade verdict.
+ *
+ * THREE BOUNDS, ALL COUNTED. A hold that is unbounded in size is a memory leak
+ * and a hold that is unbounded in age is the gate's original complaint. So:
+ *
+ *   - `maxPerFeed` — one busy camera can never hold more than its share, which
+ *     is what keeps camera 12 from starving the other 31.
+ *   - `maxFrames` / `maxBytes` — a hard ceiling on the whole buffer, enforced
+ *     on the way IN. When it binds, the candidate dropped is the OLDEST of the
+ *     feed that currently holds the MOST, so pressure is paid by whoever is
+ *     causing it.
+ *   - `ttlMs` — past this age the gate's insight takes over and the candidate
+ *     is dropped as expired rather than analysed.
+ *
+ * Every one of those three drops is COUNTED. A silent eviction is the same
+ * defect as the silent drop this class was built to fix — it would move the
+ * lost frame from one invisible place to another.
+ *
+ * SERVICE ORDER is least-recently-served feed first, oldest candidate within
+ * that feed. Across feeds that is round-robin, so service cannot be won by
+ * whichever timer happens to fire first. Within a feed it is FIFO, because
+ * consecutive candidates from one feed are frames of the SAME event and the
+ * earliest one is the one that shows the transition — a person entering a
+ * restricted area is visible in the frame where they enter, and by the last
+ * frame of the burst they may already be out of view.
+ *
+ * THREADING. Node is single-threaded and no method here awaits, so `peek()`
+ * followed by `take()` is one critical section by construction: they are
+ * guaranteed to name the same candidate. `CloudSensingManager.pumpCandidates`
+ * depends on that — it peeks to learn the feed, acquires an admission slot for
+ * it, and only then commits with `take()`.
+ */
+/** One frame the cascade judged worth an inference, waiting for a slot. */
+export interface VlmCandidate {
+    /** Feed the frame came from. */
+    readonly name: string;
+    /** The encoded frame, exactly as the capture path produced it. */
+    readonly jpeg: Buffer;
+    /** Clock reading when the cascade admitted it as a candidate. */
+    readonly enqueuedAtMs: number;
+    /** The capture mode the tick would have POSTed with. */
+    readonly captureMode: string;
+    /** The cascade reason that made this a candidate (diagnostics). */
+    readonly reason: string;
+    /**
+     * The cascade's stationary-suppression key for this frame. Carried rather
+     * than recomputed so that when the frame finally reaches the model, THAT
+     * frame's baseline is the one committed — a held candidate can be served long
+     * after later frames from the same feed were evaluated.
+     */
+    readonly signature: string | null;
+    /**
+     * The dimensions THIS frame was decoded at, carried rather than re-read.
+     *
+     * A held candidate can be served long after the camera moved on — and on a
+     * feed that renegotiates resolution, asking the camera at serve time would
+     * describe a frame that is not the one in `jpeg`. Same reasoning as
+     * `signature`: the datum belongs to the frame, so it travels with it.
+     * Optional because a provider need not implement `getResolution()`.
+     */
+    readonly imageWidth?: number;
+    readonly imageHeight?: number;
+}
+export interface VlmCandidateBufferOptions {
+    /**
+     * Candidates held across ALL feeds. Default 32 — one per feed on the
+     * 32-camera recorder this was sized against, so the common case is "every
+     * camera may hold its event" and contention only appears when several fire
+     * at once.
+     */
+    maxFrames?: number;
+    /**
+     * Candidates one feed may hold. Default 2 — the onset frame plus one
+     * follow-up. Motion is temporally clustered, so a third frame of the same
+     * burst is a near-duplicate of the second and buys nothing a slot could not.
+     */
+    maxPerFeed?: number;
+    /**
+     * Total encoded bytes held. Default 16 MiB. This is the bound that stays
+     * true when the frame size changes: measured on the production CCTV fixtures
+     * at `jpegQuality` 70, a 640x480 frame encodes to ~54 KB and a 1920x1080
+     * frame to ~199 KB, so 32 candidates is ~1.7 MB at the default capture size
+     * and ~6.2 MB at 1080p — the FRAME cap binds first at every realistic
+     * resolution, and the byte cap is what keeps that true if it stops being.
+     */
+    maxBytes?: number;
+    /**
+     * How long a candidate stays worth a slot (ms). Default 90000 — see
+     * DEFAULT_CANDIDATE_TTL_MS.
+     */
+    ttlMs?: number;
+    /** Clock injection for tests. Default `Date.now`. */
+    now?: () => number;
+}
+export interface VlmCandidateFeedStats {
+    name: string;
+    /** Candidates this feed is holding right now. */
+    buffered: number;
+    enqueued: number;
+    served: number;
+    evicted: number;
+    expired: number;
+}
+export interface VlmCandidateBufferStats {
+    /** Candidates held right now, across all feeds. */
+    buffered: number;
+    /** Encoded bytes held right now. */
+    bytes: number;
+    maxFrames: number;
+    maxPerFeed: number;
+    maxBytes: number;
+    ttlMs: number;
+    /** Cumulative candidates accepted. */
+    enqueued: number;
+    /** Cumulative candidates handed to the model. */
+    served: number;
+    /** Cumulative candidates dropped to make room — the fairness cost, visible. */
+    evicted: number;
+    /** Cumulative candidates dropped for being older than `ttlMs`. */
+    expired: number;
+    /** Age (ms) of the oldest held candidate, or null when empty. */
+    oldestAgeMs: number | null;
+    perFeed: VlmCandidateFeedStats[];
+}
+/**
+ * DEFAULT_CANDIDATE_TTL_MS — how long an alert is still an alert.
+ *
+ * The admission gate's sentence is right at a long enough horizon: a frame the
+ * model looks at ten minutes late describes a scene that no longer exists, and
+ * the slot it burns would have been better spent on something current. The
+ * only question is where that horizon actually sits, and the answer comes from
+ * what the frame is FOR, not from how fresh it is in the abstract.
+ *
+ * The events this connector exists to catch — a spill, a fall, someone in a
+ * restricted area — persist on the order of a minute or two, and the response
+ * to one is a person walking over to look. An alert that lands 90 s late still
+ * finds the spill on the floor and the person still down, and is worth every
+ * bit of the slot it takes. One that lands ten minutes late is a report rather
+ * than an alert: either somebody already noticed or nobody is going to.
+ *
+ * 90 s is also three full 30 s face-triggered cadences, so a candidate
+ * survives a couple of rounds of contention on a saturated recorder, and it is
+ * well inside the 5 min still-scene heartbeat, so a held candidate can never
+ * outlive the feed's own next guaranteed report. The buffer may delay a frame;
+ * it can never stand in for the cadence.
+ */
+export declare const DEFAULT_CANDIDATE_TTL_MS = 90000;
+/** Why an `offer()` did not result in a held candidate. */
+export type VlmCandidateOfferResult = 
+/** Held. */
+'buffered'
+/** Could not be held at all (a single frame larger than the whole budget). */
+ | 'rejected';
+export declare class VlmCandidateBuffer {
+    private readonly maxFrames;
+    private readonly maxPerFeed;
+    private readonly maxBytes;
+    private readonly ttlMs;
+    private readonly now;
+    private readonly feeds;
+    private held;
+    private heldBytes;
+    private enqueued;
+    private served;
+    private evicted;
+    private expired;
+    /** Monotonic tie-break so two feeds served in the same millisecond rotate. */
+    private serveTick;
+    private readonly serveOrder;
+    constructor(options?: VlmCandidateBufferOptions);
+    getMaxFrames(): number;
+    getMaxPerFeed(): number;
+    getTtlMs(): number;
+    /** Candidates held right now. */
+    size(): number;
+    /** Encoded bytes held right now. */
+    bytes(): number;
+    /**
+     * Hold one candidate. The CALLER guarantees the cascade classified it as
+     * interesting — a no-change frame must never be offered, because a buffer of
+     * undifferentiated frames is the queue the admission gate exists to refuse.
+     *
+     * Never blocks and never grows past the caps: room is made by evicting, and
+     * every eviction is counted.
+     */
+    offer(candidate: Omit<VlmCandidate, 'enqueuedAtMs'> & {
+        enqueuedAtMs?: number;
+    }, nowMs?: number): VlmCandidateOfferResult;
+    /**
+     * The candidate that would be served next, WITHOUT removing it. Least
+     * recently served feed, oldest candidate within it.
+     *
+     * Nothing here awaits, so a `peek()` immediately followed by `take()` is
+     * guaranteed to name the same candidate — which is what lets a caller
+     * acquire an admission slot for the right feed before committing.
+     */
+    peek(nowMs?: number): VlmCandidate | null;
+    /** Remove and return the next candidate (same one `peek()` names). */
+    take(nowMs?: number): VlmCandidate | null;
+    /**
+     * Drop every candidate older than `ttlMs`, counting each one. Idempotent and
+     * safe to call as often as convenient — it is a scan over a few dozen items.
+     */
+    expire(nowMs?: number): number;
+    /** Age (ms) of the oldest held candidate, or null when empty. */
+    oldestAgeMs(nowMs?: number): number | null;
+    /** Candidates this feed is holding right now. */
+    bufferedFor(name: string): number;
+    /** Drop everything and zero every counter (a stop()/start() cycle is clean). */
+    reset(): void;
+    getStats(nowMs?: number): VlmCandidateBufferStats;
+    private feedQueue;
+    /**
+     * Least-recently-served feed that is holding something. A feed the buffer has
+     * never served outranks one it has, so a camera whose event has been waiting
+     * is not overtaken by the camera that was just served.
+     */
+    private nextFeed;
+    /** Drop the feed that holds the MOST candidates by one. False when empty. */
+    private evictFromFullestFeed;
+    private evictOldestOf;
+}
+//# sourceMappingURL=VlmCandidateBuffer.d.ts.map

package/dist/VlmCandidateBuffer.d.ts.map

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

package/dist/VlmCandidateBuffer.js

@@ -0,0 +1,349 @@
+"use strict";
+/**
+ * VlmCandidateBuffer — the bounded hold between the cascade and the admission
+ * gate, for frames the cascade has ALREADY decided are interesting.
+ *
+ * WHY THIS EXISTS, AND WHY IT IS NOT THE QUEUE THE GATE REFUSES.
+ * `VlmAdmissionGate` drops rather than queues, and its reason is correct as
+ * stated: "by the time a queued frame reached the model the scene has moved
+ * on." That is a statement about AMBIENT SAMPLING, where every frame is
+ * interchangeable and the newest one is strictly the best one, so holding an
+ * old frame is pure loss.
+ *
+ * Alerting is the other case, and alerting is the product. By the time a frame
+ * reaches this buffer the motion cascade has already spent its decode and its
+ * detector and concluded THIS frame is different from the scene it had — a
+ * person walked in, something fell, an aisle that was empty is not. Those
+ * frames are not interchangeable with the next one: at a 30 s scan cadence the
+ * next look is a different event, and on a saturated recorder it may be
+ * thirteen minutes away. Dropping the one frame that carried the event and
+ * later analysing an empty aisle is not "staying fresh"; it is answering a
+ * question nobody asked while the one that mattered went unrecorded.
+ *
+ * So the buffer holds CANDIDATES ONLY. A frame the cascade classified as
+ * no-change must never enter — that would rebuild exactly the undifferentiated
+ * backlog the gate exists to prevent, and the caller is responsible for that
+ * invariant because only the caller has the cascade verdict.
+ *
+ * THREE BOUNDS, ALL COUNTED. A hold that is unbounded in size is a memory leak
+ * and a hold that is unbounded in age is the gate's original complaint. So:
+ *
+ *   - `maxPerFeed` — one busy camera can never hold more than its share, which
+ *     is what keeps camera 12 from starving the other 31.
+ *   - `maxFrames` / `maxBytes` — a hard ceiling on the whole buffer, enforced
+ *     on the way IN. When it binds, the candidate dropped is the OLDEST of the
+ *     feed that currently holds the MOST, so pressure is paid by whoever is
+ *     causing it.
+ *   - `ttlMs` — past this age the gate's insight takes over and the candidate
+ *     is dropped as expired rather than analysed.
+ *
+ * Every one of those three drops is COUNTED. A silent eviction is the same
+ * defect as the silent drop this class was built to fix — it would move the
+ * lost frame from one invisible place to another.
+ *
+ * SERVICE ORDER is least-recently-served feed first, oldest candidate within
+ * that feed. Across feeds that is round-robin, so service cannot be won by
+ * whichever timer happens to fire first. Within a feed it is FIFO, because
+ * consecutive candidates from one feed are frames of the SAME event and the
+ * earliest one is the one that shows the transition — a person entering a
+ * restricted area is visible in the frame where they enter, and by the last
+ * frame of the burst they may already be out of view.
+ *
+ * THREADING. Node is single-threaded and no method here awaits, so `peek()`
+ * followed by `take()` is one critical section by construction: they are
+ * guaranteed to name the same candidate. `CloudSensingManager.pumpCandidates`
+ * depends on that — it peeks to learn the feed, acquires an admission slot for
+ * it, and only then commits with `take()`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VlmCandidateBuffer = exports.DEFAULT_CANDIDATE_TTL_MS = void 0;
+/**
+ * DEFAULT_CANDIDATE_TTL_MS — how long an alert is still an alert.
+ *
+ * The admission gate's sentence is right at a long enough horizon: a frame the
+ * model looks at ten minutes late describes a scene that no longer exists, and
+ * the slot it burns would have been better spent on something current. The
+ * only question is where that horizon actually sits, and the answer comes from
+ * what the frame is FOR, not from how fresh it is in the abstract.
+ *
+ * The events this connector exists to catch — a spill, a fall, someone in a
+ * restricted area — persist on the order of a minute or two, and the response
+ * to one is a person walking over to look. An alert that lands 90 s late still
+ * finds the spill on the floor and the person still down, and is worth every
+ * bit of the slot it takes. One that lands ten minutes late is a report rather
+ * than an alert: either somebody already noticed or nobody is going to.
+ *
+ * 90 s is also three full 30 s face-triggered cadences, so a candidate
+ * survives a couple of rounds of contention on a saturated recorder, and it is
+ * well inside the 5 min still-scene heartbeat, so a held candidate can never
+ * outlive the feed's own next guaranteed report. The buffer may delay a frame;
+ * it can never stand in for the cadence.
+ */
+exports.DEFAULT_CANDIDATE_TTL_MS = 90000;
+const DEFAULT_MAX_FRAMES = 32;
+const DEFAULT_MAX_PER_FEED = 2;
+const DEFAULT_MAX_BYTES = 16 * 1024 * 1024;
+class VlmCandidateBuffer {
+    constructor(options = {}) {
+        this.feeds = new Map();
+        this.held = 0;
+        this.heldBytes = 0;
+        this.enqueued = 0;
+        this.served = 0;
+        this.evicted = 0;
+        this.expired = 0;
+        /** Monotonic tie-break so two feeds served in the same millisecond rotate. */
+        this.serveTick = 0;
+        this.serveOrder = new Map();
+        this.maxFrames = Math.max(1, Math.trunc(options.maxFrames ?? DEFAULT_MAX_FRAMES));
+        // A per-feed cap above the global cap is not a cap; clamp so the two can
+        // never disagree about what "one feed's share" means.
+        this.maxPerFeed = Math.min(this.maxFrames, Math.max(1, Math.trunc(options.maxPerFeed ?? DEFAULT_MAX_PER_FEED)));
+        this.maxBytes = Math.max(1, Math.trunc(options.maxBytes ?? DEFAULT_MAX_BYTES));
+        this.ttlMs = Math.max(1, Math.trunc(options.ttlMs ?? exports.DEFAULT_CANDIDATE_TTL_MS));
+        this.now = options.now ?? Date.now;
+    }
+    getMaxFrames() {
+        return this.maxFrames;
+    }
+    getMaxPerFeed() {
+        return this.maxPerFeed;
+    }
+    getTtlMs() {
+        return this.ttlMs;
+    }
+    /** Candidates held right now. */
+    size() {
+        return this.held;
+    }
+    /** Encoded bytes held right now. */
+    bytes() {
+        return this.heldBytes;
+    }
+    /**
+     * Hold one candidate. The CALLER guarantees the cascade classified it as
+     * interesting — a no-change frame must never be offered, because a buffer of
+     * undifferentiated frames is the queue the admission gate exists to refuse.
+     *
+     * Never blocks and never grows past the caps: room is made by evicting, and
+     * every eviction is counted.
+     */
+    offer(candidate, nowMs) {
+        const now = nowMs ?? this.now();
+        this.expire(now);
+        const entry = {
+            name: candidate.name,
+            jpeg: candidate.jpeg,
+            captureMode: candidate.captureMode,
+            reason: candidate.reason,
+            signature: candidate.signature,
+            imageWidth: candidate.imageWidth,
+            imageHeight: candidate.imageHeight,
+            enqueuedAtMs: candidate.enqueuedAtMs ?? now,
+        };
+        const incomingBytes = entry.jpeg.length;
+        // A single frame larger than the entire budget can never be held, and
+        // emptying the buffer for it would trade N real candidates for zero. Say
+        // no, and count it — an uncounted refusal is the defect this class fixes.
+        if (incomingBytes > this.maxBytes) {
+            const feed = this.feedQueue(entry.name);
+            feed.evicted++;
+            this.evicted++;
+            return 'rejected';
+        }
+        const feed = this.feedQueue(entry.name);
+        // 1. This feed's own share first, so the eviction lands on the feed that
+        //    is over its allowance rather than on a quiet neighbour.
+        while (feed.items.length >= this.maxPerFeed) {
+            this.evictOldestOf(feed);
+        }
+        // 2. Then the global ceilings. Pressure is paid by whoever holds the most.
+        while (this.held + 1 > this.maxFrames ||
+            this.heldBytes + incomingBytes > this.maxBytes) {
+            if (!this.evictFromFullestFeed())
+                break;
+        }
+        feed.items.push(entry);
+        this.held++;
+        this.heldBytes += incomingBytes;
+        feed.enqueued++;
+        this.enqueued++;
+        return 'buffered';
+    }
+    /**
+     * The candidate that would be served next, WITHOUT removing it. Least
+     * recently served feed, oldest candidate within it.
+     *
+     * Nothing here awaits, so a `peek()` immediately followed by `take()` is
+     * guaranteed to name the same candidate — which is what lets a caller
+     * acquire an admission slot for the right feed before committing.
+     */
+    peek(nowMs) {
+        this.expire(nowMs ?? this.now());
+        const feed = this.nextFeed();
+        return feed ? feed.items[0] : null;
+    }
+    /** Remove and return the next candidate (same one `peek()` names). */
+    take(nowMs) {
+        const now = nowMs ?? this.now();
+        this.expire(now);
+        const feed = this.nextFeed();
+        if (!feed)
+            return null;
+        const item = feed.items.shift();
+        if (!item)
+            return null;
+        this.held--;
+        this.heldBytes -= item.jpeg.length;
+        feed.served++;
+        this.served++;
+        feed.lastServedAtMs = now;
+        this.serveOrder.set(feed.name, ++this.serveTick);
+        return item;
+    }
+    /**
+     * Drop every candidate older than `ttlMs`, counting each one. Idempotent and
+     * safe to call as often as convenient — it is a scan over a few dozen items.
+     */
+    expire(nowMs) {
+        const now = nowMs ?? this.now();
+        let dropped = 0;
+        for (const feed of this.feeds.values()) {
+            while (feed.items.length > 0 && now - feed.items[0].enqueuedAtMs > this.ttlMs) {
+                const item = feed.items.shift();
+                this.held--;
+                this.heldBytes -= item.jpeg.length;
+                feed.expired++;
+                this.expired++;
+                dropped++;
+            }
+        }
+        return dropped;
+    }
+    /** Age (ms) of the oldest held candidate, or null when empty. */
+    oldestAgeMs(nowMs) {
+        const now = nowMs ?? this.now();
+        let oldest = null;
+        for (const feed of this.feeds.values()) {
+            const head = feed.items[0];
+            if (!head)
+                continue;
+            const age = Math.max(0, now - head.enqueuedAtMs);
+            if (oldest === null || age > oldest)
+                oldest = age;
+        }
+        return oldest;
+    }
+    /** Candidates this feed is holding right now. */
+    bufferedFor(name) {
+        return this.feeds.get(name)?.items.length ?? 0;
+    }
+    /** Drop everything and zero every counter (a stop()/start() cycle is clean). */
+    reset() {
+        this.feeds.clear();
+        this.serveOrder.clear();
+        this.held = 0;
+        this.heldBytes = 0;
+        this.enqueued = 0;
+        this.served = 0;
+        this.evicted = 0;
+        this.expired = 0;
+        this.serveTick = 0;
+    }
+    getStats(nowMs) {
+        const now = nowMs ?? this.now();
+        this.expire(now);
+        return {
+            buffered: this.held,
+            bytes: this.heldBytes,
+            maxFrames: this.maxFrames,
+            maxPerFeed: this.maxPerFeed,
+            maxBytes: this.maxBytes,
+            ttlMs: this.ttlMs,
+            enqueued: this.enqueued,
+            served: this.served,
+            evicted: this.evicted,
+            expired: this.expired,
+            oldestAgeMs: this.oldestAgeMs(now),
+            perFeed: [...this.feeds.values()].map((f) => ({
+                name: f.name,
+                buffered: f.items.length,
+                enqueued: f.enqueued,
+                served: f.served,
+                evicted: f.evicted,
+                expired: f.expired,
+            })),
+        };
+    }
+    // ─── Private ────────────────────────────────────────────────────────────────
+    feedQueue(name) {
+        let feed = this.feeds.get(name);
+        if (!feed) {
+            feed = {
+                name,
+                items: [],
+                lastServedAtMs: null,
+                enqueued: 0,
+                served: 0,
+                evicted: 0,
+                expired: 0,
+            };
+            this.feeds.set(name, feed);
+        }
+        return feed;
+    }
+    /**
+     * Least-recently-served feed that is holding something. A feed the buffer has
+     * never served outranks one it has, so a camera whose event has been waiting
+     * is not overtaken by the camera that was just served.
+     */
+    nextFeed() {
+        let best = null;
+        let bestOrder = Infinity;
+        let bestOldest = Infinity;
+        for (const feed of this.feeds.values()) {
+            const head = feed.items[0];
+            if (!head)
+                continue;
+            // Never served ⇒ order 0, which sorts ahead of every served feed.
+            const order = this.serveOrder.get(feed.name) ?? 0;
+            if (order < bestOrder || (order === bestOrder && head.enqueuedAtMs < bestOldest)) {
+                best = feed;
+                bestOrder = order;
+                bestOldest = head.enqueuedAtMs;
+            }
+        }
+        return best;
+    }
+    /** Drop the feed that holds the MOST candidates by one. False when empty. */
+    evictFromFullestFeed() {
+        let victim = null;
+        for (const feed of this.feeds.values()) {
+            if (feed.items.length === 0)
+                continue;
+            if (victim === null ||
+                feed.items.length > victim.items.length ||
+                // Same depth ⇒ the one whose head is oldest, so ties are broken toward
+                // the frame closest to expiring anyway.
+                (feed.items.length === victim.items.length &&
+                    feed.items[0].enqueuedAtMs < victim.items[0].enqueuedAtMs)) {
+                victim = feed;
+            }
+        }
+        if (!victim)
+            return false;
+        this.evictOldestOf(victim);
+        return true;
+    }
+    evictOldestOf(feed) {
+        const item = feed.items.shift();
+        if (!item)
+            return;
+        this.held--;
+        this.heldBytes -= item.jpeg.length;
+        feed.evicted++;
+        this.evicted++;
+    }
+}
+exports.VlmCandidateBuffer = VlmCandidateBuffer;
+//# sourceMappingURL=VlmCandidateBuffer.js.map

package/dist/VlmCandidateBuffer.js.map

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