@capybara-hq/kernel 0.1.0-rc.0 → 0.1.0-rc.10

package/dist/infra/lifecycle/process-guards.d.ts

@@ -0,0 +1,52 @@
+import type { KernelLogger } from "../../log.js";
+/**
+ * Process-level guards for `capybara start`: an unhandled rejection or an uncaught exception is
+ * logged and the process keeps running, unless they come in bursts.
+ *
+ * Node's default for an async failure nobody handles is to kill the process. That default assumes
+ * the program state is corrupt, which holds for errors thrown by business logic, but the ones seen
+ * in practice come from peripheral I/O (a telemetry export, an event emitter's `error` nobody
+ * listens to, an SDK of an extension). With several replicas the same peripheral failure takes
+ * every replica down at once. Both mechanisms are guarded: `unhandledRejection` alone does not
+ * catch an `error` event thrown synchronously by an EventEmitter (`uncaughtException`).
+ *
+ * Swallowing is not unconditional: peripheral noise is sporadic, real corruption repeats. More than
+ * {@link GUARD_CIRCUIT_LIMIT} fatal events within {@link GUARD_CIRCUIT_WINDOW_MS} open the circuit:
+ * the process exits with 1 and the orchestrator (Kubernetes, docker restart) starts a clean one.
+ *
+ * What this cannot save: a V8 heap exhaustion is a hard abort no listener sees; and a resource that
+ * first fails through an uncaught event and afterwards only through caught errors (500s) keeps the
+ * process alive but broken, which used to self-heal through a crash and a restart. Known trade-off.
+ *
+ * Every line of the recorder is wrapped: a handler that throws while the process handles a fatal
+ * event would defeat the guard. Records go through the kernel logger (pino, redacted) with
+ * `marker: "process-guard"`; only `kind: "circuit-open"` is worth alerting on.
+ *
+ * Installed only by `capybara start` (apps/capybara), never by `createKernelApp` / tests / library
+ * code paths: a library must not take over process-wide handlers.
+ */
+/** The fatal events allowed within the window; one more opens the circuit (exit 1). */
+export declare const GUARD_CIRCUIT_LIMIT = 5;
+/** The circuit's observation window (ms). */
+export declare const GUARD_CIRCUIT_WINDOW_MS = 60000;
+/** The fixed marker on every guard record. */
+export declare const GUARD_LOG_MARKER = "process-guard";
+/** The guarded events (Node's two mechanisms) and the circuit opening. */
+export type GuardKind = "unhandledRejection" | "uncaughtException" | "circuit-open";
+export interface ProcessGuardDeps {
+    /** The logger to write to, read on every event (`capybara start` switches to the configured one). */
+    log: () => Pick<KernelLogger, "error">;
+    /** Ends the process when the circuit opens. */
+    exit: (code: number) => void;
+    /** The current time in ms; default `Date.now`. */
+    now?: () => number;
+    /** Where the events come from; default `process`. */
+    process?: Pick<NodeJS.EventEmitter, "on" | "off">;
+}
+/**
+ * A recorder for fatal events: logs one record and exits once more than
+ * {@link GUARD_CIRCUIT_LIMIT} events fell within {@link GUARD_CIRCUIT_WINDOW_MS}. Never throws.
+ */
+export declare function createFatalRecorder(deps: Omit<ProcessGuardDeps, "process">): (kind: Exclude<GuardKind, "circuit-open">, err: unknown) => void;
+/** Installs both guards; returns a function that removes them. */
+export declare function installProcessGuards(deps: ProcessGuardDeps): () => void;

package/dist/infra/lifecycle/process-guards.js

@@ -0,0 +1,90 @@
+/**
+ * Process-level guards for `capybara start`: an unhandled rejection or an uncaught exception is
+ * logged and the process keeps running, unless they come in bursts.
+ *
+ * Node's default for an async failure nobody handles is to kill the process. That default assumes
+ * the program state is corrupt, which holds for errors thrown by business logic, but the ones seen
+ * in practice come from peripheral I/O (a telemetry export, an event emitter's `error` nobody
+ * listens to, an SDK of an extension). With several replicas the same peripheral failure takes
+ * every replica down at once. Both mechanisms are guarded: `unhandledRejection` alone does not
+ * catch an `error` event thrown synchronously by an EventEmitter (`uncaughtException`).
+ *
+ * Swallowing is not unconditional: peripheral noise is sporadic, real corruption repeats. More than
+ * {@link GUARD_CIRCUIT_LIMIT} fatal events within {@link GUARD_CIRCUIT_WINDOW_MS} open the circuit:
+ * the process exits with 1 and the orchestrator (Kubernetes, docker restart) starts a clean one.
+ *
+ * What this cannot save: a V8 heap exhaustion is a hard abort no listener sees; and a resource that
+ * first fails through an uncaught event and afterwards only through caught errors (500s) keeps the
+ * process alive but broken, which used to self-heal through a crash and a restart. Known trade-off.
+ *
+ * Every line of the recorder is wrapped: a handler that throws while the process handles a fatal
+ * event would defeat the guard. Records go through the kernel logger (pino, redacted) with
+ * `marker: "process-guard"`; only `kind: "circuit-open"` is worth alerting on.
+ *
+ * Installed only by `capybara start` (apps/capybara), never by `createKernelApp` / tests / library
+ * code paths: a library must not take over process-wide handlers.
+ */
+/** The fatal events allowed within the window; one more opens the circuit (exit 1). */
+export const GUARD_CIRCUIT_LIMIT = 5;
+/** The circuit's observation window (ms). */
+export const GUARD_CIRCUIT_WINDOW_MS = 60_000;
+/** The fixed marker on every guard record. */
+export const GUARD_LOG_MARKER = "process-guard";
+/**
+ * A recorder for fatal events: logs one record and exits once more than
+ * {@link GUARD_CIRCUIT_LIMIT} events fell within {@link GUARD_CIRCUIT_WINDOW_MS}. Never throws.
+ */
+export function createFatalRecorder(deps) {
+    const now = deps.now ?? Date.now;
+    let recent = [];
+    let open = false;
+    return (kind, err) => {
+        // Exiting already: log nothing more. A failing log write (EPIPE on a dead stdout) raises the
+        // next event itself; logging it again would keep the process busy forever and starve the exit.
+        if (open)
+            return;
+        try {
+            const t = now();
+            recent = recent.filter((x) => t - x < GUARD_CIRCUIT_WINDOW_MS);
+            recent.push(t);
+            safely(() => deps
+                .log()
+                .error(kind === "unhandledRejection" ? "unhandled promise rejection" : "uncaught exception", { marker: GUARD_LOG_MARKER, kind, err }));
+            if (recent.length > GUARD_CIRCUIT_LIMIT && !open) {
+                open = true;
+                safely(() => deps.log().error("too many fatal events; exiting so the process is restarted clean", {
+                    marker: GUARD_LOG_MARKER,
+                    kind: "circuit-open",
+                    events: recent.length,
+                    windowMs: GUARD_CIRCUIT_WINDOW_MS,
+                }));
+                deps.exit(1);
+            }
+        }
+        catch {
+            // Recording must never take the process down: that is what this module prevents
+        }
+    };
+}
+/** Runs fn, swallowing what it throws (a logger failing must not skip the circuit). */
+function safely(fn) {
+    try {
+        fn();
+    }
+    catch {
+        // ignored
+    }
+}
+/** Installs both guards; returns a function that removes them. */
+export function installProcessGuards(deps) {
+    const target = deps.process ?? process;
+    const record = createFatalRecorder(deps);
+    const onRejection = (reason) => record("unhandledRejection", reason);
+    const onException = (err) => record("uncaughtException", err);
+    target.on("unhandledRejection", onRejection);
+    target.on("uncaughtException", onException);
+    return () => {
+        target.off("unhandledRejection", onRejection);
+        target.off("uncaughtException", onException);
+    };
+}

package/dist/infra/lifecycle/shutdown-signals.d.ts

@@ -0,0 +1,30 @@
+import type { KernelLogger } from "../../log.js";
+/** The signals that shut the kernel down. */
+export declare const SHUTDOWN_SIGNALS: ["SIGTERM", "SIGINT"];
+/** Where the signals come from and how the process ends (tests pass their own). */
+export interface ShutdownSignalOptions {
+    /** Default `process`. */
+    signals?: Pick<NodeJS.EventEmitter, "on" | "off">;
+    /**
+     * Ends the process: 0 after a completed shutdown, 1 after a failed one or on a second signal.
+     * Default `process.exit`.
+     */
+    exit?: (code: number) => void;
+}
+export interface ShutdownSignalHandle {
+    /** The shutdown a signal started, settled once `exit` was called; undefined before any signal. */
+    exiting(): Promise<void> | undefined;
+    /** Removes the listeners. */
+    dispose(): void;
+}
+/**
+ * Installs SIGTERM / SIGINT handlers around a running (or starting) kernel application, in place
+ * of Nest's `enableShutdownHooks()`. The first signal runs `close` (`closeKernelApp`: the shutdown
+ * begins at once, so a start in progress stops at its next checkpoint, then the stop phases and
+ * the infra closes, all within the 30 s stop budget) and exits with 0, or 1 when it failed, after
+ * flushing the logs. A second signal while that runs exits with 1 at once, so an operator's second
+ * Ctrl-C (or an orchestrator's repeated SIGTERM) never waits on a stuck shutdown. Nest's handlers
+ * would begin the shutdown only after every module's `onModuleDestroy`, ignore a second signal,
+ * flush nothing and end the process by re-raising the signal.
+ */
+export declare function handleShutdownSignals(close: () => Promise<void>, log: KernelLogger, opts?: ShutdownSignalOptions): ShutdownSignalHandle;

package/dist/infra/lifecycle/shutdown-signals.js

@@ -0,0 +1,48 @@
+/** The signals that shut the kernel down. */
+export const SHUTDOWN_SIGNALS = ["SIGTERM", "SIGINT"];
+/**
+ * Installs SIGTERM / SIGINT handlers around a running (or starting) kernel application, in place
+ * of Nest's `enableShutdownHooks()`. The first signal runs `close` (`closeKernelApp`: the shutdown
+ * begins at once, so a start in progress stops at its next checkpoint, then the stop phases and
+ * the infra closes, all within the 30 s stop budget) and exits with 0, or 1 when it failed, after
+ * flushing the logs. A second signal while that runs exits with 1 at once, so an operator's second
+ * Ctrl-C (or an orchestrator's repeated SIGTERM) never waits on a stuck shutdown. Nest's handlers
+ * would begin the shutdown only after every module's `onModuleDestroy`, ignore a second signal,
+ * flush nothing and end the process by re-raising the signal.
+ */
+export function handleShutdownSignals(close, log, opts = {}) {
+    const signals = opts.signals ?? process;
+    const exit = opts.exit ?? ((code) => process.exit(code));
+    let exiting;
+    // Set by a second signal: the forced exit(1) stays the process's code
+    let forced = false;
+    const dispose = () => {
+        for (const s of SHUTDOWN_SIGNALS)
+            signals.off(s, onSignal);
+    };
+    function onSignal(signal) {
+        if (exiting) {
+            log.warn("second signal received; exiting immediately", { signal });
+            dispose();
+            forced = true;
+            exit(1);
+            return;
+        }
+        log.info("signal received; shutting down", { signal });
+        const end = (code) => log
+            .flush()
+            .catch(() => { })
+            .then(() => {
+            dispose();
+            if (!forced)
+                exit(code);
+        });
+        exiting = close().then(() => end(0), (err) => {
+            log.error("shutdown failed", { err });
+            return end(1);
+        });
+    }
+    for (const s of SHUTDOWN_SIGNALS)
+        signals.on(s, onSignal);
+    return { exiting: () => exiting, dispose };
+}

package/dist/infra/lock/key-template.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Expands the placeholders of a key template from the method arguments:
+ * - `#{0}`: the argument at that index, as a string;
+ * - `#{1.book.title}`: a property path of the argument at that index;
+ * - `#{user.id}`: the same as `#{0.user.id}` (the index 0 may be omitted).
+ *
+ * With `opts.result` (cache eviction), `#{result}` and `#{result.id}` read the method's return value.
+ *
+ * A placeholder that cannot be resolved is left as written.
+ */
+export declare function generateKey(pattern: string, args: readonly unknown[], opts?: {
+    result: unknown;
+}): string;

package/dist/infra/lock/key-template.js

@@ -0,0 +1,46 @@
+// Ported from octok-platform libs/common/src/utils/common.utils.ts#generateKey (owner-approved, 2026-10-28).
+/** Reads a dotted path (`a.b.c`) from a value; undefined when any step is missing. */
+function get(value, path) {
+    let cur = value;
+    for (const part of path.split(".")) {
+        if (cur === null || cur === undefined)
+            return undefined;
+        cur = cur[part];
+    }
+    return cur;
+}
+const show = (v) => v !== undefined && v !== null ? String(v) : undefined;
+/**
+ * Expands the placeholders of a key template from the method arguments:
+ * - `#{0}`: the argument at that index, as a string;
+ * - `#{1.book.title}`: a property path of the argument at that index;
+ * - `#{user.id}`: the same as `#{0.user.id}` (the index 0 may be omitted).
+ *
+ * With `opts.result` (cache eviction), `#{result}` and `#{result.id}` read the method's return value.
+ *
+ * A placeholder that cannot be resolved is left as written.
+ */
+export function generateKey(pattern, args, opts) {
+    if (opts) {
+        pattern = pattern.replace(/#\{result(?:\.([^}]+))?\}/g, (match, path) => (path === undefined ? show(opts.result) : show(get(opts.result, path))) ?? match);
+    }
+    // `#{<index>.<path>}`
+    let key = pattern.replace(/#\{(\d+)\.([^}]+)\}/g, (match, indexStr, path) => {
+        const index = Number.parseInt(indexStr, 10);
+        if (index >= args.length)
+            return match;
+        return show(get(args[index], path)) ?? match;
+    });
+    // `#{<path>}` reads from the first argument
+    key = key.replace(/#\{([^}]+)\}/g, (match, content) => {
+        if (/^\d+$/.test(content) || args.length === 0)
+            return match;
+        return show(get(args[0], content)) ?? match;
+    });
+    // `#{<index>}`
+    key = key.replace(/#\{(\d+)\}/g, (match, indexStr) => {
+        const index = Number.parseInt(indexStr, 10);
+        return index < args.length ? String(args[index]) : match;
+    });
+    return key;
+}

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

@@ -0,0 +1,3 @@
+/** Global: `LockService` (and the `@WithLock` decorator, which reads it from `this.lockService`). */
+export declare class LockModule {
+}

package/dist/infra/lock/lock.module.js

@@ -0,0 +1,16 @@
+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;
+};
+import { Global, Module } from "@nestjs/common";
+import { LockService } from "./lock.service.js";
+/** Global: `LockService` (and the `@WithLock` decorator, which reads it from `this.lockService`). */
+let LockModule = class LockModule {
+};
+LockModule = __decorate([
+    Global(),
+    Module({ providers: [LockService], exports: [LockService] })
+], LockModule);
+export { LockModule };

package/dist/infra/lock/lock.service.d.ts

@@ -0,0 +1,120 @@
+import type { Redis } from "ioredis";
+import { ApiError } from "../../errors.js";
+import type { KernelLogger } from "../../log.js";
+import { type SharedLeaseKeys, type SharedLeaseKind } from "./shared-lease.js";
+export interface AcquireOptions {
+    /** Lock lifetime without renewal; a crashed holder's lock expires within it. */
+    ttlMs: number;
+    /** How long to keep trying; 0 (default) tries once, `Infinity` waits until it is taken. */
+    waitMs?: number;
+    /** Pause between attempts while waiting (default 100). */
+    retryMs?: number;
+    /** Ends the wait: the call throws the signal's reason (checked before the first attempt too). */
+    signal?: AbortSignal;
+}
+export interface LockHandle {
+    /** Stops renewing and deletes the key if it is still ours. Idempotent. */
+    release(): Promise<void>;
+    /**
+     * Aborts when the lock was lost: the key is gone or taken, or no renewal succeeded by the
+     * deadline (send time of the last successful renewal + TTL − TTL/3).
+     */
+    readonly lost: AbortSignal;
+}
+/**
+ * A renewed lease ({@link LockService.hold}): a {@link LockHandle} whose holder value is the
+ * caller's (other replicas read it), with an explicit renewal and an abandon for a holder that
+ * hands the key over to its TTL.
+ */
+export interface LeaseHandle extends LockHandle {
+    /** Renews now; false (and `lost` aborts) when the key is no longer ours. */
+    renew(): Promise<boolean>;
+    /** Stops renewing without deleting: the key expires within its TTL. `release` still deletes it while ours. */
+    abandon(): void;
+}
+/**
+ * A held lease of a shared lease ({@link LockService.tryShared} / {@link LockService.tryExclusive}):
+ * renewed every TTL/3 like {@link LockService.hold} (lost at the same deadline), released in its
+ * current kind.
+ */
+export interface SharedLeaseHandle extends LeaseHandle {
+    readonly token: string;
+    /** `exclusive` until a successful {@link downgrade}, then `shared`. */
+    readonly kind: SharedLeaseKind;
+    /**
+     * exclusive → shared in one step (same token, same `lost`; the deadline moves like a renewal).
+     * False (and `lost` aborts) when the exclusive lease was no longer ours. Throws when the lease is
+     * not exclusive (any more) or was released.
+     */
+    downgrade(): Promise<boolean>;
+}
+export declare const prefixed: (key: string) => string;
+/**
+ * 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).
+ */
+export declare class LockService {
+    private readonly redis;
+    private readonly log;
+    constructor(redis: Redis, log: KernelLogger);
+    /**
+     * 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.
+     */
+    acquire(key: string, opts: AcquireOptions): Promise<LockHandle | undefined>;
+    /** Runs `fn` under the lock; throws `lock.acquire_failed` when it cannot be taken. */
+    run<T>(key: string, opts: AcquireOptions, fn: (handle: LockHandle) => Promise<T>): Promise<T>;
+    /** Sets `key` to `holder` for `ttlMs` unless it exists (no `lock:` prefix, no renewal timer). */
+    lease(key: string, holder: string, ttlMs: number): Promise<boolean>;
+    /** Extends `key` to `ttlMs` when `holder` still owns it. */
+    renew(key: string, holder: string, ttlMs: number): Promise<boolean>;
+    /** The holder value of `key` (a lease's or a lock's token); null when nobody holds it. */
+    holderOf(key: string): Promise<string | null>;
+    /** Deletes `key` when `holder` still owns it. */
+    releaseIf(key: string, holder: string): Promise<boolean>;
+    /**
+     * 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).
+     */
+    hold(key: string, holder: string, ttlMs: number): Promise<LeaseHandle | undefined>;
+    /**
+     * 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.
+     */
+    tryShared(keys: SharedLeaseKeys, token: string, cap: number, ttlMs: number): Promise<SharedLeaseHandle | 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.
+     */
+    tryExclusive(keys: SharedLeaseKeys, token: string, ttlMs: number, intentTtlMs?: number): Promise<SharedLeaseHandle | undefined>;
+    /** Live shared leases of `keys` (expired ones are purged first). */
+    sharedCount(keys: Pick<SharedLeaseKeys, "lock" | "users">): Promise<number>;
+    /** The watchdog of a shared lease we just took; its kind changes once, on a downgrade. */
+    private watchShared;
+    /** The renewal watchdog of a key we just took (the `SET NX` was sent at `sentAt`). */
+    private watch;
+    /**
+     * 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: string, ttlMs: number, ops: {
+        renew(): Promise<boolean>;
+        release(): Promise<void>;
+    }, acquiredAt?: number): LeaseHandle;
+    /** {@link keepAlive}'s implementation, with {@link Watched.renewWith}. */
+    private watchdog;
+}
+export declare function lockAcquireFailed(lockKey: string): ApiError;