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

package/dist/orgs/offboarding.js

@@ -1,11 +1,35 @@
+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 { DIRECTORY_EXTENSION_POINT } from "@capybara-hq/plugin-sdk";
+import { Inject, Injectable } from "@nestjs/common";
 import { sql } from "kysely";
+import { retargetSetupRequests } from "../agents/pending-connector-requests.js";
+import { EventLog } from "../conversations/event-log.js";
 import { ApiError } from "../errors.js";
 import { enabledExtensionsQuery } from "../extensions/enabled.js";
+import { ExtensionRegistry } from "../extensions/registry.js";
 import { audit } from "../identity/audit.js";
-/** 兜底扫描：维护队列任务名、job scheduler id（不含 `:`）、周期与每次条数。 */
+import { SessionService } from "../identity/sessions.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { Transactional } from "../infra/database/transactional.decorator.js";
+import { LockService } from "../infra/lock/lock.service.js";
+import { LockedCron } from "../infra/schedule/locked-cron.decorator.js";
+import { KERNEL_LOGGER, REDIS } from "../infra/tokens.js";
+import { RunControl } from "../runtime/run-control.js";
+import { SandboxJobs } from "../sandbox/jobs.js";
+import { ApprovalsService } from "../tools/approvals.service.js";
+import { Credentials } from "../tools/credentials.js";
+import { QuestionsService } from "../tools/questions.service.js";
+/** The safety-net sweep: cron job name (no `:`), every 10 minutes, and the rows per page. */
 export const OFFBOARD_SWEEP_JOB = "offboard-sweep";
-export const OFFBOARD_SWEEP_SCHEDULER_ID = "offboard-sweep-every-10m";
-export const OFFBOARD_SWEEP_EVERY_MS = 600_000;
 export const OFFBOARD_SWEEP_BATCH = 500;
 /** 一次兜底扫描最多翻的页数（每页 {@link OFFBOARD_SWEEP_BATCH} 条），防止单次任务无限长。 */
 export const OFFBOARD_SWEEP_MAX_PAGES = 20;
@@ -18,30 +42,51 @@ const ACTIVE = ["queued", "running", "waiting"];
 const DIRECTORY_SOURCE_PREFIX = "directory:";
 /**
  * 成员离职（spec 3.3）：管理员移出、本人离开与通讯录同步共用这一条路径，全部写入在调用方的同一个事务内，
- * 要么都生效要么都不生效。Redis 吊销标记、事件发布与中止进行中的运行是提交后的尽力而为（{@link afterCommit}），
+ * 要么都生效要么都不生效。Redis 吊销标记、事件发布与中止进行中的运行是提交后的尽力而为（{@link afterOffboard}），
  * 漏掉的运行由兜底扫描（{@link sweep}：发起人已不是该组织成员的进行中运行）中止。框架无关。
  *
  * 已接受的窄窗口：离职提交时正在进行的 OAuth token 刷新（`Credentials` 刷新锁内）可能在提交之后把此人的
  * 个人凭据重新写回（upsert）。凭据只在此人以成员身份调用工具时使用，而其运行已被中止、成员关系已删除，
  * 残留的凭据不会被使用；重新加入组织后会被新的连接覆盖。
  */
-export class Offboarding {
-    deps;
-    constructor(deps) {
-        this.deps = deps;
-        deps.maintenance?.schedule({
-            id: OFFBOARD_SWEEP_SCHEDULER_ID,
-            name: OFFBOARD_SWEEP_JOB,
-            everyMs: () => OFFBOARD_SWEEP_EVERY_MS,
-        });
-        deps.maintenance?.handle(OFFBOARD_SWEEP_JOB, async () => {
-            await this.sweep();
-        });
+let Offboarding = class Offboarding {
+    db;
+    txHost;
+    sessions;
+    redis;
+    registry;
+    eventLog;
+    sandboxJobs;
+    runs;
+    credentials;
+    approvals;
+    questions;
+    log;
+    constructor(db, txHost, sessions, redis, registry, eventLog, 
+    /** The departed member's environments: one-off maintenance jobs, destroyed by a worker. */
+    sandboxJobs, 
+    /** Stops the departed member's runs (`by: null`, a system action). */
+    runs, credentials, approvals, questions, log) {
+        this.db = db;
+        this.txHost = txHost;
+        this.sessions = sessions;
+        this.redis = redis;
+        this.registry = registry;
+        this.eventLog = eventLog;
+        this.sandboxJobs = sandboxJobs;
+        this.runs = runs;
+        this.credentials = credentials;
+        this.approvals = approvals;
+        this.questions = questions;
+        this.log = log;
     }
     /**
-     * 在事务 `t` 内（调用方应已锁组织行——顺序：组织行 → 成员关系，并完成「最后一个 owner」等前置检查）：
+     * In the caller's transaction (`mandatory`: the caller holds the org row lock, order org row →
+     * membership, and did the "last owner" checks)：
      * 1. 删除成员关系（非成员 → `member.not_found`；删后组织没有 owner → `org.last_owner`），清空指向该组织的会话当前组织；
-     * 2. 吊销该账号**全部**会话与个人令牌（令牌与会话是账号级的，无法只吊销「该组织下」的，按保守处理）；
+     * 2. Removal and directory offboarding revoke **every** session and personal token of the
+     *    account (both are account-wide, so conservatively all); a person who leaves (`left`) keeps
+     *    them, and the session's current org is cleared (the membership check ends the access);
      * 3. 删除其在该组织所有连接器上的个人凭据；
      * 4. 取消其作为处理人的 pending 审批与提问（写 cancelled 事件），记下此人在该组织进行中的运行（提交后中止）；
      * 5. 其负责的该组织 agent 转给组织所有者（最早加入的 owner）并置 `needs_reassignment = true`；
@@ -51,10 +96,12 @@ export class Offboarding {
      *    以及成员关系自身的 `directory:<插件>` 来源，不论此人当初是不是由通讯录加入（手动重新加入后再被移出也不会被同步加回）；
      *    同步不再把此人加回，直到有人手动重新加入（{@link MembersService.add} 删除排除）；
      * 8. 审计 `org.member.offboarded`；
-     * 9. 记下此人在该组织对话里还没销毁的沙箱（提交后销毁，尽力而为）。
+     * 9. Soft-deletes the person's environments in the org and clears their default row (the
+     *    instances and files are destroyed after the commit, best effort; the hourly sweep finishes
+     *    any left).
      */
-    async offboard(t, orgId, accountId, reason, actor = {}) {
-        const deleted = await t
+    async offboard(orgId, accountId, reason, actor = {}) {
+        const deleted = await this.db
             .deleteFrom("memberships")
             .where("org_id", "=", orgId)
             .where("account_id", "=", accountId)
@@ -70,7 +117,7 @@ export class Offboarding {
         // deleted or re-keyed, so NO KEY UPDATE: it still excludes FOR SHARE and other writers, but not
         // the foreign key checks (FOR KEY SHARE) of a transaction that writes rows referencing them,
         // which may already hold a conversation row this transaction waits for (40P01)
-        await t
+        await this.db
             .selectFrom("agents")
             .select("id")
             .where("org_id", "=", orgId)
@@ -82,7 +129,7 @@ export class Offboarding {
         // then the member's conversations in id order, before any of their queue rows (final review
         // m2): queue dispatch, send-now and remove lock a conversation, then its queue rows; deleting
         // the rows first and updating the conversations after could deadlock with them (40P01)
-        await t
+        await this.db
             .selectFrom("conversations")
             .select("id")
             .where("org_id", "=", orgId)
@@ -90,7 +137,7 @@ export class Offboarding {
             .orderBy("id")
             .forNoKeyUpdate()
             .execute();
-        const owner = await t
+        const owner = await this.db
             .selectFrom("memberships")
             .select("account_id")
             .where("org_id", "=", orgId)
@@ -102,41 +149,50 @@ export class Offboarding {
         if (!owner) {
             throw new ApiError("org.last_owner", "An organization must keep at least one owner");
         }
-        await t
+        await this.db
             .updateTable("sessions")
             .set({ current_org_id: null })
             .where("account_id", "=", accountId)
             .where("current_org_id", "=", orgId)
             .execute();
-        const sessions = await t
-            .updateTable("sessions")
-            .set({ revoked_at: sql `now()` })
-            .where("account_id", "=", accountId)
-            .where("revoked_at", "is", null)
-            .returning("id")
-            .execute();
-        const tokens = await t
-            .updateTable("api_tokens")
-            .set({ revoked_at: sql `now()` })
-            .where("kind", "=", "personal")
-            .where("account_id", "=", accountId)
-            .where("revoked_at", "is", null)
-            .returning("id")
-            .execute();
-        const credentials = await this.deps.credentials.clearAccount(orgId, accountId, t);
-        const approvals = await this.deps.approvals.cancelPendingFor(t, orgId, accountId);
-        const questions = await this.deps.questions.cancelPendingFor(t, orgId, accountId);
+        // A person who leaves keeps their sign-in and personal tokens: the org guard reads the
+        // membership on every request, so access to this org ends with the row above, and their other
+        // orgs keep working. Removal and directory offboarding revoke both (account-wide, conservative).
+        const revoke = reason !== "left";
+        const sessions = revoke
+            ? await this.db
+                .updateTable("sessions")
+                .set({ revoked_at: sql `now()` })
+                .where("account_id", "=", accountId)
+                .where("revoked_at", "is", null)
+                .returning("id")
+                .execute()
+            : [];
+        const tokens = revoke
+            ? await this.db
+                .updateTable("api_tokens")
+                .set({ revoked_at: sql `now()` })
+                .where("kind", "=", "personal")
+                .where("account_id", "=", accountId)
+                .where("revoked_at", "is", null)
+                .returning("id")
+                .execute()
+            : [];
+        // in this transaction (the approvals and questions services join it: `mandatory`)
+        const credentials = await this.credentials.clearAccount(orgId, accountId);
+        const approvals = await this.approvals.cancelPendingFor(orgId, accountId);
+        const questions = await this.questions.cancelPendingFor(orgId, accountId);
         const notify = new Map(approvals.seqs);
         for (const [c, seq] of questions.seqs)
             notify.set(c, Math.max(notify.get(c) ?? 0, seq));
-        const runs = await t
+        const runs = await this.db
             .selectFrom("runs")
             .innerJoin("conversations", "conversations.id", "runs.conversation_id")
             .select(["runs.id", "runs.conversation_id", "runs.status"])
             .where("conversations.org_id", "=", orgId)
             // 评测回放的隐藏对话由评测 worker 驱动（不执行工具），随评测运行停下，不在这里中止。
             // 评测运行的创建者离开组织也不取消评测运行（Ruling S1-b）：管理员发起的评测运行是组织的工作，
-            // 只有取消、删除评测集、删除组织或 agent 才会停下（见 evals/budget.ts cancelEvalRuns）
+            // 只有取消、删除评测集、删除组织或 agent 才会停下（见 evals/budget.ts `EvalBudget.cancelRuns`）
             // a removed member's sub-agents run with their identity and credentials: stopped too
             .where("conversations.kind", "in", ["chat", "subagent"])
             .where("runs.status", "in", ACTIVE)
@@ -145,7 +201,7 @@ export class Offboarding {
             eb("conversations.account_id", "=", accountId),
         ]))
             .execute();
-        const agents = await t
+        const agents = await this.db
             .updateTable("agents")
             .set({
             owner_account_id: owner.account_id,
@@ -157,21 +213,23 @@ export class Offboarding {
             .where("deleted_at", "is", null)
             .returning("id")
             .execute();
-        const threads = await t
+        // their connector setup requests follow them to the org owner (ruling P4-T6-4)
+        await retargetSetupRequests(this.db.db, agents.map((a) => a.id), owner.account_id);
+        const threads = await this.db
             .updateTable("channel_threads")
             .set({ archived_at: sql `now()` })
             .where("account_id", "=", accountId)
             .where("archived_at", "is", null)
             .where("connection_id", "in", (eb) => eb.selectFrom("channel_connections").select("id").where("org_id", "=", orgId))
             .executeTakeFirst();
-        const grants = await t
+        const grants = await this.db
             .deleteFrom("tool_grants")
             .where("org_id", "=", orgId)
             .where("account_id", "=", accountId)
             .executeTakeFirst();
-        const excluded = reason === "directory" ? [] : await this.exclusionPlugins(t, orgId, deleted.source);
+        const excluded = reason === "directory" ? [] : await this.exclusionPlugins(orgId, deleted.source);
         if (excluded.length > 0) {
-            await t
+            await this.db
                 .insertInto("directory_exclusions")
                 .values(excluded.map((plugin) => ({
                 org_id: orgId,
@@ -184,7 +242,7 @@ export class Offboarding {
         }
         // Queued messages never go out after their author leaves (they also hold `@` resource bodies
         // read with the person's credentials): deleted here, so no dispatch can pick them up.
-        const queued = await t
+        const queued = await this.db
             .deleteFrom("conversation_queue")
             .where("conversation_id", "in", (eb) => eb
             .selectFrom("conversations")
@@ -195,21 +253,27 @@ export class Offboarding {
             .execute();
         const queueConversations = [...new Set(queued.map((r) => r.conversation_id))];
         if (queueConversations.length > 0) {
-            await t
+            await this.db
                 .updateTable("conversations")
                 .set({ queue_paused: false, queue_pause_reason: null })
                 .where("id", "in", queueConversations)
                 .execute();
         }
-        const sandboxes = await t
-            .selectFrom("sandboxes")
-            .innerJoin("conversations", "conversations.id", "sandboxes.conversation_id")
-            .select("sandboxes.conversation_id")
-            .where("conversations.org_id", "=", orgId)
-            .where("conversations.account_id", "=", accountId)
-            .where("sandboxes.status", "<>", "destroyed")
+        const environments = await this.db
+            .updateTable("environments")
+            .set({ deleted_at: sql `now()`, updated_at: sql `now()` })
+            .where("org_id", "=", orgId)
+            .where("owner_kind", "=", "personal")
+            .where("owner_account_id", "=", accountId)
+            .where("deleted_at", "is", null)
+            .returning("id")
+            .execute();
+        await this.db
+            .deleteFrom("environment_defaults")
+            .where("org_id", "=", orgId)
+            .where("account_id", "=", accountId)
             .execute();
-        await audit(t, {
+        await audit(this.db.db, {
             ...(actor.actorAccountId !== undefined && { actorAccountId: actor.actorAccountId }),
             ...(actor.actorTokenId !== undefined && { actorTokenId: actor.actorTokenId }),
             orgId,
@@ -229,7 +293,7 @@ export class Offboarding {
                 channelThreadsArchived: Number(threads.numUpdatedRows),
                 toolGrantsDeleted: Number(grants.numDeletedRows),
                 ...(excluded.length > 0 && { directoryExcluded: excluded }),
-                ...(sandboxes.length > 0 && { sandboxesToDestroy: sandboxes.length }),
+                ...(environments.length > 0 && { environmentsDeleted: environments.length }),
                 ...(queued.length > 0 && { queuedMessagesDeleted: queued.length }),
             },
         });
@@ -243,20 +307,24 @@ export class Offboarding {
                 status: r.status,
             })),
             newOwnerId: agents.length > 0 ? owner.account_id : null,
-            sandboxConversations: sandboxes.map((r) => r.conversation_id),
+            environments: environments.map((r) => r.id),
             queueConversations,
         };
     }
     /** 要写排除的通讯录插件：该组织启用的已加载通讯录插件 ∪ 成员关系自身的 `directory:<插件>` 来源，去重排序。 */
-    async exclusionPlugins(t, orgId, source) {
+    async exclusionPlugins(orgId, source) {
         const out = new Set();
         if (source?.startsWith(DIRECTORY_SOURCE_PREFIX)) {
             out.add(source.slice(DIRECTORY_SOURCE_PREFIX.length));
         }
-        const loaded = this.deps.directoryPlugins?.() ?? [];
+        // Ruling A24: every loaded directory extension enabled in the org
+        const loaded = this.registry
+            .list("directory")
+            .filter((e) => e.capability === DIRECTORY_EXTENSION_POINT)
+            .map((e) => e.plugin);
         if (loaded.length > 0) {
-            const rows = await t
-                .selectFrom(enabledExtensionsQuery(t, orgId).as("en"))
+            const rows = await this.db
+                .selectFrom(enabledExtensionsQuery(this.db.db, orgId).as("en"))
                 .select("en.plugin")
                 .where("en.plugin", "in", loaded)
                 .execute();
@@ -266,42 +334,44 @@ export class Offboarding {
         return [...out].sort();
     }
     /**
-     * 提交之后：写会话吊销标记、发布 cancelled 事件、中止此人在该组织进行中的运行、投递销毁其对话沙箱的任务。
-     * 每步失败只记 warn。
+     * After the commit (callers register it with the infra `afterCommit` inside their transaction):
+     * writes the session revocation markers, publishes the cancelled events, stops the person's
+     * runs in the org and schedules destroying their environments. A failing step only logs a
+     * warning.
      */
-    async afterCommit(r) {
-        const { sessions, eventLog, log } = this.deps;
+    async afterOffboard(r) {
+        const { sessions, log, eventLog } = this;
         try {
-            await sessions?.markRevoked(r.revokedSessionIds);
+            await sessions.markRevoked(r.revokedSessionIds);
         }
         catch (err) {
-            log?.warn("offboarding: cannot write session revocation markers", { err });
+            log.warn("offboarding: cannot write session revocation markers", { err });
         }
         for (const [conversationId, seq] of r.notify) {
             try {
-                await eventLog?.notify(conversationId, seq);
+                await eventLog.notify(conversationId, seq);
             }
             catch (err) {
-                log?.warn("offboarding: event notify failed", { conversationId, err });
+                log.warn("offboarding: event notify failed", { conversationId, err });
             }
         }
         for (const conversationId of r.queueConversations) {
             try {
-                await eventLog?.publishChanged?.(conversationId, "queue");
+                await eventLog.publishChanged(conversationId, "queue");
             }
             catch (err) {
-                log?.warn("offboarding: queue change notify failed", { conversationId, err });
+                log.warn("offboarding: queue change notify failed", { conversationId, err });
             }
         }
         for (const run of r.runs)
             await this.stopRun(run);
-        if (r.sandboxConversations.length > 0 && this.deps.sandboxes) {
+        if (r.environments.length > 0) {
             try {
-                await this.deps.sandboxes.destroy(r.sandboxConversations);
+                await this.sandboxJobs.destroy(r.environments);
             }
             catch (err) {
-                log?.warn("offboarding: cannot schedule sandbox destruction", {
-                    count: r.sandboxConversations.length,
+                log.warn("offboarding: cannot schedule environment destruction", {
+                    count: r.environments.length,
                     err,
                 });
             }
@@ -313,9 +383,7 @@ export class Offboarding {
      * 不像会话中止那样随后起新一轮运行：离职者的待处理消息不再处理。
      */
     async stopRun(run) {
-        const ctl = this.deps.runs;
-        if (!ctl)
-            return;
+        const ctl = this.runs;
         try {
             if (run.status === "waiting" &&
                 (await ctl.abortWaiting(run.conversationId, run.runId, null))) {
@@ -326,12 +394,12 @@ export class Offboarding {
             await ctl.requestAbort(run.runId, null);
             // 广播中止的运行要等所在副本到达步骤边界才真正结束：广播成功后记标记，扫描在其有效期内不再重复广播
             // （广播失败不记，下一轮扫描重试）
-            await this.deps.redis
-                ?.set(offboardAbortKey(run.runId), "1", "EX", OFFBOARD_ABORT_MARK_TTL_SECONDS)
-                .catch((err) => this.deps.log?.warn("offboarding: cannot mark abort", { err }));
+            await this.redis
+                .set(offboardAbortKey(run.runId), "1", "EX", OFFBOARD_ABORT_MARK_TTL_SECONDS)
+                .catch((err) => this.log.warn("offboarding: cannot mark abort", { err }));
         }
         catch (err) {
-            this.deps.log?.warn("offboarding: cannot stop run", { runId: run.runId, err });
+            this.log.warn("offboarding: cannot stop run", { runId: run.runId, err });
         }
     }
     /**
@@ -342,11 +410,8 @@ export class Offboarding {
      * 不每轮重复广播；标记过期仍未结束的再处理一次。返回本次处理（未跳过）的运行数。
      * 现任成员（含匿名访客这样的 guest 成员）发起的运行不受影响。
      */
-    async sweep() {
-        const { db } = this.deps;
-        if (!db || !this.deps.runs)
-            return 0;
-        const batch = this.deps.sweepBatch ?? OFFBOARD_SWEEP_BATCH;
+    async sweep(batch = OFFBOARD_SWEEP_BATCH) {
+        const db = this.db;
         // 游标的时间用文本保存完整的微秒精度（JS Date 只有毫秒，会让同一行再被取到）
         let after;
         let total = 0;
@@ -373,7 +438,7 @@ export class Offboarding {
                 if (await this.recentlyAborted(r.id))
                     continue;
                 total++;
-                this.deps.log?.warn("offboard sweep: stopping run of a former member", { runId: r.id });
+                this.log.warn("offboard sweep: stopping run of a former member", { runId: r.id });
                 await this.stopRun({
                     conversationId: r.conversation_id,
                     runId: r.id,
@@ -389,10 +454,56 @@ export class Offboarding {
     }
     async recentlyAborted(runId) {
         try {
-            return (await this.deps.redis?.exists(offboardAbortKey(runId))) === 1;
+            return (await this.redis.exists(offboardAbortKey(runId))) === 1;
         }
         catch {
             return false;
         }
     }
-}
+};
+__decorate([
+    Transactional({ propagation: "mandatory" })
+], Offboarding.prototype, "offboard", null);
+Offboarding = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(TransactionHost)),
+    __param(2, Inject(SessionService)),
+    __param(3, Inject(REDIS)),
+    __param(4, Inject(ExtensionRegistry)),
+    __param(5, Inject(EventLog)),
+    __param(6, Inject(SandboxJobs)),
+    __param(7, Inject(RunControl)),
+    __param(8, Inject(Credentials)),
+    __param(9, Inject(ApprovalsService)),
+    __param(10, Inject(QuestionsService)),
+    __param(11, Inject(KERNEL_LOGGER))
+], Offboarding);
+export { Offboarding };
+/**
+ * The offboarding safety-net sweep ({@link Offboarding.sweep}) every 10 minutes, once per tick
+ * across replicas; a worker-role job (`WorkerModule`).
+ */
+let OffboardSweepJob = class OffboardSweepJob {
+    offboarding;
+    lockService;
+    log;
+    constructor(offboarding, lockService, log) {
+        this.offboarding = offboarding;
+        this.lockService = lockService;
+        this.log = log;
+    }
+    async run() {
+        await this.offboarding.sweep();
+    }
+};
+__decorate([
+    LockedCron("*/10 * * * *", { name: OFFBOARD_SWEEP_JOB })
+], OffboardSweepJob.prototype, "run", null);
+OffboardSweepJob = __decorate([
+    Injectable(),
+    __param(0, Inject(Offboarding)),
+    __param(1, Inject(LockService)),
+    __param(2, Inject(KERNEL_LOGGER))
+], OffboardSweepJob);
+export { OffboardSweepJob };

package/dist/orgs/org-lock.d.ts

@@ -1,15 +1,15 @@
-import type { Transaction } from "kysely";
-import type { KernelDatabase } from "../db/kernel-schema.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
 import { type OrgAction, type OrgRole } from "./roles.js";
-type Trx = Transaction<KernelDatabase>;
-/** 被锁组织的元数据（审计记录改动前的值用）。 */
+/** The locked org's metadata (audits record the values before a change). */
 export interface LockedOrg {
     slug: string;
     name: string;
 }
 /**
- * `SELECT … FROM capybara.orgs WHERE id = $1 AND deleted_at IS NULL FOR NO KEY UPDATE`：锁住组织行，
- * 串行化同一组织的成员 / 邀请 / 令牌 / 配置写操作。组织不存在或已软删除时返回 undefined。
+ * The org row lock that serializes an organization's member / invitation / token / config writes.
+ * Every method joins the caller's transaction (`mandatory`), which holds the row lock until it
+ * ends; called outside one it throws instead of locking nothing.
  *
  * NO KEY UPDATE, not UPDATE: the holders still exclude each other (and `FOR SHARE` readers), but a
  * foreign key check against the org row (`FOR KEY SHARE`, taken by every insert of a row that
@@ -17,16 +17,30 @@ export interface LockedOrg {
  * With FOR UPDATE, offboarding (org row, then the member's conversations) deadlocked with an event
  * log append (a conversation row, then the org foreign key check).
  */
-export declare function tryLockOrg(t: Trx, orgId: string): Promise<LockedOrg | undefined>;
-/** 同 `tryLockOrg`，组织不存在或已软删除 → `org.not_found`。 */
-export declare function lockOrg(t: Trx, orgId: string): Promise<LockedOrg>;
-/**
- * 依赖角色的组织写操作的执行期复核（spec 3.6 R5）：锁组织行，并在锁内实时重读发起人的角色。
- * 组织不存在或已软删除 → `org.not_found`；发起人不是成员或角色不足以执行 `action` → `forbidden`。
- * 服务只接收发起人账号 id，不接收调用方传入的角色。
- */
-export declare function lockOrgAndAuthorize(t: Trx, orgId: string, actorAccountId: string, action: OrgAction): Promise<{
-    org: LockedOrg;
-    role: OrgRole;
-}>;
-export {};
+export declare class OrgLock {
+    private readonly db;
+    readonly txHost: TransactionHost;
+    constructor(db: KernelDb, txHost: TransactionHost);
+    /** Locks the org row; undefined when the org does not exist or is soft-deleted. */
+    tryLock(orgId: string): Promise<LockedOrg | undefined>;
+    /** Like {@link tryLock}; a missing or soft-deleted org → `org.not_found`. */
+    lock(orgId: string): Promise<LockedOrg>;
+    /**
+     * The run-time re-check of a role-dependent org write (spec 3.6 R5): locks the org row and
+     * re-reads the actor's role under it. A missing or soft-deleted org → `org.not_found`; the actor
+     * is not a member or the role does not allow `action` → `forbidden`. Services take only the
+     * actor's account id, never a role from the caller.
+     */
+    lockAndAuthorize(orgId: string, actorAccountId: string, action: OrgAction): Promise<{
+        org: LockedOrg;
+        role: OrgRole;
+    }>;
+    /**
+     * {@link lockAndAuthorize} for an account; for the kernel itself (`null`: a job acting for no
+     * person, such as the plugin scope sync) only the lock, since no role applies.
+     */
+    lockFor(orgId: string, actor: string | null, action: OrgAction): Promise<void>;
+}
+/** The one {@link OrgLock}: identity (service tokens), orgs and the other domains import it. */
+export declare class OrgLockModule {
+}