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

package/dist/models/purposes.js

@@ -1,20 +1,37 @@
+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 { SuperAdminLock } from "../identity/super-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` 声明的；
- * - 映射 = 部署默认（`org_id` 为 null，企业管理员设）+ 组织覆盖（组织管理员设，`org.models.manage`）；
+ * - 映射 = 部署默认（`org_id` 为 null，超级管理员设）+ 组织覆盖（组织管理员设，`org.models.manage`）；
  *   生效的映射先取组织覆盖、再取部署默认，都没有 → `model.unconfigured`；
- * - 目标模型按部署范围解析（与运行时一致），参数按目标模型自己的声明严格校验；不做模型白名单；
+ * - a target's kind must equal the purpose's kind; an org's override must be enabled in the org on
+ *   save (a deployment default: not disabled on the platform), and an effective target disabled in
+ *   the org (by either layer) counts as unconfigured there (spec B §5.3)；参数按目标模型自己的声明严格校验；
  * - 每次都查 PG，不在进程内缓存（多副本下改映射立即生效）。`ctx.models` 仍预留，插件暂不能调用。
  */
 /**
@@ -26,22 +43,36 @@ export const KERNEL_PURPOSES = [
     { purpose: "eval", kind: "chat", label: { zh: "评测评委", en: "Eval judge" } },
     /** Conversation titles (UI refresh B); unmapped → the conversation's current chat model. */
     { purpose: "title", kind: "chat", label: { zh: "会话标题", en: "Conversation titles" } },
+    /**
+     * The `WebFetch` extraction call (web tools spec §5); unmapped → the calling conversation's
+     * current chat model (a sub-agent's call: the sub-agent's).
+     */
+    { purpose: "web_fetch", kind: "chat", label: { zh: "网页提取", en: "Web page extraction" } },
     {
         purpose: "subagent_fast",
         kind: "chat",
-        label: { zh: "子代理：快速", en: "Sub-agent: fast" },
+        label: { zh: "子智能体：快速", en: "Sub-agent: fast" },
     },
     {
         purpose: "subagent_standard",
         kind: "chat",
-        label: { zh: "子代理：标准", en: "Sub-agent: standard" },
+        label: { zh: "子智能体：标准", en: "Sub-agent: standard" },
     },
     {
         purpose: "subagent_capable",
         kind: "chat",
-        label: { zh: "子代理：最强", en: "Sub-agent: capable" },
+        label: { zh: "子智能体：最强", en: "Sub-agent: capable" },
     },
 ];
+/** {@link PurposeListing}s of `views`, the display names read in one call. */
+export async function withDeclaredByNames(views, names) {
+    const plugins = views.map((v) => v.declaredBy).filter((d) => d !== "kernel");
+    const found = await names.many(plugins);
+    return views.map((v) => ({
+        ...v,
+        declaredByName: v.declaredBy === "kernel" ? null : (found.get(v.declaredBy) ?? null),
+    }));
+}
 /** `PUT …/model-purposes/:purpose` 的 body：设映射，或 `target: null` 清除。 */
 export const PURPOSE_PUT = z
     .object({
@@ -54,6 +85,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 +114,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 +144,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 +168,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)
@@ -141,11 +191,17 @@ export class ModelPurposesService {
     async list(orgId) {
         return this.views(this.declared(), orgId);
     }
-    /** 校验目标：模型可解析（部署范围）、参数按它的声明严格通过。 */
-    async check(target) {
+    /**
+     * 校验目标：模型可解析且启用（an org's override for the org, a deployment default in the
+     * platform view）、its kind is the purpose's `kind`、参数按它的声明严格通过。
+     */
+    async check(orgId, target, kind) {
         let info;
         try {
-            ({ info } = await this.d.registry.resolve(target.model));
+            info =
+                orgId === null
+                    ? await this.providers.platformInfo(target.model, { kind: "callable" })
+                    : (await this.providers.resolve(orgId, target.model, { kind: "callable" })).info;
         }
         catch (e) {
             if (e instanceof ProviderListError)
@@ -155,69 +211,135 @@ export class ModelPurposesService {
             }
             throw e;
         }
+        if (info.kind !== kind) {
+            throw invalid([
+                {
+                    path: "target.model",
+                    message: `this purpose needs ${kind === "embedding" ? "an" : "a"} ${kind} model, not ${info.kind}`,
+                },
+            ]);
+        }
         const issues = paramIssues("target.params", info.parameters, target.params);
         if (issues.length > 0)
             throw invalid(issues);
     }
-    async set(orgId, purpose, target, actor, actorTokenId) {
+    async set(orgId, purpose, target, actor, actorTokenId, auditDetail) {
         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.check(orgId, target, decl.kind);
+        await this.write(orgId, purpose, target, actor, actorTokenId, auditDetail);
         const [view] = await this.views([decl], orgId ?? undefined);
         return view;
     }
-    /** 设置（或 `null` 清除）部署默认；只有企业管理员（事务内复核）。 */
-    setDefault(purpose, target, actor, actorTokenId) {
-        return this.set(null, purpose, target, actor, actorTokenId);
+    /**
+     * The checks {@link set} runs before writing, nothing written: an unknown purpose, and a target
+     * model the scope cannot use, of another kind, or with invalid params (the Platform tool's
+     * precheck, so a known failure never reaches the confirmation card).
+     */
+    async validate(orgId, purpose, target) {
+        const decl = this.find(purpose);
+        if (target)
+            await this.check(orgId, target, decl.kind);
+    }
+    /** The mapping write of {@link set}, under the super admin or org lock. */
+    async write(orgId, purpose, target, actor, actorTokenId, auditDetail) {
+        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, ...auditDetail },
+        });
+    }
+    /** 设置（或 `null` 清除）部署默认；只有超级管理员（事务内复核）。 */
+    setDefault(purpose, target, actor, actorTokenId, 
+    /** Merged into the audit detail (a write made through the Platform tool). */
+    auditDetail) {
+        return this.set(null, purpose, target, actor, actorTokenId, auditDetail);
     }
     /** 设置（或 `null` 清除）组织覆盖；事务内锁组织并复核 `org.models.manage`。 */
-    setOrg(orgId, purpose, target, actor, actorTokenId) {
-        return this.set(orgId, purpose, target, actor, actorTokenId);
+    setOrg(orgId, purpose, target, actor, actorTokenId, 
+    /** Merged into the audit detail (a write made through the Platform tool). */
+    auditDetail) {
+        return this.set(orgId, purpose, target, actor, actorTokenId, auditDetail);
     }
-    /** 生效的映射：组织覆盖，否则部署默认；都没有 → `model.unconfigured`；用途未声明 → `model.purpose_unknown`。 */
+    /**
+     * 生效的映射：组织覆盖，否则部署默认；都没有 → `model.unconfigured`；用途未声明 → `model.purpose_unknown`。
+     * An effective target the org cannot use counts as unconfigured there (spec B §5.3): checked in
+     * the registry's org view, so a model the platform or the org disabled, a provider off or needing
+     * configuration in the org, a model gone from the org's list or of another kind than the purpose
+     * all give `model.unconfigured`. A provider whose list fails (`ProviderListError`) keeps the
+     * mapping: the call that follows resolves the model again and fails there, retryably, so paths
+     * that only read the mapping (sub-agent tiers, eval start, `ctx.models.describe`) do not fail on
+     * a transient list error.
+     */
     async resolve(orgId, purpose) {
-        const [view] = await this.views([this.find(purpose)], orgId);
+        const decl = this.find(purpose);
+        const [view] = await this.views([decl], orgId);
         if (!view?.effective) {
             throw new ApiError("model.unconfigured", `No model is configured for the "${purpose}" purpose`);
         }
+        try {
+            await this.providers.resolve(orgId, view.effective.model, { kind: decl.kind });
+        }
+        catch (e) {
+            if (e instanceof ProviderListError)
+                return view.effective;
+            if (e instanceof ApiError && e.code === "agent.model_unavailable") {
+                throw new ApiError("model.unconfigured", `The model configured for the "${purpose}" purpose is not available in this organization`);
+            }
+            throw e;
+        }
         return view.effective;
     }
+    /** The target a {@link chat} call on `purpose` uses: the mapping, else `fallback` when unmapped. */
+    async chatTarget(orgId, purpose, fallback) {
+        try {
+            return await this.resolve(orgId, purpose);
+        }
+        catch (e) {
+            if (!(e instanceof ApiError && e.code === "model.unconfigured") || !fallback)
+                throw e;
+            return fallback;
+        }
+    }
+    /**
+     * The limits of the model a {@link chat} call on `purpose` would use now (the same mapping and
+     * `fallback` rule): its context window and output cap, so a caller can size its request (e.g.
+     * the `WebFetch` page) before the call. Fails as `chat` does before sending.
+     */
+    async chatLimits(orgId, purpose, opts = {}) {
+        const target = await this.chatTarget(orgId, purpose, opts.fallback);
+        const { info } = await this.providers.resolve(orgId, target.model);
+        return { contextWindow: info.contextWindow, maxOutputTokens: info.maxOutputTokens };
+    }
     /**
      * 按用途发一次对话请求：解析映射、按目标模型的声明宽松处理参数（补默认值，与运行时一致），用 `consumeModelStream`
      * 收完（只有流空闲看门狗）。输出上限取 `min(req.maxOutputTokens, 目标模型的 maxOutputTokens)`。
@@ -225,26 +347,21 @@ export class ModelPurposesService {
      * `opts.fallback`: the target used when the purpose is not mapped (`model.unconfigured`).
      * `opts.beforeSend`: called with the resolved target and the final request just before sending;
      * what it throws is thrown as is (a pre-send failure, e.g. a denied `model.request` hook).
+     * `opts.paramDefaults`: values for parameters the target does not set, kept only where the
+     * target model declares the key and the value fits it (e.g. `thinking: "off"` for a short call).
      */
     async chat(orgId, purpose, req, signal, opts = {}) {
-        let target;
-        try {
-            target = await this.resolve(orgId, purpose);
-        }
-        catch (e) {
-            if (!(e instanceof ApiError && e.code === "model.unconfigured") || !opts.fallback)
-                throw e;
-            target = opts.fallback;
-        }
-        const { provider, info } = await this.d.registry.resolve(target.model);
+        const target = await this.chatTarget(orgId, purpose, opts.fallback);
+        const { provider, info } = await this.providers.resolve(orgId, target.model);
         const request = {
             ...req,
             model: info.id,
-            params: sanitizeParams(info.parameters, target.params).value,
+            // undeclared or unfitting defaults are dropped like any other parameter
+            params: sanitizeParams(info.parameters, { ...opts.paramDefaults, ...target.params }).value,
             // 输出上限不超过目标模型自己的上限（与运行时 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 +381,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(SuperAdminLock)),
+    __param(6, Inject(OrgLock))
+], ModelPurposesService);
+export { ModelPurposesService };

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,23 @@
-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 { EffectiveConfigs } from "../extensions/effective-config.js";
+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 键）：同步进行中又有同步请求被锁挡掉。 */
@@ -32,9 +36,11 @@ export declare const DIRECTORY_MAX_PAGES = 10000;
 export type DirectorySyncTrigger = "schedule" | "changed" | "manual";
 /**
  * 不同步的原因（陈旧任务、插件已停用 / 配置不再有效、组织已删除、另一同步在跑；`not_configured`：插件的
- * `Directory.configured` 说这份组织配置没配好通讯录，Ruling A28，静默跳过）。
+ * `Directory.configured` 说这份组织配置没配好通讯录，Ruling A28，静默跳过）。`needs_config`: the
+ * extension's effective deployment config for the org is not valid (layering spec A §6): skipped
+ * silently like `not_configured`; the org admin sees the extension as needing configuration.
  */
-export type DirectorySkipReason = "plugin_unavailable" | "org_not_found" | "not_enabled" | "config_invalid" | "not_configured" | "locked";
+export type DirectorySkipReason = "plugin_unavailable" | "org_not_found" | "not_enabled" | "config_invalid" | "not_configured" | "needs_config" | "locked";
 export type DirectorySyncResult = {
     status: "skipped";
     reason: DirectorySkipReason;
@@ -72,26 +78,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 +115,37 @@ 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 effective;
+    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">, effective: Pick<EffectiveConfigs, "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). */
+    /**
+     * 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).
+     */
     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>;
@@ -128,12 +154,14 @@ export declare 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.
      */
     request(orgId: string, plugin: string, actorAccountId: string, actorTokenId?: string): Promise<{
         jobId: string;
     }>;
+    private authorize;
     /**
      * 每小时扫描：给每个可同步的 (组织, 插件) 投递一次同步（job id 按小时桶），返回投递的目标。
      * 已存配置不再满足 schema 的跳过（记 warn）；单个投递失败记 warn、继续其他目标。
@@ -157,10 +185,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>;
 }