@capybara-hq/kernel 0.1.0-rc.1 → 0.1.0-rc.3

package/dist/infra/lock/lock.service.js

@@ -0,0 +1,343 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+// Ported from octok-platform libs/common/src/decorators/with-lock.decorator.ts and
+// libs/flow/src/runtime/redis-token-lock.ts (owner-approved, 2026-10-28).
+// Adapted to the kernel: pino logger, ApiError, and a `lost` signal when renewal fails.
+import { randomUUID } from "node:crypto";
+import { Inject, Injectable } from "@nestjs/common";
+import { ApiError } from "../../errors.js";
+import { currentStore } from "../database/transaction-host.js";
+import { KERNEL_LOGGER, REDIS } from "../tokens.js";
+import { ACQUIRE_EXCLUSIVE, ACQUIRE_SHARED, COUNT_SHARED_LEASES, DOWNGRADE_SHARED_LEASE, RELEASE_SHARED_LEASE, RENEW_SHARED_LEASE, } from "./shared-lease.js";
+/** Deletes the key only while it holds our token. */
+const RELEASE_IF = `if redis.call('get', KEYS[1]) == ARGV[1] then return redis.call('del', KEYS[1]) else return 0 end`;
+/** Extends the key only while it holds our token. */
+const RENEW_IF = `if redis.call('get', KEYS[1]) == ARGV[1] then return redis.call('pexpire', KEYS[1], tonumber(ARGV[2])) else return 0 end`;
+/** Resolves after `ms`; rejects with the abort reason when `signal` aborts first. */
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(signal.reason);
+            return;
+        }
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal?.reason);
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+/**
+ * Locks and leases are never taken inside a transaction: a lock released before the COMMIT lets
+ * the next holder read rows not yet committed, and one held across it holds a connection while
+ * waiting. Take the lock first, then open the transaction.
+ */
+function assertNoTransaction(op) {
+    if (currentStore()) {
+        throw new Error(`LockService.${op}() must not run inside a transaction: take the lock first, then open it.`);
+    }
+}
+export const prefixed = (key) => (key.startsWith("lock:") ? key : `lock:${key}`);
+/**
+ * Redis distributed locks: `SET NX PX` with a Lua compare-and-delete release and a watchdog that
+ * renews every TTL/3 (short lock plus renewal: a long job keeps it, a crashed holder's lock
+ * expires within the TTL). Also the primitives for leases whose holder is a caller-chosen string
+ * (`lease` / `renew` / `releaseIf`, used by the sandbox leases).
+ */
+let LockService = class LockService {
+    redis;
+    log;
+    constructor(redis, log) {
+        this.redis = redis;
+        this.log = log;
+    }
+    /**
+     * Tries to take `lock:<key>`; resolves `undefined` when it stays held by someone else until
+     * `waitMs` ran out. An aborted `signal` throws its reason instead.
+     */
+    async acquire(key, opts) {
+        assertNoTransaction("acquire");
+        const lockKey = prefixed(key);
+        const token = randomUUID();
+        const deadline = Date.now() + (opts.waitMs ?? 0);
+        const retryMs = opts.retryMs ?? 100;
+        for (;;) {
+            opts.signal?.throwIfAborted();
+            const sentAt = Date.now();
+            if ((await this.redis.set(lockKey, token, "PX", Math.ceil(opts.ttlMs), "NX")) === "OK") {
+                this.log.debug("lock acquired", { lockKey });
+                return this.watch(lockKey, token, opts.ttlMs, sentAt);
+            }
+            const remaining = deadline - Date.now();
+            if (remaining <= 0) {
+                // Contention is normal in a multi-replica deployment, not an error.
+                this.log.info("lock held elsewhere", { lockKey });
+                return undefined;
+            }
+            await sleep(Math.min(retryMs, remaining), opts.signal);
+        }
+    }
+    /** Runs `fn` under the lock; throws `lock.acquire_failed` when it cannot be taken. */
+    async run(key, opts, fn) {
+        const handle = await this.acquire(key, opts);
+        if (!handle)
+            throw lockAcquireFailed(prefixed(key));
+        try {
+            return await fn(handle);
+        }
+        finally {
+            await handle.release();
+        }
+    }
+    /** Sets `key` to `holder` for `ttlMs` unless it exists (no `lock:` prefix, no renewal timer). */
+    async lease(key, holder, ttlMs) {
+        assertNoTransaction("lease");
+        return (await this.redis.set(key, holder, "PX", Math.ceil(ttlMs), "NX")) === "OK";
+    }
+    /** Extends `key` to `ttlMs` when `holder` still owns it. */
+    async renew(key, holder, ttlMs) {
+        return (await this.redis.eval(RENEW_IF, 1, key, holder, String(Math.ceil(ttlMs)))) === 1;
+    }
+    /** The holder value of `key` (a lease's or a lock's token); null when nobody holds it. */
+    holderOf(key) {
+        return this.redis.get(key);
+    }
+    /** Deletes `key` when `holder` still owns it. */
+    async releaseIf(key, holder) {
+        return (await this.redis.eval(RELEASE_IF, 1, key, holder)) === 1;
+    }
+    /**
+     * Takes `key` (no `lock:` prefix) with the caller's `holder` value for `ttlMs`, unless it is
+     * held, and renews it every TTL/3 like {@link acquire} (a run longer than the TTL keeps it, a
+     * crashed holder's key expires within the TTL). Resolves `undefined` when the key is held; tries
+     * once. For leases whose holder other replicas read (the conversation run lock: the run id).
+     */
+    async hold(key, holder, ttlMs) {
+        assertNoTransaction("hold");
+        const sentAt = Date.now();
+        if (!(await this.lease(key, holder, ttlMs)))
+            return undefined;
+        return this.watch(key, holder, ttlMs, sentAt);
+    }
+    /**
+     * One try at a shared lease of `keys` for `token` (at most `cap` shared holders; not granted
+     * while an exclusive holder, another `SET NX` value of the lock key or another token's intent
+     * exists). Resolves `undefined` when not granted; a granted lease is renewed every TTL/3.
+     */
+    async tryShared(keys, token, cap, ttlMs) {
+        assertNoTransaction("tryShared");
+        const sentAt = Date.now();
+        const ok = await this.redis.eval(ACQUIRE_SHARED, 3, keys.lock, keys.users, keys.intent, token, cap, Math.ceil(ttlMs));
+        return Number(ok) === 1 ? this.watchShared(keys, token, "shared", ttlMs, sentAt) : undefined;
+    }
+    /**
+     * One try at the exclusive lease of `keys` for `token` (granted only when no lease of either
+     * kind exists). With `intentTtlMs` a failed try sets (or refreshes) the intent to `token` unless
+     * another token's intent exists, so new shared leases wait; a successful try clears our intent.
+     */
+    async tryExclusive(keys, token, ttlMs, intentTtlMs) {
+        assertNoTransaction("tryExclusive");
+        const sentAt = Date.now();
+        const ok = await this.redis.eval(ACQUIRE_EXCLUSIVE, 3, keys.lock, keys.users, keys.intent, token, Math.ceil(ttlMs), intentTtlMs === undefined ? 0 : 1, Math.ceil(intentTtlMs ?? 0));
+        return Number(ok) === 1 ? this.watchShared(keys, token, "exclusive", ttlMs, sentAt) : undefined;
+    }
+    /** Live shared leases of `keys` (expired ones are purged first). */
+    async sharedCount(keys) {
+        return Number(await this.redis.eval(COUNT_SHARED_LEASES, 2, keys.lock, keys.users));
+    }
+    /** The watchdog of a shared lease we just took; its kind changes once, on a downgrade. */
+    watchShared(keys, token, initial, ttlMs, sentAt) {
+        let kind = initial;
+        let released = false;
+        /** The DOWNGRADE eval in flight, if any. */
+        let downgrading;
+        const ttl = String(Math.ceil(ttlMs));
+        const w = this.watchdog(keys.lock, ttlMs, {
+            renew: async () => {
+                // a downgrade still in flight decides the kind to renew (Redis may have made it shared)
+                await downgrading?.catch(() => { });
+                return (Number(await this.redis.eval(RENEW_SHARED_LEASE, 2, keys.lock, keys.users, token, ttl, kind)) === 1);
+            },
+            release: async () => {
+                // a downgrade still in flight decides the kind the lease has in Redis
+                await downgrading?.catch(() => { });
+                await this.redis.eval(RELEASE_SHARED_LEASE, 2, keys.lock, keys.users, token, kind);
+            },
+        }, sentAt);
+        return {
+            token,
+            get kind() {
+                return kind;
+            },
+            lost: w.lost,
+            renew: () => w.renew(),
+            abandon: () => w.abandon(),
+            release: async () => {
+                released = true;
+                await w.release();
+            },
+            downgrade: async () => {
+                if (kind !== "exclusive" || released)
+                    throw new Error("lease is not exclusive");
+                w.lost.throwIfAborted();
+                return w.renewWith(async () => {
+                    downgrading = this.redis
+                        .eval(DOWNGRADE_SHARED_LEASE, 2, keys.lock, keys.users, token, ttl)
+                        .then((r) => Number(r) === 1);
+                    try {
+                        const done = await downgrading;
+                        // Redis made it shared: record that even when the lease was lost or released while the
+                        // call was in flight, so the release removes the shared member (no leak)
+                        if (done)
+                            kind = "shared";
+                        return done;
+                    }
+                    finally {
+                        downgrading = undefined;
+                    }
+                });
+            },
+        };
+    }
+    /** The renewal watchdog of a key we just took (the `SET NX` was sent at `sentAt`). */
+    watch(lockKey, token, ttlMs, sentAt) {
+        return this.keepAlive(lockKey, ttlMs, {
+            renew: () => this.renew(lockKey, token, ttlMs),
+            release: async () => {
+                if (!(await this.releaseIf(lockKey, token))) {
+                    this.log.warn("lock was not ours at release (expired or taken)", { lockKey });
+                }
+            },
+        }, sentAt);
+    }
+    /**
+     * The renewal watchdog for a lease kept by other means than a `SET NX` key (e.g. an org quota
+     * slot, a member of a Redis sorted set): calls `ops.renew` every TTL/3 while held. A renewal
+     * answered `false` marks it lost at once (`lost` aborts, one WARN `lock lost` with `label`).
+     * Loss is a deadline (decision R19 of the Nest kernel spec), not a counter. The deadline is the
+     * send time of the last successful renewal (or of the acquire, `acquiredAt`, default now) + TTL −
+     * TTL/3; any successful renewal through the handle (the watchdog's or an explicit `renew()`)
+     * moves it; when it passes without one, `lost` aborts, even with a renewal still in flight. So a
+     * holder gives up one renewal period before the key can expire elsewhere. `release` stops
+     * renewing and calls `ops.release` once.
+     */
+    keepAlive(label, ttlMs, ops, acquiredAt = Date.now()) {
+        return this.watchdog(label, ttlMs, ops, acquiredAt);
+    }
+    /** {@link keepAlive}'s implementation, with {@link Watched.renewWith}. */
+    watchdog(label, ttlMs, ops, acquiredAt) {
+        const lockKey = label;
+        const lost = new AbortController();
+        let released = false;
+        let stopped = false;
+        const intervalMs = Math.max(1, Math.floor(ttlMs / 3));
+        /** Send time of the last successful renewal (or of the acquire). */
+        let lastOkSentAt = acquiredAt;
+        let deadline;
+        const stop = () => {
+            stopped = true;
+            clearInterval(timer);
+            clearTimeout(deadline);
+        };
+        const lose = (reason) => {
+            // released or abandoned: the holder gave the lease up, so a late answer loses nothing
+            if (released || stopped || lost.signal.aborted)
+                return;
+            this.log.warn(reason, { lockKey });
+            lost.abort(new Error(`lock lost: ${lockKey}`));
+            stop();
+        };
+        const deadlineAt = () => lastOkSentAt + ttlMs - intervalMs;
+        const arm = () => {
+            clearTimeout(deadline);
+            if (stopped)
+                return;
+            const ms = Math.max(0, deadlineAt() - Date.now());
+            deadline = setTimeout(() => lose("lock lost: renewal kept failing"), ms);
+            deadline.unref();
+        };
+        /** One renewal: a success moves the deadline (by its send time), `false` loses the lease. */
+        const renewOnce = async (op = () => ops.renew()) => {
+            const sentAt = Date.now();
+            const ok = await op();
+            if (released || lost.signal.aborted)
+                return false;
+            if (!ok) {
+                lose("lock lost: the key is gone or taken");
+                return false;
+            }
+            if (sentAt > lastOkSentAt) {
+                lastOkSentAt = sentAt;
+                arm();
+            }
+            return true;
+        };
+        const timer = setInterval(() => {
+            // the deadline timer decides the loss; this check only backs it up on the watchdog's own
+            // clock (both fire at the deadline: never earlier)
+            if (Date.now() >= deadlineAt()) {
+                lose("lock lost: renewal kept failing");
+                return;
+            }
+            renewOnce().catch((err) => {
+                if (released || stopped)
+                    return;
+                // a transient Redis error: the next tick retries; the deadline decides the loss
+                this.log.warn("lock renewal failed", { lockKey, err });
+            });
+        }, intervalMs);
+        timer.unref();
+        arm();
+        return {
+            lost: lost.signal,
+            // an explicit renewal: a Redis error is thrown to the caller, not logged (the watchdog's
+            // own failures are, once each)
+            renew: async () => {
+                if (released || lost.signal.aborted)
+                    return false;
+                return renewOnce();
+            },
+            renewWith: async (op) => {
+                if (released || lost.signal.aborted)
+                    return false;
+                return renewOnce(op);
+            },
+            abandon: stop,
+            release: async () => {
+                if (released)
+                    return;
+                released = true;
+                stop();
+                try {
+                    await ops.release();
+                }
+                catch (err) {
+                    // warn: the key expires within its TTL anyway
+                    this.log.warn("lock release failed", { lockKey, err });
+                }
+            },
+        };
+    }
+};
+LockService = __decorate([
+    Injectable(),
+    __param(0, Inject(REDIS)),
+    __param(1, Inject(KERNEL_LOGGER))
+], LockService);
+export { LockService };
+export function lockAcquireFailed(lockKey) {
+    return new ApiError("lock.acquire_failed", "The operation is already in progress; retry later.", [
+        { lockKey },
+    ]);
+}

package/dist/infra/lock/shared-lease.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Shared and exclusive leases on one resource (a reader-writer lease across replicas): up to `cap`
+ * shared holders at once, or one exclusive holder alone, with writer preference through an intent
+ * key. The Redis layout (the caller names the three keys; no `lock:` prefix is added):
+ *
+ * - `lock`: the exclusive holder's token, or `shared` while shared leases exist (so a plain
+ *   `SET NX` holder of the same key and the shared holders exclude each other);
+ * - `users`: sorted set of shared holders' tokens scored by their expiry (ms, Redis server clock);
+ * - `intent`: an exclusive waiter's token; while it exists no new shared lease is granted except
+ *   to the waiter's own token.
+ *
+ * Every script purges expired shared leases first, and every key carries a TTL. The scripts are
+ * the protocol of {@link LockService.tryShared} / {@link LockService.tryExclusive} and the handle
+ * they return (renewal, release, downgrade).
+ */
+/** The three keys of one shared lease (see the module comment). */
+export interface SharedLeaseKeys {
+    lock: string;
+    users: string;
+    intent: string;
+}
+export type SharedLeaseKind = "shared" | "exclusive";
+/** A Lua script whose `body` sees `now` (ms, the Redis server clock). */
+export declare function redisClockScript(body: string): string;
+/**
+ * A Lua script that reads a shared lease atomically with other keys (a domain's own records next
+ * to the lease, e.g. the sandbox holder records): KEYS[1] is the lease's lock key and KEYS[2] its
+ * users set (as {@link SharedLeaseKeys}); `body` sees `now` (ms, the Redis server clock) and `cur`,
+ * the lock key's value once expired shared leases are dropped (`'shared'`, an exclusive holder's
+ * token, or false). The lease layout stays in this module.
+ */
+export declare function sharedLeaseReadScript(body: string): string;
+/** KEYS lock, users, intent; ARGV token, cap, ttl. */
+export declare const ACQUIRE_SHARED = "local t = redis.call('TIME'); local now = tonumber(t[1]) * 1000 + math.floor(tonumber(t[2]) / 1000)\n\nredis.call('ZREMRANGEBYSCORE', KEYS[2], '-inf', now)\nlocal cur = redis.call('GET', KEYS[1])\nif cur == 'shared' and redis.call('ZCARD', KEYS[2]) == 0 then\n  redis.call('DEL', KEYS[1])\n  cur = false\nend\nif cur and cur ~= 'shared' then return 0 end\nlocal it = redis.call('GET', KEYS[3])\nif it and it ~= ARGV[1] then return 0 end\nif redis.call('ZCARD', KEYS[2]) >= tonumber(ARGV[2]) then return 0 end\nlocal ttl = tonumber(ARGV[3])\nredis.call('ZADD', KEYS[2], now + ttl, ARGV[1])\n\nif redis.call('PTTL', KEYS[2]) < ttl then redis.call('PEXPIRE', KEYS[2], ttl) end\nlocal lt = redis.call('PTTL', KEYS[1])\nif redis.call('GET', KEYS[1]) ~= 'shared' or lt < ttl then\n  redis.call('SET', KEYS[1], 'shared', 'PX', math.max(ttl, lt))\nend\nreturn 1";
+/** KEYS lock, users, intent; ARGV token, ttl, setIntent (0/1), intentTtl. */
+export declare const ACQUIRE_EXCLUSIVE = "local t = redis.call('TIME'); local now = tonumber(t[1]) * 1000 + math.floor(tonumber(t[2]) / 1000)\n\nredis.call('ZREMRANGEBYSCORE', KEYS[2], '-inf', now)\nlocal cur = redis.call('GET', KEYS[1])\nif cur == 'shared' and redis.call('ZCARD', KEYS[2]) == 0 then\n  redis.call('DEL', KEYS[1])\n  cur = false\nend\nif cur or redis.call('ZCARD', KEYS[2]) > 0 then\n  if ARGV[3] == '1' then\n    local it = redis.call('GET', KEYS[3])\n    if (not it) or it == ARGV[1] then\n      redis.call('SET', KEYS[3], ARGV[1], 'PX', tonumber(ARGV[4]))\n    end\n  end\n  return 0\nend\nredis.call('SET', KEYS[1], ARGV[1], 'PX', tonumber(ARGV[2]))\nif redis.call('GET', KEYS[3]) == ARGV[1] then redis.call('DEL', KEYS[3]) end\nreturn 1";
+/** KEYS lock, users; ARGV token, ttl, kind. Shared: lost when the member is gone or the lock holds a token. */
+export declare const RENEW_SHARED_LEASE = "local t = redis.call('TIME'); local now = tonumber(t[1]) * 1000 + math.floor(tonumber(t[2]) / 1000)\nlocal ttl = tonumber(ARGV[2])\nif ARGV[3] == 'exclusive' then\n  if redis.call('GET', KEYS[1]) == ARGV[1] then\n    redis.call('PEXPIRE', KEYS[1], ttl)\n    return 1\n  end\n  return 0\nend\nredis.call('ZREMRANGEBYSCORE', KEYS[2], '-inf', now)\nif not redis.call('ZSCORE', KEYS[2], ARGV[1]) then return 0 end\nlocal cur = redis.call('GET', KEYS[1])\nif cur and cur ~= 'shared' then\n  redis.call('ZREM', KEYS[2], ARGV[1])\n  return 0\nend\nredis.call('ZADD', KEYS[2], 'XX', now + ttl, ARGV[1])\n\nif redis.call('PTTL', KEYS[2]) < ttl then redis.call('PEXPIRE', KEYS[2], ttl) end\nlocal lt = redis.call('PTTL', KEYS[1])\nif redis.call('GET', KEYS[1]) ~= 'shared' or lt < ttl then\n  redis.call('SET', KEYS[1], 'shared', 'PX', math.max(ttl, lt))\nend\nreturn 1";
+/** KEYS lock, users; ARGV token, kind. */
+export declare const RELEASE_SHARED_LEASE = "local t = redis.call('TIME'); local now = tonumber(t[1]) * 1000 + math.floor(tonumber(t[2]) / 1000)\nif ARGV[2] == 'exclusive' then\n  if redis.call('GET', KEYS[1]) == ARGV[1] then redis.call('DEL', KEYS[1]) end\n  return 1\nend\nredis.call('ZREM', KEYS[2], ARGV[1])\n\nredis.call('ZREMRANGEBYSCORE', KEYS[2], '-inf', now)\nlocal cur = redis.call('GET', KEYS[1])\nif cur == 'shared' and redis.call('ZCARD', KEYS[2]) == 0 then\n  redis.call('DEL', KEYS[1])\n  cur = false\nend\nreturn 1";
+/** KEYS lock, users; ARGV token, ttl. */
+export declare const DOWNGRADE_SHARED_LEASE = "local t = redis.call('TIME'); local now = tonumber(t[1]) * 1000 + math.floor(tonumber(t[2]) / 1000)\nif redis.call('GET', KEYS[1]) ~= ARGV[1] then return 0 end\nlocal ttl = tonumber(ARGV[2])\nredis.call('ZADD', KEYS[2], now + ttl, ARGV[1])\n\nif redis.call('PTTL', KEYS[2]) < ttl then redis.call('PEXPIRE', KEYS[2], ttl) end\nlocal lt = redis.call('PTTL', KEYS[1])\nif redis.call('GET', KEYS[1]) ~= 'shared' or lt < ttl then\n  redis.call('SET', KEYS[1], 'shared', 'PX', math.max(ttl, lt))\nend\nreturn 1";
+/** KEYS lock, users; returns the live shared count. */
+export declare const COUNT_SHARED_LEASES = "local t = redis.call('TIME'); local now = tonumber(t[1]) * 1000 + math.floor(tonumber(t[2]) / 1000)\n\nredis.call('ZREMRANGEBYSCORE', KEYS[2], '-inf', now)\nlocal cur = redis.call('GET', KEYS[1])\nif cur == 'shared' and redis.call('ZCARD', KEYS[2]) == 0 then\n  redis.call('DEL', KEYS[1])\n  cur = false\nend\nreturn redis.call('ZCARD', KEYS[2])";

package/dist/infra/lock/shared-lease.js

@@ -0,0 +1,121 @@
+/**
+ * Shared and exclusive leases on one resource (a reader-writer lease across replicas): up to `cap`
+ * shared holders at once, or one exclusive holder alone, with writer preference through an intent
+ * key. The Redis layout (the caller names the three keys; no `lock:` prefix is added):
+ *
+ * - `lock`: the exclusive holder's token, or `shared` while shared leases exist (so a plain
+ *   `SET NX` holder of the same key and the shared holders exclude each other);
+ * - `users`: sorted set of shared holders' tokens scored by their expiry (ms, Redis server clock);
+ * - `intent`: an exclusive waiter's token; while it exists no new shared lease is granted except
+ *   to the waiter's own token.
+ *
+ * Every script purges expired shared leases first, and every key carries a TTL. The scripts are
+ * the protocol of {@link LockService.tryShared} / {@link LockService.tryExclusive} and the handle
+ * they return (renewal, release, downgrade).
+ */
+/** Sets `now` (ms, the Redis server clock, the same on every replica). */
+const NOW = `local t = redis.call('TIME'); local now = tonumber(t[1]) * 1000 + math.floor(tonumber(t[2]) / 1000)`;
+/**
+ * After {@link NOW} (KEYS[1] the lock key, KEYS[2] the users set): drops expired shared leases and
+ * a `shared` value no live lease backs, and sets `cur` to the lock key's value (false when absent).
+ */
+const PURGE = `
+redis.call('ZREMRANGEBYSCORE', KEYS[2], '-inf', now)
+local cur = redis.call('GET', KEYS[1])
+if cur == 'shared' and redis.call('ZCARD', KEYS[2]) == 0 then
+  redis.call('DEL', KEYS[1])
+  cur = false
+end`;
+/** A Lua script whose `body` sees `now` (ms, the Redis server clock). */
+export function redisClockScript(body) {
+    return `${NOW}
+${body}`;
+}
+/**
+ * A Lua script that reads a shared lease atomically with other keys (a domain's own records next
+ * to the lease, e.g. the sandbox holder records): KEYS[1] is the lease's lock key and KEYS[2] its
+ * users set (as {@link SharedLeaseKeys}); `body` sees `now` (ms, the Redis server clock) and `cur`,
+ * the lock key's value once expired shared leases are dropped (`'shared'`, an exclusive holder's
+ * token, or false). The lease layout stays in this module.
+ */
+export function sharedLeaseReadScript(body) {
+    return `${NOW}
+${PURGE}
+${body}`;
+}
+/**
+ * Keeps the users set and the `shared` lock value alive for at least `ttl` without shortening a
+ * longer TTL another holder set (holders may use different TTLs).
+ */
+const KEEP_SHARED = `
+if redis.call('PTTL', KEYS[2]) < ttl then redis.call('PEXPIRE', KEYS[2], ttl) end
+local lt = redis.call('PTTL', KEYS[1])
+if redis.call('GET', KEYS[1]) ~= 'shared' or lt < ttl then
+  redis.call('SET', KEYS[1], 'shared', 'PX', math.max(ttl, lt))
+end`;
+/** KEYS lock, users, intent; ARGV token, cap, ttl. */
+export const ACQUIRE_SHARED = `${NOW}
+${PURGE}
+if cur and cur ~= 'shared' then return 0 end
+local it = redis.call('GET', KEYS[3])
+if it and it ~= ARGV[1] then return 0 end
+if redis.call('ZCARD', KEYS[2]) >= tonumber(ARGV[2]) then return 0 end
+local ttl = tonumber(ARGV[3])
+redis.call('ZADD', KEYS[2], now + ttl, ARGV[1])
+${KEEP_SHARED}
+return 1`;
+/** KEYS lock, users, intent; ARGV token, ttl, setIntent (0/1), intentTtl. */
+export const ACQUIRE_EXCLUSIVE = `${NOW}
+${PURGE}
+if cur or redis.call('ZCARD', KEYS[2]) > 0 then
+  if ARGV[3] == '1' then
+    local it = redis.call('GET', KEYS[3])
+    if (not it) or it == ARGV[1] then
+      redis.call('SET', KEYS[3], ARGV[1], 'PX', tonumber(ARGV[4]))
+    end
+  end
+  return 0
+end
+redis.call('SET', KEYS[1], ARGV[1], 'PX', tonumber(ARGV[2]))
+if redis.call('GET', KEYS[3]) == ARGV[1] then redis.call('DEL', KEYS[3]) end
+return 1`;
+/** KEYS lock, users; ARGV token, ttl, kind. Shared: lost when the member is gone or the lock holds a token. */
+export const RENEW_SHARED_LEASE = `${NOW}
+local ttl = tonumber(ARGV[2])
+if ARGV[3] == 'exclusive' then
+  if redis.call('GET', KEYS[1]) == ARGV[1] then
+    redis.call('PEXPIRE', KEYS[1], ttl)
+    return 1
+  end
+  return 0
+end
+redis.call('ZREMRANGEBYSCORE', KEYS[2], '-inf', now)
+if not redis.call('ZSCORE', KEYS[2], ARGV[1]) then return 0 end
+local cur = redis.call('GET', KEYS[1])
+if cur and cur ~= 'shared' then
+  redis.call('ZREM', KEYS[2], ARGV[1])
+  return 0
+end
+redis.call('ZADD', KEYS[2], 'XX', now + ttl, ARGV[1])
+${KEEP_SHARED}
+return 1`;
+/** KEYS lock, users; ARGV token, kind. */
+export const RELEASE_SHARED_LEASE = `${NOW}
+if ARGV[2] == 'exclusive' then
+  if redis.call('GET', KEYS[1]) == ARGV[1] then redis.call('DEL', KEYS[1]) end
+  return 1
+end
+redis.call('ZREM', KEYS[2], ARGV[1])
+${PURGE}
+return 1`;
+/** KEYS lock, users; ARGV token, ttl. */
+export const DOWNGRADE_SHARED_LEASE = `${NOW}
+if redis.call('GET', KEYS[1]) ~= ARGV[1] then return 0 end
+local ttl = tonumber(ARGV[2])
+redis.call('ZADD', KEYS[2], now + ttl, ARGV[1])
+${KEEP_SHARED}
+return 1`;
+/** KEYS lock, users; returns the live shared count. */
+export const COUNT_SHARED_LEASES = `${NOW}
+${PURGE}
+return redis.call('ZCARD', KEYS[2])`;

package/dist/infra/lock/with-lock.decorator.d.ts

@@ -0,0 +1,28 @@
+export interface WithLockOptions {
+    /**
+     * Lock key; `lock:` is prepended unless present. Placeholders expand from the method
+     * arguments: `#{0}`, `#{1.book.title}`, `#{user.id}` (= `#{0.user.id}`).
+     */
+    key: string;
+    /** Lock lifetime without renewal, ms (default 30000); the lock is renewed every TTL/3. */
+    ttl?: number;
+    /** How long to wait for the lock, ms (default 5000); 0 tries once. */
+    waitTimeout?: number;
+    /** Pause between attempts, ms (default 100). */
+    retryInterval?: number;
+}
+/**
+ * Method decorator: only one caller at a time, across replicas, runs the method for a given key.
+ * Throws `ApiError("lock.acquire_failed")` (409, `details[0].lockKey`) when the lock is not
+ * obtained in `waitTimeout`. The class must inject the service as a property named `lockService`:
+ *
+ * ```ts
+ * constructor(@Inject(LockService) readonly lockService: LockService) {}
+ * ```
+ *
+ * Never inside a transaction: the lock would be released before COMMIT.
+ *
+ * The method's arguments are the caller's, so it gets no signal of the lock's loss: a body that
+ * must stop when the lock is lost uses `LockService.run`, whose callback gets the handle (`lost`).
+ */
+export declare function WithLock(options: WithLockOptions): (_target: object, _key: string | symbol, descriptor: PropertyDescriptor) => PropertyDescriptor;

package/dist/infra/lock/with-lock.decorator.js

@@ -0,0 +1,49 @@
+// Ported from octok-platform libs/common/src/decorators/with-lock.decorator.ts (owner-approved, 2026-10-28).
+// Adapted: the LockService comes from the `lockService` property, as `@Transactional` reads `txHost`.
+import { currentStore } from "../database/transaction-host.js";
+import { generateKey } from "./key-template.js";
+import { lockAcquireFailed, prefixed } from "./lock.service.js";
+/**
+ * Method decorator: only one caller at a time, across replicas, runs the method for a given key.
+ * Throws `ApiError("lock.acquire_failed")` (409, `details[0].lockKey`) when the lock is not
+ * obtained in `waitTimeout`. The class must inject the service as a property named `lockService`:
+ *
+ * ```ts
+ * constructor(@Inject(LockService) readonly lockService: LockService) {}
+ * ```
+ *
+ * Never inside a transaction: the lock would be released before COMMIT.
+ *
+ * The method's arguments are the caller's, so it gets no signal of the lock's loss: a body that
+ * must stop when the lock is lost uses `LockService.run`, whose callback gets the handle (`lost`).
+ */
+export function WithLock(options) {
+    return (_target, _key, descriptor) => {
+        const original = descriptor.value;
+        descriptor.value = async function (...args) {
+            const service = this.lockService;
+            if (!service) {
+                throw new Error("@WithLock() needs the class to inject `LockService` as `lockService` " +
+                    "(`@Inject(LockService) readonly lockService: LockService`).");
+            }
+            if (currentStore()) {
+                throw new Error("@WithLock() must not run inside a transaction: lock first, then open it.");
+            }
+            const key = generateKey(options.key, args);
+            const handle = await service.acquire(key, {
+                ttlMs: options.ttl ?? 30_000,
+                waitMs: options.waitTimeout ?? 5_000,
+                retryMs: options.retryInterval ?? 100,
+            });
+            if (!handle)
+                throw lockAcquireFailed(prefixed(key));
+            try {
+                return await original.apply(this, args);
+            }
+            finally {
+                await handle.release();
+            }
+        };
+        return descriptor;
+    };
+}

package/dist/infra/logging/logging.module.d.ts

@@ -0,0 +1,16 @@
+import { type DynamicModule } from "@nestjs/common";
+import type { KernelConfig } from "../../config/schema.js";
+import type { KernelLogger } from "../../log.js";
+export interface LoggingModuleOptions {
+    /** An existing logger (tests, embedders); default: the one the config describes. */
+    logger?: KernelLogger;
+}
+/**
+ * Provides the process logger as `KERNEL_LOGGER`. The logger is created before the Nest context
+ * (it must exist for startup errors), so it is passed in or derived from the startup config here.
+ */
+export declare class LoggingModule {
+    static forRoot(config: KernelConfig, opts?: LoggingModuleOptions): DynamicModule;
+    /** Provides `logger` (a context without a config: `KernelCliModule.overPool`). */
+    static forLogger(logger: KernelLogger): DynamicModule;
+}

package/dist/infra/logging/logging.module.js

@@ -0,0 +1,34 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var LoggingModule_1;
+import { Global, Module } from "@nestjs/common";
+import { createConfiguredLogger } from "../../log-config.js";
+import { KERNEL_LOGGER } from "../tokens.js";
+/**
+ * Provides the process logger as `KERNEL_LOGGER`. The logger is created before the Nest context
+ * (it must exist for startup errors), so it is passed in or derived from the startup config here.
+ */
+let LoggingModule = LoggingModule_1 = class LoggingModule {
+    static forRoot(config, opts = {}) {
+        return LoggingModule_1.forLogger(opts.logger ?? createConfiguredLogger(config));
+    }
+    /** Provides `logger` (a context without a config: `KernelCliModule.overPool`). */
+    static forLogger(logger) {
+        return {
+            module: LoggingModule_1,
+            global: true,
+            providers: [{ provide: KERNEL_LOGGER, useValue: logger }],
+            exports: [KERNEL_LOGGER],
+        };
+    }
+};
+LoggingModule = LoggingModule_1 = __decorate([
+    Global(),
+    Module({})
+    // biome-ignore lint/complexity/noStaticOnlyClass: a Nest dynamic module
+], LoggingModule);
+export { LoggingModule };

package/dist/infra/queue/configured-processor.d.ts

@@ -0,0 +1,18 @@
+import { type WorkerHost } from "@nestjs/bullmq";
+import type { ClassProvider, Type } from "@nestjs/common";
+import type { WorkerOptions } from "bullmq";
+/** The BullMQ worker options a configured processor takes (connection and prefix come from the queue). */
+export type ProcessorWorkerOptions = Omit<WorkerOptions, "connection" | "autorun" | "prefix" | "sharedConnection">;
+/**
+ * A `@Processor(queue)` provider whose worker options come from the application's startup config
+ * (`@Processor` reads them from class metadata when the worker is built, at module init, so they
+ * cannot be read from an injected service). Returns `{ provide: base, useClass }` with a subclass
+ * of `base` decorated for this application only, so two applications in one process (tests, the
+ * dual-replica harness) each get their own options. `base` is an `@Injectable` `WorkerHost` without
+ * `@Processor` of its own; inject it by `base`.
+ *
+ * The worker never starts by itself (`autorun: false`): the role that consumes calls
+ * `worker.run()` once the start sequence reached it (the kernel's worker role, after the extension
+ * load), and pauses it on stop.
+ */
+export declare function configuredProcessor<T extends WorkerHost>(base: Type<T>, queue: string, options: ProcessorWorkerOptions): ClassProvider<T>;