@bendyline/gezel-inference 0.0.0-stage → 1.0.0

package/dist/remotes/pinned-fetch.js

@@ -0,0 +1,193 @@
+/**
+ * `fetch` dispatchers for talking to a paired remote daemon over the LAN.
+ *
+ * A paired server presents its loopback TLS cert (SAN `127.0.0.1`) on a
+ * routable address, so SAN/hostname matching can't apply. The **exact-cert
+ * pin** is the trust boundary instead — only the one cert captured at pairing
+ * validates; any substitute (a MITM's own self-signed cert) fails the CA
+ * check. Continuity across the server's per-boot cert rotation is proven
+ * separately by the device-identity signature over the cert fingerprint
+ * (see [identity.ts](./identity.ts) `verifyIdentitySignature`).
+ *
+ * Uses undici directly (not Node's global fetch) so the Agent and fetch come
+ * from the same package version — mismatched undici ABIs throw at request time
+ * (see client/node-tls.ts for the gory details).
+ */
+import { Agent, fetch as undiciFetch } from 'undici';
+import { IdentityResponseSchema, certFingerprintFromPem, fingerprintOfPublicKeyPem, verifyIdentitySignature, } from './identity.js';
+async function closeFetch(fetchImpl) {
+    const close = fetchImpl?.close;
+    if (typeof close === 'function')
+        await close.call(fetchImpl);
+}
+/**
+ * Pin a single self-signed cert as the sole CA and skip hostname/SAN
+ * verification. Long-call-friendly (no header/body timeouts) for streamed
+ * inference + large artifact downloads.
+ */
+export function createPinnedFetch(certPem) {
+    const dispatcher = new Agent({
+        connect: {
+            ca: certPem,
+            rejectUnauthorized: true,
+            // SAN matching is meaningless for a pinned loopback cert reached by LAN
+            // IP; the cert identity itself is the pin, reinforced by the identity
+            // signature verified at connect time.
+            checkServerIdentity: () => undefined,
+        },
+        allowH2: true,
+        headersTimeout: 0,
+        bodyTimeout: 0,
+    });
+    const pinned = ((url, init) => undiciFetch(url, { ...init, dispatcher }));
+    pinned.close = async () => {
+        await dispatcher.close();
+    };
+    return pinned;
+}
+/**
+ * TOFU bootstrap fetch used ONLY for the very first `/v1/identity` call during
+ * pairing, before any cert is pinned. Accepts the server's self-signed cert
+ * unconditionally; the response's identity signature + out-of-band fingerprint
+ * comparison are what actually establish trust (SSH `known_hosts` semantics).
+ * Never reuse this for inference — pair, pin, then use {@link createPinnedFetch}.
+ */
+export function createInsecureBootstrapFetch() {
+    const dispatcher = new Agent({
+        connect: { rejectUnauthorized: false },
+        allowH2: true,
+        headersTimeout: 10_000,
+        bodyTimeout: 10_000,
+    });
+    const bootstrap = ((url, init) => undiciFetch(url, { ...init, dispatcher }));
+    bootstrap.close = async () => {
+        await dispatcher.close();
+    };
+    return bootstrap;
+}
+/**
+ * Fetch through a paired identity. If the daemon rotated its ephemeral TLS
+ * certificate, refresh it over an insecure bootstrap channel but accept it
+ * only when the already-pinned device identity signs the new fingerprint.
+ */
+export function createPairedRemoteFetch(remote, registry, deps = {}) {
+    const baseUrl = new URL(remote.baseUrl);
+    if (baseUrl.protocol !== 'https:' ||
+        baseUrl.username ||
+        baseUrl.password ||
+        baseUrl.pathname !== '/' ||
+        baseUrl.search ||
+        baseUrl.hash) {
+        throw new Error('paired remote transport requires an exact HTTPS origin');
+    }
+    const makePinned = deps.createPinned ?? createPinnedFetch;
+    const makeBootstrap = deps.createBootstrap ?? createInsecureBootstrapFetch;
+    let active = remote.tlsCertPem ? makePinned(remote.tlsCertPem) : null;
+    let refresh = null;
+    let closed = false;
+    const paired = (async (url, init) => {
+        if (closed)
+            throw new Error('paired remote fetch is closed');
+        if (!active) {
+            refresh ??= refreshPairedCertificate(remote, registry, makeBootstrap).then((cert) => {
+                active = makePinned(cert);
+            });
+            await refresh.finally(() => {
+                refresh = null;
+            });
+        }
+        try {
+            return await active(url, init);
+        }
+        catch (originalError) {
+            if (init?.signal?.aborted)
+                throw originalError;
+            refresh ??= refreshPairedCertificate(remote, registry, makeBootstrap).then((cert) => {
+                const previous = active;
+                active = makePinned(cert);
+                void closeFetch(previous);
+            });
+            try {
+                await refresh;
+            }
+            catch {
+                throw originalError;
+            }
+            finally {
+                refresh = null;
+            }
+            return await active(url, init);
+        }
+    });
+    paired.close = async () => {
+        if (closed)
+            return;
+        closed = true;
+        await refresh?.catch(() => undefined);
+        const current = active;
+        active = null;
+        await closeFetch(current);
+    };
+    return paired;
+}
+const sharedFetches = new WeakMap();
+/** Reuse one managed Undici agent per paired server instead of leaking one per operation. */
+export function getPairedRemoteFetch(remote, registry) {
+    let entries = sharedFetches.get(registry);
+    if (!entries) {
+        entries = new Map();
+        sharedFetches.set(registry, entries);
+    }
+    const connectionKey = `${remote.baseUrl}\0${remote.pinnedIdentityFingerprint}`;
+    const existing = entries.get(remote.remoteId);
+    if (existing?.connectionKey === connectionKey)
+        return existing.fetch;
+    if (existing)
+        void existing.fetch.close();
+    const managed = createPairedRemoteFetch(remote, registry);
+    entries.set(remote.remoteId, { connectionKey, fetch: managed });
+    return managed;
+}
+export async function closePairedRemoteFetches(registry, remoteId) {
+    const entries = sharedFetches.get(registry);
+    if (!entries)
+        return;
+    if (remoteId !== undefined) {
+        const entry = entries.get(remoteId);
+        entries.delete(remoteId);
+        await entry?.fetch.close();
+        return;
+    }
+    sharedFetches.delete(registry);
+    await Promise.allSettled(Array.from(entries.values(), (entry) => entry.fetch.close()));
+}
+async function refreshPairedCertificate(remote, registry, createBootstrap) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(new Error('remote certificate refresh timed out')), 10_000);
+    timeout.unref?.();
+    const bootstrap = createBootstrap();
+    try {
+        const response = await bootstrap(`${remote.baseUrl}/v1/identity`, {
+            signal: controller.signal,
+        });
+        if (!response.ok)
+            throw new Error(`remote identity refresh returned HTTP ${response.status}`);
+        const identity = IdentityResponseSchema.parse(await response.json());
+        if (fingerprintOfPublicKeyPem(identity.publicKeyPem) !== remote.pinnedIdentityFingerprint ||
+            identity.fingerprint !== remote.pinnedIdentityFingerprint ||
+            !identity.tlsCertPem ||
+            !identity.tlsCertFingerprint ||
+            !identity.sig ||
+            certFingerprintFromPem(identity.tlsCertPem) !== identity.tlsCertFingerprint ||
+            !verifyIdentitySignature(remote.pinnedIdentityKey, identity.tlsCertFingerprint, identity.sig)) {
+            throw new Error('remote certificate refresh failed pinned-identity verification');
+        }
+        await registry.update(remote.remoteId, { tlsCertPem: identity.tlsCertPem });
+        remote.tlsCertPem = identity.tlsCertPem;
+        return identity.tlsCertPem;
+    }
+    finally {
+        clearTimeout(timeout);
+        await closeFetch(bootstrap);
+    }
+}

package/dist/remotes/types.d.ts

@@ -0,0 +1,54 @@
+export interface PairedRemote {
+    /** Stable id A assigns to this server = its full identity fingerprint. */
+    remoteId: string;
+    /** Base URL A reaches the server at, e.g. `https://192.168.1.50:6229`. */
+    baseUrl: string;
+    /** Human label shown in A's model picker / Remote Servers panel. */
+    displayName: string;
+    /** Per-device bearer token the server issued A (scope `remote-inference`). */
+    token: string;
+    /** The server's identity public key (SPKI PEM), pinned at pairing (TOFU). */
+    pinnedIdentityKey: string;
+    /** Hex SHA-256 of the pinned identity key — the comparable fingerprint. */
+    pinnedIdentityFingerprint: string;
+    /**
+     * The server's current TLS cert (PEM), used as the CA for A's trusting
+     * fetch. Refreshed from `/v1/identity` when the server rotates it; the
+     * identity signature is what proves continuity, not this cert.
+     */
+    tlsCertPem?: string;
+    /** Scopes the server granted (currently `['remote-inference']`). */
+    scopes: string[];
+    /**
+     * `gezelVersion` from the peer's `/v1/identity`, when it reported one.
+     * Absent for a peer too old to publish it. Read by the native-capacity
+     * authority check, which must know whether the broker deciding this
+     * machine's memory is the same build as the one asking.
+     */
+    gezelVersion?: string;
+    pairedAt: number;
+    /** Last time A successfully reached this server (in-memory unless flushed). */
+    lastSeenAt?: number;
+    /**
+     * Runtime-managed connections are never persisted and cannot be removed by
+     * the ordinary pairing UI. Today the only managed peer is this computer's
+     * machine-wide engine broker.
+     */
+    managed?: 'machine-engine';
+}
+export interface RemotesRegistry {
+    list(): PairedRemote[];
+    get(remoteId: string): PairedRemote | null;
+    /** Upsert a paired server. Re-pairing the same id or base URL replaces it atomically. */
+    add(remote: PairedRemote): Promise<void>;
+    /** Install/replace a runtime-only peer without writing its rotating token. */
+    setEphemeral(remote: PairedRemote): void;
+    /** Remove a runtime-only peer. Persisted pairings are never affected. */
+    removeEphemeral(remoteId: string): boolean;
+    /** Patch fields of an existing entry (token rotation, cert refresh, re-pin). */
+    update(remoteId: string, patch: Partial<Omit<PairedRemote, 'remoteId'>>): Promise<boolean>;
+    /** Forget a server. Returns true if a record was removed. */
+    remove(remoteId: string): Promise<boolean>;
+    /** Bump `lastSeenAt` in memory (no disk write). */
+    touch(remoteId: string): void;
+}

package/dist/remotes/types.js

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

package/dist/runtime-lock.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Thrown when a gezel home already has a live daemon. The CLI's `gezel
+ * start` / the supervisor surface this as an actionable message rather
+ * than a stack trace.
+ */
+export declare class SingleInstanceError extends Error {
+    readonly holderPid: number;
+    readonly lockPath: string;
+    constructor(holderPid: number, lockPath: string);
+}
+export interface RuntimeLock {
+    release(): Promise<void>;
+}
+/**
+ * Acquire an exclusive single-instance lock for a gezel home so two daemons
+ * can't share one `~/.gezel/` and race its on-disk state (config, sessions,
+ * tasks, runtime files). Atomic `O_CREAT|O_EXCL` create of
+ * `<runtimeDir>/lock` holding the owner pid; a stale lock (dead holder) is
+ * reclaimed. Throws {@link SingleInstanceError} when a live daemon holds it.
+ *
+ * The returned `release()` removes the lock — call it on graceful shutdown.
+ * A hard crash leaves a stale lock that the next start reclaims via the
+ * pid-liveness check.
+ */
+export declare function acquireSingleInstanceLock(opts: {
+    runtimeDir: string;
+    lockPath: string;
+    isAlive?: (pid: number) => boolean;
+}): Promise<RuntimeLock>;

package/dist/runtime-lock.js

@@ -0,0 +1,85 @@
+import { mkdir, open, readFile, rm } from 'node:fs/promises';
+/**
+ * Thrown when a gezel home already has a live daemon. The CLI's `gezel
+ * start` / the supervisor surface this as an actionable message rather
+ * than a stack trace.
+ */
+export class SingleInstanceError extends Error {
+    holderPid;
+    lockPath;
+    constructor(holderPid, lockPath) {
+        super(holderPid > 0
+            ? `Another gezel daemon is already running for this home (pid ${holderPid}). Stop it first with \`gezel stop --daemon\` (plain \`gezel stop\` only halts AI work), or use a different GEZEL_HOME.`
+            : `Could not acquire the single-instance lock at ${lockPath}.`);
+        this.holderPid = holderPid;
+        this.lockPath = lockPath;
+        this.name = 'SingleInstanceError';
+    }
+}
+function defaultIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        // ESRCH → no such process (dead). EPERM → exists but we can't signal it
+        // (alive, owned by another user). Anything else → treat as dead.
+        return err.code === 'EPERM';
+    }
+}
+async function readHolderPid(lockPath) {
+    try {
+        const pid = Number.parseInt((await readFile(lockPath, 'utf8')).trim(), 10);
+        return Number.isFinite(pid) ? pid : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Acquire an exclusive single-instance lock for a gezel home so two daemons
+ * can't share one `~/.gezel/` and race its on-disk state (config, sessions,
+ * tasks, runtime files). Atomic `O_CREAT|O_EXCL` create of
+ * `<runtimeDir>/lock` holding the owner pid; a stale lock (dead holder) is
+ * reclaimed. Throws {@link SingleInstanceError} when a live daemon holds it.
+ *
+ * The returned `release()` removes the lock — call it on graceful shutdown.
+ * A hard crash leaves a stale lock that the next start reclaims via the
+ * pid-liveness check.
+ */
+export async function acquireSingleInstanceLock(opts) {
+    const isAlive = opts.isAlive ?? defaultIsAlive;
+    await mkdir(opts.runtimeDir, { recursive: true });
+    for (let attempt = 0; attempt < 3; attempt++) {
+        try {
+            const handle = await open(opts.lockPath, 'wx'); // fails with EEXIST if present
+            try {
+                await handle.writeFile(`${process.pid}\n`);
+            }
+            finally {
+                await handle.close();
+            }
+            return {
+                async release() {
+                    // Only remove the lock if it's still ours — defends against a
+                    // narrow race where another process reclaimed our stale lock.
+                    const holder = await readHolderPid(opts.lockPath);
+                    if (holder === null || holder === process.pid) {
+                        await rm(opts.lockPath, { force: true }).catch(() => { });
+                    }
+                },
+            };
+        }
+        catch (err) {
+            if (err.code !== 'EEXIST')
+                throw err;
+            const holder = await readHolderPid(opts.lockPath);
+            if (holder !== null && holder !== process.pid && isAlive(holder)) {
+                throw new SingleInstanceError(holder, opts.lockPath);
+            }
+            // Stale (dead holder / our own pid / unreadable) — reclaim and retry.
+            await rm(opts.lockPath, { force: true }).catch(() => { });
+        }
+    }
+    throw new SingleInstanceError(-1, opts.lockPath);
+}

package/dist/search/relevance-stage.d.ts

@@ -0,0 +1,81 @@
+import { type RelevanceModelOverride, type RelevanceThresholds, type RetrievalRelevanceSummary, type RetrievalTraceSurface, type UnifiedSearchResult } from '@bendyline/gezel';
+import type { ResolvedRelevanceModel } from '../relevance/relevance-core.js';
+import type { RelevanceRunStatus, RelevanceScorer } from '../relevance/relevance-model.js';
+/**
+ * The relevance-model stage of a search: re-judge the top of the fused order
+ * with a cross-encoder, then reorder (and, for a calibrated model, drop) by
+ * what it says. Everything the search arms report is rank-derived, so this
+ * is the one place an absolute "is this on topic?" enters retrieval.
+ *
+ * Two rules keep it safe to leave on. It never holds a caller for a model
+ * load: a cold model answers `cold`, starts warming, and the results pass
+ * through untouched. And a model without calibrated thresholds may reorder
+ * but never drop — its raw scores have not been measured against anything.
+ */
+/** The model a surface scores with, as resolved from the setting or a preview override. */
+export interface ActiveRelevance {
+    model: ResolvedRelevanceModel;
+    thresholds: RelevanceThresholds | null;
+    budgetMs: number;
+    /** `flat`: order by model relevance across corpora instead of the weighted score. */
+    order: 'weighted' | 'flat';
+    /** Filter surfaces: the relevance a knowledge passage needs (default KNOWLEDGE_FILTER_MIN_RELEVANCE). */
+    knowledgeKeep?: number;
+}
+/** What SearchService needs from the relevance model manager. */
+export interface RelevanceStageProvider {
+    readonly scorer: RelevanceScorer;
+    forSurface(surface: RetrievalTraceSurface, override?: RelevanceModelOverride): Promise<ActiveRelevance | null>;
+}
+/**
+ * `filter` drops what a calibrated model scores below keep — the injection
+ * surfaces, where noise costs the model's attention. `reorder` drops only
+ * below drop — the search tool, where a weak lead is still a lead.
+ */
+export type RelevanceStageMode = 'filter' | 'reorder';
+export interface RelevanceStageRequest {
+    surface: RetrievalTraceSurface;
+    mode: RelevanceStageMode;
+    /** The text passages are judged against; the search query when absent. */
+    query?: string;
+    /** How many candidates, from the top of the fused order, are scored. */
+    window?: number;
+    /** Resolved already, or a preview's override. Absent: resolve for the surface. Null: off. */
+    active?: ActiveRelevance | null;
+    /** Wait for a cold model to load rather than pass through (calibration, warm previews). */
+    waitForLoad?: boolean;
+}
+export interface RelevanceStageReport {
+    modelId: string;
+    status: RelevanceRunStatus;
+    calibrated: boolean;
+    /** At least one candidate carries a model score, so the order is the model's. */
+    applied: boolean;
+    ms: number;
+    /** Every candidate in fused order, before the stage — what traces rank against. */
+    fused: UnifiedSearchResult[];
+    /** Activated model score per candidate id. */
+    scores: Map<string, number>;
+    /** Scored below the mode's cutoff and removed. */
+    hidden: UnifiedSearchResult[];
+}
+export declare const RELEVANCE_WINDOW: Record<RetrievalTraceSurface, number>;
+/** Test seam: forget cached scores. */
+export declare function clearRelevanceScoreCache(): void;
+/** The text a candidate is judged on: its title, then the fullest body at hand. */
+export declare function relevancePassage(result: UnifiedSearchResult, chunkText?: string): string;
+export declare function applyRelevanceModel(args: {
+    results: UnifiedSearchResult[];
+    query: string;
+    active: ActiveRelevance;
+    scorer: RelevanceScorer;
+    mode: RelevanceStageMode;
+    window: number;
+    passages: (window: UnifiedSearchResult[]) => Promise<string[]>;
+    waitForLoad?: boolean;
+}): Promise<{
+    results: UnifiedSearchResult[];
+    report: RelevanceStageReport;
+}>;
+/** The trace/history summary of a stage run. */
+export declare function relevanceSummary(report: RelevanceStageReport): RetrievalRelevanceSummary;

package/dist/search/relevance-stage.js

@@ -0,0 +1,177 @@
+import { createHash } from 'node:crypto';
+import { KNOWLEDGE_FILTER_MIN_RELEVANCE, MODEL_RELEVANCE_ANCHORS, compareSearchResults, relevanceFromModelScore, scoreResult, } from '@bendyline/gezel';
+export const RELEVANCE_WINDOW = {
+    turn: 24,
+    references: 20,
+    search: 24,
+};
+/**
+ * Characters of passage sent per candidate. A cross-encoder's cost grows
+ * with every token of every pair; a heading plus a chunk's opening is what
+ * says whether the chunk is on topic.
+ */
+const PASSAGE_CHARS = 1_000;
+const CACHE_ENTRIES = 4_096;
+const scoreCache = new Map();
+function cacheKey(modelId, query, id, passage) {
+    return createHash('sha1')
+        .update(modelId)
+        .update('\0')
+        .update(query)
+        .update('\0')
+        .update(id)
+        .update('\0')
+        .update(passage)
+        .digest('hex');
+}
+function cacheGet(key) {
+    const value = scoreCache.get(key);
+    if (value !== undefined) {
+        scoreCache.delete(key);
+        scoreCache.set(key, value);
+    }
+    return value;
+}
+function cacheSet(key, value) {
+    scoreCache.set(key, value);
+    while (scoreCache.size > CACHE_ENTRIES) {
+        const oldest = scoreCache.keys().next().value;
+        if (oldest === undefined)
+            break;
+        scoreCache.delete(oldest);
+    }
+}
+/** Test seam: forget cached scores. */
+export function clearRelevanceScoreCache() {
+    scoreCache.clear();
+}
+/** The text a candidate is judged on: its title, then the fullest body at hand. */
+export function relevancePassage(result, chunkText) {
+    const snippet = result.snippet ?? '';
+    const body = chunkText && chunkText.length > snippet.length ? chunkText : snippet;
+    const text = body || result.subtitle || '';
+    return `${result.title}\n${text}`.slice(0, PASSAGE_CHARS);
+}
+/**
+ * The cutoff in calibrated-relevance space, or null when the model may not
+ * drop. On a filter surface a knowledge passage has to clear the stricter
+ * knowledge bar: "not off topic" is enough for the user's own project, not
+ * for an encyclopedia that always has a plausible-looking neighbour.
+ */
+function cutoffFor(mode, thresholds, kind, knowledgeKeep) {
+    if (!thresholds)
+        return null;
+    if (mode === 'reorder')
+        return MODEL_RELEVANCE_ANCHORS.drop;
+    return kind === 'knowledge'
+        ? Math.max(MODEL_RELEVANCE_ANCHORS.keep, knowledgeKeep)
+        : MODEL_RELEVANCE_ANCHORS.keep;
+}
+export async function applyRelevanceModel(args) {
+    const started = performance.now();
+    const { model, thresholds } = args.active;
+    const report = (status, scores = new Map(), hidden = []) => ({
+        modelId: model.id,
+        status,
+        calibrated: thresholds !== null,
+        applied: scores.size > 0,
+        ms: Math.round(performance.now() - started),
+        fused: args.results,
+        scores,
+        hidden,
+    });
+    const readiness = args.scorer.status(model.id);
+    if (readiness === 'disabled' || readiness === 'unavailable') {
+        return { results: args.results, report: report(readiness) };
+    }
+    if (readiness !== 'ready' && !args.waitForLoad) {
+        if (readiness === 'cold')
+            void args.scorer.warm(model);
+        return { results: args.results, report: report('cold') };
+    }
+    const windowed = args.results.slice(0, args.window);
+    const tail = args.results.slice(args.window);
+    // A text judge cannot see pixels or sound: a media hit that cleared its
+    // modality's vector floor keeps its fused place rather than being judged
+    // on a caption that may be one word.
+    const toJudge = windowed.filter((result) => !isVectorMediaHit(result));
+    const texts = await args.passages(toJudge);
+    const keys = toJudge.map((result, i) => cacheKey(model.id, args.query, result.id, texts[i] ?? ''));
+    const scores = new Map();
+    const missing = [];
+    keys.forEach((key, i) => {
+        const cached = cacheGet(key);
+        if (cached === undefined)
+            missing.push(i);
+        else
+            scores.set(toJudge[i].id, cached);
+    });
+    let status = 'scored';
+    if (missing.length > 0) {
+        const spent = performance.now() - started;
+        const run = await args.scorer.score({
+            model,
+            query: args.query,
+            passages: missing.map((i) => texts[i] ?? ''),
+            budgetMs: Math.max(1, args.active.budgetMs - spent),
+            ...(args.waitForLoad ? { waitForLoad: true } : {}),
+        });
+        status = run.status;
+        run.scores?.forEach((score, j) => {
+            if (score === null || score === undefined)
+                return;
+            const i = missing[j];
+            scores.set(toJudge[i].id, score);
+            cacheSet(keys[i], score);
+        });
+    }
+    if (scores.size === 0)
+        return { results: args.results, report: report(status) };
+    const knowledgeKeep = args.active.knowledgeKeep ?? KNOWLEDGE_FILTER_MIN_RELEVANCE;
+    const judged = [];
+    const unscored = [];
+    const hidden = [];
+    for (const result of windowed) {
+        if (isVectorMediaHit(result)) {
+            judged.push(result);
+            continue;
+        }
+        const score = scores.get(result.id);
+        if (score === undefined) {
+            unscored.push(result);
+            continue;
+        }
+        const relevance = relevanceFromModelScore(score, thresholds);
+        const cutoff = cutoffFor(args.mode, thresholds, result.kind, knowledgeKeep);
+        if (cutoff !== null && relevance < cutoff) {
+            hidden.push(result);
+            continue;
+        }
+        const rescored = scoreResult(result.kind, relevance);
+        judged.push({
+            ...result,
+            ...rescored,
+            ...(args.active.order === 'flat' ? { score: rescored.relevance } : {}),
+        });
+    }
+    judged.sort(compareSearchResults);
+    return {
+        results: [...judged, ...unscored, ...tail],
+        report: report(status, scores, hidden),
+    };
+}
+/** A media row found by its own vector arm, past its modality's measured floor. */
+function isVectorMediaHit(result) {
+    return result.media !== undefined && result.arm === 'vector';
+}
+/** The trace/history summary of a stage run. */
+export function relevanceSummary(report) {
+    return {
+        modelId: report.modelId,
+        status: report.status,
+        calibrated: report.calibrated,
+        scored: report.scores.size,
+        hidden: report.hidden.length,
+        ms: report.ms,
+    };
+}