lorenz 0.1.0

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

@@ -0,0 +1,165 @@
+import { randomBytes } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { createMutex } from "./mutex.js";
+/** UTC calendar-day key (YYYY-MM-DD) used to roll the daily spend accumulator. */
+function utcDayKey(now) {
+    return now.toISOString().slice(0, 10);
+}
+export function createLedger(options) {
+    const { ledgerPath, clock, usesLedger } = options;
+    const spendPath = path.join(path.dirname(ledgerPath), "spend.json");
+    // One in-process mutex serializes every read-modify-write against the ledger and
+    // the spend sidecar. Without it, concurrent settles (the pool calls
+    // `recordDailyWorkerSeconds` fire-and-forget per worker) interleave their
+    // read-then-write and lose updates, under-counting the daily budget.
+    const fileMutex = createMutex();
+    // Disabled ledger: every method is inert. Reads still return a coherent zeroed
+    // view (an empty inventory and a today-keyed zero spend) so callers need no
+    // special-casing, and writes never touch the filesystem.
+    if (!usesLedger) {
+        return {
+            async flush() { },
+            async load() {
+                return Promise.resolve([]);
+            },
+            async upsert() { },
+            async delete() { },
+            async loadDailySpend() {
+                return Promise.resolve({ workerSecondsToday: 0, dayKey: utcDayKey(clock.now()) });
+            },
+            async recordDailyWorkerSeconds() { },
+            async flushDailyWorkerSeconds() { },
+        };
+    }
+    async function writeAtomic(filePath, text) {
+        await fs.mkdir(path.dirname(filePath), { recursive: true });
+        // Unique tmp sibling so concurrent writers never collide on the tmp name,
+        // then a single atomic rename swaps in a complete file. A reader therefore
+        // never observes a half-written ledger.
+        const tmpPath = `${filePath}.${randomBytes(6).toString("hex")}.tmp`;
+        await fs.writeFile(tmpPath, text, "utf8");
+        try {
+            await fs.rename(tmpPath, filePath);
+        }
+        catch (error) {
+            await fs.rm(tmpPath, { force: true });
+            throw error;
+        }
+    }
+    async function load() {
+        let text;
+        try {
+            text = await fs.readFile(ledgerPath, "utf8");
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return [];
+            throw error;
+        }
+        // Corruption tolerance: a truncated or garbage file must not throw. The pool
+        // defers to driver.list() as the authoritative inventory in that case.
+        try {
+            const parsed = JSON.parse(text);
+            if (!parsed || !Array.isArray(parsed.rows))
+                return [];
+            return parsed.rows;
+        }
+        catch {
+            return [];
+        }
+    }
+    async function flush(rows) {
+        const file = { rows: [...rows] };
+        await writeAtomic(ledgerPath, `${JSON.stringify(file, null, 2)}\n`);
+    }
+    async function upsert(row) {
+        await fileMutex.runExclusive(async () => {
+            const rows = await load();
+            const index = rows.findIndex((existing) => existing.workerId === row.workerId);
+            if (index === -1)
+                rows.push(row);
+            else
+                rows[index] = row;
+            await flush(rows);
+        });
+    }
+    async function remove(workerId) {
+        await fileMutex.runExclusive(async () => {
+            const rows = await load();
+            const next = rows.filter((row) => row.workerId !== workerId);
+            if (next.length === rows.length)
+                return;
+            await flush(next);
+        });
+    }
+    async function readSpendFile() {
+        let text;
+        try {
+            text = await fs.readFile(spendPath, "utf8");
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return null;
+            throw error;
+        }
+        try {
+            const parsed = JSON.parse(text);
+            if (!parsed ||
+                typeof parsed.workerSecondsToday !== "number" ||
+                typeof parsed.dayKey !== "string") {
+                return null;
+            }
+            return { workerSecondsToday: parsed.workerSecondsToday, dayKey: parsed.dayKey };
+        }
+        catch {
+            return null;
+        }
+    }
+    // Reads the sidecar and rolls it to the current UTC day. A stored day that is
+    // not today (or a missing/corrupt sidecar) yields a zeroed accumulator keyed
+    // on today, so a restart within the same day carries the total while a day
+    // boundary resets it.
+    async function loadDailySpend() {
+        const today = utcDayKey(clock.now());
+        const stored = await readSpendFile();
+        if (!stored || stored.dayKey !== today) {
+            return { workerSecondsToday: 0, dayKey: today };
+        }
+        return stored;
+    }
+    async function recordDailyWorkerSeconds(workerSeconds) {
+        // Serialize the read-modify-write so concurrent settles accumulate rather than
+        // clobber the single global spend.json (a lost-update would under-count the
+        // daily budget, which the pool seeds from this sidecar after a restart).
+        await fileMutex.runExclusive(async () => {
+            const current = await loadDailySpend();
+            const next = {
+                dayKey: current.dayKey,
+                workerSecondsToday: current.workerSecondsToday + workerSeconds,
+            };
+            await writeAtomic(spendPath, `${JSON.stringify(next, null, 2)}\n`);
+        });
+    }
+    async function flushDailyWorkerSeconds(workerSecondsToday) {
+        // SET (not add) the authoritative absolute total under the same fileMutex, so a
+        // clean-drain flush is serialized AFTER any earlier fire-and-forget additive
+        // write and durably records the final daily total. Keyed on today's UTC day so
+        // a flush straddling a day boundary writes the new day's accumulator.
+        await fileMutex.runExclusive(async () => {
+            const today = utcDayKey(clock.now());
+            const next = { dayKey: today, workerSecondsToday };
+            await writeAtomic(spendPath, `${JSON.stringify(next, null, 2)}\n`);
+        });
+    }
+    return {
+        flush,
+        load,
+        upsert,
+        delete: remove,
+        loadDailySpend,
+        recordDailyWorkerSeconds,
+        flushDailyWorkerSeconds,
+    };
+}
+//# sourceMappingURL=ledger.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ledger.js","sourceRoot":"","sources":["../src/ledger.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAClC,OAAO,IAAI,MAAM,WAAW,CAAC;AAI7B,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAwDzC,kFAAkF;AAClF,SAAS,SAAS,CAAC,GAAS;IAC1B,OAAO,GAAG,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AACxC,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,OAAsB;IACjD,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC;IAClD,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,YAAY,CAAC,CAAC;IAEpE,iFAAiF;IACjF,oEAAoE;IACpE,0EAA0E;IAC1E,qEAAqE;IACrE,MAAM,SAAS,GAAG,WAAW,EAAE,CAAC;IAEhC,+EAA+E;IAC/E,4EAA4E;IAC5E,yDAAyD;IACzD,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,OAAO;YACL,KAAK,CAAC,KAAK,KAAI,CAAC;YAChB,KAAK,CAAC,IAAI;gBACR,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;YAC7B,CAAC;YACD,KAAK,CAAC,MAAM,KAAI,CAAC;YACjB,KAAK,CAAC,MAAM,KAAI,CAAC;YACjB,KAAK,CAAC,cAAc;gBAClB,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,kBAAkB,EAAE,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;YACpF,CAAC;YACD,KAAK,CAAC,wBAAwB,KAAI,CAAC;YACnC,KAAK,CAAC,uBAAuB,KAAI,CAAC;SACnC,CAAC;IACJ,CAAC;IAED,KAAK,UAAU,WAAW,CAAC,QAAgB,EAAE,IAAY;QACvD,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC5D,0EAA0E;QAC1E,2EAA2E;QAC3E,wCAAwC;QACxC,MAAM,OAAO,GAAG,GAAG,QAAQ,IAAI,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC;QACpE,MAAM,EAAE,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;QAC1C,IAAI,CAAC;YACH,MAAM,EAAE,CAAC,MAAM,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QACrC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,EAAE,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;YACtC,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED,KAAK,UAAU,IAAI;QACjB,IAAI,IAAY,CAAC;QACjB,IAAI,CAAC;YACH,IAAI,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;QAC/C,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ;gBAAE,OAAO,EAAE,CAAC;YAClE,MAAM,KAAK,CAAC;QACd,CAAC;QACD,6EAA6E;QAC7E,uEAAuE;QACvE,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAwB,CAAC;YACvD,IAAI,CAAC,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC;gBAAE,OAAO,EAAE,CAAC;YACtD,OAAO,MAAM,CAAC,IAAI,CAAC;QACrB,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,CAAC;QACZ,CAAC;IACH,CAAC;IAED,KAAK,UAAU,KAAK,CAAC,IAA8B;QACjD,MAAM,IAAI,GAAe,EAAE,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC;QAC7C,MAAM,WAAW,CAAC,UAAU,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;IACtE,CAAC;IAED,KAAK,UAAU,MAAM,CAAC,GAAc;QAClC,MAAM,SAAS,CAAC,YAAY,CAAC,KAAK,IAAI,EAAE;YACtC,MAAM,IAAI,GAAG,MAAM,IAAI,EAAE,CAAC;YAC1B,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,QAAQ,KAAK,GAAG,CAAC,QAAQ,CAAC,CAAC;YAC/E,IAAI,KAAK,KAAK,CAAC,CAAC;gBAAE,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;;gBAC5B,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC;YACvB,MAAM,KAAK,CAAC,IAAI,CAAC,CAAC;QACpB,CAAC,CAAC,CAAC;IACL,CAAC;IAED,KAAK,UAAU,MAAM,CAAC,QAAgB;QACpC,MAAM,SAAS,CAAC,YAAY,CAAC,KAAK,IAAI,EAAE;YACtC,MAAM,IAAI,GAAG,MAAM,IAAI,EAAE,CAAC;YAC1B,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC;YAC7D,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM;gBAAE,OAAO;YACxC,MAAM,KAAK,CAAC,IAAI,CAAC,CAAC;QACpB,CAAC,CAAC,CAAC;IACL,CAAC;IAED,KAAK,UAAU,aAAa;QAC1B,IAAI,IAAY,CAAC;QACjB,IAAI,CAAC;YACH,IAAI,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;QAC9C,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ;gBAAE,OAAO,IAAI,CAAC;YACpE,MAAM,KAAK,CAAC;QACd,CAAC;QACD,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAwB,CAAC;YACvD,IACE,CAAC,MAAM;gBACP,OAAO,MAAM,CAAC,kBAAkB,KAAK,QAAQ;gBAC7C,OAAO,MAAM,CAAC,MAAM,KAAK,QAAQ,EACjC,CAAC;gBACD,OAAO,IAAI,CAAC;YACd,CAAC;YACD,OAAO,EAAE,kBAAkB,EAAE,MAAM,CAAC,kBAAkB,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC;QAClF,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED,8EAA8E;IAC9E,6EAA6E;IAC7E,2EAA2E;IAC3E,sBAAsB;IACtB,KAAK,UAAU,cAAc;QAC3B,MAAM,KAAK,GAAG,SAAS,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC;QACrC,MAAM,MAAM,GAAG,MAAM,aAAa,EAAE,CAAC;QACrC,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,KAAK,KAAK,EAAE,CAAC;YACvC,OAAO,EAAE,kBAAkB,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;QAClD,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,KAAK,UAAU,wBAAwB,CAAC,aAAqB;QAC3D,+EAA+E;QAC/E,4EAA4E;QAC5E,yEAAyE;QACzE,MAAM,SAAS,CAAC,YAAY,CAAC,KAAK,IAAI,EAAE;YACtC,MAAM,OAAO,GAAG,MAAM,cAAc,EAAE,CAAC;YACvC,MAAM,IAAI,GAAe;gBACvB,MAAM,EAAE,OAAO,CAAC,MAAM;gBACtB,kBAAkB,EAAE,OAAO,CAAC,kBAAkB,GAAG,aAAa;aAC/D,CAAC;YACF,MAAM,WAAW,CAAC,SAAS,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;QACrE,CAAC,CAAC,CAAC;IACL,CAAC;IAED,KAAK,UAAU,uBAAuB,CAAC,kBAA0B;QAC/D,gFAAgF;QAChF,6EAA6E;QAC7E,+EAA+E;QAC/E,sEAAsE;QACtE,MAAM,SAAS,CAAC,YAAY,CAAC,KAAK,IAAI,EAAE;YACtC,MAAM,KAAK,GAAG,SAAS,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC;YACrC,MAAM,IAAI,GAAe,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,EAAE,CAAC;YAC/D,MAAM,WAAW,CAAC,SAAS,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;QACrE,CAAC,CAAC,CAAC;IACL,CAAC;IAED,OAAO;QACL,KAAK;QACL,IAAI;QACJ,MAAM;QACN,MAAM,EAAE,MAAM;QACd,cAAc;QACd,wBAAwB;QACxB,uBAAuB;KACxB,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,10 @@
+import type { Mutex } from "./types.js";
+/**
+ * Creates a promise-chain async mutex. Each `runExclusive` call appends its body
+ * to a tail promise so bodies run strictly one at a time in call order. The tail
+ * advances regardless of whether a body resolves or throws, so a failing body
+ * never deadlocks the next caller. The caller still observes the body's own
+ * resolution/rejection.
+ */
+export declare function createMutex(): Mutex;
+//# sourceMappingURL=mutex.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mutex.d.ts","sourceRoot":"","sources":["../src/mutex.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC;;;;;;GAMG;AACH,wBAAgB,WAAW,IAAI,KAAK,CAiBnC"}

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

@@ -0,0 +1,22 @@
+/**
+ * Creates a promise-chain async mutex. Each `runExclusive` call appends its body
+ * to a tail promise so bodies run strictly one at a time in call order. The tail
+ * advances regardless of whether a body resolves or throws, so a failing body
+ * never deadlocks the next caller. The caller still observes the body's own
+ * resolution/rejection.
+ */
+export function createMutex() {
+    // `tail` is the promise the next body must wait on. It is intentionally
+    // detached from each body's success/failure so a throwing body still releases.
+    let tail = Promise.resolve();
+    return {
+        async runExclusive(fn) {
+            const run = tail.then(async () => fn());
+            // Advance the chain once this body settles (resolve OR reject), swallowing
+            // the result so the tail never carries a rejection forward to the next body.
+            tail = run.then(() => undefined, () => undefined);
+            return run;
+        },
+    };
+}
+//# sourceMappingURL=mutex.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mutex.js","sourceRoot":"","sources":["../src/mutex.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,UAAU,WAAW;IACzB,wEAAwE;IACxE,+EAA+E;IAC/E,IAAI,IAAI,GAAkB,OAAO,CAAC,OAAO,EAAE,CAAC;IAE5C,OAAO;QACL,KAAK,CAAC,YAAY,CAAI,EAAoB;YACxC,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;YACxC,2EAA2E;YAC3E,6EAA6E;YAC7E,IAAI,GAAG,GAAG,CAAC,IAAI,CACb,GAAG,EAAE,CAAC,SAAS,EACf,GAAG,EAAE,CAAC,SAAS,CAChB,CAAC;YACF,OAAO,GAAG,CAAC;QACb,CAAC;KACF,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,33 @@
+import { type WorkerDriverRegistry } from "@lorenz/worker-sdk";
+import type { WorkerPoolSettings } from "@lorenz/domain";
+import type { ClockPort } from "@lorenz/domain";
+import type { WorkerPool } from "./types.js";
+/**
+ * Dependencies the pool factory receives. Deliberately excludes any workspace or
+ * hook deps: the pool owns worker lifecycle only (the runner owns workspaces). The
+ * `ledgerPath` is optional and only consulted when the resolved driver's
+ * `capabilities.usesLedger` is true (cloud); a purely in-memory driver does zero
+ * fs I/O.
+ */
+export interface CreateWorkerPoolDeps {
+    clock: ClockPort;
+    logEvent: (event: Record<string, unknown>) => void;
+    ledgerPath?: string;
+    /**
+     * Worker-driver registry the pool resolves `settings.driver` against. The
+     * composition root registers driver extensions and passes its registry here;
+     * absent, the pool falls back to the process-wide
+     * {@link defaultWorkerDriverRegistry}.
+     */
+    drivers?: WorkerDriverRegistry | undefined;
+}
+/**
+ * Constructs a {@link WorkerPool}. Resolves the driver for `settings.driver`
+ * through `deps.drivers` (falling back to the process-wide default registry),
+ * throwing `worker_pool_driver_unavailable` for an unregistered kind so the daemon
+ * fails loud at startup, and wires the write-ahead ledger only when the driver
+ * declares `usesLedger` AND a `ledgerPath` is supplied. No workspace/hook deps
+ * are taken: the pool owns worker lifecycle only.
+ */
+export declare function createWorkerPool(settings: WorkerPoolSettings, deps: CreateWorkerPoolDeps): WorkerPool;
+//# sourceMappingURL=pool.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pool.d.ts","sourceRoot":"","sources":["../src/pool.ts"],"names":[],"mappings":"AAEA,OAAO,EAKL,KAAK,oBAAoB,EAG1B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACzD,OAAO,KAAK,EAAE,SAAS,EAAe,MAAM,gBAAgB,CAAC;AAO7D,OAAO,KAAK,EAKV,UAAU,EAMX,MAAM,YAAY,CAAC;AAEpB;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,SAAS,CAAC;IACjB,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IACnD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,oBAAoB,GAAG,SAAS,CAAC;CAC5C;AAkyDD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,kBAAkB,EAC5B,IAAI,EAAE,oBAAoB,GACzB,UAAU,CAEZ"}