@capybara-hq/kernel 0.1.0-rc.2 → 0.1.0-rc.20

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

@@ -5,12 +5,15 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
 var LoggingModule_1;
-import { Global, Module } from "@nestjs/common";
+import { Global, Module, Scope } from "@nestjs/common";
+import { INQUIRER } from "@nestjs/core";
 import { createConfiguredLogger } from "../../log-config.js";
-import { KERNEL_LOGGER } from "../tokens.js";
+import { KERNEL_LOGGER, KERNEL_ROOT_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.
+ * Provides the process logger as `KERNEL_ROOT_LOGGER` and, as `KERNEL_LOGGER`, one child per injecting
+ * class with `context` = the class name (the `[context=…]` of the pretty output; octok's
+ * per-class Nest logger context). 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 = {}) {
@@ -21,8 +24,16 @@ let LoggingModule = LoggingModule_1 = class LoggingModule {
         return {
             module: LoggingModule_1,
             global: true,
-            providers: [{ provide: KERNEL_LOGGER, useValue: logger }],
-            exports: [KERNEL_LOGGER],
+            providers: [
+                { provide: KERNEL_ROOT_LOGGER, useValue: logger },
+                {
+                    provide: KERNEL_LOGGER,
+                    scope: Scope.TRANSIENT,
+                    inject: [KERNEL_ROOT_LOGGER, INQUIRER],
+                    useFactory: (root, inquirer) => contextLogger(root, inquirer),
+                },
+            ],
+            exports: [KERNEL_ROOT_LOGGER, KERNEL_LOGGER],
         };
     }
 };
@@ -32,3 +43,10 @@ LoggingModule = LoggingModule_1 = __decorate([
     // biome-ignore lint/complexity/noStaticOnlyClass: a Nest dynamic module
 ], LoggingModule);
 export { LoggingModule };
+/** The child of `root` for the class instance `inquirer`; `root` itself for a factory provider. */
+function contextLogger(root, inquirer) {
+    const name = inquirer?.constructor?.name;
+    return typeof name === "string" && name !== "" && name !== "Object"
+        ? root.child({ context: name })
+        : root;
+}

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

@@ -0,0 +1,6 @@
+/**
+ * Global: {@link ReplicaPresence}, on every role (each process reports itself; `KernelLifecycle`
+ * starts and stops it), read by the admin health overview.
+ */
+export declare class PresenceModule {
+}

package/dist/infra/presence/presence.module.js

@@ -0,0 +1,22 @@
+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 { ReplicaPresence } from "./replica-presence.js";
+/**
+ * Global: {@link ReplicaPresence}, on every role (each process reports itself; `KernelLifecycle`
+ * starts and stops it), read by the admin health overview.
+ */
+let PresenceModule = class PresenceModule {
+};
+PresenceModule = __decorate([
+    Global(),
+    Module({
+        providers: [ReplicaPresence],
+        exports: [ReplicaPresence],
+    })
+], PresenceModule);
+export { PresenceModule };

package/dist/infra/presence/replica-presence.d.ts

@@ -0,0 +1,87 @@
+import type { Redis } from "ioredis";
+import type { KernelLogger } from "../../log.js";
+import { KernelConfigService } from "../config/kernel-config.service.js";
+/** How often each process writes its presence (admin overview spec §5.1). */
+export declare const PRESENCE_DEFAULT_INTERVAL_MS = 15000;
+/** Optional provider: the presence interval (ms) instead of {@link PRESENCE_DEFAULT_INTERVAL_MS} (tests). */
+export declare const PRESENCE_INTERVAL_MS: unique symbol;
+/** The ZSET of live replicas: member = replica id, score = last beat (Redis server clock, ms). */
+export declare const REPLICAS_KEY = "capk:replicas";
+/** One replica's facts: `capk:replica:<replicaId>`. */
+export declare const replicaKey: (replicaId: string) => string;
+/** A kernel role (`roles` in the config). */
+export type ReplicaRole = "api" | "worker" | "gateway";
+/** What a live replica last reported about itself. */
+export interface LiveReplica {
+    /** The process id (`ReplicaStatusStore.replicaId`, the gateway heartbeat's member). */
+    id: string;
+    roles: ReplicaRole[];
+    /** `KERNEL_VERSION` of the process. */
+    version: string;
+    /** When the process's start sequence was done, before it listens (ISO 8601). */
+    startedAt: string;
+    /** The configured `http.replicaId` (the `x-capybara-replica` header), null when unset. */
+    httpReplicaId: string | null;
+    /** Channel long connections this process holds (0 without the gateway role). */
+    channelsHeld: number;
+    /** Device sockets open on this process (0 without the gateway role). */
+    devicesConnected: number;
+}
+/** The per-process facts the presence reports, read at every beat. */
+export interface PresenceSources {
+    /** This process's replica id (`ReplicaStatusStore.replicaId`). */
+    replicaId: string;
+    channelsHeld(): number;
+    devicesConnected(): number;
+}
+/**
+ * The replicas with a beat newer than `windowMs` (Redis server clock): one script for the members,
+ * then one pipelined HGETALL each. A member whose facts already expired is left out. Sorted by
+ * start time, then id.
+ */
+export declare function readLiveReplicas(redis: Pick<Redis, "eval" | "pipeline">, windowMs: number): Promise<LiveReplica[]>;
+/**
+ * Replica presence (admin overview spec §5.1): every process, whatever its roles, says every
+ * {@link PRESENCE_DEFAULT_INTERVAL_MS} that it is alive, with its roles, version, start time and
+ * the connections it holds, so the admin console can tell which replicas run in which role.
+ *
+ * Multi-replica: the state lives only in Redis, with a TTL of three intervals on both keys; the
+ * score is the Redis server clock (replica clocks may drift), as in the gateway heartbeat. Each
+ * process writes only its own entry and holds nothing other processes need: no lock, no
+ * transaction, no shared job. So it is not a `@LockedInterval` (that runs once across replicas)
+ * but a `setTimeout` chain of this process (`unref`), started by `KernelLifecycle` at the end of
+ * the start (after the start gate opened) and stopped first thing in the stop, which removes the
+ * entry at once; a crashed process ages out of {@link live} within the window. A failing beat is
+ * logged at warn and never thrown.
+ */
+export declare class ReplicaPresence {
+    private readonly redis;
+    private readonly config;
+    private readonly log;
+    /** The beat interval; the window (and the TTL) is three of them. */
+    readonly intervalMs: number;
+    private sources;
+    private startedAt;
+    private timer;
+    private running;
+    private halted;
+    constructor(redis: Redis, config: Pick<KernelConfigService, "get">, log: Pick<KernelLogger, "warn">, intervalMs?: number);
+    /** How long an entry stays live without a beat (ms). */
+    get windowMs(): number;
+    /** Starts beating (the first beat at once). Called once, at the end of the start. */
+    start(sources: PresenceSources): void;
+    private schedule;
+    private beat;
+    /**
+     * Stops beating and waits for a beat in flight, leaving the entry to age out (a crash looks like
+     * this; the tests use it as one). Idempotent.
+     */
+    halt(): Promise<void>;
+    /** The stop: {@link halt}, then removes this process's entry at once (best effort). Idempotent. */
+    stop(): Promise<void>;
+    /**
+     * The live replicas (a beat within the window, by the Redis server clock), sorted by start time.
+     * Throws when Redis does not answer.
+     */
+    live(): Promise<LiveReplica[]>;
+}

package/dist/infra/presence/replica-presence.js

@@ -0,0 +1,189 @@
+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); }
+};
+import { Inject, Injectable, Optional } from "@nestjs/common";
+import { KERNEL_VERSION } from "../../version.js";
+import { KernelConfigService } from "../config/kernel-config.service.js";
+import { KERNEL_LOGGER, REDIS } from "../tokens.js";
+/** How often each process writes its presence (admin overview spec §5.1). */
+export const PRESENCE_DEFAULT_INTERVAL_MS = 15_000;
+/** Optional provider: the presence interval (ms) instead of {@link PRESENCE_DEFAULT_INTERVAL_MS} (tests). */
+export const PRESENCE_INTERVAL_MS = Symbol("PRESENCE_INTERVAL_MS");
+/** The ZSET of live replicas: member = replica id, score = last beat (Redis server clock, ms). */
+export const REPLICAS_KEY = "capk:replicas";
+/** One replica's facts: `capk:replica:<replicaId>`. */
+export const replicaKey = (replicaId) => `capk:replica:${replicaId}`;
+/**
+ * One beat: ZADD the member at the server clock, write the facts, give both keys a TTL of the
+ * window and trim members older than it. KEYS: the ZSET, the replica's hash. ARGV: the replica id,
+ * the window (ms), then the hash's field / value pairs.
+ */
+const BEAT = `
+local t = redis.call('TIME')
+local now = tonumber(t[1]) * 1000 + math.floor(tonumber(t[2]) / 1000)
+local ttl = tonumber(ARGV[2])
+redis.call('ZADD', KEYS[1], now, ARGV[1])
+redis.call('HSET', KEYS[2], unpack(ARGV, 3))
+redis.call('PEXPIRE', KEYS[2], ttl)
+redis.call('PEXPIRE', KEYS[1], ttl)
+redis.call('ZREMRANGEBYSCORE', KEYS[1], '-inf', now - ttl)
+return now
+`;
+/** The members newer than the window (ARGV[1], ms) by the Redis server clock. */
+const LIVE = `
+local t = redis.call('TIME')
+local now = tonumber(t[1]) * 1000 + math.floor(tonumber(t[2]) / 1000)
+return redis.call('ZRANGEBYSCORE', KEYS[1], '(' .. (now - tonumber(ARGV[1])), '+inf')
+`;
+const ROLES = ["api", "worker", "gateway"];
+const count = (v) => {
+    const n = Number(v);
+    return Number.isInteger(n) && n >= 0 ? n : 0;
+};
+/**
+ * The replicas with a beat newer than `windowMs` (Redis server clock): one script for the members,
+ * then one pipelined HGETALL each. A member whose facts already expired is left out. Sorted by
+ * start time, then id.
+ */
+export async function readLiveReplicas(redis, windowMs) {
+    const ids = (await redis.eval(LIVE, 1, REPLICAS_KEY, windowMs));
+    if (ids.length === 0)
+        return [];
+    const pipe = redis.pipeline();
+    for (const id of ids)
+        pipe.hgetall(replicaKey(id));
+    const res = (await pipe.exec()) ?? [];
+    const out = [];
+    ids.forEach((id, i) => {
+        const [err, h] = res[i] ?? [null, null];
+        if (err)
+            throw err;
+        const f = h;
+        if (f === null || f.version === undefined)
+            return;
+        out.push({
+            id,
+            roles: (f.roles ?? "")
+                .split(",")
+                .filter((r) => ROLES.includes(r)),
+            version: f.version,
+            startedAt: f.startedAt ?? "",
+            httpReplicaId: f.httpReplicaId ? f.httpReplicaId : null,
+            channelsHeld: count(f.channelsHeld),
+            devicesConnected: count(f.devicesConnected),
+        });
+    });
+    return out.sort((a, b) => a.startedAt.localeCompare(b.startedAt) || a.id.localeCompare(b.id));
+}
+/**
+ * Replica presence (admin overview spec §5.1): every process, whatever its roles, says every
+ * {@link PRESENCE_DEFAULT_INTERVAL_MS} that it is alive, with its roles, version, start time and
+ * the connections it holds, so the admin console can tell which replicas run in which role.
+ *
+ * Multi-replica: the state lives only in Redis, with a TTL of three intervals on both keys; the
+ * score is the Redis server clock (replica clocks may drift), as in the gateway heartbeat. Each
+ * process writes only its own entry and holds nothing other processes need: no lock, no
+ * transaction, no shared job. So it is not a `@LockedInterval` (that runs once across replicas)
+ * but a `setTimeout` chain of this process (`unref`), started by `KernelLifecycle` at the end of
+ * the start (after the start gate opened) and stopped first thing in the stop, which removes the
+ * entry at once; a crashed process ages out of {@link live} within the window. A failing beat is
+ * logged at warn and never thrown.
+ */
+let ReplicaPresence = class ReplicaPresence {
+    redis;
+    config;
+    log;
+    /** The beat interval; the window (and the TTL) is three of them. */
+    intervalMs;
+    sources;
+    startedAt = "";
+    timer;
+    running;
+    halted = false;
+    constructor(redis, config, log, intervalMs) {
+        this.redis = redis;
+        this.config = config;
+        this.log = log;
+        this.intervalMs = intervalMs ?? PRESENCE_DEFAULT_INTERVAL_MS;
+    }
+    /** How long an entry stays live without a beat (ms). */
+    get windowMs() {
+        return this.intervalMs * 3;
+    }
+    /** Starts beating (the first beat at once). Called once, at the end of the start. */
+    start(sources) {
+        if (this.sources !== undefined || this.halted)
+            return;
+        this.sources = sources;
+        this.startedAt = new Date().toISOString();
+        this.schedule(0);
+    }
+    schedule(ms) {
+        if (this.halted)
+            return;
+        this.timer = setTimeout(() => {
+            this.running = this.beat().finally(() => {
+                this.running = undefined;
+                this.schedule(this.intervalMs);
+            });
+        }, ms);
+        this.timer.unref?.();
+    }
+    async beat() {
+        const s = this.sources;
+        if (s === undefined || this.halted)
+            return;
+        try {
+            const http = this.config.get().http.replicaId;
+            await this.redis.eval(BEAT, 2, REPLICAS_KEY, replicaKey(s.replicaId), s.replicaId, this.windowMs, "roles", this.config.get().roles.join(","), "version", KERNEL_VERSION, "startedAt", this.startedAt, "httpReplicaId", http === undefined ? "" : String(http), "channelsHeld", s.channelsHeld(), "devicesConnected", s.devicesConnected());
+        }
+        catch (err) {
+            this.log.warn("replica presence beat failed", { err });
+        }
+    }
+    /**
+     * Stops beating and waits for a beat in flight, leaving the entry to age out (a crash looks like
+     * this; the tests use it as one). Idempotent.
+     */
+    async halt() {
+        this.halted = true;
+        clearTimeout(this.timer);
+        await this.running;
+    }
+    /** The stop: {@link halt}, then removes this process's entry at once (best effort). Idempotent. */
+    async stop() {
+        await this.halt();
+        const s = this.sources;
+        if (s === undefined)
+            return;
+        this.sources = undefined;
+        try {
+            await this.redis.multi().zrem(REPLICAS_KEY, s.replicaId).del(replicaKey(s.replicaId)).exec();
+        }
+        catch (err) {
+            this.log.warn("cannot remove replica presence", { err });
+        }
+    }
+    /**
+     * The live replicas (a beat within the window, by the Redis server clock), sorted by start time.
+     * Throws when Redis does not answer.
+     */
+    live() {
+        return readLiveReplicas(this.redis, this.windowMs);
+    }
+};
+ReplicaPresence = __decorate([
+    Injectable(),
+    __param(0, Inject(REDIS)),
+    __param(1, Inject(KernelConfigService)),
+    __param(2, Inject(KERNEL_LOGGER)),
+    __param(3, Optional()),
+    __param(3, Inject(PRESENCE_INTERVAL_MS))
+], ReplicaPresence);
+export { ReplicaPresence };

package/dist/infra/queue/add-job-once.d.ts

@@ -0,0 +1,14 @@
+import { type JobsOptions } from "bullmq";
+import type { Redis } from "ioredis";
+/** One job to add: its name, data and options (a deterministic `jobId` makes the add idempotent). */
+export interface OneJob<T> {
+    name: string;
+    data: T;
+    opts: JobsOptions;
+}
+/**
+ * Adds one job to a kernel queue from a process that hosts no queue of its own (a CLI command),
+ * over the caller's Redis connection (left open), with BullMQ's default key prefix like the
+ * kernel's queues. The queue handle is closed again before returning.
+ */
+export declare function addJobOnce<T>(connection: Redis, queue: string, job: OneJob<T>): Promise<void>;

package/dist/infra/queue/add-job-once.js

@@ -0,0 +1,16 @@
+import { Queue } from "bullmq";
+/**
+ * Adds one job to a kernel queue from a process that hosts no queue of its own (a CLI command),
+ * over the caller's Redis connection (left open), with BullMQ's default key prefix like the
+ * kernel's queues. The queue handle is closed again before returning.
+ */
+export async function addJobOnce(connection, queue, job) {
+    const q = new Queue(queue, { connection });
+    try {
+        // biome-ignore lint/suspicious/noExplicitAny: BullMQ's name and data generics do not line up here
+        await q.add(job.name, job.data, job.opts);
+    }
+    finally {
+        await q.close();
+    }
+}

package/dist/infra/queue/redis-connection.d.ts

@@ -1,4 +1,10 @@
 import type { RedisOptions } from "bullmq";
+/**
+ * TCP keepalive of every long-lived kernel Redis connection: probes start after 10 s idle (the OS
+ * default is 2 hours), so a connection a dropped network left half-open is found and reconnected
+ * before a command waits on it, not at the next write (EPIPE).
+ */
+export declare const REDIS_KEEPALIVE_MS = 10000;
 /**
  * BullMQ connection options from the kernel's Redis URL, the same connection the hand-made
  * `new Redis(url, { maxRetriesPerRequest: null })` workers use: BullMQ requires

package/dist/infra/queue/redis-connection.js

@@ -1,3 +1,9 @@
+/**
+ * TCP keepalive of every long-lived kernel Redis connection: probes start after 10 s idle (the OS
+ * default is 2 hours), so a connection a dropped network left half-open is found and reconnected
+ * before a command waits on it, not at the next write (EPIPE).
+ */
+export const REDIS_KEEPALIVE_MS = 10_000;
 /**
  * BullMQ connection options from the kernel's Redis URL, the same connection the hand-made
  * `new Redis(url, { maxRetriesPerRequest: null })` workers use: BullMQ requires
@@ -14,5 +20,6 @@ export function bullConnectionOptions(url) {
         ...(db !== undefined && Number.isInteger(db) && { db }),
         ...(u.protocol === "rediss:" && { tls: {} }),
         maxRetriesPerRequest: null,
+        keepAlive: REDIS_KEEPALIVE_MS,
     };
 }

package/dist/infra/redis/redis.module.js

@@ -14,6 +14,7 @@ import { closeWithin } from "../close-within.js";
 import { KernelConfigService } from "../config/kernel-config.service.js";
 import { GracefulShutdownModule } from "../lifecycle/graceful-shutdown.module.js";
 import { GracefulShutdown } from "../lifecycle/graceful-shutdown.service.js";
+import { REDIS_KEEPALIVE_MS } from "../queue/redis-connection.js";
 import { KERNEL_BUS, KERNEL_LOGGER, REDIS, REDIS_SUBSCRIBER } from "../tokens.js";
 /**
  * Closes the bus subscriber, then the main connection, at the end of the shutdown
@@ -64,7 +65,10 @@ RedisModule = __decorate([
                 provide: REDIS,
                 inject: [KernelConfigService, KERNEL_LOGGER],
                 useFactory: (config, log) => {
-                    const redis = new Redis(config.get().redis.url, { lazyConnect: true });
+                    const redis = new Redis(config.get().redis.url, {
+                        lazyConnect: true,
+                        keepAlive: REDIS_KEEPALIVE_MS,
+                    });
                     redis.on("error", (err) => log.error("redis connection error", { err }));
                     return redis;
                 },
@@ -72,7 +76,7 @@ RedisModule = __decorate([
             {
                 provide: REDIS_SUBSCRIBER,
                 inject: [KernelConfigService, KERNEL_LOGGER],
-                useFactory: (config, log) => createBusSubscriber(() => new Redis(config.get().redis.url), log),
+                useFactory: (config, log) => createBusSubscriber(() => new Redis(config.get().redis.url, { keepAlive: REDIS_KEEPALIVE_MS }), log),
             },
             {
                 provide: KERNEL_BUS,

package/dist/infra/throttler/named-throttlers.d.ts

@@ -8,6 +8,8 @@ export interface NamedThrottler {
     ttl: number;
     /** The 429 message (today's text of the route that used the limiter). */
     message: string;
+    /** The 429 error code; default `auth.rate_limited` (the credential routes'). */
+    code?: "auth.rate_limited" | "rate_limited";
     /** The credential group: throttlers of one group are reserved together (one Redis hash tag). */
     group: string;
     /** What a successful attempt does to this counter: delete it, or give one attempt back. */
@@ -25,6 +27,16 @@ export interface NamedThrottler {
  * | `PUT /api/v1/me/password` | `change-password`, `change-password-ip` |
  * | `POST /api/v1/setup` | `setup-token`, `setup-ip` |
  * | `POST /api/v1/invitations/:token/accept` | `invitation`, `invitation-ip` |
+ * | `GET /api/v1/device/pending/:userCode`, `POST /api/v1/device/confirm`, `POST /api/v1/device/deny` | `device-code-account` |
+ *
+ * `POST /api/v1/orgs/:orgId/ui/client/reports` and `POST /api/v1/admin/ui/client/reports` opt in to
+ * `client-reports` with `@Throttled` (20 per minute per account: a crash loop in a browser must
+ * not flood the table).
+ *
+ * `POST /api/v1/device/authorize` and `POST /api/v1/device/token` opt in to `device-authorize-ip`
+ * and `device-token-ip` with `@Throttled` (every request counts; neither checks a guessable
+ * credential: the device code is 32 random bytes). `POST …/guides/:guideId/checks/:checkId/run`
+ * opts in to `setup-check` (setup guides v2 §10.3: each run may call a third party).
  */
 export declare const NAMED_THROTTLERS: readonly NamedThrottler[];
 /** The storage key of a named throttler's counter for a tracker (shared by the guard and success paths). */

package/dist/infra/throttler/named-throttlers.js

@@ -28,6 +28,16 @@ const LOGIN_MSG = "Too many failed login attempts; try again later";
  * | `PUT /api/v1/me/password` | `change-password`, `change-password-ip` |
  * | `POST /api/v1/setup` | `setup-token`, `setup-ip` |
  * | `POST /api/v1/invitations/:token/accept` | `invitation`, `invitation-ip` |
+ * | `GET /api/v1/device/pending/:userCode`, `POST /api/v1/device/confirm`, `POST /api/v1/device/deny` | `device-code-account` |
+ *
+ * `POST /api/v1/orgs/:orgId/ui/client/reports` and `POST /api/v1/admin/ui/client/reports` opt in to
+ * `client-reports` with `@Throttled` (20 per minute per account: a crash loop in a browser must
+ * not flood the table).
+ *
+ * `POST /api/v1/device/authorize` and `POST /api/v1/device/token` opt in to `device-authorize-ip`
+ * and `device-token-ip` with `@Throttled` (every request counts; neither checks a guessable
+ * credential: the device code is 32 random bytes). `POST …/guides/:guideId/checks/:checkId/run`
+ * opts in to `setup-check` (setup guides v2 §10.3: each run may call a third party).
  */
 export const NAMED_THROTTLERS = [
     // (login, IP): 10; an attacker filling one login from one IP leaves the owner's other IPs alone (R25)
@@ -114,6 +124,63 @@ export const NAMED_THROTTLERS = [
         message: "Too many invitation attempts; try again later",
         getTracker: ip,
     },
+    // device sign-in codes issued per client address (each one holds Redis state for its TTL): 20.
+    // Opted in with @Throttled, which counts every request before the handler: group and onSuccess
+    // are unused (they matter only to CredentialThrottler).
+    {
+        name: "device-authorize-ip",
+        group: "device-authorize",
+        onSuccess: "clear",
+        limit: 20,
+        ttl: CREDENTIAL_WINDOW_MS,
+        message: "Too many device sign-in attempts; try again later",
+        getTracker: ip,
+    },
+    // device token polls per client address (@Throttled like device-authorize-ip): 600, one login
+    // polls up to 120 times (600 s / 5 s), so several machines behind one NAT address fit
+    {
+        name: "device-token-ip",
+        group: "device-token",
+        onSuccess: "clear",
+        limit: 600,
+        ttl: CREDENTIAL_WINDOW_MS,
+        message: "Too many device sign-in polls; try again later",
+        getTracker: ip,
+    },
+    // user codes tried per signed-in person (guessing another machine's code): 10, refunded on success
+    {
+        name: "device-code-account",
+        group: "device-code",
+        onSuccess: "refund",
+        limit: 10,
+        ttl: CREDENTIAL_WINDOW_MS,
+        message: "Too many device code attempts; try again later",
+        getTracker: (req) => sha256(principalAccountId(req)),
+    },
+    // client code crash reports per signed-in account (counted before the handler): 20 / minute
+    {
+        name: "client-reports",
+        group: "client-reports",
+        onSuccess: "clear",
+        limit: 20,
+        ttl: 60_000,
+        message: "Too many client reports; try again later",
+        getTracker: (req) => sha256(principalAccountId(req)),
+    },
+    // setup check runs per signed-in person (setup guides v2 §10.5): 30 a minute, every request
+    // counts (@Throttled); a cached answer costs no third-party call but still counts, as the page
+    // asks at most once per row and stale result. The edge of the route (with `retry-after`): the
+    // budget shared with the Platform tool's setup.check is SetupChecksService's own counter
+    {
+        name: "setup-check",
+        group: "setup-check",
+        onSuccess: "clear",
+        limit: 30,
+        ttl: 60_000,
+        message: "Too many setup check runs; try again in a minute",
+        code: "rate_limited",
+        getTracker: (req) => sha256(principalAccountId(req)),
+    },
 ];
 /** The storage key of a named throttler's counter for a tracker (shared by the guard and success paths). */
 export const throttlerKey = (name, tracker) => sha256(`${name}:${tracker}`);

package/dist/infra/throttler/throttler.guard.js

@@ -56,7 +56,7 @@ let KernelThrottlerGuard = class KernelThrottlerGuard extends ThrottlerGuard {
         const known = NAMED_THROTTLERS.find((t) => t.name === name);
         if (!known)
             throw new Error(`unknown throttler "${name}"`);
-        throw new ApiError("auth.rate_limited", known.message);
+        throw new ApiError(known.code ?? "auth.rate_limited", known.message);
     }
 };
 KernelThrottlerGuard = __decorate([

package/dist/infra/tokens.d.ts

@@ -1,6 +1,11 @@
 /** Injection tokens of the global infra modules. */
-/** The process logger (`KernelLogger`). */
+/**
+ * A class's logger (`KernelLogger`): the process logger with `context` set to the injecting class's
+ * name. Transient, so `app.get` cannot resolve it; use `KERNEL_ROOT_LOGGER` outside an injection.
+ */
 export declare const KERNEL_LOGGER: unique symbol;
+/** The process logger itself (`KernelLogger`), without a context. */
+export declare const KERNEL_ROOT_LOGGER: unique symbol;
 /** The startup input of `KernelConfigService`: `{ config, env }`. */
 export declare const KERNEL_CONFIG_INPUT: unique symbol;
 /** The Kysely pool, untyped (`Kysely<any>`); infra only, services inject `KernelDb`. */

package/dist/infra/tokens.js

@@ -1,6 +1,11 @@
 /** Injection tokens of the global infra modules. */
-/** The process logger (`KernelLogger`). */
+/**
+ * A class's logger (`KernelLogger`): the process logger with `context` set to the injecting class's
+ * name. Transient, so `app.get` cannot resolve it; use `KERNEL_ROOT_LOGGER` outside an injection.
+ */
 export const KERNEL_LOGGER = Symbol("KERNEL_LOGGER");
+/** The process logger itself (`KernelLogger`), without a context. */
+export const KERNEL_ROOT_LOGGER = Symbol("KERNEL_ROOT_LOGGER");
 /** The startup input of `KernelConfigService`: `{ config, env }`. */
 export const KERNEL_CONFIG_INPUT = Symbol("KERNEL_CONFIG_INPUT");
 /** The Kysely pool, untyped (`Kysely<any>`); infra only, services inject `KernelDb`. */

package/dist/kernel.module.js

@@ -9,6 +9,7 @@ import { Global, Module } from "@nestjs/common";
 import { APP_INTERCEPTOR } from "@nestjs/core";
 import { CatalogModule } from "./catalog/catalog.module.js";
 import { ChannelsModule } from "./channels/channels.module.js";
+import { ClientModule } from "./client/client.module.js";
 import { TitlesModule } from "./conversations/titles.js";
 import { ExtensionsModule } from "./extensions/extensions.module.js";
 import { ApiModule } from "./http/api.module.js";
@@ -24,6 +25,7 @@ import { databaseCheck, HEALTH_CHECKS, redisCheck } from "./infra/health/health.
 import { GracefulShutdownModule } from "./infra/lifecycle/graceful-shutdown.module.js";
 import { LockModule } from "./infra/lock/lock.module.js";
 import { LoggingModule } from "./infra/logging/logging.module.js";
+import { PresenceModule } from "./infra/presence/presence.module.js";
 import { QueueModule } from "./infra/queue/queue.module.js";
 import { RedisModule } from "./infra/redis/redis.module.js";
 import { KernelThrottlerModule } from "./infra/throttler/throttler.module.js";
@@ -31,8 +33,11 @@ import { KERNEL_POOL, REDIS } from "./infra/tokens.js";
 import { ValidationModule } from "./infra/validation/validation.module.js";
 import { KernelLifecycle } from "./lifecycle/kernel-lifecycle.js";
 import { KERNEL_APP_OPTIONS } from "./lifecycle/tokens.js";
+import { LocalDevicesModule } from "./local-devices/local-devices.module.js";
 import { createConfiguredLogger } from "./log-config.js";
 import { KERNEL_OVERRIDE_TOKENS } from "./overrides.js";
+import { PlatformModule } from "./platform/platform.module.js";
+import { PlatformOpsModule } from "./platform/platform-ops.module.js";
 import { GatewayModule } from "./roles/gateway.module.js";
 import { WorkerModule } from "./roles/worker.module.js";
 import { UsageReportModule } from "./runtime/usage-report.js";
@@ -97,6 +102,8 @@ let KernelModule = KernelModule_1 = class KernelModule {
                 QueueModule.forRoot(),
                 KernelThrottlerModule,
                 HealthModule,
+                // every process's presence beat (admin overview spec §5.1), whatever its roles
+                PresenceModule,
                 ValidationModule,
                 ErrorFilterModule,
                 KernelAppOptionsModule.forRoot({ ...options, logger }),
@@ -108,6 +115,14 @@ let KernelModule = KernelModule_1 = class KernelModule {
                 TitlesModule,
                 UsageReportModule,
                 ChannelsModule,
+                // client extensions: the client builds stored with extension packages
+                ClientModule,
+                // the @local sandbox provider, registered on every role (any replica may relay to a machine)
+                LocalDevicesModule,
+                // the Platform tool's operation registry and actor facts
+                PlatformModule,
+                // its operations (skills, agents, ...), registered at start on every role
+                PlatformOpsModule,
                 // the role modules, by `roles` (nest kernel spec §2)
                 ...(config.roles.includes("api") ? [ApiModule] : []),
                 ...(config.roles.includes("worker") ? [WorkerModule.forRoot(config)] : []),