lorenz 0.1.0

package/packages/worker-host-pool/dist/index.js

@@ -0,0 +1,311 @@
+import { startReverseTunnel, waitForRemoteTcpPort } from "@lorenz/ssh";
+export class WorkerHostPool {
+    nextRemoteMcpPort = 46_000;
+    nextRemoteMcpLeaseId = 1;
+    availableRemoteMcpPorts = [];
+    remoteMcpTunnelsByEndpoint = new Map();
+    remoteMcpTunnelEntriesByLeaseId = new Map();
+    // Per-run tunnels are keyed by `${workerHost}#${runKey}`, NOT host-coalesced,
+    // so each run owns a distinct entry (and distinct remote port). One run's
+    // localPort change can never replace another run's entry.
+    perRunMcpTunnels = new Map();
+    async acquireRemoteMcpTunnel(workerHost, localHost, localPort) {
+        const endpointKey = this.remoteMcpTunnelEndpointKey(workerHost, localHost, localPort);
+        const current = this.remoteMcpTunnelsByEndpoint.get(endpointKey);
+        if (current && !current.processEnded) {
+            await this.waitForRemoteMcpTunnelReady(current);
+            return this.createRemoteMcpTunnelLease(current);
+        }
+        if (current)
+            this.closeRemoteMcpTunnel(current, true);
+        const recycledPort = this.availableRemoteMcpPorts.shift();
+        const remotePort = recycledPort ?? this.nextRemoteMcpPort;
+        let process;
+        try {
+            process = startReverseTunnel(workerHost, remotePort, localHost, localPort);
+        }
+        catch (error) {
+            if (recycledPort !== undefined)
+                this.recycleRemoteMcpPort(recycledPort);
+            throw error;
+        }
+        if (recycledPort === undefined)
+            this.nextRemoteMcpPort += 1;
+        const entry = {
+            workerHost,
+            localHost,
+            localPort,
+            process,
+            leaseIds: new Set(),
+            readyPromise: Promise.resolve(),
+            remotePort,
+            processEnded: false,
+            recyclePortOnProcessEnd: false,
+        };
+        this.remoteMcpTunnelsByEndpoint.set(endpointKey, entry);
+        process.on("close", () => this.handleRemoteMcpTunnelProcessEnd(entry, endpointKey));
+        process.on("exit", () => this.handleRemoteMcpTunnelProcessEnd(entry, endpointKey));
+        process.on("error", () => this.handleRemoteMcpTunnelProcessEnd(entry, endpointKey));
+        entry.readyPromise = this.confirmRemoteMcpTunnelReady(entry);
+        await this.waitForRemoteMcpTunnelReady(entry);
+        return this.createRemoteMcpTunnelLease(entry);
+    }
+    releaseRemoteMcpTunnel(lease) {
+        const entry = this.remoteMcpTunnelEntriesByLeaseId.get(lease.leaseId);
+        if (!entry)
+            return;
+        if (entry.workerHost !== lease.workerHost || entry.remotePort !== lease.remotePort) {
+            return;
+        }
+        this.remoteMcpTunnelEntriesByLeaseId.delete(lease.leaseId);
+        entry.leaseIds.delete(lease.leaseId);
+        if (entry.leaseIds.size > 0)
+            return;
+        this.closeRemoteMcpTunnel(entry, true);
+    }
+    async openForRun(workerHost, runKey, localHost, localPort) {
+        const key = perRunKey(workerHost, runKey);
+        const current = this.perRunMcpTunnels.get(key);
+        if (current &&
+            !current.processEnded &&
+            current.localHost === localHost &&
+            current.localPort === localPort) {
+            await this.waitForRemoteMcpTunnelReady(current);
+            return this.createRemoteMcpTunnelLease(current);
+        }
+        if (current)
+            this.closePerRunMcpTunnel(key, current, true);
+        const remotePort = this.allocateRemoteMcpPort();
+        const recycledPort = remotePort < this.nextRemoteMcpPort ? remotePort : undefined;
+        let process;
+        try {
+            process = startReverseTunnel(workerHost, remotePort, localHost, localPort);
+        }
+        catch (error) {
+            if (recycledPort !== undefined)
+                this.recycleRemoteMcpPort(recycledPort);
+            throw error;
+        }
+        if (recycledPort === undefined)
+            this.nextRemoteMcpPort += 1;
+        const entry = {
+            workerHost,
+            localHost,
+            localPort,
+            process,
+            leaseIds: new Set(),
+            readyPromise: Promise.resolve(),
+            remotePort,
+            processEnded: false,
+            recyclePortOnProcessEnd: false,
+        };
+        this.perRunMcpTunnels.set(key, entry);
+        process.on("close", () => this.handlePerRunMcpTunnelProcessEnd(key, entry));
+        process.on("exit", () => this.handlePerRunMcpTunnelProcessEnd(key, entry));
+        process.on("error", () => this.handlePerRunMcpTunnelProcessEnd(key, entry));
+        entry.readyPromise = this.confirmPerRunMcpTunnelReady(key, entry);
+        await this.waitForRemoteMcpTunnelReady(entry);
+        return this.createRemoteMcpTunnelLease(entry);
+    }
+    closeForRun(workerHost, runKey) {
+        const key = perRunKey(workerHost, runKey);
+        const entry = this.perRunMcpTunnels.get(key);
+        if (!entry)
+            return;
+        // Each openForRun call on this run minted one lease; drop one per close
+        // and keep the tunnel while other holders of the same run remain.
+        const [leaseId] = entry.leaseIds;
+        if (leaseId !== undefined) {
+            entry.leaseIds.delete(leaseId);
+            this.remoteMcpTunnelEntriesByLeaseId.delete(leaseId);
+        }
+        if (entry.leaseIds.size > 0)
+            return;
+        this.closePerRunMcpTunnel(key, entry, true);
+    }
+    // Allocate a remote port, reusing a recycled candidate only when no live
+    // entry (host-keyed OR per-run) still holds it. This guards the
+    // recycled-port-vs-stale-entry interaction under N concurrent live ports.
+    allocateRemoteMcpPort() {
+        while (this.availableRemoteMcpPorts.length > 0) {
+            const candidate = this.availableRemoteMcpPorts.shift();
+            if (!this.isRemoteMcpPortLive(candidate))
+                return candidate;
+        }
+        return this.nextRemoteMcpPort;
+    }
+    isRemoteMcpPortLive(remotePort) {
+        for (const entry of this.remoteMcpTunnelsByEndpoint.values()) {
+            if (entry.remotePort === remotePort)
+                return true;
+        }
+        for (const entry of this.perRunMcpTunnels.values()) {
+            if (entry.remotePort === remotePort)
+                return true;
+        }
+        return false;
+    }
+    async confirmPerRunMcpTunnelReady(key, entry) {
+        const processEndWatcher = this.watchRemoteMcpTunnelSetupProcessEnd(entry);
+        try {
+            await Promise.race([
+                waitForRemoteTcpPort(entry.workerHost, entry.remotePort),
+                processEndWatcher.promise,
+            ]);
+        }
+        catch (error) {
+            this.closePerRunMcpTunnel(key, entry, true);
+            throw error;
+        }
+        finally {
+            processEndWatcher.dispose();
+        }
+    }
+    handlePerRunMcpTunnelProcessEnd(key, entry) {
+        if (entry.processEnded)
+            return;
+        entry.processEnded = true;
+        if (this.perRunMcpTunnels.get(key) === entry) {
+            this.closePerRunMcpTunnel(key, entry, true);
+            return;
+        }
+        if (entry.recyclePortOnProcessEnd)
+            this.recycleRemoteMcpPort(entry.remotePort);
+    }
+    closePerRunMcpTunnel(key, entry, recyclePort) {
+        if (this.perRunMcpTunnels.get(key) === entry) {
+            this.perRunMcpTunnels.delete(key);
+        }
+        for (const leaseId of entry.leaseIds) {
+            this.remoteMcpTunnelEntriesByLeaseId.delete(leaseId);
+        }
+        entry.leaseIds.clear();
+        if (recyclePort) {
+            if (entry.processEnded) {
+                this.recycleRemoteMcpPort(entry.remotePort);
+            }
+            else {
+                entry.recyclePortOnProcessEnd = true;
+            }
+        }
+        if (!entry.processEnded) {
+            entry.process.kill();
+        }
+    }
+    closeRemoteMcpTunnel(entry, recyclePort) {
+        const endpointKey = this.remoteMcpTunnelEndpointKey(entry.workerHost, entry.localHost, entry.localPort);
+        if (this.remoteMcpTunnelsByEndpoint.get(endpointKey) === entry) {
+            this.remoteMcpTunnelsByEndpoint.delete(endpointKey);
+        }
+        for (const leaseId of entry.leaseIds) {
+            this.remoteMcpTunnelEntriesByLeaseId.delete(leaseId);
+        }
+        entry.leaseIds.clear();
+        if (recyclePort) {
+            if (entry.processEnded) {
+                this.recycleRemoteMcpPort(entry.remotePort);
+            }
+            else {
+                entry.recyclePortOnProcessEnd = true;
+            }
+        }
+        if (!entry.processEnded) {
+            entry.process.kill();
+        }
+    }
+    handleRemoteMcpTunnelProcessEnd(entry, endpointKey) {
+        if (entry.processEnded)
+            return;
+        entry.processEnded = true;
+        if (this.remoteMcpTunnelsByEndpoint.get(endpointKey) === entry) {
+            this.closeRemoteMcpTunnel(entry, true);
+            return;
+        }
+        if (entry.recyclePortOnProcessEnd)
+            this.recycleRemoteMcpPort(entry.remotePort);
+    }
+    async waitForRemoteMcpTunnelReady(entry) {
+        try {
+            await entry.readyPromise;
+        }
+        catch (error) {
+            throw this.remoteMcpTunnelSetupError(entry, error);
+        }
+        if (entry.processEnded) {
+            throw this.remoteMcpTunnelSetupError(entry, new Error("reverse_tunnel_process_ended"));
+        }
+    }
+    async confirmRemoteMcpTunnelReady(entry) {
+        const processEndWatcher = this.watchRemoteMcpTunnelSetupProcessEnd(entry);
+        try {
+            await Promise.race([
+                waitForRemoteTcpPort(entry.workerHost, entry.remotePort),
+                processEndWatcher.promise,
+            ]);
+        }
+        catch (error) {
+            this.closeRemoteMcpTunnel(entry, true);
+            throw error;
+        }
+        finally {
+            processEndWatcher.dispose();
+        }
+    }
+    watchRemoteMcpTunnelSetupProcessEnd(entry) {
+        let dispose = () => { };
+        const promise = new Promise((_, reject) => {
+            const rejectOnce = (reason) => {
+                dispose();
+                reject(new Error(reason));
+            };
+            const onClose = (code, signal) => {
+                rejectOnce(`reverse_tunnel_closed: ${code ?? "null"} ${signal ?? "null"}`);
+            };
+            const onExit = (code, signal) => {
+                rejectOnce(`reverse_tunnel_exited: ${code ?? "null"} ${signal ?? "null"}`);
+            };
+            const onError = (error) => {
+                rejectOnce(`reverse_tunnel_error: ${error.message}`);
+            };
+            dispose = () => {
+                entry.process.off("close", onClose);
+                entry.process.off("exit", onExit);
+                entry.process.off("error", onError);
+            };
+            entry.process.once("close", onClose);
+            entry.process.once("exit", onExit);
+            entry.process.once("error", onError);
+        });
+        return { promise, dispose };
+    }
+    remoteMcpTunnelSetupError(entry, cause) {
+        return new Error(`remote_mcp_tunnel_setup_failed: ${entry.workerHost} ${entry.remotePort}`, {
+            cause,
+        });
+    }
+    recycleRemoteMcpPort(remotePort) {
+        if (this.availableRemoteMcpPorts.includes(remotePort))
+            return;
+        this.availableRemoteMcpPorts.push(remotePort);
+        this.availableRemoteMcpPorts.sort((left, right) => left - right);
+    }
+    createRemoteMcpTunnelLease(entry) {
+        const leaseId = String(this.nextRemoteMcpLeaseId);
+        this.nextRemoteMcpLeaseId += 1;
+        entry.leaseIds.add(leaseId);
+        this.remoteMcpTunnelEntriesByLeaseId.set(leaseId, entry);
+        return {
+            leaseId,
+            workerHost: entry.workerHost,
+            remotePort: entry.remotePort,
+        };
+    }
+    remoteMcpTunnelEndpointKey(workerHost, localHost, localPort) {
+        return `${workerHost}\0${localHost}\0${localPort}`;
+    }
+}
+function perRunKey(workerHost, runKey) {
+    return `${workerHost}#${runKey}`;
+}
+export const workerHostPool = new WorkerHostPool();
+//# sourceMappingURL=index.js.map

package/packages/worker-host-pool/dist/index.js.map

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

package/packages/worker-host-pool/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@lorenz/worker-host-pool",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "dependencies": {
+    "@lorenz/ssh": "file:../ssh"
+  }
+}

package/packages/worker-pool/dist/index.d.ts

@@ -0,0 +1,6 @@
+export type { AcquireRequest, AcquireResult, WorkerLease, WorkerOutcome, WorkerPool, WorkerPoolSnapshot, WorkerRecord, WorkerState, LedgerRow, MachineLease, Mutex, } from "./types.js";
+export { createMutex } from "./mutex.js";
+export { createWorkerPool, type CreateWorkerPoolDeps } from "./pool.js";
+export { WorkerDriverRegistry, defaultWorkerDriverRegistry, FakeWorkerDriver, POOL_OWNED_LABEL, registerFakeWorkerDriver, } from "@lorenz/worker-sdk";
+export type { WorkerDescriptor, WorkerDriver, WorkerDriverFactory, WorkerHealth, DriverDeps, TeardownReason, } from "@lorenz/worker-sdk";
+//# sourceMappingURL=index.d.ts.map

package/packages/worker-pool/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAUA,YAAY,EACV,cAAc,EACd,aAAa,EACb,WAAW,EACX,aAAa,EACb,UAAU,EACV,kBAAkB,EAClB,YAAY,EACZ,WAAW,EACX,SAAS,EACT,YAAY,EACZ,KAAK,GACN,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEzC,OAAO,EAAE,gBAAgB,EAAE,KAAK,oBAAoB,EAAE,MAAM,WAAW,CAAC;AAIxE,OAAO,EACL,oBAAoB,EACpB,2BAA2B,EAC3B,gBAAgB,EAChB,gBAAgB,EAChB,wBAAwB,GACzB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,gBAAgB,EAChB,YAAY,EACZ,mBAAmB,EACnB,YAAY,EACZ,UAAU,EACV,cAAc,GACf,MAAM,oBAAoB,CAAC"}

package/packages/worker-pool/dist/index.js

@@ -0,0 +1,15 @@
+// Public barrel for @lorenz/worker-pool: the pool ENGINE.
+//
+// Exports the pool surface (createWorkerPool + the lease/inventory/snapshot types)
+// and re-exports the driver contract from `@lorenz/worker-sdk` so the engine
+// surface stays one-stop for the runtime/CLI. Importing this barrel has NO side
+// effects: no driver is registered here. Concrete drivers live in extensions
+// (and the in-memory fake in the SDK); the composition root registers them into
+// a `WorkerDriverRegistry` (or the process-wide default) and threads that registry
+// to `createWorkerPool` via `CreateWorkerPoolDeps.drivers`.
+export { createMutex } from "./mutex.js";
+export { createWorkerPool } from "./pool.js";
+// Driver-contract surface re-exported from the SDK so downstream engine
+// consumers can keep importing it from this package.
+export { WorkerDriverRegistry, defaultWorkerDriverRegistry, FakeWorkerDriver, POOL_OWNED_LABEL, registerFakeWorkerDriver, } from "@lorenz/worker-sdk";
+//# sourceMappingURL=index.js.map

package/packages/worker-pool/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,0DAA0D;AAC1D,EAAE;AACF,mFAAmF;AACnF,6EAA6E;AAC7E,gFAAgF;AAChF,6EAA6E;AAC7E,gFAAgF;AAChF,mFAAmF;AACnF,4DAA4D;AAgB5D,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEzC,OAAO,EAAE,gBAAgB,EAA6B,MAAM,WAAW,CAAC;AAExE,wEAAwE;AACxE,qDAAqD;AACrD,OAAO,EACL,oBAAoB,EACpB,2BAA2B,EAC3B,gBAAgB,EAChB,gBAAgB,EAChB,wBAAwB,GACzB,MAAM,oBAAoB,CAAC"}

package/packages/worker-pool/dist/lease.d.ts

@@ -0,0 +1,36 @@
+import type { WorkerLease, WorkerOutcome, WorkerRecord, Mutex } from "./types.js";
+/**
+ * Settles a lease against its worker. Invoked by `createLease` INSIDE the per-worker
+ * mutex (so a reaper tick and a release can never both decrement `inFlight`).
+ * The callback owns the real accounting: decrement `inFlight`, mark the worker for
+ * recycle on `poison`, and run any returning/destroy bookkeeping. It is only
+ * ever called once per lease, and only when the lease still owns the worker.
+ */
+type OnSettle = (record: WorkerRecord, outcome: WorkerOutcome, reason: string | null) => Promise<void>;
+/**
+ * Dependencies the pool injects when it hands out a lease. `record` is the
+ * shared inventory record (mutated only inside `mutex`); `clock` stamps
+ * heartbeats; `onSettle` is the pool's accounting callback.
+ */
+export interface CreateLeaseOptions {
+    leaseId: string;
+    record: WorkerRecord;
+    mutex: Mutex;
+    clock: {
+        now(): number;
+    };
+    acquiredAtMs: number;
+    expiresAtMs: number | null;
+    onSettle: OnSettle;
+}
+/**
+ * Builds a `WorkerLease` over a single worker generation. The lease settles exactly
+ * once: a per-lease `settled` flag short-circuits a double `release`/`fail`, and
+ * the actual settlement runs inside the per-worker `mutex` where it re-checks
+ * ownership. A stale generation (the worker was re-stamped with a newer `leaseId`)
+ * or an already-DESTROYED worker is a no-op that NEVER touches `inFlight`, so a
+ * late-resolving run from an old generation cannot underflow the live count.
+ */
+export declare function createLease(options: CreateLeaseOptions): WorkerLease;
+export {};
+//# sourceMappingURL=lease.d.ts.map

package/packages/worker-pool/dist/lease.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lease.d.ts","sourceRoot":"","sources":["../src/lease.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAElF;;;;;;GAMG;AACH,KAAK,QAAQ,GAAG,CACd,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,aAAa,EACtB,MAAM,EAAE,MAAM,GAAG,IAAI,KAClB,OAAO,CAAC,IAAI,CAAC,CAAC;AAEnB;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,YAAY,CAAC;IACrB,KAAK,EAAE,KAAK,CAAC;IACb,KAAK,EAAE;QAAE,GAAG,IAAI,MAAM,CAAA;KAAE,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,QAAQ,EAAE,QAAQ,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,WAAW,CA4CpE"}

package/packages/worker-pool/dist/lease.js

@@ -0,0 +1,53 @@
+/**
+ * Builds a `WorkerLease` over a single worker generation. The lease settles exactly
+ * once: a per-lease `settled` flag short-circuits a double `release`/`fail`, and
+ * the actual settlement runs inside the per-worker `mutex` where it re-checks
+ * ownership. A stale generation (the worker was re-stamped with a newer `leaseId`)
+ * or an already-DESTROYED worker is a no-op that NEVER touches `inFlight`, so a
+ * late-resolving run from an old generation cannot underflow the live count.
+ */
+export function createLease(options) {
+    const { leaseId, record, mutex, clock, acquiredAtMs, expiresAtMs, onSettle } = options;
+    // Per-lease guard so a second release/fail from the SAME lease is a no-op.
+    // This is distinct from the leaseId ownership check (cross-generation).
+    let settled = false;
+    async function settle(outcome, reason) {
+        // Cheap pre-check outside the mutex: an already-settled lease never queues.
+        if (settled)
+            return;
+        await mutex.runExclusive(async () => {
+            // Re-check inside the lock: a concurrent settle may have flipped the flag
+            // while this body waited its turn in the chain.
+            if (settled)
+                return;
+            // Ownership/state guard: the worker must still belong to THIS lease generation
+            // and not have been destroyed by the reaper. A mismatch is a cross-generation
+            // stale release (or a destroyed worker) and must not touch `inFlight`.
+            if (record.leaseId !== leaseId || record.state === "DESTROYED") {
+                settled = true;
+                return;
+            }
+            settled = true;
+            await onSettle(record, outcome, reason);
+        });
+    }
+    return {
+        leaseId,
+        workerId: record.workerId,
+        workerHost: record.workerHost,
+        acquiredAtMs,
+        expiresAtMs,
+        async release(outcome = "healthy") {
+            await settle(outcome, null);
+        },
+        async fail(reason) {
+            await settle("poison", reason);
+        },
+        heartbeat() {
+            // Best-effort liveness stamp read by the reaper's orphan detection. A stale
+            // generation's heartbeat is harmless: the record is no longer this lease's.
+            record.lastHeartbeatMs = clock.now();
+        },
+    };
+}
+//# sourceMappingURL=lease.js.map

package/packages/worker-pool/dist/lease.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lease.js","sourceRoot":"","sources":["../src/lease.ts"],"names":[],"mappings":"AA8BA;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CAAC,OAA2B;IACrD,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC;IAEvF,2EAA2E;IAC3E,wEAAwE;IACxE,IAAI,OAAO,GAAG,KAAK,CAAC;IAEpB,KAAK,UAAU,MAAM,CAAC,OAAsB,EAAE,MAAqB;QACjE,4EAA4E;QAC5E,IAAI,OAAO;YAAE,OAAO;QACpB,MAAM,KAAK,CAAC,YAAY,CAAC,KAAK,IAAI,EAAE;YAClC,0EAA0E;YAC1E,gDAAgD;YAChD,IAAI,OAAO;gBAAE,OAAO;YACpB,+EAA+E;YAC/E,8EAA8E;YAC9E,uEAAuE;YACvE,IAAI,MAAM,CAAC,OAAO,KAAK,OAAO,IAAI,MAAM,CAAC,KAAK,KAAK,WAAW,EAAE,CAAC;gBAC/D,OAAO,GAAG,IAAI,CAAC;gBACf,OAAO;YACT,CAAC;YACD,OAAO,GAAG,IAAI,CAAC;YACf,MAAM,QAAQ,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;QAC1C,CAAC,CAAC,CAAC;IACL,CAAC;IAED,OAAO;QACL,OAAO;QACP,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,YAAY;QACZ,WAAW;QACX,KAAK,CAAC,OAAO,CAAC,UAAyB,SAAS;YAC9C,MAAM,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QAC9B,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,MAAc;YACvB,MAAM,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QACjC,CAAC;QACD,SAAS;YACP,4EAA4E;YAC5E,4EAA4E;YAC5E,MAAM,CAAC,eAAe,GAAG,KAAK,CAAC,GAAG,EAAE,CAAC;QACvC,CAAC;KACF,CAAC;AACJ,CAAC"}

package/packages/worker-pool/dist/ledger.d.ts

@@ -0,0 +1,51 @@
+import type { ClockPort } from "@lorenz/domain";
+import type { LedgerRow } from "./types.js";
+/**
+ * Write-ahead ledger for cloud drivers. A provisional row is flushed BEFORE
+ * the driver is asked to create a machine, then upserted with the real
+ * `driverRef`/`workerHost` once the driver returns. A crash between create
+ * and ledger-correlate is therefore recoverable: a hydrate reconciles
+ * `driver.list()` (authoritative) against these rows by labels or workerId.
+ *
+ * Every mutating method is a no-op for non-cloud drivers (`usesLedger:false`),
+ * so the fake / static-ssh drivers perform ZERO fs I/O. The ledger is pure fs
+ * over an injected path with no coupling to the pool.
+ */
+export interface Ledger {
+    /** Replace the entire ledger contents atomically (tmp file + rename). */
+    flush(rows: ReadonlyArray<LedgerRow>): Promise<void>;
+    /** Read all rows. Missing or corrupt file returns [] (defer to driver.list()). */
+    load(): Promise<LedgerRow[]>;
+    /** Insert or replace a row keyed by `workerId`, then flush atomically. */
+    upsert(row: LedgerRow): Promise<void>;
+    /** Remove a row by `workerId`, then flush atomically. */
+    delete(workerId: string): Promise<void>;
+    /** Read the persisted daily spend, rolling the day key when the UTC day changed. */
+    loadDailySpend(): Promise<DailySpend>;
+    /** Add wall-clock worker-seconds to today's accumulator and persist atomically. */
+    recordDailyWorkerSeconds(workerSeconds: number): Promise<void>;
+    /**
+     * Durably SET today's accumulator to an ABSOLUTE total (not additive) and persist
+     * atomically. Used on a clean drain to flush the pool's authoritative in-memory
+     * daily total, so a crash that dropped an in-flight fire-and-forget additive
+     * record cannot lose the delta. Serialized behind any earlier additive writes.
+     */
+    flushDailyWorkerSeconds(workerSecondsToday: number): Promise<void>;
+}
+/**
+ * Persisted daily worker-second spend. `dayKey` is the UTC calendar day the
+ * accumulator belongs to; a clock crossing midnight UTC zeroes `workerSecondsToday`
+ * so the daily cap rolls over (and survives a restart within the same day).
+ */
+interface DailySpend {
+    workerSecondsToday: number;
+    dayKey: string;
+}
+export interface LedgerOptions {
+    ledgerPath: string;
+    clock: ClockPort;
+    usesLedger: boolean;
+}
+export declare function createLedger(options: LedgerOptions): Ledger;
+export {};
+//# sourceMappingURL=ledger.d.ts.map

package/packages/worker-pool/dist/ledger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger.d.ts","sourceRoot":"","sources":["../src/ledger.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAGhD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C;;;;;;;;;;GAUG;AACH,MAAM,WAAW,MAAM;IACrB,yEAAyE;IACzE,KAAK,CAAC,IAAI,EAAE,aAAa,CAAC,SAAS,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD,kFAAkF;IAClF,IAAI,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;IAC7B,0EAA0E;IAC1E,MAAM,CAAC,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,yDAAyD;IACzD,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxC,oFAAoF;IACpF,cAAc,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC;IACtC,mFAAmF;IACnF,wBAAwB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/D;;;;;OAKG;IACH,uBAAuB,CAAC,kBAAkB,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpE;AAED;;;;GAIG;AACH,UAAU,UAAU;IAClB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC;CAChB;AAMD,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,SAAS,CAAC;IACjB,UAAU,EAAE,OAAO,CAAC;CACrB;AAOD,wBAAgB,YAAY,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,CA8J3D"}