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

package/dist/orgs/directory-sync.js

@@ -1,18 +1,41 @@
+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 { randomUUID } from "node:crypto";
 import { DIRECTORY_EXTENSION_POINT, } from "@capybara-hq/plugin-sdk";
+import { getQueueToken } from "@nestjs/bullmq";
+import { Inject, Injectable } from "@nestjs/common";
 import { ApiError } from "../errors.js";
+import { EffectiveConfigs } from "../extensions/effective-config.js";
 import { enabledExtensionsByOrg } from "../extensions/enabled.js";
+import { OrgExtensionConfigs } from "../extensions/org-config.js";
+import { ExtensionRegistry } from "../extensions/registry.js";
 import { audit } from "../identity/audit.js";
-import { ConversationLock } from "../runtime/conversation-lock.js";
-import { lockOrgAndAuthorize, tryLockOrg } from "./org-lock.js";
-/** 每小时扫描：维护队列任务名、job scheduler id（不含 `:`）与周期。 */
+import { ExternalIdentities } from "../identity/external.js";
+import { afterCommit } from "../infra/database/after-commit.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 { MAINTENANCE_QUEUE_NAME } from "../runtime/maintenance-queue.js";
+import { Offboarding } from "./offboarding.js";
+import { OrgLock } from "./org-lock.js";
+/** The hourly scan: cron job name (no `:`). */
 export const DIRECTORY_SCAN_JOB = "directory-scan";
-export const DIRECTORY_SCAN_SCHEDULER_ID = "directory-scan-hourly";
-export const DIRECTORY_SCAN_EVERY_MS = 3_600_000;
-/** 一次 (组织, 插件) 同步的维护任务名。 */
+/** The job name of one (org, extension) sync on the maintenance queue. */
 export const DIRECTORY_SYNC_JOB = "directory-sync";
-/** 同步锁的 Redis 键前缀（键为 `<前缀><orgId>:<plugin>`，带 TTL、持有期间续租）。 */
-export const DIRECTORY_SYNC_LOCK_PREFIX = "capk:directory-sync:";
+/** The run lock's TTL (renewed while held); a crashed holder's lock expires within it. */
+export const DIRECTORY_SYNC_LOCK_TTL_MS = 30_000;
+/** The `LockService` key of one (org, extension) sync: one sync at a time. */
+export const directorySyncLockKey = (orgId, plugin) => `directory-sync:${orgId}:${plugin}`;
 /** 脏标记的保留时长（秒）：锁被占时记下，持有者跑完后取走并补一轮。 */
 export const DIRECTORY_SYNC_DIRTY_TTL_SECONDS = 3_600;
 /** 脏标记（Redis 键）：同步进行中又有同步请求被锁挡掉。 */
@@ -58,6 +81,8 @@ export function directorySyncJobId(orgId, plugin, trigger, now = new Date()) {
             return `${base}-manual-${randomUUID()}`;
     }
 }
+/** Skips that log nothing and enqueue nothing: Ruling A28 and an org needing configuration. */
+const silentSkip = (reason) => reason === "not_configured" || reason === "needs_config";
 /** 组织已删除（同步途中）：停止本轮。 */
 class OrgGone extends Error {
 }
@@ -66,10 +91,14 @@ class OrgGone extends Error {
  *
  * - 维护队列每小时 `directory-scan`：给每个「插件提供 `directory@1`、在该组织启用、组织级配置满足 schema」的
  *   (组织, 插件) 投递一次同步（job id 按小时桶去重，多副本重复扫描只跑一次）；手动与 `directory_changed` 也投递同步。
- * - 同一 (组织, 插件) 同时只跑一个同步（Redis 锁 `capk:directory-sync:<org>:<plugin>`，持有期间续租）；
- *   锁被占时本任务记下脏标记 `capk:directory-sync-dirty:<org>:<plugin>`（1 小时）后结束；持有者释放锁后 GETDEL
- *   取走标记，有就投递一次 changed 同步（在跑的那一轮可能已经读过变化之前的页）。Ruling A32：移除阶段前 GET
- *   （不取走）脏标记，有就本轮按不完整处理、不移除任何人（审计 `partialReason = changed_during_sync`），移除留给补跑。
+ * - One sync at a time per (org, extension): the `LockService` lock
+ *   `lock:directory-sync:<org>:<plugin>`, renewed while held. A sync that finds the lock taken sets
+ *   the dirty flag `capk:directory-sync-dirty:<org>:<plugin>` (1 hour) and ends; after releasing
+ *   the lock the holder takes the flag with GETDEL and, if it was set, enqueues one `changed` sync
+ *   (the running round may have read pages from before the change). Ruling A32: before the removal
+ *   phase the holder GETs the flag (without taking it); if it is set, the round counts as
+ *   incomplete and removes nobody (audit `partialReason = changed_during_sync`), leaving removals
+ *   to the follow-up sync.
  *   After writing the flag, a blocked sync tries the lock once more: when the holder finished in
  *   between (and its GETDEL found no flag), this sync clears the flag and runs itself.
  * - Ruling A17：非手动触发的一轮，计划移除数超过 `max(5, 20% × 现有通讯录成员数)`，或列表里没有在职成员而已有
@@ -86,51 +115,65 @@ class OrgGone extends Error {
  *   能力）时，扫描、`directory_changed` 与执行时的复核都静默跳过（不投递、不审计、不记警告），手动触发 409
  *   `directory.not_configured`。
  * - 审计 `org.directory.synced`（计数、是否不完整）。任务执行时再核对插件与配置：已停用的插件的陈旧任务什么都不做。
+ *
+ * The hourly scan is {@link DirectoryScanJob} (a `@LockedCron`); one-off syncs are jobs on the maintenance queue (same name and
+ * job ids as before), consumed by `MaintenanceProcessor`.
  */
-export class DirectorySync {
-    d;
-    lock;
-    constructor(d) {
-        this.d = d;
-        this.lock = new ConversationLock(d.redis, d.log, DIRECTORY_SYNC_LOCK_PREFIX);
-        const m = d.maintenance;
-        if (m) {
-            m.schedule({
-                id: DIRECTORY_SCAN_SCHEDULER_ID,
-                name: DIRECTORY_SCAN_JOB,
-                everyMs: () => DIRECTORY_SCAN_EVERY_MS,
-            });
-            m.handle(DIRECTORY_SCAN_JOB, async () => {
-                const targets = await this.scan();
-                if (targets.length > 0)
-                    d.log.info("directory syncs enqueued", { count: targets.length });
-            });
-            m.handle(DIRECTORY_SYNC_JOB, async (job) => {
-                const data = job.data;
-                const r = await this.sync(data.orgId, data.plugin, data);
-                // 通讯录未配置（Ruling A28）静默跳过
-                if (r.status === "skipped" && r.reason !== "not_configured") {
-                    d.log.info("directory sync skipped", {
-                        orgId: data.orgId,
-                        plugin: data.plugin,
-                        reason: r.reason,
-                    });
-                }
+let DirectorySync = class DirectorySync {
+    db;
+    txHost;
+    redis;
+    registry;
+    orgConfigs;
+    effective;
+    external;
+    offboarding;
+    orgLock;
+    queue;
+    lockService;
+    log;
+    constructor(db, txHost, redis, registry, orgConfigs, effective, external, offboarding, orgLock, queue, lockService, log) {
+        this.db = db;
+        this.txHost = txHost;
+        this.redis = redis;
+        this.registry = registry;
+        this.orgConfigs = orgConfigs;
+        this.effective = effective;
+        this.external = external;
+        this.offboarding = offboarding;
+        this.orgLock = orgLock;
+        this.queue = queue;
+        this.lockService = lockService;
+        this.log = log;
+    }
+    /** A `directory-sync` job (dispatched by `MaintenanceProcessor`). */
+    async runSyncJob(data) {
+        const r = await this.sync(data.orgId, data.plugin, data);
+        // 通讯录未配置（Ruling A28）and an org needing configuration (spec A §6) are skipped silently
+        if (r.status === "skipped" && !silentSkip(r.reason)) {
+            this.log.info("directory sync skipped", {
+                orgId: data.orgId,
+                plugin: data.plugin,
+                reason: r.reason,
             });
         }
     }
     /** 插件提供的 `directory@1`；未加载或不提供时 undefined。 */
     provider(plugin) {
-        return this.d.host
+        return this.registry
             .list("directory")
             .find((e) => e.plugin === plugin && e.capability === DIRECTORY_EXTENSION_POINT)?.impl;
     }
-    /** The org exists, the extension provides a directory, is enabled in the org and its org config satisfies the schema (reuses the `OrgExtensionConfigs.get` validation). */
+    /**
+     * The org exists, the extension provides a directory, is enabled in the org, its org config
+     * satisfies the schema (reuses the `OrgExtensionConfigs.get` validation) and its effective
+     * deployment config for the org is valid (layering spec A §6).
+     */
     async eligible(orgId, plugin) {
         const directory = this.provider(plugin);
         if (!directory)
             return { ok: false, reason: "plugin_unavailable" };
-        const org = await this.d.db
+        const org = await this.db
             .selectFrom("orgs")
             .select("id")
             .where("id", "=", orgId)
@@ -140,10 +183,10 @@ export class DirectorySync {
             return { ok: false, reason: "org_not_found" };
         let cfg;
         try {
-            cfg = await this.d.orgExtensionConfigs.get(orgId, plugin);
+            cfg = await this.orgConfigs.get(orgId, plugin);
         }
         catch (err) {
-            this.d.log.warn("directory sync: stored organization config is invalid", {
+            this.log.warn("directory sync: stored organization config is invalid", {
                 orgId,
                 plugin,
                 err,
@@ -152,11 +195,21 @@ export class DirectorySync {
         }
         if (!cfg?.enabled)
             return { ok: false, reason: "not_enabled" };
+        let effective;
+        try {
+            effective = await this.effective.get(orgId, plugin);
+        }
+        catch (err) {
+            this.log.warn("directory sync: cannot read the effective config", { orgId, plugin, err });
+            return { ok: false, reason: "config_invalid" };
+        }
+        if (!effective.ok)
+            return { ok: false, reason: "needs_config" };
         // Ruling A28：插件说通讯录没配好（组织只用它的别的能力）→ 不同步；插件实现出错按未配置处理
         if (directory.configured !== undefined) {
             let configured = false;
             try {
-                configured = directory.configured(cfg.config) === true;
+                configured = directory.configured(cfg.config, effective.config) === true;
             }
             catch {
                 configured = false;
@@ -164,23 +217,20 @@ export class DirectorySync {
             if (!configured)
                 return { ok: false, reason: "not_configured" };
         }
-        return { ok: true, directory, orgConfig: cfg.config };
+        return { ok: true, directory, orgConfig: cfg.config, config: effective.config };
     }
     /**
      * 投递一次 `directory_changed` 同步（按分钟桶去重）；返回 job id。入站 `directory_changed` 经
-     * {@link DirectorySyncScheduler} 调用这里。通讯录未配置（`Directory.configured` 返回 false，Ruling A28）时
+     * `ChannelInbound`（`directory_changed`）调用这里。通讯录未配置（`Directory.configured` 返回 false，Ruling A28）时
      * 静默不投递，返回 undefined；其他不可同步的情况照常投递，由任务执行时跳过。
      */
     async enqueue(orgId, plugin, now = new Date()) {
         const e = await this.eligible(orgId, plugin);
-        if (!e.ok && e.reason === "not_configured")
+        if (!e.ok && silentSkip(e.reason))
             return undefined;
         return this.addJob(orgId, plugin, "changed", directorySyncJobId(orgId, plugin, "changed", now));
     }
     async addJob(orgId, plugin, trigger, jobId, requestedBy) {
-        const m = this.d.maintenance;
-        if (!m)
-            throw new Error("directory sync: maintenance queue is not available");
         if (jobId.includes(":"))
             throw new Error("directory sync: job id must not contain ':'");
         const data = {
@@ -190,8 +240,10 @@ export class DirectorySync {
             ...(requestedBy !== undefined && { requestedBy: requestedBy.accountId }),
             ...(requestedBy?.tokenId !== undefined && { requestedByToken: requestedBy.tokenId }),
         };
-        await m.add(DIRECTORY_SYNC_JOB, data, {
+        await this.queue.add(DIRECTORY_SYNC_JOB, data, {
             jobId,
+            // the maintenance queue's jobs run once (no retry), as before
+            attempts: 1,
             removeOnComplete: { age: KEEP_COMPLETED_SECONDS[trigger] },
             removeOnFail: KEEP_FAILED,
         });
@@ -201,13 +253,12 @@ export class DirectorySync {
      * Manual trigger by an admin: re-checks `org.members.manage` live under the org row lock, then that
      * the extension can sync (does not provide a directory -> `extension.not_found`, not enabled ->
      * `extension.not_enabled`, config no longer valid -> `extension.config_invalid`, the extension says
-     * the directory is not configured -> `directory.not_configured`, Ruling A28), and enqueues a sync
+     * the directory is not configured -> `directory.not_configured`, Ruling A28; the effective config
+     * is not valid in the org -> `extension.needs_config`, layering spec A §6), and enqueues a sync
      * job with a unique id.
      */
     async request(orgId, plugin, actorAccountId, actorTokenId) {
-        await this.d.db
-            .transaction()
-            .execute((t) => lockOrgAndAuthorize(t, orgId, actorAccountId, "org.members.manage"));
+        await this.authorize(orgId, actorAccountId);
         const e = await this.eligible(orgId, plugin);
         if (!e.ok) {
             switch (e.reason) {
@@ -221,24 +272,29 @@ export class DirectorySync {
                     throw new ApiError("extension.config_invalid", `Invalid organization config for extension ${plugin}`);
                 case "not_configured":
                     throw new ApiError("directory.not_configured", `The directory of extension ${plugin} is not configured for this organization`);
+                case "needs_config":
+                    throw new ApiError("extension.needs_config", `Extension ${plugin} needs configuration in this organization`);
             }
         }
         const jobId = await this.addJob(orgId, plugin, "manual", directorySyncJobId(orgId, plugin, "manual"), { accountId: actorAccountId, tokenId: actorTokenId });
         return { jobId };
     }
+    async authorize(orgId, actorAccountId) {
+        await this.orgLock.lockAndAuthorize(orgId, actorAccountId, "org.members.manage");
+    }
     /**
      * 每小时扫描：给每个可同步的 (组织, 插件) 投递一次同步（job id 按小时桶），返回投递的目标。
      * 已存配置不再满足 schema 的跳过（记 warn）；单个投递失败记 warn、继续其他目标。
      */
     async scan(now = new Date()) {
-        const plugins = this.d.host
+        const plugins = this.registry
             .list("directory")
             .filter((e) => e.capability === DIRECTORY_EXTENSION_POINT)
             .map((e) => e.plugin);
         if (plugins.length === 0)
             return [];
-        const rows = await this.d.db
-            .selectFrom(enabledExtensionsByOrg(this.d.db).as("en"))
+        const rows = await this.db
+            .selectFrom(enabledExtensionsByOrg(this.db.db).as("en"))
             .innerJoin("orgs", "orgs.id", "en.org_id")
             .select(["en.org_id", "en.plugin"])
             .where("orgs.deleted_at", "is", null)
@@ -256,7 +312,7 @@ export class DirectorySync {
                 out.push({ orgId: r.org_id, plugin: r.plugin, jobId });
             }
             catch (err) {
-                this.d.log.warn("cannot enqueue directory sync", {
+                this.log.warn("cannot enqueue directory sync", {
                     orgId: r.org_id,
                     plugin: r.plugin,
                     err,
@@ -271,26 +327,26 @@ export class DirectorySync {
         if (!e.ok)
             return { status: "skipped", reason: e.reason };
         const dirtyKey = directorySyncDirtyKey(orgId, plugin);
-        const lockKey = `${orgId}:${plugin}`;
-        let lease = await this.lock.acquire(lockKey, randomUUID());
+        const lockKey = directorySyncLockKey(orgId, plugin);
+        const lockOpts = { ttlMs: DIRECTORY_SYNC_LOCK_TTL_MS };
+        let lease = await this.lockService.acquire(lockKey, lockOpts);
         if (!lease) {
             // 在跑的那一轮可能已经读过变化之前的页：记下脏标记，由持有者跑完后补一轮
-            await this.d.redis.set(dirtyKey, "1", "EX", DIRECTORY_SYNC_DIRTY_TTL_SECONDS);
+            await this.redis.set(dirtyKey, "1", "EX", DIRECTORY_SYNC_DIRTY_TTL_SECONDS);
             // The holder may have released the lock and taken the flag (GETDEL) between the failed
             // attempt and the write above: the flag would then wait an hour with nobody to rerun, and
             // the next sync would skip its removals. Try the lock once more after the write: if it is
             // still held, its holder takes the flag after releasing; if not, run this sync now.
-            lease = await this.lock.acquire(lockKey, randomUUID());
+            lease = await this.lockService.acquire(lockKey, lockOpts);
             if (!lease)
                 return { status: "skipped", reason: "locked" };
             // No page has been read yet, so this run covers every change flagged so far.
-            await this.d.redis.del(dirtyKey);
+            await this.redis.del(dirtyKey);
         }
-        const abort = new AbortController();
         // 锁丢了（续租失败、过期后被他人取得）：停止本轮，不再移除任何人
-        lease.onLost(() => abort.abort(new Error("directory sync lock lost")));
+        const signal = lease.lost;
         try {
-            return await this.run(orgId, plugin, e.directory, e.orgConfig, abort.signal, opts);
+            return await this.run(orgId, plugin, e.directory, e.orgConfig, e.config, signal, opts);
         }
         finally {
             await lease.release().catch(() => { });
@@ -303,16 +359,16 @@ export class DirectorySync {
      */
     async rerunIfDirty(orgId, plugin, dirtyKey) {
         try {
-            if ((await this.d.redis.getdel(dirtyKey)) === null)
+            if ((await this.redis.getdel(dirtyKey)) === null)
                 return;
             const jobId = `directory-sync-${orgId}-${plugin}-rerun-${randomUUID()}`;
             await this.addJob(orgId, plugin, "changed", jobId);
         }
         catch (err) {
-            this.d.log.warn("directory sync: cannot enqueue follow-up sync", { orgId, plugin, err });
+            this.log.warn("directory sync: cannot enqueue follow-up sync", { orgId, plugin, err });
         }
     }
-    async run(orgId, plugin, directory, orgConfig, signal, opts) {
+    async run(orgId, plugin, directory, orgConfig, config, signal, opts) {
         const source = `directory:${plugin}`;
         const counts = { added: 0, removed: 0, skippedLastOwner: 0, failed: 0, total: 0 };
         /** 本轮仍在职的账号（只在本次任务内使用）。 */
@@ -329,6 +385,7 @@ export class DirectorySync {
                 signal.throwIfAborted();
                 const r = await directory.listMembers({
                     orgConfig,
+                    config,
                     ...(cursor !== undefined && { cursor }),
                     signal: AbortSignal.any([signal, AbortSignal.timeout(DIRECTORY_PAGE_TIMEOUT_MS)]),
                 });
@@ -351,7 +408,7 @@ export class DirectorySync {
                         if (err instanceof OrgGone)
                             throw err;
                         counts.failed++;
-                        this.d.log.warn("directory sync: cannot add member", { orgId, plugin, err });
+                        this.log.warn("directory sync: cannot add member", { orgId, plugin, err });
                     }
                 }
                 const next = r.next;
@@ -364,7 +421,7 @@ export class DirectorySync {
             listed = true;
         }
         catch (err) {
-            this.d.log.warn("directory sync stopped before listing all members", { orgId, plugin, err });
+            this.log.warn("directory sync stopped before listing all members", { orgId, plugin, err });
         }
         const trigger = opts.trigger ?? "manual";
         let partial = !listed || counts.failed > 0;
@@ -375,8 +432,8 @@ export class DirectorySync {
             if (!still.ok) {
                 partial = true;
                 // 途中通讯录配置被清空（Ruling A28）：照样不移除，但不记警告
-                if (still.reason !== "not_configured") {
-                    this.d.log.warn("directory sync: plugin no longer eligible before removals", {
+                if (!silentSkip(still.reason)) {
+                    this.log.warn("directory sync: plugin no longer eligible before removals", {
                         orgId,
                         plugin,
                         reason: still.reason,
@@ -390,10 +447,10 @@ export class DirectorySync {
         if (!partial) {
             let dirty;
             try {
-                dirty = await this.d.redis.get(directorySyncDirtyKey(orgId, plugin));
+                dirty = await this.redis.get(directorySyncDirtyKey(orgId, plugin));
             }
             catch (err) {
-                this.d.log.warn("directory sync: cannot read the dirty flag; skipping removals", {
+                this.log.warn("directory sync: cannot read the dirty flag; skipping removals", {
                     orgId,
                     plugin,
                     err,
@@ -406,7 +463,7 @@ export class DirectorySync {
             }
         }
         if (!partial) {
-            const existing = await this.d.db
+            const existing = await this.db
                 .selectFrom("memberships")
                 .select("account_id")
                 .where("org_id", "=", orgId)
@@ -420,13 +477,13 @@ export class DirectorySync {
                 (planned.length > threshold || (active === 0 && existing.length > 0))) {
                 partial = true;
                 removalBlocked = true;
-                this.d.log.warn("directory sync: mass removal blocked", {
+                this.log.warn("directory sync: mass removal blocked", {
                     orgId,
                     plugin,
                     planned: planned.length,
                     existing: existing.length,
                 });
-                await audit(this.d.db, {
+                await audit(this.db.db, {
                     orgId,
                     action: "org.directory.removal_blocked",
                     target: plugin,
@@ -454,7 +511,7 @@ export class DirectorySync {
                     counts.failed++;
             }
         }
-        await audit(this.d.db, {
+        await audit(this.db.db, {
             ...(opts.requestedBy !== undefined && { actorAccountId: opts.requestedBy }),
             ...(opts.requestedByToken !== undefined && { actorTokenId: opts.requestedByToken }),
             orgId,
@@ -492,35 +549,37 @@ export class DirectorySync {
             emailVerified: m.emailVerified === true,
             displayName: m.displayName,
         };
-        return this.d.db.transaction().execute(async (t) => {
-            if (!(await tryLockOrg(t, orgId)))
-                throw new OrgGone("organization deleted during sync");
-            const { accountId } = await this.d.external.resolve(identity, t, { linkedVia: "directory" });
-            const excluded = await t
-                .selectFrom("directory_exclusions")
-                .select("account_id")
-                .where("org_id", "=", orgId)
-                .where("account_id", "=", accountId)
-                .where("plugin", "=", plugin)
-                .executeTakeFirst();
-            if (excluded)
-                return { accountId, added: false };
-            const inserted = await t
-                .insertInto("memberships")
-                .values({ org_id: orgId, account_id: accountId, role: "member", source })
-                .onConflict((oc) => oc.columns(["org_id", "account_id"]).doNothing())
-                .returning("account_id")
-                .executeTakeFirst();
-            if (inserted) {
-                await audit(t, {
-                    orgId,
-                    action: "org.member.added",
-                    target: accountId,
-                    detail: { role: "member", source },
-                });
-            }
-            return { accountId, added: inserted !== undefined };
-        });
+        return this.addMemberIn(orgId, plugin, source, identity);
+    }
+    /** One short transaction per member, under the org row lock. */
+    async addMemberIn(orgId, plugin, source, identity) {
+        if (!(await this.orgLock.tryLock(orgId)))
+            throw new OrgGone("organization deleted during sync");
+        const { accountId } = await this.external.resolve(identity, { linkedVia: "directory" });
+        const excluded = await this.db
+            .selectFrom("directory_exclusions")
+            .select("account_id")
+            .where("org_id", "=", orgId)
+            .where("account_id", "=", accountId)
+            .where("plugin", "=", plugin)
+            .executeTakeFirst();
+        if (excluded)
+            return { accountId, added: false };
+        const inserted = await this.db
+            .insertInto("memberships")
+            .values({ org_id: orgId, account_id: accountId, role: "member", source })
+            .onConflict((oc) => oc.columns(["org_id", "account_id"]).doNothing())
+            .returning("account_id")
+            .executeTakeFirst();
+        if (inserted) {
+            await audit(this.db.db, {
+                orgId,
+                action: "org.member.added",
+                target: accountId,
+                detail: { role: "member", source },
+            });
+        }
+        return { accountId, added: inserted !== undefined };
     }
     /**
      * 一个离职者：独立事务内先锁组织行、再锁其成员关系行（与 `switchCurrentOrg` / 移出成员同一顺序），
@@ -529,30 +588,82 @@ export class DirectorySync {
      */
     async offboardOne(orgId, plugin, source, accountId) {
         try {
-            const result = await this.d.db.transaction().execute(async (t) => {
-                if (!(await tryLockOrg(t, orgId)))
-                    return undefined;
-                const row = await t
-                    .selectFrom("memberships")
-                    .select("source")
-                    .where("org_id", "=", orgId)
-                    .where("account_id", "=", accountId)
-                    .forUpdate()
-                    .executeTakeFirst();
-                if (row?.source !== source)
-                    return undefined;
-                return this.d.offboarding.offboard(t, orgId, accountId, "directory");
-            });
-            if (!result)
-                return "gone";
-            await this.d.offboarding.afterCommit(result);
-            return "removed";
+            const result = await this.offboardIn(orgId, source, accountId);
+            return result ? "removed" : "gone";
         }
         catch (err) {
             if (err instanceof ApiError && err.code === "org.last_owner")
                 return "last_owner";
-            this.d.log.warn("directory sync: cannot offboard member", { orgId, plugin, accountId, err });
+            this.log.warn("directory sync: cannot offboard member", { orgId, plugin, accountId, err });
             return "failed";
         }
     }
-}
+    async offboardIn(orgId, source, accountId) {
+        if (!(await this.orgLock.tryLock(orgId)))
+            return undefined;
+        const row = await this.db
+            .selectFrom("memberships")
+            .select("source")
+            .where("org_id", "=", orgId)
+            .where("account_id", "=", accountId)
+            .forUpdate()
+            .executeTakeFirst();
+        if (row?.source !== source)
+            return undefined;
+        const result = await this.offboarding.offboard(orgId, accountId, "directory");
+        // the markers, events and run stops follow the root commit (none after a rollback)
+        afterCommit(() => this.offboarding.afterOffboard(result));
+        return result;
+    }
+};
+__decorate([
+    Transactional()
+], DirectorySync.prototype, "authorize", null);
+__decorate([
+    Transactional()
+], DirectorySync.prototype, "addMemberIn", null);
+__decorate([
+    Transactional()
+], DirectorySync.prototype, "offboardIn", null);
+DirectorySync = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(TransactionHost)),
+    __param(2, Inject(REDIS)),
+    __param(3, Inject(ExtensionRegistry)),
+    __param(4, Inject(OrgExtensionConfigs)),
+    __param(5, Inject(EffectiveConfigs)),
+    __param(6, Inject(ExternalIdentities)),
+    __param(7, Inject(Offboarding)),
+    __param(8, Inject(OrgLock)),
+    __param(9, Inject(getQueueToken(MAINTENANCE_QUEUE_NAME))),
+    __param(10, Inject(LockService)),
+    __param(11, Inject(KERNEL_LOGGER))
+], DirectorySync);
+export { DirectorySync };
+/** The hourly directory scan ({@link DirectorySync.scan}), once per tick across replicas; a worker-role job (`WorkerModule`). */
+let DirectoryScanJob = class DirectoryScanJob {
+    directory;
+    lockService;
+    log;
+    constructor(directory, lockService, log) {
+        this.directory = directory;
+        this.lockService = lockService;
+        this.log = log;
+    }
+    async run() {
+        const targets = await this.directory.scan();
+        if (targets.length > 0)
+            this.log.info("directory syncs enqueued", { count: targets.length });
+    }
+};
+__decorate([
+    LockedCron("0 * * * *", { name: DIRECTORY_SCAN_JOB })
+], DirectoryScanJob.prototype, "run", null);
+DirectoryScanJob = __decorate([
+    Injectable(),
+    __param(0, Inject(DirectorySync)),
+    __param(1, Inject(LockService)),
+    __param(2, Inject(KERNEL_LOGGER))
+], DirectoryScanJob);
+export { DirectoryScanJob };

package/dist/orgs/invitations.controller.d.ts

@@ -1,14 +1,14 @@
 import type { FastifyReply, FastifyRequest } from "fastify";
 import { z } from "zod";
-import type { KernelConfig } from "../config/schema.js";
 import type { Account } from "../identity/accounts.js";
 import { type Principal } from "../identity/principal.js";
-import type { LoginRateLimiter } from "../identity/rate-limit.js";
-import type { SessionService } from "../identity/sessions.js";
-import { type InvitableRole, type Invitation, type InvitationStatus, type InvitationsService } from "./invitations.service.js";
+import { SessionService } from "../identity/sessions.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { CredentialThrottler } from "../infra/throttler/credential-throttler.js";
+import { type InvitableRole, type Invitation, type InvitationStatus, InvitationsService } from "./invitations.service.js";
 import { type OrgContext } from "./org.guard.js";
 import type { OrgRole } from "./roles.js";
-declare const CreateBody: z.ZodObject<{
+declare const CreateSchema: z.ZodObject<{
     role: z.ZodEnum<{
         admin: "admin";
         guest: "guest";
@@ -21,10 +21,10 @@ export declare class InvitationsController {
     private readonly invitations;
     private readonly sessions;
     private readonly config;
-    private readonly limiter;
-    constructor(invitations: InvitationsService, sessions: SessionService, config: () => KernelConfig, limiter: LoginRateLimiter);
+    private readonly throttler;
+    constructor(invitations: InvitationsService, sessions: SessionService, config: KernelConfigService, throttler: CredentialThrottler);
     /** 令牌只在此返回一次。 */
-    create(principal: Principal, org: OrgContext, body: z.infer<typeof CreateBody>): Promise<{
+    create(principal: Principal, org: OrgContext, body: z.infer<typeof CreateSchema>): Promise<{
         invitation: Invitation;
         token: string;
     }>;