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

package/dist/models/purposes.d.ts

@@ -1,9 +1,13 @@
-import { type ContentBlock, type ExtensionManifest, type ModelRequest, type ModelUsage, type ParamValue, type StopReason } from "@capybara-hq/plugin-sdk";
+import { type ContentBlock, type ModelRequest, type ModelUsage, type ParamValue, type StopReason } from "@capybara-hq/plugin-sdk";
 import { z } from "zod";
 import { ModelRef } from "../agents/definition.js";
-import type { KernelConfig } from "../config/schema.js";
-import type { KernelDb } from "../db/kernel-schema.js";
-import { type ProviderRegistry } from "../runtime/providers.js";
+import { ExtensionRegistry } from "../extensions/registry.js";
+import { EnterpriseAdminLock } from "../identity/enterprise-admin.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { OrgLock } from "../orgs/org-lock.js";
+import { ProviderRegistry } from "../runtime/providers.js";
 /**
  * 模型用途映射（C9）：内核与插件按「用途」取模型，不在代码里写死模型。
  * - 用途 = 内核用途 {@link KERNEL_PURPOSES}（目前只有评委 `eval`），或已加载插件 `permissions.models` 声明的；
@@ -82,6 +86,18 @@ export declare const PURPOSE_PUT: z.ZodObject<{
     }, z.core.$strict>>;
 }, z.core.$strict>;
 export type PurposePut = z.infer<typeof PURPOSE_PUT>;
+declare const PurposePutDto_base: import("../infra/validation/create-zod-dto.js").ZodDtoClass<z.ZodObject<{
+    target: z.ZodNullable<z.ZodObject<{
+        model: z.ZodObject<{
+            provider: z.ZodString;
+            model: z.ZodString;
+        }, z.core.$strict>;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>>;
+/** {@link PURPOSE_PUT} as a DTO (`@ZBody(PurposePutDto)`). */
+export declare class PurposePutDto extends PurposePutDto_base {
+}
 /**
  * 用途请求已经发出、但没有正常收完（出错、超时、中止）：`tokens` 是应计入预算的估算用量（输入估算 + 已流出字符 / 4，
  * 与评测回放一致），`cause` 是原始错误。请求发出之前的失败（未映射、模型不可用）原样抛出。
@@ -93,16 +109,19 @@ export declare class PurposeAttemptError extends Error {
     readonly model: string;
     constructor(cause: unknown, tokens: number, provider: string, model: string);
 }
-export interface ModelPurposesDeps {
-    db: KernelDb;
-    registry: Pick<ProviderRegistry, "resolve">;
-    config: () => KernelConfig;
-    /** 已加载插件的清单（取 `permissions.models`）。 */
-    manifests: () => readonly ExtensionManifest[];
-}
+/**
+ * The model purposes (one provider). Extension-declared purposes come from the manifests in the
+ * {@link ExtensionRegistry}; targets resolve through the model provider registry.
+ */
 export declare class ModelPurposesService {
-    private readonly d;
-    constructor(d: ModelPurposesDeps);
+    private readonly db;
+    private readonly extensions;
+    private readonly config;
+    private readonly providers;
+    readonly txHost: TransactionHost;
+    private readonly adminLock;
+    private readonly orgLock;
+    constructor(db: KernelDb, extensions: ExtensionRegistry, config: KernelConfigService, providers: Pick<ProviderRegistry, "resolve">, txHost: TransactionHost, adminLock: EnterpriseAdminLock, orgLock: OrgLock);
     /** 全部已声明的用途：内核的在前，其后按插件加载顺序。 */
     private declared;
     private find;
@@ -113,6 +132,8 @@ export declare class ModelPurposesService {
     /** 校验目标：模型可解析（部署范围）、参数按它的声明严格通过。 */
     private check;
     private set;
+    /** The mapping write of {@link set}, under the enterprise admin or org lock. */
+    private write;
     /** 设置（或 `null` 清除）部署默认；只有企业管理员（事务内复核）。 */
     setDefault(purpose: string, target: PurposeTarget | null, actor: string, actorTokenId?: string): Promise<PurposeView>;
     /** 设置（或 `null` 清除）组织覆盖；事务内锁组织并复核 `org.models.manage`。 */
@@ -138,3 +159,4 @@ export declare class ModelPurposesService {
         model: string;
     }>;
 }
+export {};

package/dist/models/purposes.js

@@ -1,14 +1,29 @@
+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 { sanitizeParams, } from "@capybara-hq/plugin-sdk";
+import { Inject, Injectable } from "@nestjs/common";
 import { z } from "zod";
-import { paramIssues } from "../agents/agents.service.js";
-import { ModelRef } from "../agents/definition.js";
+import { ModelRef, paramIssues } from "../agents/definition.js";
 import { ApiError } from "../errors.js";
+import { ExtensionRegistry } from "../extensions/registry.js";
 import { audit } from "../identity/audit.js";
-import { lockEnterpriseAdminsAndAuthorize } from "../identity/enterprise-admin.js";
-import { lockOrgAndAuthorize } from "../orgs/org-lock.js";
+import { EnterpriseAdminLock } from "../identity/enterprise-admin.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.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 { createZodDto } from "../infra/validation/create-zod-dto.js";
+import { OrgLock } from "../orgs/org-lock.js";
 import { estimateTokens } from "../runtime/context/tokens.js";
 import { consumeModelStream } from "../runtime/model-call.js";
-import { ProviderListError } from "../runtime/providers.js";
+import { ProviderListError, ProviderRegistry } from "../runtime/providers.js";
 /**
  * 模型用途映射（C9）：内核与插件按「用途」取模型，不在代码里写死模型。
  * - 用途 = 内核用途 {@link KERNEL_PURPOSES}（目前只有评委 `eval`），或已加载插件 `permissions.models` 声明的；
@@ -54,6 +69,9 @@ export const PURPOSE_PUT = z
         .nullable(),
 })
     .strict();
+/** {@link PURPOSE_PUT} as a DTO (`@ZBody(PurposePutDto)`). */
+export class PurposePutDto extends createZodDto(PURPOSE_PUT, "ModelPurposePut") {
+}
 /**
  * 用途请求已经发出、但没有正常收完（出错、超时、中止）：`tokens` 是应计入预算的估算用量（输入估算 + 已流出字符 / 4，
  * 与评测回放一致），`cause` 是原始错误。请求发出之前的失败（未映射、模型不可用）原样抛出。
@@ -80,10 +98,26 @@ const targetOf = (r) => r === undefined
         model: { provider: r.provider, model: r.model },
         params: (r.params ?? {}),
     };
-export class ModelPurposesService {
-    d;
-    constructor(d) {
-        this.d = d;
+/**
+ * The model purposes (one provider). Extension-declared purposes come from the manifests in the
+ * {@link ExtensionRegistry}; targets resolve through the model provider registry.
+ */
+let ModelPurposesService = class ModelPurposesService {
+    db;
+    extensions;
+    config;
+    providers;
+    txHost;
+    adminLock;
+    orgLock;
+    constructor(db, extensions, config, providers, txHost, adminLock, orgLock) {
+        this.db = db;
+        this.extensions = extensions;
+        this.config = config;
+        this.providers = providers;
+        this.txHost = txHost;
+        this.adminLock = adminLock;
+        this.orgLock = orgLock;
     }
     /** 全部已声明的用途：内核的在前，其后按插件加载顺序。 */
     declared() {
@@ -94,7 +128,7 @@ export class ModelPurposesService {
             declaredBy: "kernel",
         }));
         const seen = new Set(out.map((p) => p.purpose));
-        for (const m of this.d.manifests()) {
+        for (const m of this.extensions.manifests()) {
             for (const p of m.permissions?.models ?? []) {
                 if (seen.has(p.purpose))
                     continue;
@@ -118,7 +152,7 @@ export class ModelPurposesService {
     async rows(purposes, orgId) {
         if (purposes.length === 0)
             return [];
-        return this.d.db
+        return this.db
             .selectFrom("model_purpose_mappings")
             .select(["org_id", "purpose", "provider", "model", "params"])
             .where("purpose", "in", purposes)
@@ -145,7 +179,7 @@ export class ModelPurposesService {
     async check(target) {
         let info;
         try {
-            ({ info } = await this.d.registry.resolve(target.model));
+            ({ info } = await this.providers.resolve(target.model));
         }
         catch (e) {
             if (e instanceof ProviderListError)
@@ -163,45 +197,47 @@ export class ModelPurposesService {
         const decl = this.find(purpose);
         if (target)
             await this.check(target);
-        await this.d.db.transaction().execute(async (trx) => {
-            if (orgId === null)
-                await lockEnterpriseAdminsAndAuthorize(trx, actor);
-            else
-                await lockOrgAndAuthorize(trx, orgId, actor, "org.models.manage");
-            if (target === null) {
-                await trx
-                    .deleteFrom("model_purpose_mappings")
-                    .where("purpose", "=", purpose)
-                    .where((eb) => (orgId === null ? eb("org_id", "is", null) : eb("org_id", "=", orgId)))
-                    .execute();
-            }
-            else {
-                const values = {
-                    provider: target.model.provider,
-                    model: target.model.model,
-                    params: JSON.stringify(target.params),
-                    updated_by: actor,
-                };
-                await trx
-                    .insertInto("model_purpose_mappings")
-                    .values({ org_id: orgId, purpose, ...values })
-                    .onConflict((oc) => oc
-                    .constraint("model_purpose_mappings_scope_key")
-                    .doUpdateSet({ ...values, updated_at: new Date() }))
-                    .execute();
-            }
-            await audit(trx, {
-                actorAccountId: actor,
-                ...(actorTokenId !== undefined && { actorTokenId }),
-                ...(orgId !== null && { orgId }),
-                action: "model.purpose_mapped",
-                target: purpose,
-                detail: { scope: orgId === null ? "deployment" : "org", target },
-            });
-        });
+        await this.write(orgId, purpose, target, actor, actorTokenId);
         const [view] = await this.views([decl], orgId ?? undefined);
         return view;
     }
+    /** The mapping write of {@link set}, under the enterprise admin or org lock. */
+    async write(orgId, purpose, target, actor, actorTokenId) {
+        if (orgId === null)
+            await this.adminLock.lockAndAuthorize(actor);
+        else
+            await this.orgLock.lockAndAuthorize(orgId, actor, "org.models.manage");
+        if (target === null) {
+            await this.db
+                .deleteFrom("model_purpose_mappings")
+                .where("purpose", "=", purpose)
+                .where((eb) => (orgId === null ? eb("org_id", "is", null) : eb("org_id", "=", orgId)))
+                .execute();
+        }
+        else {
+            const values = {
+                provider: target.model.provider,
+                model: target.model.model,
+                params: JSON.stringify(target.params),
+                updated_by: actor,
+            };
+            await this.db
+                .insertInto("model_purpose_mappings")
+                .values({ org_id: orgId, purpose, ...values })
+                .onConflict((oc) => oc
+                .constraint("model_purpose_mappings_scope_key")
+                .doUpdateSet({ ...values, updated_at: new Date() }))
+                .execute();
+        }
+        await audit(this.db.db, {
+            actorAccountId: actor,
+            ...(actorTokenId !== undefined && { actorTokenId }),
+            ...(orgId !== null && { orgId }),
+            action: "model.purpose_mapped",
+            target: purpose,
+            detail: { scope: orgId === null ? "deployment" : "org", target },
+        });
+    }
     /** 设置（或 `null` 清除）部署默认；只有企业管理员（事务内复核）。 */
     setDefault(purpose, target, actor, actorTokenId) {
         return this.set(null, purpose, target, actor, actorTokenId);
@@ -236,7 +272,7 @@ export class ModelPurposesService {
                 throw e;
             target = opts.fallback;
         }
-        const { provider, info } = await this.d.registry.resolve(target.model);
+        const { provider, info } = await this.providers.resolve(target.model);
         const request = {
             ...req,
             model: info.id,
@@ -244,7 +280,7 @@ export class ModelPurposesService {
             // 输出上限不超过目标模型自己的上限（与运行时 assembleModelRequest 一致）
             maxOutputTokens: Math.min(req.maxOutputTokens, info.maxOutputTokens),
         };
-        const idleMs = info.streamIdleTimeoutMs ?? this.d.config().runtime.streamIdleMs;
+        const idleMs = info.streamIdleTimeoutMs ?? this.config.get().runtime.streamIdleMs;
         await opts.beforeSend?.(target.model, request);
         let chars = 0;
         try {
@@ -264,4 +300,18 @@ export class ModelPurposesService {
             throw new PurposeAttemptError(err, tokens, target.model.provider, target.model.model);
         }
     }
-}
+};
+__decorate([
+    Transactional()
+], ModelPurposesService.prototype, "write", null);
+ModelPurposesService = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(ExtensionRegistry)),
+    __param(2, Inject(KernelConfigService)),
+    __param(3, Inject(ProviderRegistry)),
+    __param(4, Inject(TransactionHost)),
+    __param(5, Inject(EnterpriseAdminLock)),
+    __param(6, Inject(OrgLock))
+], ModelPurposesService);
+export { ModelPurposesService };

package/dist/net/public-address.js

@@ -6,8 +6,9 @@ import { BlockList, isIP } from "node:net";
  * checked addresses only (see `safe-fetch.ts`), so a DNS answer that changes between check and
  * connect (DNS rebinding, e.g. `10.0.0.1.nip.io`) cannot reach a private address.
  *
- * The blocked ranges are those of `plugins/sandbox-docker/egress-proxy/proxy.mjs`, ported here
- * because the kernel must not import from a plugin. IPv6 addresses that embed an IPv4 address
+ * The blocked ranges are those of the sandbox-docker plugin's egress proxy
+ * (`plugins/sandbox-docker/egress-proxy/proxy.mjs` in capybara-hq/plugins), ported here because the
+ * kernel must not import from a plugin. IPv6 addresses that embed an IPv4 address
  * (v4-mapped `::ffff:0:0/96`, v4-compatible `::/96`, NAT64 `64:ff9b::/96`, 6to4 `2002::/16`) are
  * judged by the embedded IPv4 address; anything unparseable is refused. One addition over proxy.mjs:
  * SIIT IPv4-translated addresses (`::ffff:0:a.b.c.d`, `::ffff:0:0:0/96`, RFC 2765) are also judged by

package/dist/orgs/directory-sync.controller.d.ts

@@ -1,5 +1,5 @@
 import { type Principal } from "../identity/principal.js";
-import type { DirectorySync } from "./directory-sync.js";
+import { DirectorySync } from "./directory-sync.js";
 import { type OrgContext } from "./org.guard.js";
 /**
  * Manual directory sync (`/api/v1/orgs/:orgId/extensions/:extension/directory/sync`): it adds and

package/dist/orgs/directory-sync.controller.js

@@ -8,8 +8,8 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
 import { Controller, HttpCode, Inject, Param, Post } from "@nestjs/common";
-import { DIRECTORY_SYNC } from "../http/tokens.js";
 import { CurrentPrincipal, patTokenId, requireUser, } from "../identity/principal.js";
+import { DirectorySync } from "./directory-sync.js";
 import { CurrentOrg, OrgAction } from "./org.guard.js";
 /**
  * Manual directory sync (`/api/v1/orgs/:orgId/extensions/:extension/directory/sync`): it adds and
@@ -35,6 +35,6 @@ __decorate([
 ], DirectorySyncController.prototype, "sync", null);
 DirectorySyncController = __decorate([
     Controller("api/v1/orgs/:orgId/extensions/:extension/directory"),
-    __param(0, Inject(DIRECTORY_SYNC))
+    __param(0, Inject(DirectorySync))
 ], DirectorySyncController);
 export { DirectorySyncController };

package/dist/orgs/directory-sync.d.ts

@@ -1,19 +1,22 @@
-import { type Logger } from "@capybara-hq/plugin-sdk";
+import type { Queue } from "bullmq";
 import type { Redis } from "ioredis";
-import type { KernelDb } from "../db/kernel-schema.js";
-import type { ExtensionHost } from "../extensions/host.js";
-import type { OrgExtensionConfigs } from "../extensions/org-config.js";
-import type { ExternalIdentities } from "../identity/external.js";
-import type { Maintenance } from "../runtime/maintenance.js";
-import type { Offboarding } from "./offboarding.js";
-/** 每小时扫描：维护队列任务名、job scheduler id（不含 `:`）与周期。 */
+import { OrgExtensionConfigs } from "../extensions/org-config.js";
+import { ExtensionRegistry } from "../extensions/registry.js";
+import { ExternalIdentities } from "../identity/external.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { LockService } from "../infra/lock/lock.service.js";
+import type { KernelLogger } from "../log.js";
+import { Offboarding } from "./offboarding.js";
+import { OrgLock } from "./org-lock.js";
+/** The hourly scan: cron job name (no `:`). */
 export declare const DIRECTORY_SCAN_JOB = "directory-scan";
-export declare const DIRECTORY_SCAN_SCHEDULER_ID = "directory-scan-hourly";
-export declare const DIRECTORY_SCAN_EVERY_MS = 3600000;
-/** 一次 (组织, 插件) 同步的维护任务名。 */
+/** The job name of one (org, extension) sync on the maintenance queue. */
 export declare const DIRECTORY_SYNC_JOB = "directory-sync";
-/** 同步锁的 Redis 键前缀（键为 `<前缀><orgId>:<plugin>`，带 TTL、持有期间续租）。 */
-export declare 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 declare const DIRECTORY_SYNC_LOCK_TTL_MS = 30000;
+/** The `LockService` key of one (org, extension) sync: one sync at a time. */
+export declare const directorySyncLockKey: (orgId: string, plugin: string) => string;
 /** 脏标记的保留时长（秒）：锁被占时记下，持有者跑完后取走并补一轮。 */
 export declare const DIRECTORY_SYNC_DIRTY_TTL_SECONDS = 3600;
 /** 脏标记（Redis 键）：同步进行中又有同步请求被锁挡掉。 */
@@ -72,26 +75,27 @@ export declare function minuteBucket(d?: Date): string;
  * `directory_changed` 按分钟桶去重；手动触发每次唯一，不会被同一小时的扫描任务吞掉。
  */
 export declare function directorySyncJobId(orgId: string, plugin: string, trigger: DirectorySyncTrigger, now?: Date): string;
-export interface DirectorySyncDeps {
-    db: KernelDb;
-    redis: Redis;
-    host: Pick<ExtensionHost, "list">;
-    orgExtensionConfigs: Pick<OrgExtensionConfigs, "get">;
-    external: Pick<ExternalIdentities, "resolve">;
-    offboarding: Pick<Offboarding, "offboard" | "afterCommit">;
-    /** 给了就登记每小时扫描与同步任务（worker 角色执行）；不给时只能直接调用 `sync`。 */
-    maintenance?: Pick<Maintenance, "add" | "handle" | "schedule">;
-    log: Pick<Logger, "warn" | "info">;
+/** The data of a `directory-sync` job. */
+export interface SyncJobData {
+    orgId: string;
+    plugin: string;
+    trigger: DirectorySyncTrigger;
+    requestedBy?: string;
+    requestedByToken?: string;
 }
 /**
  * 通讯录同步（`directory@1`）：把企业通讯录同步为组织成员。框架无关。
  *
  * - 维护队列每小时 `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% × 现有通讯录成员数)`，或列表里没有在职成员而已有
@@ -108,18 +112,32 @@ export interface DirectorySyncDeps {
  *   能力）时，扫描、`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 declare class DirectorySync {
-    private readonly d;
-    private readonly lock;
-    constructor(d: DirectorySyncDeps);
+    private readonly db;
+    readonly txHost: TransactionHost;
+    private readonly redis;
+    private readonly registry;
+    private readonly orgConfigs;
+    private readonly external;
+    private readonly offboarding;
+    private readonly orgLock;
+    private readonly queue;
+    readonly lockService: LockService;
+    readonly log: KernelLogger;
+    constructor(db: KernelDb, txHost: TransactionHost, redis: Redis, registry: Pick<ExtensionRegistry, "list">, orgConfigs: Pick<OrgExtensionConfigs, "get">, external: Pick<ExternalIdentities, "resolve">, offboarding: Pick<Offboarding, "offboard" | "afterOffboard">, orgLock: OrgLock, queue: Pick<Queue, "add">, lockService: LockService, log: KernelLogger);
+    /** A `directory-sync` job (dispatched by `MaintenanceProcessor`). */
+    runSyncJob(data: SyncJobData): Promise<void>;
     /** 插件提供的 `directory@1`；未加载或不提供时 undefined。 */
     private provider;
     /** 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). */
     private eligible;
     /**
      * 投递一次 `directory_changed` 同步（按分钟桶去重）；返回 job id。入站 `directory_changed` 经
-     * {@link DirectorySyncScheduler} 调用这里。通讯录未配置（`Directory.configured` 返回 false，Ruling A28）时
+     * `ChannelInbound`（`directory_changed`）调用这里。通讯录未配置（`Directory.configured` 返回 false，Ruling A28）时
      * 静默不投递，返回 undefined；其他不可同步的情况照常投递，由任务执行时跳过。
      */
     enqueue(orgId: string, plugin: string, now?: Date): Promise<string | undefined>;
@@ -134,6 +152,7 @@ export declare class DirectorySync {
     request(orgId: string, plugin: string, actorAccountId: string, actorTokenId?: string): Promise<{
         jobId: string;
     }>;
+    private authorize;
     /**
      * 每小时扫描：给每个可同步的 (组织, 插件) 投递一次同步（job id 按小时桶），返回投递的目标。
      * 已存配置不再满足 schema 的跳过（记 warn）；单个投递失败记 warn、继续其他目标。
@@ -157,10 +176,21 @@ export declare class DirectorySync {
      * 组织行锁内完成（与移出成员同一把锁、与移出时写排除串行），组织已删除 → {@link OrgGone}。
      */
     private addMember;
+    /** One short transaction per member, under the org row lock. */
+    private addMemberIn;
     /**
      * 一个离职者：独立事务内先锁组织行、再锁其成员关系行（与 `switchCurrentOrg` / 移出成员同一顺序），
      * 确认仍是本通讯录加入的，再走 `Offboarding.offboard`（吊销会话与令牌、删个人凭据、转交 agent 都在这个事务里）。
      * 最后一个 owner → 回滚并返回 `last_owner`；期间已被移除或不再是本通讯录加入的 → `gone`。
      */
     private offboardOne;
+    private offboardIn;
+}
+/** The hourly directory scan ({@link DirectorySync.scan}), once per tick across replicas; a worker-role job (`WorkerModule`). */
+export declare class DirectoryScanJob {
+    private readonly directory;
+    readonly lockService: LockService;
+    readonly log: KernelLogger;
+    constructor(directory: Pick<DirectorySync, "scan">, lockService: LockService, log: KernelLogger);
+    run(): Promise<void>;
 }