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

package/dist/infra/config/kernel-config.service.js

@@ -0,0 +1,157 @@
+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 } from "@nestjs/common";
+import { changedPaths, configFields, getPath, secretValues, setPath } from "../../config/fields.js";
+import { resolveConfig } from "../../config/load.js";
+import { KernelConfigSchema } from "../../config/schema.js";
+import { KERNEL_CONFIG_INPUT, KERNEL_LOGGER } from "../tokens.js";
+/**
+ * Appliers of the hot-reloadable fields: the key is a dotted path marked `hot` in the schema. A
+ * hot field without an applier here makes the service refuse to start, so "marked hot but never
+ * takes effect" cannot happen.
+ */
+const HOT_APPLIERS = {
+    "log.level": (k, v) => k.log.setLevel(String(v)),
+    // The runtime reads the concurrency cap through the config service on every quota request.
+    "runtime.orgConcurrency": () => { },
+    // Eval org concurrency is read the same way at every quota request.
+    "evals.orgConcurrency": () => { },
+    // Login methods and trusted identity sources are read on every request.
+    "auth.loginSources": () => { },
+    "auth.trustedIdentitySources": () => { },
+    // The hook registry reads the time limit on every run.
+    "hooks.timeoutMs": () => { },
+    // The provider registry reads the list time limit at every listModels call.
+    "models.listTimeoutMs": () => { },
+    "models.embedTimeoutMs": () => { },
+    // SandboxService reads the shared-lease cap at every acquisition.
+    "sandbox.maxConcurrentCommands": () => { },
+    // The environments service reads the personal limit at every create.
+    "environments.maxPersonal": () => { },
+    // The device relay reads the reconnect grace at every disconnect and token response.
+    "environments.device.reconnectGraceSeconds": () => { },
+    // Sub-agent limits are read at every dispatch, child step and tool resolution.
+    "subagents.maxDepth": () => { },
+    "subagents.maxConcurrentPerConversation": () => { },
+    "subagents.maxDispatchesPerRun": () => { },
+    "subagents.maxTokensPerRun": () => { },
+    // The web tools read these limits through the config service on every call.
+    "web.search.maxResults": () => { },
+    "web.fetch.maxPageChars": () => { },
+    "web.fetch.maxAnswerTokens": () => { },
+    "web.fetch.cacheSeconds": () => { },
+    "web.fetch.timeoutMs": () => { },
+};
+/**
+ * Environment variables of renamed config keys, with their replacements: warned about once when
+ * the service starts (agent map spec §6: `subagents.maxConcurrentPerRun` became
+ * `subagents.maxConcurrentPerConversation`). A retired file or Nacos key cannot be told here: the
+ * schema strips unknown keys before the kernel receives its config.
+ */
+const RETIRED_ENV = [
+    [
+        "CAPYBARA_SUBAGENTS__MAX_CONCURRENT_PER_RUN",
+        "CAPYBARA_SUBAGENTS__MAX_CONCURRENT_PER_CONVERSATION",
+    ],
+];
+const HOT_PATHS = configFields(KernelConfigSchema)
+    .filter((f) => f.meta?.hot)
+    .map((f) => f.path);
+const errMsg = (e) => (e instanceof Error ? e.message : String(e));
+/** The current kernel config: `get()` always returns the latest hot-applied value. */
+let KernelConfigService = class KernelConfigService {
+    log;
+    current;
+    env;
+    listeners = new Set();
+    constructor(input, log) {
+        this.log = log;
+        for (const p of HOT_PATHS) {
+            if (!HOT_APPLIERS[p])
+                throw new Error(`config field ${p} is marked hot but has no applier`);
+        }
+        this.current = input.config;
+        this.env = input.env ?? process.env;
+        log.setLevel(input.config.log.level);
+        log.addSecrets(secretValues(KernelConfigSchema, input.config));
+        for (const [old, now] of RETIRED_ENV) {
+            if (this.env[old] !== undefined) {
+                log.warn(`${old} is no longer read and is ignored; set ${now} instead`, { env: old });
+            }
+        }
+    }
+    get() {
+        return this.current;
+    }
+    /** Subscribes to applied changes (hot fields only); returns the unsubscribe function. */
+    onChange(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    /**
+     * Hot reload: re-validates the raw config; only hot fields are applied, other changes warn and
+     * list the keys needing a restart; a validation failure keeps the current config.
+     */
+    apply(raw) {
+        const log = this.log;
+        let next;
+        try {
+            next = resolveConfig(raw, this.env);
+        }
+        catch (e) {
+            log.error("config reload rejected; keeping current config", { error: errMsg(e) });
+            return;
+        }
+        log.addSecrets(secretValues(KernelConfigSchema, next));
+        const changed = changedPaths(KernelConfigSchema, this.current, next);
+        if (changed.length === 0)
+            return;
+        const hot = changed.filter((p) => HOT_PATHS.includes(p));
+        const restart = changed.filter((p) => !HOT_PATHS.includes(p));
+        const updated = structuredClone(this.current);
+        const applied = [];
+        for (const p of hot) {
+            try {
+                HOT_APPLIERS[p]({ log }, getPath(next, p));
+                setPath(updated, p, getPath(next, p));
+                applied.push(p);
+            }
+            catch (e) {
+                log.error("config reload: cannot apply field; keeping current value", {
+                    key: p,
+                    error: errMsg(e),
+                });
+            }
+        }
+        this.current = updated;
+        if (applied.length > 0) {
+            log.info("config reloaded", { applied });
+            for (const l of [...this.listeners]) {
+                try {
+                    l(updated, applied);
+                }
+                catch (e) {
+                    log.error("config change listener threw", { error: errMsg(e) });
+                }
+            }
+        }
+        if (restart.length > 0) {
+            log.warn("config changed but requires restart to take effect", { keys: restart });
+        }
+    }
+};
+KernelConfigService = __decorate([
+    Injectable(),
+    __param(0, Inject(KERNEL_CONFIG_INPUT)),
+    __param(1, Inject(KERNEL_LOGGER))
+], KernelConfigService);
+export { KernelConfigService };

package/dist/infra/database/after-commit.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Runs a side effect (enqueue a job, publish on the bus) only after the root transaction commits;
+ * a rollback drops it; it runs outside any transaction. Outside a transaction it runs immediately.
+ * A failing hook is logged and never fails the committed call.
+ */
+export declare function afterCommit(fn: () => void | Promise<void>): void;

package/dist/infra/database/after-commit.js

@@ -0,0 +1,9 @@
+import { queueAfterCommit } from "./transaction-host.js";
+/**
+ * Runs a side effect (enqueue a job, publish on the bus) only after the root transaction commits;
+ * a rollback drops it; it runs outside any transaction. Outside a transaction it runs immediately.
+ * A failing hook is logged and never fails the committed call.
+ */
+export function afterCommit(fn) {
+    queueAfterCommit(fn);
+}

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

@@ -0,0 +1,25 @@
+import { type DynamicModule } from "@nestjs/common";
+import type { Kysely } from "kysely";
+import type { KernelLogger } from "../../log.js";
+import { GracefulShutdown } from "../lifecycle/graceful-shutdown.service.js";
+/**
+ * Closes the pool at the end of the shutdown (`GracefulShutdown.closeLast`: after everything that
+ * uses it has stopped, together with Redis), within what is left of the total stop budget.
+ */
+export declare class PoolLifecycle {
+    private readonly pool;
+    private readonly log;
+    private readonly shutdown;
+    constructor(pool: Kysely<any>, log: KernelLogger, shutdown: GracefulShutdown);
+    close(): Promise<void>;
+}
+/** Global: the Kysely pool, `TransactionHost`, the context-aware `KernelDb` and `XactLock`. */
+export declare class DatabaseModule {
+    /** The pool `db.*` of the config describes, closed at shutdown ({@link PoolLifecycle}). */
+    static forRoot(): DynamicModule;
+    /**
+     * The handles over a pool the caller owns and closes (`@capybara-hq/testing`'s
+     * `createLocalAccount`, which has a pool and no config): the context never closes it.
+     */
+    static borrowing(pool: Kysely<any>): DynamicModule;
+}

package/dist/infra/database/database.module.js

@@ -0,0 +1,91 @@
+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 { Global, Inject, Injectable, Module, } from "@nestjs/common";
+import { createDb } from "../../db/pool.js";
+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 { KERNEL_LOGGER, KERNEL_POOL } from "../tokens.js";
+import { KernelDb } from "./kernel-db.js";
+import { TransactionHost } from "./transaction-host.js";
+import { XactLock } from "./xact-lock.js";
+/**
+ * Closes the pool at the end of the shutdown (`GracefulShutdown.closeLast`: after everything that
+ * uses it has stopped, together with Redis), within what is left of the total stop budget.
+ */
+let PoolLifecycle = class PoolLifecycle {
+    pool;
+    log;
+    shutdown;
+    constructor(
+    // biome-ignore lint/suspicious/noExplicitAny: the pool carries no schema types
+    pool, log, shutdown) {
+        this.pool = pool;
+        this.log = log;
+        this.shutdown = shutdown;
+        shutdown.closeLast(() => this.close());
+    }
+    async close() {
+        await closeWithin("pg", this.pool.destroy(), this.shutdown.remainingMs(), this.log);
+    }
+};
+PoolLifecycle = __decorate([
+    Injectable(),
+    __param(0, Inject(KERNEL_POOL)),
+    __param(1, Inject(KERNEL_LOGGER)),
+    __param(2, Inject(GracefulShutdown))
+], PoolLifecycle);
+export { PoolLifecycle };
+/** The handles over the pool, the same for both pool sources. */
+function databaseModule(pool, imports) {
+    return {
+        module: DatabaseModule,
+        global: true,
+        imports,
+        providers: [...pool, TransactionHost, KernelDb, XactLock],
+        exports: [KERNEL_POOL, TransactionHost, KernelDb, XactLock],
+    };
+}
+/** Global: the Kysely pool, `TransactionHost`, the context-aware `KernelDb` and `XactLock`. */
+let DatabaseModule = class DatabaseModule {
+    /** The pool `db.*` of the config describes, closed at shutdown ({@link PoolLifecycle}). */
+    static forRoot() {
+        return databaseModule([
+            {
+                provide: KERNEL_POOL,
+                inject: [KernelConfigService, KERNEL_LOGGER],
+                useFactory: (config, log) => {
+                    const { db } = config.get();
+                    return createDb(db.url, db.poolMax, (err) => log.error("pg idle client error", { err }), {
+                        connectTimeoutMs: db.connectTimeoutMs,
+                        idleTimeoutMs: db.idleTimeoutMs,
+                        onClientError: (err) => log.warn("pg client error", { err }),
+                    });
+                },
+            },
+            PoolLifecycle,
+        ], [GracefulShutdownModule]);
+    }
+    /**
+     * The handles over a pool the caller owns and closes (`@capybara-hq/testing`'s
+     * `createLocalAccount`, which has a pool and no config): the context never closes it.
+     */
+    // biome-ignore lint/suspicious/noExplicitAny: the pool carries no schema types
+    static borrowing(pool) {
+        return databaseModule([{ provide: KERNEL_POOL, useValue: pool }], []);
+    }
+};
+DatabaseModule = __decorate([
+    Global(),
+    Module({})
+    // biome-ignore lint/complexity/noStaticOnlyClass: a Nest dynamic module
+], DatabaseModule);
+export { DatabaseModule };

package/dist/infra/database/kernel-db.d.ts

@@ -0,0 +1,22 @@
+import type { Kysely, Transaction } from "kysely";
+import { type KernelDatabase } from "../../db/kernel-schema.js";
+import { TransactionHost } from "./transaction-host.js";
+type View = Kysely<KernelDatabase>;
+/** The Kysely query entry points services use; each resolves to the context transaction or the pool. */
+declare const QUERY_METHODS: readonly ["selectFrom", "selectNoFrom", "insertInto", "replaceInto", "updateTable", "deleteFrom", "mergeInto", "with", "withRecursive", "executeQuery"];
+type QueryMethod = (typeof QUERY_METHODS)[number];
+export interface KernelDb extends Pick<View, QueryMethod | "fn"> {
+}
+/**
+ * What services inject instead of a Kysely instance: every call resolves to the transaction of
+ * the current async context (opened by `@Transactional()`), else to the pool; the `capybara`
+ * schema view applies either way. No `trx` parameters are passed around.
+ */
+export declare class KernelDb {
+    readonly pool: Kysely<any>;
+    private readonly txHost;
+    constructor(pool: Kysely<any>, txHost: TransactionHost);
+    /** The kernel-schema handle of the current context (transaction or pool). */
+    get db(): View | Transaction<KernelDatabase>;
+}
+export {};

package/dist/infra/database/kernel-db.js

@@ -0,0 +1,65 @@
+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 } from "@nestjs/common";
+import { kernelDb } from "../../db/kernel-schema.js";
+import { KERNEL_POOL } from "../tokens.js";
+import { TransactionHost } from "./transaction-host.js";
+/** The Kysely query entry points services use; each resolves to the context transaction or the pool. */
+const QUERY_METHODS = [
+    "selectFrom",
+    "selectNoFrom",
+    "insertInto",
+    "replaceInto",
+    "updateTable",
+    "deleteFrom",
+    "mergeInto",
+    "with",
+    "withRecursive",
+    "executeQuery",
+];
+/**
+ * What services inject instead of a Kysely instance: every call resolves to the transaction of
+ * the current async context (opened by `@Transactional()`), else to the pool; the `capybara`
+ * schema view applies either way. No `trx` parameters are passed around.
+ */
+let KernelDb = class KernelDb {
+    pool;
+    txHost;
+    constructor(
+    // biome-ignore lint/suspicious/noExplicitAny: the pool carries no schema types
+    pool, txHost) {
+        this.pool = pool;
+        this.txHost = txHost;
+    }
+    /** The kernel-schema handle of the current context (transaction or pool). */
+    get db() {
+        return kernelDb(this.txHost.current() ?? this.pool);
+    }
+};
+KernelDb = __decorate([
+    Injectable()
+    // biome-ignore lint/suspicious/noUnsafeDeclarationMerging: types the prototype-attached query methods
+    ,
+    __param(0, Inject(KERNEL_POOL)),
+    __param(1, Inject(TransactionHost))
+], KernelDb);
+export { KernelDb };
+for (const name of QUERY_METHODS) {
+    Object.defineProperty(KernelDb.prototype, name, {
+        value(...args) {
+            return this.db[name](...args);
+        },
+    });
+}
+Object.defineProperty(KernelDb.prototype, "fn", {
+    get() {
+        return this.db.fn;
+    },
+});

package/dist/infra/database/transaction-host.d.ts

@@ -0,0 +1,50 @@
+import type { AccessMode, IsolationLevel, Kysely, Transaction } from "kysely";
+import type { KernelLogger } from "../../log.js";
+type AfterCommitHook = () => void | Promise<void>;
+interface TransactionStore {
+    pool: Kysely<any>;
+    trx: Transaction<any>;
+    /** Side effects queued by `afterCommit`, run after this root transaction commits. */
+    hooks: AfterCommitHook[];
+    /** Set once the transaction settled: continuations that outlive it must not use it. */
+    done: boolean;
+}
+export type Propagation = "required" | "requires_new" | "mandatory";
+export interface TransactionOptions {
+    /**
+     * `required` (default): join the transaction in context, else open one. `requires_new`: a
+     * separate transaction on the pool, whatever the context. `mandatory`: join the transaction in
+     * context, and throw outside one (for methods whose correctness depends on a lock the caller
+     * took in its transaction).
+     */
+    propagation?: Propagation;
+    /** Isolation level of a transaction this call opens (ignored when it joins one). */
+    isolationLevel?: IsolationLevel;
+    /** Access mode of a transaction this call opens (ignored when it joins one). */
+    accessMode?: AccessMode;
+}
+/** Queues `fn` on the current live root transaction; with none open, runs it at once. */
+export declare function queueAfterCommit(fn: AfterCommitHook): void;
+/** The transaction store in the current async context (used by `afterCommit`). */
+export declare function currentStore(): TransactionStore | undefined;
+/**
+ * Runs `fn` with no transaction in context, whatever the caller had open. Queue processors and
+ * scheduled jobs start from here: a job outlives the transaction that enqueued it and must never
+ * join (or write through) a transaction that may already be committed or rolled back.
+ */
+export declare function runOutsideTransaction<T>(fn: () => T): T;
+export declare class TransactionHost {
+    private readonly pool;
+    private readonly log;
+    constructor(pool: Kysely<any>, log: KernelLogger);
+    /** The transaction of the current async context on this pool, if any. */
+    current(): Transaction<any> | undefined;
+    /**
+     * Runs `fn` in a transaction: a throw rolls back, a return commits. REQUIRED (default) joins the
+     * transaction in context; `requires_new` always opens its own on the pool; `mandatory` joins the
+     * one in context and throws when there is none. Hooks queued by `afterCommit` run after the
+     * root's COMMIT, outside any transaction, and are dropped on rollback.
+     */
+    run<T>(fn: () => Promise<T>, opts?: TransactionOptions): Promise<T>;
+}
+export {};

package/dist/infra/database/transaction-host.js

@@ -0,0 +1,125 @@
+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/typeorm/transaction-context.ts (owner-approved, 2026-10-28).
+// Adapted to Kysely: the context holds a Kysely `Transaction` instead of a TypeORM QueryRunner.
+import { AsyncLocalStorage } from "node:async_hooks";
+import { Inject, Injectable } from "@nestjs/common";
+import { KERNEL_LOGGER, KERNEL_POOL } from "../tokens.js";
+/** One store for the process: `afterCommit` (a free function) reads it without a host instance. */
+const storage = new AsyncLocalStorage();
+/** Logger for hook failures outside a transaction; set by `TransactionHost`, console until then. */
+let hookLog = {
+    error: (msg, fields) => console.error(`[afterCommit] ${msg}`, fields ?? ""),
+};
+const errMsg = (e) => (e instanceof Error ? e.message : String(e));
+/** Queues `fn` on the current live root transaction; with none open, runs it at once. */
+export function queueAfterCommit(fn) {
+    const store = liveStore();
+    if (store) {
+        store.hooks.push(fn);
+        return;
+    }
+    try {
+        const r = fn();
+        if (r instanceof Promise) {
+            r.catch((e) => hookLog.error("afterCommit hook failed", { error: errMsg(e) }));
+        }
+    }
+    catch (e) {
+        hookLog.error("afterCommit hook failed", { error: errMsg(e) });
+    }
+}
+/** The store of the current context unless its transaction already finished. */
+function liveStore() {
+    const store = storage.getStore();
+    return store && !store.done ? store : undefined;
+}
+/** The transaction store in the current async context (used by `afterCommit`). */
+export function currentStore() {
+    return liveStore();
+}
+/**
+ * Runs `fn` with no transaction in context, whatever the caller had open. Queue processors and
+ * scheduled jobs start from here: a job outlives the transaction that enqueued it and must never
+ * join (or write through) a transaction that may already be committed or rolled back.
+ */
+export function runOutsideTransaction(fn) {
+    return storage.exit(fn);
+}
+let TransactionHost = class TransactionHost {
+    pool;
+    log;
+    constructor(
+    // biome-ignore lint/suspicious/noExplicitAny: the pool carries no schema types
+    pool, log) {
+        this.pool = pool;
+        this.log = log;
+        hookLog = log;
+    }
+    /** The transaction of the current async context on this pool, if any. */
+    // biome-ignore lint/suspicious/noExplicitAny: the pool carries no schema types
+    current() {
+        const store = liveStore();
+        return store?.pool === this.pool ? store.trx : undefined;
+    }
+    /**
+     * Runs `fn` in a transaction: a throw rolls back, a return commits. REQUIRED (default) joins the
+     * transaction in context; `requires_new` always opens its own on the pool; `mandatory` joins the
+     * one in context and throws when there is none. Hooks queued by `afterCommit` run after the
+     * root's COMMIT, outside any transaction, and are dropped on rollback.
+     */
+    async run(fn, opts = {}) {
+        const propagation = opts.propagation ?? "required";
+        if (propagation === "mandatory") {
+            if (!this.current()) {
+                throw new Error('propagation "mandatory": no transaction in context (the caller must open one and ' +
+                    "hold the locks this method relies on)");
+            }
+            return fn();
+        }
+        if (propagation === "required" && this.current())
+            return fn();
+        const hooks = [];
+        let store;
+        let result;
+        try {
+            let builder = this.pool.transaction();
+            if (opts.isolationLevel !== undefined)
+                builder = builder.setIsolationLevel(opts.isolationLevel);
+            if (opts.accessMode !== undefined)
+                builder = builder.setAccessMode(opts.accessMode);
+            result = await builder.execute((trx) => {
+                store = { pool: this.pool, trx, hooks, done: false };
+                return storage.run(store, fn);
+            });
+        }
+        finally {
+            if (store)
+                store.done = true;
+        }
+        for (const hook of hooks) {
+            try {
+                // outside any transaction: a requires_new nested in an outer one must not have its side
+                // effects join (and roll back with) the outer transaction
+                await runOutsideTransaction(hook);
+            }
+            catch (e) {
+                this.log.error("afterCommit hook failed", { error: errMsg(e) });
+            }
+        }
+        return result;
+    }
+};
+TransactionHost = __decorate([
+    Injectable(),
+    __param(0, Inject(KERNEL_POOL)),
+    __param(1, Inject(KERNEL_LOGGER))
+], TransactionHost);
+export { TransactionHost };

package/dist/infra/database/transactional.decorator.d.ts

@@ -0,0 +1,15 @@
+import type { TransactionOptions } from "./transaction-host.js";
+/**
+ * Method decorator: runs the method in a database transaction (REQUIRED by default: join the one
+ * in context, else open it; a throw rolls back, a normal return commits). The class must inject
+ * the host as a property named `txHost`:
+ *
+ * ```ts
+ * constructor(@Inject(TransactionHost) readonly txHost: TransactionHost) {}
+ * ```
+ *
+ * Use `{ propagation: "requires_new" }` for a transaction independent of the caller's, and
+ * `{ propagation: "mandatory" }` for a method whose correctness depends on a lock its caller holds
+ * (it joins the caller's transaction and throws when called outside one).
+ */
+export declare function Transactional(opts?: TransactionOptions): (_target: object, _key: string | symbol, descriptor: PropertyDescriptor) => PropertyDescriptor;

package/dist/infra/database/transactional.decorator.js

@@ -0,0 +1,27 @@
+/**
+ * Method decorator: runs the method in a database transaction (REQUIRED by default: join the one
+ * in context, else open it; a throw rolls back, a normal return commits). The class must inject
+ * the host as a property named `txHost`:
+ *
+ * ```ts
+ * constructor(@Inject(TransactionHost) readonly txHost: TransactionHost) {}
+ * ```
+ *
+ * Use `{ propagation: "requires_new" }` for a transaction independent of the caller's, and
+ * `{ propagation: "mandatory" }` for a method whose correctness depends on a lock its caller holds
+ * (it joins the caller's transaction and throws when called outside one).
+ */
+export function Transactional(opts = {}) {
+    return (_target, _key, descriptor) => {
+        const original = descriptor.value;
+        descriptor.value = function (...args) {
+            const host = this.txHost;
+            if (!host) {
+                throw new Error("@Transactional() needs the class to inject `TransactionHost` as `txHost` " +
+                    "(`@Inject(TransactionHost) readonly txHost: TransactionHost`).");
+            }
+            return host.run(() => original.apply(this, args), opts);
+        };
+        return descriptor;
+    };
+}

package/dist/infra/database/xact-lock.d.ts

@@ -0,0 +1,17 @@
+import { KernelDb } from "./kernel-db.js";
+import { TransactionHost } from "./transaction-host.js";
+/**
+ * Transaction-scoped advisory locks (decision R9 of the Nest kernel spec): `pg_advisory_xact_lock`
+ * is transaction semantics, like `FOR UPDATE`. It is held by the caller's transaction and released
+ * at its COMMIT or ROLLBACK, so it serializes writers whose invariant is checked inside that same
+ * transaction ("never zero active super admins", "set up once", "one account per external
+ * identity"). The one place that takes such a lock; `propagation: "mandatory"` makes a call outside
+ * a transaction (where the lock would be released at once) throw.
+ */
+export declare class XactLock {
+    private readonly db;
+    readonly txHost: TransactionHost;
+    constructor(db: KernelDb, txHost: TransactionHost);
+    /** Takes the lock named `key` until the caller's transaction ends (waits while another holds it). */
+    lock(key: string): Promise<void>;
+}

package/dist/infra/database/xact-lock.js

@@ -0,0 +1,43 @@
+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 } from "@nestjs/common";
+import { sql } from "kysely";
+import { KernelDb } from "./kernel-db.js";
+import { TransactionHost } from "./transaction-host.js";
+import { Transactional } from "./transactional.decorator.js";
+/**
+ * Transaction-scoped advisory locks (decision R9 of the Nest kernel spec): `pg_advisory_xact_lock`
+ * is transaction semantics, like `FOR UPDATE`. It is held by the caller's transaction and released
+ * at its COMMIT or ROLLBACK, so it serializes writers whose invariant is checked inside that same
+ * transaction ("never zero active super admins", "set up once", "one account per external
+ * identity"). The one place that takes such a lock; `propagation: "mandatory"` makes a call outside
+ * a transaction (where the lock would be released at once) throw.
+ */
+let XactLock = class XactLock {
+    db;
+    txHost;
+    constructor(db, txHost) {
+        this.db = db;
+        this.txHost = txHost;
+    }
+    /** Takes the lock named `key` until the caller's transaction ends (waits while another holds it). */
+    async lock(key) {
+        await sql `SELECT pg_advisory_xact_lock(hashtext(${key}))`.execute(this.db.db);
+    }
+};
+__decorate([
+    Transactional({ propagation: "mandatory" })
+], XactLock.prototype, "lock", null);
+XactLock = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(TransactionHost))
+], XactLock);
+export { XactLock };