@theford/runly 0.0.0-stage → 0.20.0

package/dist/daemon/budget.d.ts

@@ -0,0 +1,155 @@
+import type { ResourceSpec } from '../core/manifest.js';
+import type { Budget } from '../core/policy.js';
+import { BrokerError } from '../core/util.js';
+export interface Cost {
+    memoryBytes: number;
+    cpu: number;
+    /** False when the manifest did not say and a default was assumed. */
+    declared: boolean;
+}
+/** What a service or appliance costs running and building — declared, or the conservative default. */
+export declare function costsOf(spec: ResourceSpec | undefined, budget: Budget): {
+    run: Cost;
+    build: Cost;
+};
+export interface NeedItem {
+    kind: 'build' | 'start' | 'appliance';
+    name: string;
+    cost: Cost;
+    /** A build that will not run (its `when:` inputs are unchanged): listed, costs nothing. */
+    skipped?: string;
+    /** Builds sharing a wave run at once and their costs add up; a build without one runs alone. */
+    wave?: number;
+}
+/**
+ * The budget refused (it can never fit, its queue is full, the wait ran out,
+ * or the caller went away). Nothing about the environment failed, so a bind
+ * refused this way must not count toward the hygiene escalation (decision 0007).
+ */
+export declare class BudgetRefusal extends BrokerError {
+}
+export interface Need {
+    items: NeedItem[];
+    /** Run resources of everything started — held for the whole operation. */
+    start: {
+        memoryBytes: number;
+        cpu: number;
+    };
+    /** The costliest build wave (builds of one wave run at once, so their costs add up) — held only while building. */
+    build: {
+        memoryBytes: number;
+        cpu: number;
+    };
+}
+export declare function needOf(items: NeedItem[]): Need;
+export declare const total: (n: Need) => {
+    memoryBytes: number;
+    cpu: number;
+};
+export interface Committed {
+    memoryBytes: number;
+    cpu: number;
+    /** One line per contributor, for a refusal or `runly plan`. */
+    items: Array<{
+        what: string;
+        memoryBytes: number;
+        cpu: number;
+    }>;
+}
+export interface Machine {
+    totalBytes: number;
+    /** Linux MemAvailable; null where the platform has no honest equivalent (macOS). */
+    availableBytes: number | null;
+    load1: number;
+    cores: number;
+    /** Linux PSI `/proc/pressure/cpu` "some" (percent of time a runnable task waited); null where absent. */
+    cpuPressure?: {
+        avg10: number;
+        avg60: number;
+    } | null;
+}
+/** Linux pressure stall information for the CPU, or null (no PSI: macOS, an old kernel, a container without it). */
+export declare function readCpuPressure(): {
+    avg10: number;
+    avg60: number;
+} | null;
+export declare function readMachine(): Machine;
+export interface Verdict {
+    fits: boolean;
+    /** Can never fit, whatever is released. */
+    impossible?: string;
+    /** What it would wait for. */
+    waitFor?: string;
+    committed: Committed;
+    machine: Machine;
+    budget: Budget;
+}
+/** One in-flight admission: its start part until released, its build part until the build phase ends. */
+export declare class Reservation {
+    readonly id: number;
+    readonly label: string;
+    start: {
+        memoryBytes: number;
+        cpu: number;
+    };
+    build: {
+        memoryBytes: number;
+        cpu: number;
+    };
+    private readonly onRelease;
+    constructor(id: number, label: string, start: {
+        memoryBytes: number;
+        cpu: number;
+    }, build: {
+        memoryBytes: number;
+        cpu: number;
+    }, onRelease: (r: Reservation) => void);
+    released: boolean;
+    readonly admittedAt: number;
+    /** The build phase is over: its share goes back. */
+    releaseBuild(): void;
+    /**
+     * One of the services this reservation starts is now running, and is
+     * counted as such (decision 0036): its share leaves the reservation, or
+     * `ps` and every other admission saw it twice until the whole bind ended.
+     */
+    consume(cost: {
+        memoryBytes: number;
+        cpu: number;
+    }): void;
+    release(): void;
+}
+export declare class LoadBudget {
+    private readonly policy;
+    private readonly committedRunning;
+    private readonly machine;
+    private reservations;
+    private queue;
+    private ticket;
+    /** A moving estimate of how long an admission is held, for the queue ETA. */
+    private holdMs;
+    constructor(policy: () => Budget, committedRunning: () => Committed, machine?: () => Machine);
+    /** Running services plus every in-flight reservation. */
+    committed(): Committed;
+    /** Would `need` be admitted right now (ignoring the queue)? `skipLoadGate`: a wake of a recently running service. */
+    check(need: Need, opts?: {
+        skipLoadGate?: boolean;
+    }): Verdict;
+    /** Queue position (1-based) of a label, for `runly plan`. */
+    queueLength(): number;
+    /**
+     * Wait until `need` fits and it is this request's turn; returns the
+     * reservation, which the caller MUST release. Fails clearly when the need
+     * can never fit, the queue is full, or the wait runs out.
+     */
+    admit(need: Need, label: string, opts?: {
+        onWait?: (position: number, etaMs: number, waitFor: string) => void;
+        waitMs?: number;
+        source?: string;
+        /** The caller went away: a queued request is dropped instead of binding for nobody. */
+        signal?: AbortSignal;
+        /** A wake of a service that ran recently: the CPU gate is skipped, memory still applies. */
+        skipLoadGate?: boolean;
+    }): Promise<Reservation>;
+    private reserve;
+}

package/dist/daemon/budget.js

@@ -0,0 +1,288 @@
+/**
+ * The server-wide load budget (decision 0036).
+ *
+ * Every `up` (and every start on demand) states what it needs before it
+ * builds or starts anything: the run resources of each service and appliance
+ * it will start, plus its builds — those of one dependency wave run at once, so
+ * the costliest wave's SUM is what is held, and only while it builds. A start's
+ * share is handed back as each service starts (from then on the running service
+ * itself is counted). The budget admits it when
+ *
+ *   - what runly has committed (running services' and in-flight builds'
+ *     declared resources, across every stack this daemon serves) plus the
+ *     need fits under the memory and cpu budget, and
+ *   - on Linux, MemAvailable minus the need stays above the reserve (work
+ *     that is not runly's — another daemon, a human's IDE), and
+ *   - the CPU is not saturated: on Linux with PSI, `/proc/pressure/cpu`
+ *     "some" is below `cpuPressure` percent over BOTH the last 10 s and the
+ *     last 60 s (a sustained stall, not a spike that is already over);
+ *     elsewhere the 1-minute load average is below `loadPerCore` x cores. A
+ *     wake of a service that ran recently skips this gate (the memory gates
+ *     still apply): it resumes what the box already carried.
+ *
+ * Otherwise the request queues, FIFO, with its position and an estimate, for
+ * at most `waitMs`, and then fails with what it waited for. A need of nothing
+ * (every build skipped, nothing to start) never queues. A need that can never
+ * fit (bigger than the whole budget) fails at once. Idle-stopped services
+ * release their share by no longer running. A refusal is a BudgetRefusal: the
+ * environment did not fail, so it never counts toward hygiene escalation.
+ */
+import { readFileSync } from 'node:fs';
+import { cpus, loadavg, totalmem } from 'node:os';
+import { BrokerError } from '../core/util.js';
+import { formatDuration, formatSize, parseSize } from '../core/units.js';
+/** What a service or appliance costs running and building — declared, or the conservative default. */
+export function costsOf(spec, budget) {
+    const runMem = parseSize(spec?.memory);
+    const buildMem = parseSize(spec?.build?.memory);
+    return {
+        run: {
+            memoryBytes: runMem ?? budget.defaultRun.memoryBytes,
+            cpu: spec?.cpu ?? budget.defaultRun.cpu,
+            declared: runMem !== undefined && spec?.cpu !== undefined,
+        },
+        build: {
+            memoryBytes: buildMem ?? budget.defaultBuild.memoryBytes,
+            cpu: spec?.build?.cpu ?? budget.defaultBuild.cpu,
+            declared: buildMem !== undefined && spec?.build?.cpu !== undefined,
+        },
+    };
+}
+/**
+ * The budget refused (it can never fit, its queue is full, the wait ran out,
+ * or the caller went away). Nothing about the environment failed, so a bind
+ * refused this way must not count toward the hygiene escalation (decision 0007).
+ */
+export class BudgetRefusal extends BrokerError {
+}
+export function needOf(items) {
+    const start = { memoryBytes: 0, cpu: 0 };
+    const waves = new Map();
+    items.forEach((it, i) => {
+        if (it.skipped)
+            return;
+        if (it.kind === 'build') {
+            const key = it.wave === undefined ? `solo:${i}` : `wave:${it.wave}`;
+            const w = waves.get(key) ?? { memoryBytes: 0, cpu: 0 };
+            w.memoryBytes += it.cost.memoryBytes;
+            w.cpu += it.cost.cpu;
+            waves.set(key, w);
+        }
+        else {
+            start.memoryBytes += it.cost.memoryBytes;
+            start.cpu += it.cost.cpu;
+        }
+    });
+    const build = { memoryBytes: 0, cpu: 0 };
+    for (const w of waves.values()) {
+        build.memoryBytes = Math.max(build.memoryBytes, w.memoryBytes);
+        build.cpu = Math.max(build.cpu, w.cpu);
+    }
+    return { items, start, build };
+}
+export const total = (n) => ({ memoryBytes: n.start.memoryBytes + n.build.memoryBytes, cpu: n.start.cpu + n.build.cpu });
+/** Linux pressure stall information for the CPU, or null (no PSI: macOS, an old kernel, a container without it). */
+export function readCpuPressure() {
+    if (process.platform !== 'linux')
+        return null;
+    try {
+        const line = readFileSync('/proc/pressure/cpu', 'utf8').split('\n').find((l) => l.startsWith('some '));
+        const avg10 = Number(/avg10=([\d.]+)/.exec(line ?? '')?.[1]);
+        const avg60 = Number(/avg60=([\d.]+)/.exec(line ?? '')?.[1]);
+        return Number.isFinite(avg10) && Number.isFinite(avg60) ? { avg10, avg60 } : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function readMachine() {
+    let availableBytes = null;
+    if (process.platform === 'linux') {
+        try {
+            const kb = /MemAvailable:\s+(\d+)\s+kB/.exec(readFileSync('/proc/meminfo', 'utf8'))?.[1];
+            if (kb !== undefined)
+                availableBytes = Number(kb) * 1024;
+        }
+        catch {
+            /* unreadable: the accounting half still applies */
+        }
+    }
+    return { totalBytes: totalmem(), availableBytes, load1: loadavg()[0] ?? 0, cores: cpus().length || 1, cpuPressure: readCpuPressure() };
+}
+/** One in-flight admission: its start part until released, its build part until the build phase ends. */
+export class Reservation {
+    id;
+    label;
+    start;
+    build;
+    onRelease;
+    constructor(id, label, start, build, onRelease) {
+        this.id = id;
+        this.label = label;
+        this.start = start;
+        this.build = build;
+        this.onRelease = onRelease;
+    }
+    released = false;
+    admittedAt = Date.now();
+    /** The build phase is over: its share goes back. */
+    releaseBuild() {
+        this.build = { memoryBytes: 0, cpu: 0 };
+    }
+    /**
+     * One of the services this reservation starts is now running, and is
+     * counted as such (decision 0036): its share leaves the reservation, or
+     * `ps` and every other admission saw it twice until the whole bind ended.
+     */
+    consume(cost) {
+        this.start = {
+            memoryBytes: Math.max(0, this.start.memoryBytes - cost.memoryBytes),
+            cpu: Math.max(0, this.start.cpu - cost.cpu),
+        };
+    }
+    release() {
+        if (this.released)
+            return;
+        this.released = true;
+        this.onRelease(this);
+    }
+}
+export class LoadBudget {
+    policy;
+    committedRunning;
+    machine;
+    reservations = new Map();
+    queue = [];
+    ticket = 0;
+    /** A moving estimate of how long an admission is held, for the queue ETA. */
+    holdMs = 60_000;
+    constructor(policy, committedRunning, machine = readMachine) {
+        this.policy = policy;
+        this.committedRunning = committedRunning;
+        this.machine = machine;
+    }
+    /** Running services plus every in-flight reservation. */
+    committed() {
+        const base = this.committedRunning();
+        const items = [...base.items];
+        let memoryBytes = base.memoryBytes;
+        let cpu = base.cpu;
+        for (const r of this.reservations.values()) {
+            const m = r.start.memoryBytes + r.build.memoryBytes;
+            const c = r.start.cpu + r.build.cpu;
+            if (m === 0 && c === 0)
+                continue;
+            memoryBytes += m;
+            cpu += c;
+            items.push({ what: `in flight: ${r.label}`, memoryBytes: m, cpu: c });
+        }
+        return { memoryBytes, cpu, items };
+    }
+    /** Would `need` be admitted right now (ignoring the queue)? `skipLoadGate`: a wake of a recently running service. */
+    check(need, opts = {}) {
+        const budget = this.policy();
+        const committed = this.committed();
+        const machine = this.machine();
+        const want = total(need);
+        if (!budget.enabled || (want.memoryBytes === 0 && want.cpu === 0))
+            return { fits: true, committed, machine, budget };
+        if (want.memoryBytes > budget.memoryBytes) {
+            return { fits: false, impossible: `it needs ${formatSize(want.memoryBytes)} of memory and the whole budget is ${formatSize(budget.memoryBytes)} (BACKLOT_BUDGET_MEMORY)`, committed, machine, budget };
+        }
+        if (want.cpu > budget.cpu) {
+            return { fits: false, impossible: `it needs ${want.cpu} cpu and the whole budget is ${budget.cpu} (BACKLOT_BUDGET_CPU)`, committed, machine, budget };
+        }
+        const reasons = [];
+        if (committed.memoryBytes + want.memoryBytes > budget.memoryBytes) {
+            reasons.push(`memory: needs ${formatSize(want.memoryBytes)}, the budget has ${formatSize(Math.max(0, budget.memoryBytes - committed.memoryBytes))} of ${formatSize(budget.memoryBytes)} free (runly has committed ${formatSize(committed.memoryBytes)})`);
+        }
+        if (committed.cpu + want.cpu > budget.cpu) {
+            reasons.push(`cpu: needs ${round(want.cpu)}, the budget has ${round(Math.max(0, budget.cpu - committed.cpu))} of ${round(budget.cpu)} free`);
+        }
+        if (machine.availableBytes !== null && machine.availableBytes - want.memoryBytes < budget.reserveBytes) {
+            reasons.push(`free memory: the box has ${formatSize(machine.availableBytes)} available and keeps ${formatSize(budget.reserveBytes)} in reserve (BACKLOT_BUDGET_RESERVE)`);
+        }
+        if (!opts.skipLoadGate) {
+            const psi = machine.cpuPressure ?? null;
+            if (psi) {
+                // PSI says what load average only hints at: how much of the time
+                // runnable work actually WAITED for a CPU. Both windows must be over
+                // the threshold, so a spike that is already over does not hold anyone.
+                if (budget.cpuPressure < 100 && psi.avg10 >= budget.cpuPressure && psi.avg60 >= budget.cpuPressure) {
+                    reasons.push(`cpu pressure: runnable work waited ${psi.avg10.toFixed(0)}% of the last 10s and ${psi.avg60.toFixed(0)}% of the last minute (limit ${budget.cpuPressure}%, BACKLOT_BUDGET_CPU_PRESSURE)`);
+                }
+            }
+            else if (machine.load1 > budget.loadPerCore * machine.cores) {
+                reasons.push(`load: ${machine.load1.toFixed(1)} on ${machine.cores} cores is above ${budget.loadPerCore} per core (BACKLOT_BUDGET_LOAD_PER_CORE)`);
+            }
+        }
+        return { fits: reasons.length === 0, waitFor: reasons.join('; ') || undefined, committed, machine, budget };
+    }
+    /** Queue position (1-based) of a label, for `runly plan`. */
+    queueLength() {
+        return this.queue.length;
+    }
+    /**
+     * Wait until `need` fits and it is this request's turn; returns the
+     * reservation, which the caller MUST release. Fails clearly when the need
+     * can never fit, the queue is full, or the wait runs out.
+     */
+    async admit(need, label, opts = {}) {
+        const budget = this.policy();
+        const source = opts.source ?? 'budget';
+        const gone = () => new BudgetRefusal('env-error', `'${label}' was dropped from the load budget's queue: its caller disconnected`, source);
+        if (opts.signal?.aborted)
+            throw gone();
+        const want = total(need);
+        // Nothing to build or start costs nothing: it never waits behind anyone.
+        if (want.memoryBytes === 0 && want.cpu === 0)
+            return this.reserve(need, label);
+        const first = this.check(need, opts);
+        if (first.impossible) {
+            throw new BudgetRefusal('env-error', `the load budget can never admit '${label}': ${first.impossible}. Declare smaller resources: in the manifest or raise the budget (decision 0036)`, source);
+        }
+        if (this.queue.length === 0 && first.fits)
+            return this.reserve(need, label);
+        if (this.queue.length >= budget.maxQueue) {
+            throw new BudgetRefusal('env-error', `the load budget's queue is full (${this.queue.length} waiting, BACKLOT_BUDGET_MAX_QUEUE) — '${label}' was not queued; retry later`, source);
+        }
+        const ticket = ++this.ticket;
+        this.queue.push({ ticket, label });
+        const started = Date.now();
+        const limit = opts.waitMs ?? budget.waitMs;
+        let lastBeat = 0;
+        try {
+            for (;;) {
+                if (opts.signal?.aborted)
+                    throw gone();
+                const position = this.queue.findIndex((q) => q.ticket === ticket) + 1;
+                const verdict = this.check(need, opts);
+                if (position === 1 && verdict.fits)
+                    return this.reserve(need, label);
+                const waitFor = position > 1 ? `${position - 1} request(s) ahead in the queue${verdict.waitFor ? `; ${verdict.waitFor}` : ''}` : (verdict.waitFor ?? 'its turn');
+                if (Date.now() - started > limit) {
+                    throw new BudgetRefusal('env-error', `waited ${formatDuration(Date.now() - started)} for the load budget and '${label}' still does not fit — ${waitFor}. ` +
+                        `Stop what you do not need ('runly down', 'runly ps --all' shows what runs), or raise the budget (BACKLOT_BUDGET_MEMORY, BACKLOT_BUDGET_CPU; decision 0036)`, source);
+                }
+                if (opts.onWait && Date.now() - lastBeat >= 1000) {
+                    lastBeat = Date.now();
+                    opts.onWait(position, Math.max(1000, position * this.holdMs - (Date.now() - started)), waitFor);
+                }
+                await new Promise((r) => setTimeout(r, 250));
+            }
+        }
+        finally {
+            this.queue = this.queue.filter((q) => q.ticket !== ticket);
+        }
+    }
+    reserve(need, label) {
+        const r = new Reservation(++this.ticket, label, { ...need.start }, { ...need.build }, (done) => {
+            this.reservations.delete(done.id);
+            this.holdMs = Math.round(this.holdMs * 0.7 + (Date.now() - done.admittedAt) * 0.3);
+        });
+        this.reservations.set(r.id, r);
+        return r;
+    }
+}
+const round = (n) => Math.round(n * 10) / 10;
+//# sourceMappingURL=budget.js.map

package/dist/daemon/budget.js.map

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

package/dist/daemon/election.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Try to become the daemon for this state root.
+ *
+ * Returns true if we own it and may proceed to bind the socket, false if a
+ * live daemon already holds it and we should concede.
+ */
+export declare function electSelf(path?: string): boolean;
+/** Release the lock, but only if it is still ours. */
+export declare function releaseSelf(path?: string): void;

package/dist/daemon/election.js

@@ -0,0 +1,140 @@
+/**
+ * Daemon singleton election.
+ *
+ * The socket cannot elect a leader by itself. A daemon that finds a socket file
+ * must decide whether it is live or a leftover from a crash, and the only way
+ * to answer that is to ping it — but between the ping and the bind, a second
+ * daemon can win the socket, and unlinking "the stale socket" then deletes a
+ * LIVE one. Both daemons end up bound, both sweep the same journal, and each
+ * reaps the other's processes.
+ *
+ * So election happens on a lock file first, using the same identity rule as
+ * process reclaim (decision 0019): a holder is real only if its recorded pid
+ * AND start time still match a live process. Only the winner is allowed to
+ * touch the socket.
+ */
+import { openSync, writeSync, closeSync, readFileSync, renameSync, rmSync, unlinkSync, statSync } from 'node:fs';
+import { lockPath } from '../core/paths.js';
+import { sameProcess, startTime } from '../core/procscan.js';
+const readClaim = (path) => {
+    try {
+        const raw = JSON.parse(readFileSync(path, 'utf8'));
+        return typeof raw?.pid === 'number' ? raw : undefined;
+    }
+    catch {
+        return undefined; // absent, truncated, or mid-write
+    }
+};
+const selfClaim = () => ({ pid: process.pid, startTime: startTime(process.pid) });
+/** Is this claim held by a process that is genuinely still running? */
+function claimIsLive(claim) {
+    if (!claim)
+        return false;
+    if (claim.pid === process.pid)
+        return false; // our own stale lock from a previous life
+    return sameProcess(claim.pid, claim.startTime);
+}
+/** Was this lock written within the last few seconds? */
+function recentlyTouched(path, withinMs = 3000) {
+    try {
+        return Date.now() - statSync(path).mtimeMs < withinMs;
+    }
+    catch {
+        return false;
+    }
+}
+/** Deliberately synchronous: election runs before the daemon serves anything. */
+function sleepMs(ms) {
+    const until = Date.now() + ms;
+    while (Date.now() < until) {
+        /* spin briefly */
+    }
+}
+/**
+ * Try to become the daemon for this state root.
+ *
+ * Returns true if we own it and may proceed to bind the socket, false if a
+ * live daemon already holds it and we should concede.
+ */
+export function electSelf(path = lockPath()) {
+    for (let attempt = 0; attempt < 5; attempt++) {
+        // Build the payload BEFORE creating the file. Computing it afterwards left
+        // the lock existing but EMPTY for as long as the claim took to assemble —
+        // and on platforms where identity comes from `ps` that is tens of
+        // milliseconds. A racing daemon read the empty file, concluded the holder
+        // was dead, stole the lock, and both ended up bound.
+        const claim = JSON.stringify(selfClaim());
+        try {
+            const fd = openSync(path, 'wx', 0o600);
+            try {
+                writeSync(fd, claim);
+            }
+            finally {
+                closeSync(fd);
+            }
+            return true;
+        }
+        catch (err) {
+            if (err.code !== 'EEXIST')
+                throw err;
+        }
+        const held = readClaim(path);
+        if (claimIsLive(held))
+            return false; // a real daemon owns this state root
+        // An unreadable lock that was just touched is a claim mid-write, not a
+        // stale one. Give the writer a moment rather than racing it.
+        if (!held && recentlyTouched(path)) {
+            sleepMs(50);
+            if (claimIsLive(readClaim(path)))
+                return false;
+        }
+        // The holder is dead (or the file is corrupt). Break the lock by writing a
+        // fresh claim to a private path and renaming it over the lock — rename is
+        // atomic, so concurrent breakers cannot interleave a partial file. Several
+        // may rename; the last one wins, and everyone re-reads to find out who that
+        // was. Only the process that reads its own pid back proceeds.
+        const tmp = `${path}.${process.pid}`;
+        try {
+            const fd = openSync(tmp, 'w', 0o600);
+            try {
+                writeSync(fd, JSON.stringify(selfClaim()));
+            }
+            finally {
+                closeSync(fd);
+            }
+            renameSync(tmp, path);
+        }
+        catch {
+            try {
+                rmSync(tmp, { force: true });
+            }
+            catch {
+                /* best-effort */
+            }
+            continue;
+        }
+        const now = readClaim(path);
+        if (now?.pid === process.pid)
+            return true;
+        if (claimIsLive(now))
+            return false;
+        // Another breaker won the rename but has since died — go round again.
+    }
+    // Contention that never settled. Conceding is the safe answer: a missing
+    // daemon is a clear error the client reports, whereas two daemons corrupt
+    // shared state silently.
+    return false;
+}
+/** Release the lock, but only if it is still ours. */
+export function releaseSelf(path = lockPath()) {
+    const held = readClaim(path);
+    if (held?.pid !== process.pid)
+        return;
+    try {
+        unlinkSync(path);
+    }
+    catch {
+        /* already gone */
+    }
+}
+//# sourceMappingURL=election.js.map

package/dist/daemon/election.js.map

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