@miller-tech/uap 2.21.3 → 2.36.4

package/dist/placement/ledger.d.ts

@@ -0,0 +1,323 @@
+import { z } from 'zod';
+import { type ModelRegistry } from './registry.js';
+export declare const LEDGER_VERSION = 1;
+export declare const LedgerDeviceStateSchema: z.ZodObject<{
+    kind: z.ZodEnum<["gpu", "cpu"]>;
+    total_mib: z.ZodOptional<z.ZodNumber>;
+    free_mib: z.ZodOptional<z.ZodNumber>;
+    reserved_mib: z.ZodOptional<z.ZodNumber>;
+    source: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    kind: "cpu" | "gpu";
+    source?: string | undefined;
+    total_mib?: number | undefined;
+    reserved_mib?: number | undefined;
+    free_mib?: number | undefined;
+}, {
+    kind: "cpu" | "gpu";
+    source?: string | undefined;
+    total_mib?: number | undefined;
+    reserved_mib?: number | undefined;
+    free_mib?: number | undefined;
+}>;
+export type LedgerDeviceState = z.infer<typeof LedgerDeviceStateSchema>;
+export declare const ResidentStateSchema: z.ZodEnum<["hot", "warming", "paused", "draining"]>;
+export type ResidentState = z.infer<typeof ResidentStateSchema>;
+export declare const LedgerResidentSchema: z.ZodObject<{
+    model: z.ZodString;
+    config: z.ZodString;
+    device: z.ZodString;
+    engine: z.ZodOptional<z.ZodString>;
+    endpoint: z.ZodOptional<z.ZodString>;
+    unit: z.ZodOptional<z.ZodString>;
+    state: z.ZodEnum<["hot", "warming", "paused", "draining"]>;
+    gpu_mib: z.ZodOptional<z.ZodNumber>;
+    host_rss_mib: z.ZodOptional<z.ZodNumber>;
+    holders: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    since: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    model: string;
+    config: string;
+    since: string;
+    device: string;
+    state: "hot" | "warming" | "paused" | "draining";
+    holders: string[];
+    endpoint?: string | undefined;
+    engine?: string | undefined;
+    unit?: string | undefined;
+    host_rss_mib?: number | undefined;
+    gpu_mib?: number | undefined;
+}, {
+    model: string;
+    config: string;
+    since: string;
+    device: string;
+    state: "hot" | "warming" | "paused" | "draining";
+    endpoint?: string | undefined;
+    engine?: string | undefined;
+    unit?: string | undefined;
+    host_rss_mib?: number | undefined;
+    gpu_mib?: number | undefined;
+    holders?: string[] | undefined;
+}>;
+export type LedgerResident = z.infer<typeof LedgerResidentSchema>;
+export declare const LedgerPendingSchema: z.ZodObject<{
+    id: z.ZodString;
+    requested_model: z.ZodString;
+    client: z.ZodOptional<z.ZodString>;
+    session: z.ZodOptional<z.ZodString>;
+    pid: z.ZodOptional<z.ZodNumber>;
+    created_at: z.ZodString;
+    expires_at: z.ZodString;
+    reason: z.ZodOptional<z.ZodString>;
+    /** The request's context need in cells (tokens + generation headroom),
+     * as estimated by the proxy when it parked the request. Option math is
+     * per-request (spec §4.4): cost(config, cells) — without this, the
+     * operator's `apply` and the pending list would recompute options
+     * against the 32k default instead of what the parked client needs.
+     * Absent on entries parked by older proxies → the default applies. */
+    cells: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    created_at: string;
+    requested_model: string;
+    expires_at: string;
+    reason?: string | undefined;
+    client?: string | undefined;
+    session?: string | undefined;
+    pid?: number | undefined;
+    cells?: number | undefined;
+}, {
+    id: string;
+    created_at: string;
+    requested_model: string;
+    expires_at: string;
+    reason?: string | undefined;
+    client?: string | undefined;
+    session?: string | undefined;
+    pid?: number | undefined;
+    cells?: number | undefined;
+}>;
+export type LedgerPending = z.infer<typeof LedgerPendingSchema>;
+/** Canonical placement TARGET identity for a resident: `device:endpoint`
+ * (spec §5.1 — the placement identity, never the model name). One composer,
+ * one spelling: the dashboard's admit answer, the proxy's per-target
+ * semaphore budget, and (phase 3) coordination leases must key off the
+ * identical string, so it is exported rather than re-derived per caller. */
+export declare function residentTargetId(resident: LedgerResident): string;
+export declare const PlacementLedgerSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    updated_at: z.ZodOptional<z.ZodString>;
+    devices: z.ZodRecord<z.ZodString, z.ZodObject<{
+        kind: z.ZodEnum<["gpu", "cpu"]>;
+        total_mib: z.ZodOptional<z.ZodNumber>;
+        free_mib: z.ZodOptional<z.ZodNumber>;
+        reserved_mib: z.ZodOptional<z.ZodNumber>;
+        source: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        kind: "cpu" | "gpu";
+        source?: string | undefined;
+        total_mib?: number | undefined;
+        reserved_mib?: number | undefined;
+        free_mib?: number | undefined;
+    }, {
+        kind: "cpu" | "gpu";
+        source?: string | undefined;
+        total_mib?: number | undefined;
+        reserved_mib?: number | undefined;
+        free_mib?: number | undefined;
+    }>>;
+    residents: z.ZodArray<z.ZodObject<{
+        model: z.ZodString;
+        config: z.ZodString;
+        device: z.ZodString;
+        engine: z.ZodOptional<z.ZodString>;
+        endpoint: z.ZodOptional<z.ZodString>;
+        unit: z.ZodOptional<z.ZodString>;
+        state: z.ZodEnum<["hot", "warming", "paused", "draining"]>;
+        gpu_mib: z.ZodOptional<z.ZodNumber>;
+        host_rss_mib: z.ZodOptional<z.ZodNumber>;
+        holders: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        since: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        model: string;
+        config: string;
+        since: string;
+        device: string;
+        state: "hot" | "warming" | "paused" | "draining";
+        holders: string[];
+        endpoint?: string | undefined;
+        engine?: string | undefined;
+        unit?: string | undefined;
+        host_rss_mib?: number | undefined;
+        gpu_mib?: number | undefined;
+    }, {
+        model: string;
+        config: string;
+        since: string;
+        device: string;
+        state: "hot" | "warming" | "paused" | "draining";
+        endpoint?: string | undefined;
+        engine?: string | undefined;
+        unit?: string | undefined;
+        host_rss_mib?: number | undefined;
+        gpu_mib?: number | undefined;
+        holders?: string[] | undefined;
+    }>, "many">;
+    pending: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        requested_model: z.ZodString;
+        client: z.ZodOptional<z.ZodString>;
+        session: z.ZodOptional<z.ZodString>;
+        pid: z.ZodOptional<z.ZodNumber>;
+        created_at: z.ZodString;
+        expires_at: z.ZodString;
+        reason: z.ZodOptional<z.ZodString>;
+        /** The request's context need in cells (tokens + generation headroom),
+         * as estimated by the proxy when it parked the request. Option math is
+         * per-request (spec §4.4): cost(config, cells) — without this, the
+         * operator's `apply` and the pending list would recompute options
+         * against the 32k default instead of what the parked client needs.
+         * Absent on entries parked by older proxies → the default applies. */
+        cells: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        created_at: string;
+        requested_model: string;
+        expires_at: string;
+        reason?: string | undefined;
+        client?: string | undefined;
+        session?: string | undefined;
+        pid?: number | undefined;
+        cells?: number | undefined;
+    }, {
+        id: string;
+        created_at: string;
+        requested_model: string;
+        expires_at: string;
+        reason?: string | undefined;
+        client?: string | undefined;
+        session?: string | undefined;
+        pid?: number | undefined;
+        cells?: number | undefined;
+    }>, "many">;
+    /** Last-served clock for the idle sweep (§4.4.2): model key → epoch ms
+     * of the most recent gated request forwarded to a live resident of
+     * that model. Survives syncLedger's wholesale resident rebuild by
+     * living at the top level; entries for models with no live resident
+     * are harmless residue. Absent on pre-§4.4.2 ledgers → the default. */
+    usage: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+    version: 1;
+    pending: {
+        id: string;
+        created_at: string;
+        requested_model: string;
+        expires_at: string;
+        reason?: string | undefined;
+        client?: string | undefined;
+        session?: string | undefined;
+        pid?: number | undefined;
+        cells?: number | undefined;
+    }[];
+    usage: Record<string, number>;
+    devices: Record<string, {
+        kind: "cpu" | "gpu";
+        source?: string | undefined;
+        total_mib?: number | undefined;
+        reserved_mib?: number | undefined;
+        free_mib?: number | undefined;
+    }>;
+    residents: {
+        model: string;
+        config: string;
+        since: string;
+        device: string;
+        state: "hot" | "warming" | "paused" | "draining";
+        holders: string[];
+        endpoint?: string | undefined;
+        engine?: string | undefined;
+        unit?: string | undefined;
+        host_rss_mib?: number | undefined;
+        gpu_mib?: number | undefined;
+    }[];
+    updated_at?: string | undefined;
+}, {
+    version: 1;
+    pending: {
+        id: string;
+        created_at: string;
+        requested_model: string;
+        expires_at: string;
+        reason?: string | undefined;
+        client?: string | undefined;
+        session?: string | undefined;
+        pid?: number | undefined;
+        cells?: number | undefined;
+    }[];
+    devices: Record<string, {
+        kind: "cpu" | "gpu";
+        source?: string | undefined;
+        total_mib?: number | undefined;
+        reserved_mib?: number | undefined;
+        free_mib?: number | undefined;
+    }>;
+    residents: {
+        model: string;
+        config: string;
+        since: string;
+        device: string;
+        state: "hot" | "warming" | "paused" | "draining";
+        endpoint?: string | undefined;
+        engine?: string | undefined;
+        unit?: string | undefined;
+        host_rss_mib?: number | undefined;
+        gpu_mib?: number | undefined;
+        holders?: string[] | undefined;
+    }[];
+    usage?: Record<string, number> | undefined;
+    updated_at?: string | undefined;
+}>;
+export type PlacementLedger = z.infer<typeof PlacementLedgerSchema>;
+export declare function placementLedgerPath(): string;
+export declare function emptyLedger(): PlacementLedger;
+export declare function loadLedger(path?: string): PlacementLedger;
+export declare function acquireLedgerLock(path: string, timeoutMs?: number): boolean;
+export declare function releaseLedgerLock(path: string): void;
+/** Mutate the ledger under the advisory lock: re-read, apply, stamp
+ * updated_at, write atomically. Throws (fails closed) when the lock cannot
+ * be taken — two writers must never interleave. `lockTimeoutMs` bounds the
+ * wait (default 5000ms); hot-path callers that only ADVANCE a clock use a
+ * short fuse so contention costs them a lost update, never a stalled
+ * request (see the admit forward touch, placement-routes.ts). */
+export declare function withLedger(path: string | undefined, mutate: (ledger: PlacementLedger) => void, opts?: {
+    lockTimeoutMs?: number;
+}): PlacementLedger;
+/** Live free memory for every registry device, from the probes. gpuN keys map
+ * to nvidia-smi index N; cpu keys read MemAvailable. Unprobeable devices
+ * carry no free_mib — unknown, never guessed. */
+export declare function probeDeviceStates(registry: ModelRegistry, opts?: {
+    gpu?: Map<number, {
+        total_mib?: number;
+        free_mib?: number;
+    }>;
+    hostAvailable?: number | null;
+}): Record<string, LedgerDeviceState>;
+/** Derive residents from live unit activity. A registry config whose unit
+ * is active IS a resident (fact), regardless of measurement — the ledger
+ * records what runs; measurement gates what may be LOADED. Measured
+ * residents carry their declared cost so the admission budget sum has real
+ * numbers; unmeasured ones carry none and admission fails closed on them.
+ * The `active` predicate is injectable for tests. */
+export declare function deriveLiveResidents(registry: ModelRegistry, isActive?: (unit: string) => boolean): LedgerResident[];
+/** Refresh device facts + reconcile residents in one locked write. Returns
+ * the resulting ledger. Measured gpu/host figures on reconciled residents
+ * come from the registry measurement when present (display), from the live
+ * process when possible — Phase 1 keeps registry values and leaves live
+ * attribution to `measure`. */
+export declare function syncLedger(registry: ModelRegistry, path?: string, isActive?: (unit: string) => boolean, opts?: {
+    gpuFree?: Map<number, number>;
+    hostAvailable?: number | null;
+    deviceProbe?: typeof probeDeviceStates;
+}): PlacementLedger;
+//# sourceMappingURL=ledger.d.ts.map

package/dist/placement/ledger.d.ts.map

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

package/dist/placement/ledger.js

@@ -0,0 +1,263 @@
+/**
+ * Placement ledger — `~/.uap/placement.json` (spec §4.2).
+ *
+ * Live state: devices (probe fact), residents (what is loaded, with state),
+ * pending placement requests (what is parked awaiting the operator).
+ *
+ * The ledger records intent; the probe records fact. Reads refresh device
+ * free memory from the live probes — never from the last writer's snapshot —
+ * and disagreement between the two is surfaced, not averaged.
+ *
+ * Writers hold an advisory lock (the mkdirSync-atomic pattern from
+ * src/cli/proxy-lifecycle.ts) and re-read before committing, so a stale view
+ * cannot clobber. Lock acquisition fails CLOSED (throws): a lost ledger write
+ * must be loud.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'fs';
+import { homedir } from 'os';
+import { dirname, join } from 'path';
+import { z } from 'zod';
+import { gpuStatsByIndex, hostAvailableMiB } from './probes.js';
+import { isMeasuredConfig } from './registry.js';
+export const LEDGER_VERSION = 1;
+// ---------------------------------------------------------------------------
+// Schema
+// ---------------------------------------------------------------------------
+export const LedgerDeviceStateSchema = z.object({
+    kind: z.enum(['gpu', 'cpu']),
+    total_mib: z.number().int().positive().optional(),
+    free_mib: z.number().int().nonnegative().optional(),
+    reserved_mib: z.number().int().nonnegative().optional(),
+    source: z.string().optional(),
+});
+export const ResidentStateSchema = z.enum(['hot', 'warming', 'paused', 'draining']);
+export const LedgerResidentSchema = z.object({
+    model: z.string(),
+    config: z.string(),
+    device: z.string(),
+    engine: z.string().optional(),
+    endpoint: z.string().optional(),
+    unit: z.string().optional(),
+    state: ResidentStateSchema,
+    gpu_mib: z.number().int().positive().optional(),
+    host_rss_mib: z.number().int().positive().optional(),
+    holders: z.array(z.string()).default([]),
+    since: z.string(),
+});
+export const LedgerPendingSchema = z.object({
+    id: z.string(),
+    requested_model: z.string(),
+    client: z.string().optional(),
+    session: z.string().optional(),
+    pid: z.number().int().positive().optional(),
+    created_at: z.string(),
+    expires_at: z.string(),
+    reason: z.string().optional(),
+    /** The request's context need in cells (tokens + generation headroom),
+     * as estimated by the proxy when it parked the request. Option math is
+     * per-request (spec §4.4): cost(config, cells) — without this, the
+     * operator's `apply` and the pending list would recompute options
+     * against the 32k default instead of what the parked client needs.
+     * Absent on entries parked by older proxies → the default applies. */
+    cells: z.number().int().positive().optional(),
+});
+/** Canonical placement TARGET identity for a resident: `device:endpoint`
+ * (spec §5.1 — the placement identity, never the model name). One composer,
+ * one spelling: the dashboard's admit answer, the proxy's per-target
+ * semaphore budget, and (phase 3) coordination leases must key off the
+ * identical string, so it is exported rather than re-derived per caller. */
+export function residentTargetId(resident) {
+    return `${resident.device}:${resident.endpoint ?? 'default'}`;
+}
+export const PlacementLedgerSchema = z.object({
+    version: z.literal(LEDGER_VERSION),
+    updated_at: z.string().optional(),
+    devices: z.record(z.string(), LedgerDeviceStateSchema),
+    residents: z.array(LedgerResidentSchema),
+    pending: z.array(LedgerPendingSchema),
+    /** Last-served clock for the idle sweep (§4.4.2): model key → epoch ms
+     * of the most recent gated request forwarded to a live resident of
+     * that model. Survives syncLedger's wholesale resident rebuild by
+     * living at the top level; entries for models with no live resident
+     * are harmless residue. Absent on pre-§4.4.2 ledgers → the default. */
+    usage: z.record(z.string(), z.number()).default({}),
+});
+// ---------------------------------------------------------------------------
+// Paths, load, save
+// ---------------------------------------------------------------------------
+export function placementLedgerPath() {
+    return process.env.UAP_PLACEMENT_LEDGER ?? join(homedir(), '.uap', 'placement.json');
+}
+export function emptyLedger() {
+    return { version: LEDGER_VERSION, devices: {}, residents: [], pending: [], usage: {} };
+}
+export function loadLedger(path = placementLedgerPath()) {
+    if (!existsSync(path))
+        return emptyLedger();
+    try {
+        const parsed = PlacementLedgerSchema.safeParse(JSON.parse(readFileSync(path, 'utf-8')));
+        return parsed.success ? parsed.data : emptyLedger(); // corrupt → empty, fail closed
+    }
+    catch {
+        return emptyLedger(); // unparseable → empty, never a partial read
+    }
+}
+/** Atomic write: tmp file + rename, so a reader never sees a torn document. */
+function saveLedgerAtomically(path, ledger) {
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp-${process.pid}`;
+    writeFileSync(tmp, `${JSON.stringify(ledger, null, 2)}\n`);
+    renameSync(tmp, path);
+}
+// ---------------------------------------------------------------------------
+// Advisory lock (mkdirSync-atomic, stale-steal — proxy-lifecycle pattern,
+// but fail-CLOSED: a ledger writer that cannot take the lock must not write)
+// ---------------------------------------------------------------------------
+const LOCK_STALE_MS = 30_000;
+export function acquireLedgerLock(path, timeoutMs = 5000) {
+    const lock = `${path}.lock`;
+    mkdirSync(dirname(lock), { recursive: true });
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        try {
+            mkdirSync(lock); // atomic: succeeds only if it did not exist
+            return true;
+        }
+        catch {
+            try {
+                const st = statSync(lock);
+                if (Date.now() - st.mtimeMs > LOCK_STALE_MS) {
+                    rmSync(lock, { recursive: true, force: true }); // steal a crashed holder
+                    continue;
+                }
+            }
+            catch {
+                continue; // vanished between attempts — retry
+            }
+            if (Date.now() >= deadline)
+                return false;
+            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 100); // sleep 100ms, sync context
+        }
+    }
+}
+export function releaseLedgerLock(path) {
+    rmSync(`${path}.lock`, { recursive: true, force: true });
+}
+/** Mutate the ledger under the advisory lock: re-read, apply, stamp
+ * updated_at, write atomically. Throws (fails closed) when the lock cannot
+ * be taken — two writers must never interleave. `lockTimeoutMs` bounds the
+ * wait (default 5000ms); hot-path callers that only ADVANCE a clock use a
+ * short fuse so contention costs them a lost update, never a stalled
+ * request (see the admit forward touch, placement-routes.ts). */
+export function withLedger(path = placementLedgerPath(), mutate, opts = {}) {
+    if (!acquireLedgerLock(path, opts.lockTimeoutMs)) {
+        throw new Error(`placement ledger lock held longer than expected: ${path}.lock`);
+    }
+    try {
+        const ledger = loadLedger(path);
+        mutate(ledger);
+        ledger.updated_at = new Date().toISOString();
+        saveLedgerAtomically(path, ledger);
+        return ledger;
+    }
+    finally {
+        releaseLedgerLock(path);
+    }
+}
+// ---------------------------------------------------------------------------
+// Device fact: probe live, overlay onto registry shape
+// ---------------------------------------------------------------------------
+/** Live free memory for every registry device, from the probes. gpuN keys map
+ * to nvidia-smi index N; cpu keys read MemAvailable. Unprobeable devices
+ * carry no free_mib — unknown, never guessed. */
+export function probeDeviceStates(registry, opts) {
+    const gpu = opts?.gpu ?? gpuStatsByIndex();
+    const hostAvailable = opts?.hostAvailable !== undefined ? opts.hostAvailable : hostAvailableMiB();
+    const out = {};
+    for (const [key, dev] of Object.entries(registry.devices)) {
+        const state = { kind: dev.kind, total_mib: dev.total_mib, reserved_mib: dev.reserved_mib };
+        if (dev.kind === 'gpu') {
+            const idx = /^gpu(\d+)$/.exec(key);
+            const stats = idx ? gpu.get(Number(idx[1])) : undefined;
+            if (stats?.free_mib !== undefined) {
+                state.free_mib = stats.free_mib;
+                state.source = 'nvidia-smi';
+            }
+            else {
+                state.source = 'unprobed';
+            }
+        }
+        else {
+            if (typeof hostAvailable === 'number') {
+                state.free_mib = hostAvailable;
+                state.source = 'MemAvailable';
+            }
+            else {
+                state.source = 'unprobed';
+            }
+        }
+        out[key] = state;
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// Reconcile: align ledger residents with what is actually running
+// ---------------------------------------------------------------------------
+/** Derive residents from live unit activity. A registry config whose unit
+ * is active IS a resident (fact), regardless of measurement — the ledger
+ * records what runs; measurement gates what may be LOADED. Measured
+ * residents carry their declared cost so the admission budget sum has real
+ * numbers; unmeasured ones carry none and admission fails closed on them.
+ * The `active` predicate is injectable for tests. */
+export function deriveLiveResidents(registry, isActive = () => false) {
+    const residents = [];
+    for (const [mKey, model] of Object.entries(registry.models)) {
+        for (const [cKey, cfg] of Object.entries(model.configs)) {
+            const unit = cfg.unit ?? model.unit;
+            if (!unit || !isActive(unit))
+                continue;
+            residents.push({
+                model: mKey,
+                config: cKey,
+                device: model.affinity?.device[0] ?? 'gpu0',
+                engine: cfg.engine ?? model.engine,
+                endpoint: model.endpoint,
+                unit,
+                state: 'hot',
+                gpu_mib: isMeasuredConfig(cfg) ? cfg.resident_gpu_mib : undefined,
+                host_rss_mib: isMeasuredConfig(cfg) ? cfg.host_rss_mib : undefined,
+                holders: [],
+                since: new Date().toISOString(),
+            });
+        }
+    }
+    return residents;
+}
+/** Refresh device facts + reconcile residents in one locked write. Returns
+ * the resulting ledger. Measured gpu/host figures on reconciled residents
+ * come from the registry measurement when present (display), from the live
+ * process when possible — Phase 1 keeps registry values and leaves live
+ * attribution to `measure`. */
+export function syncLedger(registry, path = placementLedgerPath(), isActive = () => false, opts) {
+    const devices = opts?.deviceProbe
+        ? opts.deviceProbe(registry, opts)
+        : probeDeviceStates(registry, opts);
+    const residents = deriveLiveResidents(registry, isActive);
+    return withLedger(path, (ledger) => {
+        ledger.devices = devices;
+        // `draining` markers survive the wholesale resident rebuild: an
+        // enforcement's drain window can outlast a concurrent `models status`
+        // or dashboard auto-refresh, and resetting victims to hot would
+        // re-open admission to a unit being stopped (spec §4.6 step 1's
+        // "refuse new requests" must hold for the whole sequence).
+        const draining = new Set(ledger.residents
+            .filter((r) => r.state === 'draining')
+            .map((r) => `${r.model}/${r.config}`));
+        ledger.residents = residents.map((r) => draining.has(`${r.model}/${r.config}`) ? { ...r, state: 'draining' } : r);
+        // Pending entries survive the sync: they are requests awaiting the
+        // operator, not backend state. Expired ones are pruned.
+        const now = new Date().toISOString();
+        ledger.pending = ledger.pending.filter((p) => p.expires_at > now);
+    });
+}
+//# sourceMappingURL=ledger.js.map

package/dist/placement/ledger.js.map

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

package/dist/placement/preview.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Impact preview (spec §4.5): the victim list the operator sees BEFORE
+ * committing, and the re-derivation check enforcement uses AFTER the yes.
+ *
+ * Nothing in this view is advisory-only: enforcement re-derives the same
+ * victim set and refuses to proceed if it differs from what the operator
+ * approved. A preview that lies is worse than no preview.
+ *
+ * In-flight status is `unknown` in phase 1: the proxy exposes no live
+ * request state yet (the phase-2 in-flight-per-target endpoint supplies it).
+ * The preview must say unknown rather than guess "idle".
+ */
+import { type ModelRegistry } from './registry.js';
+import type { LedgerResident } from './ledger.js';
+export type InFlight = 'unknown' | boolean;
+export interface VictimPreview {
+    model: string;
+    config: string;
+    device: string;
+    state: LedgerResident['state'];
+    holders: string[];
+    inflight: InFlight;
+    /** MiB the eviction returns to the device; unknown → undefined. */
+    frees_gpu_mib: number;
+    /** MiB the eviction returns to host RAM; unknown → undefined. */
+    frees_host_mib?: number;
+    /** Measured cost of loading this config back, if the registry knows it. */
+    reload_cost_mib?: number;
+    /** Human consequence from the spec §4.5 table. */
+    consequence: string;
+}
+/** Build the victim preview for a displace option. */
+export declare function buildVictimPreviews(registry: ModelRegistry, victims: LedgerResident[], inflightOf?: (victim: LedgerResident) => InFlight): VictimPreview[];
+/** Stable signature of a victim set — what the operator approved and what
+ * enforcement re-derives must produce the same string, or enforcement
+ * aborts. Order-insensitive; content-sensitive. */
+export declare function victimSignature(victims: Array<{
+    model: string;
+    config: string;
+}>): string;
+/** The enforcement-time check: re-derive the victims from live state and
+ * refuse when the set the operator approved no longer matches. A mismatch
+ * means the world moved between preview and commit — abort, re-ask. */
+export declare function previewStillValid(approved: Array<{
+    model: string;
+    config: string;
+}>, rederived: Array<{
+    model: string;
+    config: string;
+}>): boolean;
+//# sourceMappingURL=preview.d.ts.map

package/dist/placement/preview.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview.d.ts","sourceRoot":"","sources":["../../src/placement/preview.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAoB,KAAK,aAAa,EAAE,MAAM,eAAe,CAAC;AACrE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,MAAM,MAAM,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAC;AAE3C,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,cAAc,CAAC,OAAO,CAAC,CAAC;IAC/B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,EAAE,QAAQ,CAAC;IACnB,mEAAmE;IACnE,aAAa,EAAE,MAAM,CAAC;IACtB,iEAAiE;IACjE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,2EAA2E;IAC3E,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kDAAkD;IAClD,WAAW,EAAE,MAAM,CAAC;CACrB;AAaD,sDAAsD;AACtD,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,aAAa,EACvB,OAAO,EAAE,cAAc,EAAE,EACzB,UAAU,GAAE,CAAC,MAAM,EAAE,cAAc,KAAK,QAA0B,GACjE,aAAa,EAAE,CAgBjB;AAED;;mDAEmD;AACnD,wBAAgB,eAAe,CAAC,OAAO,EAAE,KAAK,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG,MAAM,CAKzF;AAED;;uEAEuE;AACvE,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,KAAK,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,EAClD,SAAS,EAAE,KAAK,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,GAClD,OAAO,CAET"}