@danypops/vehicle-core 0.18.2 → 0.18.4

package/dist/resource-pool/bounded-resource-pool.js

@@ -0,0 +1,427 @@
+import { ResourceAdmissionQueueFull, ResourceAdmissionQueueTimedOut, ResourceCapacityExceeded, ResourceInUse } from "./errors.js";
+export { ResourceAdmissionQueueFull, ResourceAdmissionQueueTimedOut, ResourceCapacityExceeded, ResourceInUse };
+const DEFAULT_MAX_ACTIVE = 3;
+/** A genuine structural ceiling on resource count -- independent of memory, protecting against pathological OS-level exhaustion (file descriptors, threads, scheduler overhead) that no amount of available headroom makes safe to exceed. maxActive itself can never be raised past this by a resource policy's own soft ceiling. */
+const DEFAULT_ABSOLUTE_MAX_ACTIVE = 32;
+const DEFAULT_BACKGROUND_ADMISSION_QUEUE_TIMEOUT_MS = 10_000;
+const DEFAULT_MAX_QUEUED_BACKGROUND_ADMISSIONS = 8;
+/**
+ * Internal signal only: admit() throws this to tell acquire() "release the serialized lock and
+ * wait outside it" -- never surfaced to a caller. Waiting for a background admission's turn can
+ * legitimately take seconds; holding admissionTail (the single global admission mutex) for that
+ * whole span would block every OTHER admission request, including foreground's, which is exactly
+ * the starvation this exists to prevent.
+ */
+class NeedsBackgroundAdmissionWait extends Error {
+}
+/**
+ * Owns the bounded lifecycle of pooled, expensive, stateful resources partitioned by an
+ * (ownerKey, partitionKey) pair -- e.g. one warm language-server process per (workspace,
+ * language), one warm browser context per (tenant, profile). Never knows how to build a resource:
+ * `acquire()` takes a lazy factory invoked only on an actual cache miss, so every caller-specific
+ * concept (what a resource even is, how to construct one) lives entirely in the caller's own
+ * closure at each call site.
+ */
+export class BoundedResourcePool {
+    options;
+    entries = new Map();
+    now;
+    maxActive;
+    absoluteMaxActive;
+    lastActiveCeilingSource = "configured";
+    lastEffectiveMaxActive;
+    partitionLimits;
+    admissionTail = Promise.resolve();
+    nextSequence = 0;
+    reservedForegroundSlots;
+    backgroundAdmissionQueueTimeoutMs;
+    maxQueuedBackgroundAdmissions;
+    admissionWaiters = new Set();
+    queuedBackgroundAdmissions = 0;
+    waitingCounts = new Map();
+    constructor(options = {}) {
+        this.options = options;
+        this.now = options.now ?? Date.now;
+        this.maxActive = options.maxActive ?? DEFAULT_MAX_ACTIVE;
+        this.partitionLimits = options.partitionLimits ?? {};
+        if (!Number.isSafeInteger(this.maxActive) || this.maxActive < 1)
+            throw new TypeError("maxActive must be a positive safe integer");
+        this.absoluteMaxActive = options.absoluteMaxActive ?? Math.max(DEFAULT_ABSOLUTE_MAX_ACTIVE, this.maxActive);
+        if (!Number.isSafeInteger(this.absoluteMaxActive) || this.absoluteMaxActive < this.maxActive) {
+            throw new TypeError("absoluteMaxActive must be a safe integer no smaller than maxActive");
+        }
+        this.lastEffectiveMaxActive = this.maxActive;
+        for (const [partitionKey, limit] of Object.entries(this.partitionLimits)) {
+            if (!partitionKey || !Number.isSafeInteger(limit) || limit < 1)
+                throw new TypeError("partition limits must be positive safe integers keyed by partition key");
+        }
+        this.reservedForegroundSlots = options.reservedForegroundSlots ?? 0;
+        if (!Number.isSafeInteger(this.reservedForegroundSlots) || this.reservedForegroundSlots < 0) {
+            throw new TypeError("reservedForegroundSlots must be a non-negative safe integer");
+        }
+        this.backgroundAdmissionQueueTimeoutMs = options.backgroundAdmissionQueueTimeoutMs ?? DEFAULT_BACKGROUND_ADMISSION_QUEUE_TIMEOUT_MS;
+        if (!Number.isSafeInteger(this.backgroundAdmissionQueueTimeoutMs) || this.backgroundAdmissionQueueTimeoutMs < 0) {
+            throw new TypeError("backgroundAdmissionQueueTimeoutMs must be a non-negative safe integer");
+        }
+        this.maxQueuedBackgroundAdmissions = options.maxQueuedBackgroundAdmissions ?? DEFAULT_MAX_QUEUED_BACKGROUND_ADMISSIONS;
+        if (!Number.isSafeInteger(this.maxQueuedBackgroundAdmissions) || this.maxQueuedBackgroundAdmissions < 1) {
+            throw new TypeError("maxQueuedBackgroundAdmissions must be a positive safe integer");
+        }
+    }
+    key(ownerKey, partitionKey) {
+        return `${ownerKey}:${partitionKey}`;
+    }
+    partitionLimit(partitionKey) {
+        return this.partitionLimits[partitionKey] ?? this.maxActive;
+    }
+    countPartition(partitionKey) {
+        let count = 0;
+        for (const entry of this.entries.values())
+            if (entry.partitionKey === partitionKey)
+                count++;
+        return count;
+    }
+    activePartitions() {
+        return Array.from(this.entries.values(), (entry) => entry.partitionKey);
+    }
+    leastRecentlyUsedIdle(partitionKey) {
+        let selected;
+        for (const candidate of this.entries) {
+            const entry = candidate[1];
+            if (entry.activeLeases > 0 || (partitionKey !== undefined && entry.partitionKey !== partitionKey))
+                continue;
+            const current = selected?.[1];
+            if (!current ||
+                entry.lastUsedAt < current.lastUsedAt ||
+                (entry.lastUsedAt === current.lastUsedAt && entry.recencySequence < current.recencySequence))
+                selected = candidate;
+        }
+        return selected;
+    }
+    async evict(entry, reason = "admission") {
+        try {
+            await entry[1].resource.close();
+        }
+        catch (error) {
+            this.options.observe?.({
+                kind: "close-failed",
+                reason,
+                partitionKey: entry[1].partitionKey,
+                errorName: error instanceof Error ? error.name : "UnknownError",
+            });
+            throw error;
+        }
+        this.entries.delete(entry[0]);
+        const kind = reason === "admission" ? "admission-evicted" : reason === "dead-replacement" ? "dead-replaced" : "resource-pressure-evicted";
+        this.options.observe?.({ kind, partitionKey: entry[1].partitionKey });
+        this.notifyAdmissionWaiters();
+    }
+    /** Wakes every queued background admission to re-check the real state -- called whenever an entry is removed OR a lease completes (an idle candidate an admit() retry might now be able to evict). A false wake just re-checks and re-waits; never a correctness issue, only a wasted retry. */
+    notifyAdmissionWaiters() {
+        if (this.admissionWaiters.size === 0)
+            return;
+        const waiters = Array.from(this.admissionWaiters);
+        this.admissionWaiters.clear();
+        for (const waiter of waiters)
+            waiter();
+    }
+    /** True while at least one background admission for this owner is currently waiting for a reserved-slot conflict to clear. */
+    waitingForAdmission(ownerKey) {
+        return (this.waitingCounts.get(ownerKey) ?? 0) > 0;
+    }
+    /**
+     * Runs entirely outside the serialized admission lock -- admissionTail is the single global
+     * admission mutex, and this wait can legitimately take up to backgroundAdmissionQueueTimeoutMs.
+     * Holding that lock for the whole wait would block every other admission request, foreground
+     * included, which is the exact starvation this exists to prevent.
+     */
+    async waitForAdmissionRoom(partitionKey, ownerKey) {
+        if (this.queuedBackgroundAdmissions >= this.maxQueuedBackgroundAdmissions) {
+            throw new ResourceAdmissionQueueFull(partitionKey, this.maxQueuedBackgroundAdmissions);
+        }
+        this.queuedBackgroundAdmissions++;
+        this.waitingCounts.set(ownerKey, (this.waitingCounts.get(ownerKey) ?? 0) + 1);
+        try {
+            const gotSignal = await new Promise((resolve) => {
+                let settled = false;
+                const finish = (ready) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    clearTimeout(timer);
+                    this.admissionWaiters.delete(onSignal);
+                    resolve(ready);
+                };
+                const onSignal = () => finish(true);
+                const timer = setTimeout(() => finish(false), this.backgroundAdmissionQueueTimeoutMs);
+                this.admissionWaiters.add(onSignal);
+            });
+            if (!gotSignal)
+                throw new ResourceAdmissionQueueTimedOut(partitionKey, this.backgroundAdmissionQueueTimeoutMs);
+        }
+        finally {
+            this.queuedBackgroundAdmissions--;
+            const remaining = (this.waitingCounts.get(ownerKey) ?? 1) - 1;
+            if (remaining <= 0)
+                this.waitingCounts.delete(ownerKey);
+            else
+                this.waitingCounts.set(ownerKey, remaining);
+        }
+    }
+    async admit(ownerKey, partitionKey, create, workKind) {
+        const partitionLimit = this.partitionLimit(partitionKey);
+        while (this.countPartition(partitionKey) >= partitionLimit) {
+            const victim = this.leastRecentlyUsedIdle(partitionKey);
+            if (!victim)
+                throw new ResourceCapacityExceeded(partitionKey, this.maxActive, partitionLimit);
+            await this.evict(victim);
+        }
+        const { ceiling: baseCeiling, source: ceilingSource } = this.baseActiveCeiling();
+        this.lastEffectiveMaxActive = baseCeiling;
+        this.lastActiveCeilingSource = ceilingSource;
+        // "Borrowable": background's own effective ceiling is reduced, but only background is ever
+        // held to it -- it constrains what background alone can grow the pool into, not a hard
+        // set-aside nothing else can reach. Foreground keeps using the full (possibly resource-
+        // budget-raised) baseCeiling unchanged.
+        const effectiveMaxActive = workKind === "background" ? Math.max(baseCeiling - this.reservedForegroundSlots, 0) : baseCeiling;
+        while (this.entries.size >= effectiveMaxActive) {
+            const victim = this.leastRecentlyUsedIdle();
+            if (victim) {
+                await this.evict(victim);
+                continue;
+            }
+            if (workKind === "background")
+                throw new NeedsBackgroundAdmissionWait();
+            throw new ResourceCapacityExceeded(partitionKey, baseCeiling, partitionLimit);
+        }
+        while (this.options.resourcePolicy && !this.options.resourcePolicy.canAdmit(this.activePartitions(), partitionKey)) {
+            const victim = this.leastRecentlyUsedIdle();
+            if (!victim)
+                throw new ResourceCapacityExceeded(partitionKey, baseCeiling, partitionLimit);
+            await this.evict(victim, "resource-pressure");
+        }
+        return {
+            resource: create(),
+            ownerKey,
+            partitionKey,
+            recencySequence: this.nextSequence++,
+            activeLeases: 0,
+            lastUsedAt: this.now(),
+        };
+    }
+    async serialized(operation) {
+        const previous = this.admissionTail;
+        let release = () => { };
+        this.admissionTail = new Promise((resolve) => {
+            release = resolve;
+        });
+        await previous;
+        try {
+            return await operation();
+        }
+        finally {
+            release();
+        }
+    }
+    /** Acquires a lease for (ownerKey, partitionKey), reusing an already-admitted resource if one is warm, or admitting a fresh one via `create()` -- called only on an actual cache miss, never speculatively. workKind defaults to "foreground". */
+    async acquire(ownerKey, partitionKey, create, workKind = "foreground") {
+        for (;;) {
+            try {
+                const entry = await this.serialized(async () => {
+                    const key = this.key(ownerKey, partitionKey);
+                    let entry = this.entries.get(key);
+                    if (entry?.resource.isAlive?.() === false) {
+                        if (entry.activeLeases > 0) {
+                            throw new ResourceCapacityExceeded(partitionKey, this.maxActive, this.partitionLimit(partitionKey));
+                        }
+                        await this.evict([key, entry], "dead-replacement");
+                        entry = undefined;
+                    }
+                    if (!entry) {
+                        entry = await this.admit(ownerKey, partitionKey, create, workKind);
+                        this.entries.set(key, entry);
+                    }
+                    entry.activeLeases++;
+                    return entry;
+                });
+                return this.lease(entry.resource, [entry]);
+            }
+            catch (error) {
+                if (!(error instanceof NeedsBackgroundAdmissionWait))
+                    throw error;
+                // Outside the lock deliberately -- see waitForAdmissionRoom's own comment. Throws
+                // ResourceAdmissionQueueFull/TimedOut instead of looping back if it can't wait.
+                await this.waitForAdmissionRoom(partitionKey, ownerKey);
+            }
+        }
+    }
+    lease(value, entries) {
+        let released = false;
+        return {
+            value,
+            [Symbol.asyncDispose]: async () => {
+                if (released)
+                    return;
+                released = true;
+                const completedAt = this.now();
+                for (const entry of entries) {
+                    entry.activeLeases--;
+                    entry.lastUsedAt = completedAt;
+                    entry.recencySequence = this.nextSequence++;
+                }
+                // A lease completing makes its entry newly idle -- exactly the condition a queued
+                // background admission's retry is waiting to find, whether or not resource pressure
+                // itself ends up evicting anything below.
+                this.notifyAdmissionWaiters();
+                await this.reconcileResources();
+            },
+        };
+    }
+    has(ownerKey, partitionKey) {
+        return this.entries.has(this.key(ownerKey, partitionKey));
+    }
+    hasAny(ownerKey) {
+        for (const entry of this.entries.values())
+            if (entry.ownerKey === ownerKey)
+                return true;
+        return false;
+    }
+    /** Every currently active resource belonging to `ownerKey` -- lets a caller's own fan-out (file-watch notifications, etc) stay pool-backed instead of duplicating the entry map. */
+    activeResourcesForOwner(ownerKey) {
+        const resources = [];
+        for (const entry of this.entries.values())
+            if (entry.ownerKey === ownerKey)
+                resources.push(entry.resource);
+        return resources;
+    }
+    /**
+     * Derives the count ceiling actually in effect right now, independent of any particular
+     * admission attempt -- the resource policy's own soft ceiling raises maxActive when it reports
+     * more room, clamped to absoluteMaxActive, and falls back to maxActive alone (source
+     * "configured") on any metric loss -- fails closed, never treated as "unlimited room."
+     */
+    baseActiveCeiling() {
+        const soft = this.options.resourcePolicy?.softActiveCeiling(this.activePartitions());
+        if (soft === undefined || !Number.isFinite(soft) || soft <= this.maxActive)
+            return { ceiling: this.maxActive, source: "configured" };
+        const clamped = Math.min(Math.floor(soft), this.absoluteMaxActive);
+        return { ceiling: clamped, source: clamped >= this.absoluteMaxActive ? "absolute-cap" : "resource-budget" };
+    }
+    status() {
+        const byPartition = {};
+        let leased = 0;
+        for (const entry of this.entries.values()) {
+            byPartition[entry.partitionKey] = (byPartition[entry.partitionKey] ?? 0) + 1;
+            if (entry.activeLeases > 0)
+                leased++;
+        }
+        const resources = this.options.resourcePolicy?.status(this.activePartitions());
+        return {
+            active: this.entries.size,
+            leased,
+            maxActive: this.maxActive,
+            effectiveMaxActive: this.lastEffectiveMaxActive,
+            activeCeilingSource: this.lastActiveCeilingSource,
+            absoluteMaxActive: this.absoluteMaxActive,
+            byPartition,
+            waitingBackgroundAdmissions: this.queuedBackgroundAdmissions,
+            ...(resources !== undefined ? { resources } : {}),
+        };
+    }
+    /** Samples every currently active entry with a real costHandle and folds it into the configured recorder, if any -- a no-op without one. Read-only over the entry map, so it deliberately does not run inside serialized(). */
+    calibrateCosts() {
+        const recorder = this.options.costRecorder;
+        if (!recorder)
+            return;
+        for (const entry of this.entries.values()) {
+            if (entry.resource.costHandle === undefined)
+                continue;
+            recorder.recordSample(entry.partitionKey, entry.resource.costHandle);
+        }
+    }
+    /** Unconditional force-close of every one of `ownerKey`'s resources, regardless of any active lease -- for the case of a remote resource swapped out from under an already-warm one, where correctness requires closing regardless of who still holds it. */
+    async closeOwner(ownerKey) {
+        const stale = Array.from(this.entries.entries()).filter(([, entry]) => entry.ownerKey === ownerKey);
+        for (const [key] of stale)
+            this.entries.delete(key);
+        await Promise.all(stale.map(([, entry]) => entry.resource.close()));
+    }
+    /** Unconditional force-close of one (ownerKey, partitionKey) resource, if any -- the single-partition sibling of closeOwner, for a caller that has already identified exactly which partition needs invalidating. */
+    async closePartition(ownerKey, partitionKey) {
+        const key = this.key(ownerKey, partitionKey);
+        const entry = this.entries.get(key);
+        if (!entry)
+            return;
+        this.entries.delete(key);
+        await entry.resource.close();
+    }
+    /**
+     * The safe sibling of closeOwner: refuses (does not evict anything) while any of this owner's
+     * resources has an active lease. Serialized against concurrent admission so a lease can't be
+     * granted between the check and the close.
+     */
+    async releaseOwnerIfIdle(ownerKey) {
+        return this.serialized(async () => {
+            const matching = Array.from(this.entries.entries()).filter(([, entry]) => entry.ownerKey === ownerKey);
+            if (matching.some(([, entry]) => entry.activeLeases > 0))
+                throw new ResourceInUse(ownerKey);
+            for (const pair of matching)
+                await this.evict(pair, "admission");
+            return { closed: matching.length };
+        });
+    }
+    async closeAll() {
+        const entries = Array.from(this.entries.values());
+        this.entries.clear();
+        await Promise.all(entries.map((entry) => entry.resource.close()));
+    }
+    async reconcileResourcesUnsafe() {
+        const policy = this.options.resourcePolicy;
+        if (!policy)
+            return 0;
+        let reaped = 0;
+        while (policy.isOverBudget(this.activePartitions())) {
+            const victim = this.leastRecentlyUsedIdle();
+            if (!victim)
+                break;
+            try {
+                await this.evict(victim, "resource-pressure");
+                reaped++;
+            }
+            catch {
+                break;
+            }
+        }
+        return reaped;
+    }
+    async reconcileResources() {
+        return this.serialized(() => this.reconcileResourcesUnsafe());
+    }
+    async reapIdle(maxIdleMs) {
+        return this.serialized(async () => {
+            let reaped = await this.reconcileResourcesUnsafe();
+            const now = this.now();
+            const effectiveMaxIdleMs = this.options.resourcePolicy?.maxIdleMs(maxIdleMs, this.activePartitions()) ?? maxIdleMs;
+            const idle = Array.from(this.entries.entries()).filter(([, entry]) => entry.activeLeases === 0 && now - entry.lastUsedAt > effectiveMaxIdleMs);
+            for (const [key, entry] of idle) {
+                try {
+                    await entry.resource.close();
+                    if (this.entries.get(key) === entry)
+                        this.entries.delete(key);
+                    reaped++;
+                }
+                catch (error) {
+                    this.options.observe?.({
+                        kind: "close-failed",
+                        reason: "idle-reap",
+                        partitionKey: entry.partitionKey,
+                        errorName: error instanceof Error ? error.name : "UnknownError",
+                    });
+                }
+            }
+            if (idle.length > 0)
+                this.notifyAdmissionWaiters();
+            return reaped;
+        });
+    }
+}

package/dist/resource-pool/errors.d.ts

@@ -0,0 +1,24 @@
+/** Raised when no idle resource can be evicted to admit a new one within the current ceiling. */
+export declare class ResourceCapacityExceeded extends Error {
+    readonly partitionKey: string;
+    readonly maxActive: number;
+    readonly partitionLimit: number;
+    constructor(partitionKey: string, maxActive: number, partitionLimit: number);
+}
+/** Raised by releaseOwnerIfIdle when at least one of the owner's own resources still has an active lease. */
+export declare class ResourceInUse extends Error {
+    readonly ownerKey: string;
+    constructor(ownerKey: string);
+}
+/** Raised when background admission is already waiting at maxQueuedBackgroundAdmissions -- fails fast rather than growing the wait queue without bound. */
+export declare class ResourceAdmissionQueueFull extends Error {
+    readonly partitionKey: string;
+    readonly maxQueued: number;
+    constructor(partitionKey: string, maxQueued: number);
+}
+/** Raised when a queued background admission waits past backgroundAdmissionQueueTimeoutMs without a slot freeing. */
+export declare class ResourceAdmissionQueueTimedOut extends Error {
+    readonly partitionKey: string;
+    readonly timeoutMs: number;
+    constructor(partitionKey: string, timeoutMs: number);
+}

package/dist/resource-pool/errors.js

@@ -0,0 +1,44 @@
+/** Raised when no idle resource can be evicted to admit a new one within the current ceiling. */
+export class ResourceCapacityExceeded extends Error {
+    partitionKey;
+    maxActive;
+    partitionLimit;
+    constructor(partitionKey, maxActive, partitionLimit) {
+        super(`no idle resource can be evicted to admit partition "${partitionKey}" within global capacity ${maxActive} and partition capacity ${partitionLimit}`);
+        this.partitionKey = partitionKey;
+        this.maxActive = maxActive;
+        this.partitionLimit = partitionLimit;
+        this.name = "ResourceCapacityExceeded";
+    }
+}
+/** Raised by releaseOwnerIfIdle when at least one of the owner's own resources still has an active lease. */
+export class ResourceInUse extends Error {
+    ownerKey;
+    constructor(ownerKey) {
+        super(`cannot release owner "${ownerKey}": a pooled resource for it still has an active lease`);
+        this.ownerKey = ownerKey;
+        this.name = "ResourceInUse";
+    }
+}
+/** Raised when background admission is already waiting at maxQueuedBackgroundAdmissions -- fails fast rather than growing the wait queue without bound. */
+export class ResourceAdmissionQueueFull extends Error {
+    partitionKey;
+    maxQueued;
+    constructor(partitionKey, maxQueued) {
+        super(`background admission for partition "${partitionKey}" is already waiting at capacity (${maxQueued} queued); retry later`);
+        this.partitionKey = partitionKey;
+        this.maxQueued = maxQueued;
+        this.name = "ResourceAdmissionQueueFull";
+    }
+}
+/** Raised when a queued background admission waits past backgroundAdmissionQueueTimeoutMs without a slot freeing. */
+export class ResourceAdmissionQueueTimedOut extends Error {
+    partitionKey;
+    timeoutMs;
+    constructor(partitionKey, timeoutMs) {
+        super(`background admission for partition "${partitionKey}" waited ${timeoutMs}ms for a resource-pool slot and gave up -- foreground demand is holding every admittable slot`);
+        this.partitionKey = partitionKey;
+        this.timeoutMs = timeoutMs;
+        this.name = "ResourceAdmissionQueueTimedOut";
+    }
+}

package/dist/resource-pool/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./bounded-resource-pool.js";
+export * from "./errors.js";
+export * from "./resource-policy.js";

package/dist/resource-pool/index.js

@@ -0,0 +1,3 @@
+export * from "./bounded-resource-pool.js";
+export * from "./errors.js";
+export * from "./resource-policy.js";

package/dist/resource-pool/resource-policy.d.ts

@@ -0,0 +1,28 @@
+/** Which ceiling actually constrained the most recent admission decision. */
+export type ResourcePoolActiveCeilingSource = "configured" | "resource-budget" | "absolute-cap";
+/**
+ * Optional plug point letting a real resource budget (memory, /proc-sampled process cost, ...)
+ * drive admission and retention decisions beyond the pool's own configured counts. A pool without
+ * one falls back to its configured maxActive/absoluteMaxActive alone -- this interface exists so a
+ * caller CAN plug in something smarter, not because every caller needs to.
+ *
+ * `Status` is left to the caller (default `unknown`) rather than fixed to one shape: the pool
+ * itself never inspects or reshapes what `status()` returns, only forwards it verbatim in its own
+ * status() report -- a caller with an existing status shape (its own field names, units, wire
+ * contract) plugs it in unchanged, no adapter required.
+ */
+export interface ResourcePoolResourcePolicy<Status = unknown> {
+    canAdmit(activePartitions: readonly string[], requestedPartition: string): boolean;
+    isOverBudget(activePartitions: readonly string[]): boolean;
+    /**
+     * A conservative, count-shaped ceiling derived from a real budget and worst-case known
+     * per-partition cost -- lets a larger real budget actually raise how many resources the pool
+     * will try to keep active, instead of a fixed configured count being the permanent bottleneck
+     * regardless of how much is genuinely available. Never authoritative on its own: canAdmit's own
+     * precise per-attempt check still gates the actual admission. Returns undefined on any metric
+     * loss -- fails closed, never treated as "unlimited room."
+     */
+    softActiveCeiling(activePartitions: readonly string[]): number | undefined;
+    maxIdleMs(configuredMaxIdleMs: number, activePartitions: readonly string[]): number;
+    status(activePartitions: readonly string[]): Status;
+}

package/dist/resource-pool/resource-policy.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@danypops/vehicle-core",
-	"version": "0.18.2",
+	"version": "0.18.4",
 	"description": "Vehicle's runtime-neutral wire contract: operation descriptors, schema codecs, failure shapes. Zero runtime dependencies, zero Bun-specific code -- the one thing every Vehicle client and server package depends on.",
 	"license": "MIT",
 	"type": "module",

package/src/cli-safety/assert-no-leading-flag-char.ts

@@ -0,0 +1,32 @@
+/**
+ * Guards against the argv-injection class behind a well-known family of CLI-wrapper CVEs
+ * (simple-git's own history includes several): a caller-influenced string that starts with `-`
+ * can be parsed by the target CLI as a *flag* (`--upload-pack`, `--exec`, `--template`, `-c`
+ * config override) instead of the literal ref/path/pattern value the caller intended. Any Vehicle
+ * operation that hands a caller-supplied string to a shelled-out CLI's argv should run it through
+ * this check first, at the exact position it reaches that argv.
+ *
+ * This is a hard rejection with no exceptions -- it has no opinion about *why* a value starting
+ * with `-` might be needed and does not attempt to allow-list specific flags. A caller whose CLI
+ * genuinely accepts caller-influenced flag-shaped arguments needs a purpose-built allow-list of
+ * its own; this primitive only ever covers the common case of a value that should always be a
+ * literal.
+ */
+export class UnsafeCliArgument extends Error {
+	constructor(
+		readonly value: string,
+		readonly fieldName?: string,
+	) {
+		super(
+			fieldName
+				? `"${value}" cannot be used as ${fieldName} -- it would be interpreted as a CLI flag, not a literal value`
+				: `"${value}" cannot be used as a CLI argument -- it would be interpreted as a flag, not a literal value`,
+		);
+		this.name = "UnsafeCliArgument";
+	}
+}
+
+/** Throws UnsafeCliArgument if `value` starts with `-`. `fieldName`, when given, names the field in the thrown error's own message for a caller with several distinct argv positions to check. */
+export function assertNoLeadingFlagChar(value: string, fieldName?: string): void {
+	if (value.startsWith("-")) throw new UnsafeCliArgument(value, fieldName);
+}

package/src/cli-safety/index.ts

@@ -0,0 +1 @@
+export * from "./assert-no-leading-flag-char.js";

package/src/index.ts

@@ -6,13 +6,16 @@
  * classification, invocation context), events, manifest, client (the port a
  * caller programs against), approvals (the Approval Gate's wire shapes), jobs
  * (Vehicle Jobs' pure pieces), schedules, watches, persistence (atomic
- * JSON), and concurrency (timer-based scheduling primitives) -- the latter
- * two are technical utilities, not Vehicle protocol capabilities, kept
- * distinct for that reason. Every symbol below is re-exported unchanged
+ * JSON), concurrency (timer-based scheduling primitives), cli-safety
+ * (argv-injection guards for any operation shelling out to a CLI), and
+ * resource-pool (bounded admission/eviction/leasing for a pooled expensive
+ * stateful resource) -- the latter four are technical utilities, not
+ * Vehicle protocol capabilities, kept distinct for that reason. Every symbol below is re-exported unchanged
  * from its historical flat-file home, so root-level `import { X } from
  * "@danypops/vehicle-core"` usage is completely unaffected by this layout.
  */
 export * from "./approvals/index.js";
+export * from "./cli-safety/index.js";
 export * from "./client/index.js";
 export * from "./concurrency/index.js";
 export * from "./content/index.js";
@@ -23,6 +26,7 @@ export * from "./jobs/index.js";
 export * from "./manifest/index.js";
 export * from "./operations/index.js";
 export * from "./persistence/index.js";
+export * from "./resource-pool/index.js";
 export * from "./schedules/index.js";
 export * from "./schemas/index.js";
 export * from "./watches/index.js";