@aiquants/auth-directory-drizzle 0.6.0 → 0.7.0

package/dist/index.d.mts

@@ -1,8 +1,8 @@
-import { AuthzAdminStore } from '@aiquants/authz-core';
-import { AuthzTables, createAdminLockoutGuard } from '@aiquants/authz-drizzle';
+import { AuthDirectoryCatalogGroup, AuthDirectoryCatalogSnapshot, AuthGroupExternalLink, AuthDirectoryMembershipMode, AuthDirectoryStatus, AuthAllowlistEntry } from '@aiquants/auth-core';
 import * as drizzle_orm_mssql_core from 'drizzle-orm/mssql-core';
 import { AnyMsSqlColumn } from 'drizzle-orm/mssql-core';
-import { AuthGroupExternalLink, AuthDirectoryMembershipMode, AuthDirectoryStatus, AuthAllowlistEntry } from '@aiquants/auth-core';
+import { AuthzAdminStore } from '@aiquants/authz-core';
+import { AuthzTables, createAdminLockoutGuard } from '@aiquants/authz-drizzle';
 import { TenantMembershipPolicy, SyncAbort, AuthDirectoryMembershipMode as AuthDirectoryMembershipMode$1, LocalGroupSnapshot, DirectoryMember, ResolvedDirectoryMember, GroupSyncPlan, DirectoryGroup, DirectoryProvider, BlastRadiusPolicy } from '@aiquants/auth-directory-core';
 
 /**
@@ -45,103 +45,19 @@ interface DirectoryDb {
 }
 /** Ensures a connection exists before the first statement. 最初の文の前に接続を確立する処理。 */
 type EnsureConnection = () => Promise<void>;
-
-/**
- * @module guards
- * @description Keeps administrative roles off groups whose membership an upstream directory owns.
- * 所属の所有者が上流ディレクトリにあるグループへ、管理ロールが付かないようにする。
- *
- * **不変条件は状態の性質であって、遷移の性質ではない。**
- *
- * 最初の実装は `assignGroupRole` だけを差し替えていた。しかしそれは「外部グループへ管理ロールを
- * 割り当てる」という 1 つの遷移を塞いだにすぎず、**無害なロールを外部グループへ割り当ててから、
- * そのロールを管理ロールへ昇格させる**という順序が開いたままだった。不変条件を守るには、それを
- * 崩し得るすべての遷移を塞ぐ必要がある。
- *
- * 崩し得る遷移は 3 つある。
- *
- * | # | 遷移 | 塞ぐもの |
- * | --- | --- | --- |
- * | 1 | 外部グループが管理ロールを得る | `assignGroupRole` |
- * | 2 | 外部グループが持つロールが管理ロールになる | `createGrant` |
- * | 3 | 管理ロールを持つグループが外部連携される | `assertGroupMayBeLinked` |
- *
- * `updateGrant` は塞ぐ必要がない。`(role_id, resource_id, action)` が一意であるため、管理リソースの
- * 4 アクションを揃えるには 4 行の付与が要り、既に 4 行あるロールは既に管理ロールである。既存行の
- * アクションを差し替えても集合の要素数は増えないので、`updateGrant` は管理権を **作れない**。
- *
- * `setRoleActive` も塞ぐ必要がない。遷移 1 の判定はロールの有効・無効を見ないため、無効な管理
- * ロールも外部グループへは割り当てられない。したがって「無効な管理ロールを外部グループが保持した
- * まま有効化される」という状態には到達し得ない。
- *
- * **なぜ認可パッケージの中で判定しないのか。** 判定を `@aiquants/authz-drizzle` の管理ストアへ
- * 埋め込むと、認可パッケージがグループの「出所」という identity 側の概念を知ることになる。依存の
- * 向きは auth → authz の一方通行で保ちたいので、包む側 (identity 側) から課す。
- *
- * **なぜ禁止するのか。** 外部グループの所属は上流の管理者が変更できる。そこへ管理ロールを付けると、
- * 上流側の 1 操作がこの配備の管理者を増やしたり、逆に最後の管理者を奪ったりする。ブレークグラス
- * 経路は常にローカルに残しておく必要がある。
- */
-
-/** The link lookup this guard needs. 本ガードが必要とするリンク参照。 */
-type ExternalLinkLookup = {
-    /**
-     * The upstream key of the group, or `null` when its membership is locally managed.
-     * そのグループの上流キー。ローカル管理なら `null`。
-     *
-     * 「外部かどうか」と「拒否メッセージに出す名前」を 1 回の照会で返す。判定のためだけに
-     * 引いて、名前のためにもう一度引く形にすると、拒否のたびに往復が 2 倍になる。
-     *
-     * ⚠️ `runner` を渡された実装は、**必ずその上で** 引くこと。別接続で引くと、この読み取りの
-     * 結果を前提に書き込む呼び出し側にとって前提が保たれない (読んだ後・書く前に連携が作られる)。
-     */
-    externalGroupKey(tenantId: string, groupId: number, runner?: unknown): Promise<string | null>;
-};
-/** Configuration of the guard. ガードの構成。 */
-type ExternalGroupGuardOptions = {
-    linkLookup: ExternalLinkLookup;
-    /** App key the administrative resource belongs to. 管理リソースが属するアプリキー。 */
-    adminAppKey: string;
-    /** Resource key that grants administration. 管理を与えるリソースキー。 */
-    adminResourceKey: string;
-    /**
-     * Refusal message. 拒否メッセージ。
-     *
-     * @param roleKey Role that would have conferred administration. 管理権を与えることになるロール。
-     * @param groupKey Group that would have held it. それを保持することになるグループ。
-     */
-    message: (roleKey: string, groupKey: string) => string;
-};
-/** Default refusal message (Japanese, matching the admin UI's locale). 既定の拒否メッセージ。 */
-declare const defaultExternalGroupGuardMessage: (roleKey: string, groupKey: string) => string;
-/**
- * Wraps an authorization admin store so administrative power cannot reach an external group.
- * 外部グループへ管理権が届かないよう認可管理ストアを包む処理。
- *
- * `assignGroupRole` と `createGrant` を差し替え、残りは透過的に委譲する。3 番目の方向
- * (連携の開始) は {@link assertGroupMayBeLinked} が担い、リンクを作る側が必ず通す。
- *
- * @param store Store to wrap. 包む対象のストア。
- * @param opts Link lookup and administrative resource identity. リンク参照と管理リソースの同定。
- * @returns A store with the same surface. 同一表面のストア。
- */
-declare function withExternalGroupGuards<R>(store: AuthzAdminStore<R>, opts: ExternalGroupGuardOptions): AuthzAdminStore<R>;
 /**
- * Refuses to link a group that already holds an administrative role.
- * 既に管理ロールを保持しているグループの外部連携を拒否する処理。
+ * Reads a driver timestamp as an instant, treating an offset-less string as UTC.
+ * ドライバの時刻を瞬間として読む処理 (オフセットの無い文字列は UTC として解釈)。
  *
- * 3 つ目の方向。これを通さずにリンクを作ると、ローカルで管理ロールを付けてから連携させる経路が
- * 残る。{@link withExternalGroupGuards} と違って呼び出し側が忘れ得るため、リンクを作る側の
- * 構成に必須ポートとして組み込むこと。
+ * ⚠️ オフセットを持たない ISO 文字列 (`2026-09-09 03:04:05.000`) は仕様上 **実行環境の時間帯**
+ * で解釈される。ドライバは通常 `Date` を返すのでこの経路は普段通らないが、通った日に JST なら
+ * 9 時間ずれる — 鮮度は「常に古い」と報告され、締切の比較は 9 時間ぶん甘くなる。読む場所ごとに
+ * 対処すると必ずどこかが漏れるので、1 つの関数に閉じる。
  *
- * @param store Authorization admin store used to read the grants. 付与を読む認可管理ストア。
- * @param tenantId Tenant the group belongs to. グループが属するテナント。
- * @param groupId Group about to be linked. 連携しようとしているグループ。
- * @param opts Administrative resource identity and refusal message. 管理リソースの同定と文言。
- * @returns Nothing; returns normally only when linking is allowed. 許可される場合のみ正常復帰。
- * @throws {Error} When the group holds the administrative role. 管理ロールを保持している場合。
+ * @param value - What the driver returned. ドライバが返した値。
+ * @returns The instant. その瞬間。
  */
-declare function assertGroupMayBeLinked(store: AuthzAdminStore, tenantId: string, groupId: number, opts: Pick<ExternalGroupGuardOptions, "adminAppKey" | "adminResourceKey" | "message">): Promise<void>;
+declare function toInstant(value: string | Date): Date;
 
 /** Minimal shape of a table this schema points a foreign key at. 外部キーの参照先に要る最小形。 */
 type ReferencedTable = {
@@ -158,7 +74,7 @@ declare const AUTH_DIRECTORY_PROVIDER_COLUMN = "provider";
  *
  * `TDGroupMemberEmail` が含まれないのは、親グループからテナントを継承するためである。
  */
-declare const AUTH_DIRECTORY_TENANT_SCOPED_TABLES: readonly ["TDGroupExternalLink", "TDTenantMembershipGroup", "TDAllowlistGroup", "TDDirectorySyncRequest", "TMAllowlist"];
+declare const AUTH_DIRECTORY_TENANT_SCOPED_TABLES: readonly ["TDGroupExternalLink", "TDTenantMembershipGroup", "TDAllowlistGroup", "TDDirectorySyncRequest", "TDDirectoryCatalog", "TMDirectoryCatalogObservation", "TMAllowlist"];
 /**
  * Builds the identity-side tables under an arbitrary schema name.
  * 任意のスキーマ名の下に identity 側テーブル群を構築する処理。
@@ -958,13 +874,13 @@ declare function defineAuthDirectorySchema<S extends string>(schemaName: S, opts
         };
         dialect: "mssql";
     }>;
-    TMAllowlist: drizzle_orm_mssql_core.MsSqlTableWithColumns<{
-        name: "TMAllowlist";
+    TDDirectoryCatalog: drizzle_orm_mssql_core.MsSqlTableWithColumns<{
+        name: "TDDirectoryCatalog";
         schema: S;
         columns: {
             createdAt: drizzle_orm_mssql_core.MsSqlColumn<{
                 name: string;
-                tableName: "TMAllowlist";
+                tableName: "TDDirectoryCatalog";
                 dataType: "object date";
                 data: Date;
                 driverParam: string | Date;
@@ -980,7 +896,7 @@ declare function defineAuthDirectorySchema<S extends string>(schemaName: S, opts
             }, {}>;
             createdBy: drizzle_orm_mssql_core.MsSqlColumn<{
                 name: string;
-                tableName: "TMAllowlist";
+                tableName: "TDDirectoryCatalog";
                 dataType: "string";
                 data: string;
                 driverParam: string | number;
@@ -996,7 +912,7 @@ declare function defineAuthDirectorySchema<S extends string>(schemaName: S, opts
             }, {}>;
             id: drizzle_orm_mssql_core.MsSqlColumn<{
                 name: string;
-                tableName: "TMAllowlist";
+                tableName: "TDDirectoryCatalog";
                 dataType: "number int53";
                 data: number;
                 driverParam: string;
@@ -1012,7 +928,7 @@ declare function defineAuthDirectorySchema<S extends string>(schemaName: S, opts
             }, {}>;
             tenantId: drizzle_orm_mssql_core.MsSqlColumn<{
                 name: string;
-                tableName: "TMAllowlist";
+                tableName: "TDDirectoryCatalog";
                 dataType: "string";
                 data: string;
                 driverParam: string | number;
@@ -1026,9 +942,9 @@ declare function defineAuthDirectorySchema<S extends string>(schemaName: S, opts
                 identity: undefined;
                 generated: undefined;
             }, {}>;
-            pattern: drizzle_orm_mssql_core.MsSqlColumn<{
+            provider: drizzle_orm_mssql_core.MsSqlColumn<{
                 name: string;
-                tableName: "TMAllowlist";
+                tableName: "TDDirectoryCatalog";
                 dataType: "string";
                 data: string;
                 driverParam: string | number;
@@ -1042,9 +958,41 @@ declare function defineAuthDirectorySchema<S extends string>(schemaName: S, opts
                 identity: undefined;
                 generated: undefined;
             }, {}>;
-            type: drizzle_orm_mssql_core.MsSqlColumn<{
+            externalId: drizzle_orm_mssql_core.MsSqlColumn<{
                 name: string;
-                tableName: "TMAllowlist";
+                tableName: "TDDirectoryCatalog";
+                dataType: "string";
+                data: string;
+                driverParam: string | number;
+                notNull: true;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: [string, ...string[]];
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}>;
+            externalKey: drizzle_orm_mssql_core.MsSqlColumn<{
+                name: string;
+                tableName: "TDDirectoryCatalog";
+                dataType: "string";
+                data: string;
+                driverParam: string | number;
+                notNull: true;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: [string, ...string[]];
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}>;
+            name: drizzle_orm_mssql_core.MsSqlColumn<{
+                name: string;
+                tableName: "TDDirectoryCatalog";
                 dataType: "string";
                 data: string;
                 driverParam: string | number;
@@ -1060,7 +1008,7 @@ declare function defineAuthDirectorySchema<S extends string>(schemaName: S, opts
             }, {}>;
             description: drizzle_orm_mssql_core.MsSqlColumn<{
                 name: string;
-                tableName: "TMAllowlist";
+                tableName: "TDDirectoryCatalog";
                 dataType: "string";
                 data: string;
                 driverParam: string | number;
@@ -1074,100 +1022,601 @@ declare function defineAuthDirectorySchema<S extends string>(schemaName: S, opts
                 identity: undefined;
                 generated: undefined;
             }, {}>;
+            memberCount: drizzle_orm_mssql_core.MsSqlColumn<{
+                name: string;
+                tableName: "TDDirectoryCatalog";
+                dataType: "number int32";
+                data: number;
+                driverParam: number;
+                notNull: false;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: undefined;
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}>;
+            observedAt: drizzle_orm_mssql_core.MsSqlColumn<{
+                name: string;
+                tableName: "TDDirectoryCatalog";
+                dataType: "object date";
+                data: Date;
+                driverParam: string | Date;
+                notNull: true;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: undefined;
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}>;
         };
         dialect: "mssql";
     }>;
-};
-/** Explicit alias for the tables `defineAuthDirectorySchema` returns (avoids TS2742). 明示型。 */
-type AuthDirectoryTables = {
-    TDGroupExternalLink: ReturnType<typeof defineAuthDirectorySchema>["TDGroupExternalLink"];
-    TDGroupMemberEmail: ReturnType<typeof defineAuthDirectorySchema>["TDGroupMemberEmail"];
-    TDTenantMembershipGroup: ReturnType<typeof defineAuthDirectorySchema>["TDTenantMembershipGroup"];
-    TDAllowlistGroup: ReturnType<typeof defineAuthDirectorySchema>["TDAllowlistGroup"];
-    TDDirectorySyncRequest: ReturnType<typeof defineAuthDirectorySchema>["TDDirectorySyncRequest"];
-    TMAllowlist: ReturnType<typeof defineAuthDirectorySchema>["TMAllowlist"];
-};
-
-/**
- * Resolves which member-ledger rows belong to one identity.
- * 台帳のどの行が 1 人の identity のものかを解決するモジュール。
- *
- * 台帳 (`TDGroupMemberEmail`) は「上流に居る人」を、ローカルユーザーへ解決できているかに
- * 関わらず保持する。ここはその台帳から本人の行だけを取り出す唯一の場所であり、帰属証明
- * (`listLedgerGroupIds`) と初回ログイン時の昇格 (`promoteLedgerForUser`) は同じ答えを見る。
- * 突合規則が 2 箇所にあると、片方だけが「本人」と認めた瞬間に権限が食い違う。
- */
-
-/** One ledger row attributed to an identity. identity に帰属した台帳 1 行。 */
-type LedgerIdentityRow = {
-    ledgerId: number;
-    groupId: number;
-    /** Inherited from the parent group — the ledger has no tenant column. 親グループ由来。 */
-    tenantId: string;
-};
-/** The two tables this resolution spans. この解決が跨る 2 表。 */
-type LedgerIdentityTables = {
-    /** `TDGroupMemberEmail`. */
-    ledger: AuthDirectoryTables["TDGroupMemberEmail"];
-    /** `TMGroup` — owns the tenant and the active flag. テナントと有効フラグの所有者。 */
-    group: AuthzTables["TMGroup"];
-};
-/**
- * Finds every ledger row that belongs to the identity, within one tenant.
- * 1 テナント内で、その identity に属する台帳行をすべて探す処理。
- *
- * 上流 ID の一致は無条件に本人。アドレスの一致は、その行が **別の** 上流 ID に紐付いていない
- * ときだけ本人である。単純な `OR` にすると後者の条件が消え、退職者のアドレスを再利用した
- * 新入社員が前任者の所属をそのまま継承する。
- *
- * ⚠️ この優先順位は **行ごと** に適用する。「ID で当たったらアドレスは見ない」という打ち切りは
- * 誤りで、同じ人物の行が ID 付きと ID 無しに混在すると ID 無しの行が丸ごと落ちる。
- *
- * @param db - Connected database surface. 接続済みの DB 面。
- * @param tables - The ledger and its parent group table. 台帳と親グループ表。
- * @param args - Tenant scope and the identity to match. テナント範囲と突合対象の identity。
- * @returns Matching rows, deduplicated and ordered by ledger id. 重複排除・台帳 ID 昇順の一致行。
- */
-declare function findLedgerRowsForIdentity(db: DirectoryDb, tables: LedgerIdentityTables, args: {
-    tenantId: string;
-    externalUserId: string | null;
-    email: string;
-}): Promise<LedgerIdentityRow[]>;
-
-/**
- * @module link-store
- * @description Reads and writes the identity-side tables: external group links, the upstream member
- * ledger, tenant membership proof, group-based login allowlist, and the sync request queue.
- * identity 側テーブルの読み書き。外部グループリンク・上流メンバー台帳・テナント帰属証明・
- * グループ単位のログイン許可・同期要求キュー。
- *
- * **テナントの扱いは 2 種類ある。混同すると事故になる。**
- *
- * - **絞り込み条件**: リンク・帰属証明グループ。読み書きの双方で SQL 述語になる。
- * - **所有者**: グループ許可。管理 UI の編集スコープを決めるだけで、**ログイン判定では
- *   述語にしない** — 認証はテナントの確定より前に起きるため、判定の時点でテナントは存在しない。
- *   このモジュールでは {@link createDirectoryLinkStore} の `isEmailAllowedByGroup` だけが
- *   その例外であり、意図的に全テナントを対象とする。
- */
-
-/**
- * Proves a group may become externally sourced. グループを外部供給にしてよいことの証明。
- *
- * `assertGroupMayBeLinked` を呼ぶだけのポートである。自由関数のままだと呼び出し側が忘れられ、
- * 「ローカルで管理ロールを付けてから連携させる」経路が残る。必須の構成項目にすることで、
- * 忘れることを構造的に不可能にする。
- */
-type LinkableAssertion = {
-    /**
-     * Owns a transaction, proves the group may be linked on it, then runs `write` on the same runner.
-     * トランザクションを所有し、その上で連携可能であることを証明してから、同じランナーで `write` を実行する処理。
-     *
-     * ⚠️ **証明だけを返す形にしてはならない。** 証明と連携の作成が別のトランザクションだと、
-     * 証明を通った直後・リンクを作る前に、そのグループへ管理ロールを割り当てる操作が
-     * 割り込める。割り当て側の検査は「まだリンクが無い」と見て通り、連携側の検査は
-     * 「まだ管理ロールが無い」と見て通る — **どちらも単独では正しく、結果だけが不変条件を破る**。
-     *
-     * @param tenantId - Tenant that owns the group. グループを所有するテナント。
+    TMDirectoryCatalogObservation: drizzle_orm_mssql_core.MsSqlTableWithColumns<{
+        name: "TMDirectoryCatalogObservation";
+        schema: S;
+        columns: {
+            createdAt: drizzle_orm_mssql_core.MsSqlColumn<{
+                name: string;
+                tableName: "TMDirectoryCatalogObservation";
+                dataType: "object date";
+                data: Date;
+                driverParam: string | Date;
+                notNull: false;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: undefined;
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}>;
+            createdBy: drizzle_orm_mssql_core.MsSqlColumn<{
+                name: string;
+                tableName: "TMDirectoryCatalogObservation";
+                dataType: "string";
+                data: string;
+                driverParam: string | number;
+                notNull: false;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: [string, ...string[]];
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}>;
+            updatedAt: drizzle_orm_mssql_core.MsSqlColumn<{
+                name: string;
+                tableName: "TMDirectoryCatalogObservation";
+                dataType: "object date";
+                data: Date;
+                driverParam: string | Date;
+                notNull: false;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: undefined;
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}>;
+            updatedBy: drizzle_orm_mssql_core.MsSqlColumn<{
+                name: string;
+                tableName: "TMDirectoryCatalogObservation";
+                dataType: "string";
+                data: string;
+                driverParam: string | number;
+                notNull: false;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: [string, ...string[]];
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}>;
+            id: drizzle_orm_mssql_core.MsSqlColumn<{
+                name: string;
+                tableName: "TMDirectoryCatalogObservation";
+                dataType: "number int53";
+                data: number;
+                driverParam: string;
+                notNull: true;
+                hasDefault: true;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: undefined;
+                baseColumn: never;
+                identity: undefined;
+                generated: {};
+            }, {}>;
+            tenantId: drizzle_orm_mssql_core.MsSqlColumn<{
+                name: string;
+                tableName: "TMDirectoryCatalogObservation";
+                dataType: "string";
+                data: string;
+                driverParam: string | number;
+                notNull: true;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: [string, ...string[]];
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}>;
+            provider: drizzle_orm_mssql_core.MsSqlColumn<{
+                name: string;
+                tableName: "TMDirectoryCatalogObservation";
+                dataType: "string";
+                data: string;
+                driverParam: string | number;
+                notNull: true;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: [string, ...string[]];
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}>;
+            observedAt: drizzle_orm_mssql_core.MsSqlColumn<{
+                name: string;
+                tableName: "TMDirectoryCatalogObservation";
+                dataType: "object date";
+                data: Date;
+                driverParam: string | Date;
+                notNull: true;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: undefined;
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}>;
+            entryCount: drizzle_orm_mssql_core.MsSqlColumn<{
+                name: string;
+                tableName: "TMDirectoryCatalogObservation";
+                dataType: "number int32";
+                data: number;
+                driverParam: number;
+                notNull: true;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: undefined;
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}>;
+        };
+        dialect: "mssql";
+    }>;
+    TMAllowlist: drizzle_orm_mssql_core.MsSqlTableWithColumns<{
+        name: "TMAllowlist";
+        schema: S;
+        columns: {
+            createdAt: drizzle_orm_mssql_core.MsSqlColumn<{
+                name: string;
+                tableName: "TMAllowlist";
+                dataType: "object date";
+                data: Date;
+                driverParam: string | Date;
+                notNull: false;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: undefined;
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}>;
+            createdBy: drizzle_orm_mssql_core.MsSqlColumn<{
+                name: string;
+                tableName: "TMAllowlist";
+                dataType: "string";
+                data: string;
+                driverParam: string | number;
+                notNull: false;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: [string, ...string[]];
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}>;
+            id: drizzle_orm_mssql_core.MsSqlColumn<{
+                name: string;
+                tableName: "TMAllowlist";
+                dataType: "number int53";
+                data: number;
+                driverParam: string;
+                notNull: true;
+                hasDefault: true;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: undefined;
+                baseColumn: never;
+                identity: undefined;
+                generated: {};
+            }, {}>;
+            tenantId: drizzle_orm_mssql_core.MsSqlColumn<{
+                name: string;
+                tableName: "TMAllowlist";
+                dataType: "string";
+                data: string;
+                driverParam: string | number;
+                notNull: true;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: [string, ...string[]];
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}>;
+            pattern: drizzle_orm_mssql_core.MsSqlColumn<{
+                name: string;
+                tableName: "TMAllowlist";
+                dataType: "string";
+                data: string;
+                driverParam: string | number;
+                notNull: true;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: [string, ...string[]];
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}>;
+            type: drizzle_orm_mssql_core.MsSqlColumn<{
+                name: string;
+                tableName: "TMAllowlist";
+                dataType: "string";
+                data: string;
+                driverParam: string | number;
+                notNull: true;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: [string, ...string[]];
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}>;
+            description: drizzle_orm_mssql_core.MsSqlColumn<{
+                name: string;
+                tableName: "TMAllowlist";
+                dataType: "string";
+                data: string;
+                driverParam: string | number;
+                notNull: false;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: [string, ...string[]];
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}>;
+        };
+        dialect: "mssql";
+    }>;
+};
+/** Explicit alias for the tables `defineAuthDirectorySchema` returns (avoids TS2742). 明示型。 */
+type AuthDirectoryTables = {
+    TDGroupExternalLink: ReturnType<typeof defineAuthDirectorySchema>["TDGroupExternalLink"];
+    TDGroupMemberEmail: ReturnType<typeof defineAuthDirectorySchema>["TDGroupMemberEmail"];
+    TDTenantMembershipGroup: ReturnType<typeof defineAuthDirectorySchema>["TDTenantMembershipGroup"];
+    TDAllowlistGroup: ReturnType<typeof defineAuthDirectorySchema>["TDAllowlistGroup"];
+    TDDirectorySyncRequest: ReturnType<typeof defineAuthDirectorySchema>["TDDirectorySyncRequest"];
+    TDDirectoryCatalog: ReturnType<typeof defineAuthDirectorySchema>["TDDirectoryCatalog"];
+    TMDirectoryCatalogObservation: ReturnType<typeof defineAuthDirectorySchema>["TMDirectoryCatalogObservation"];
+    TMAllowlist: ReturnType<typeof defineAuthDirectorySchema>["TMAllowlist"];
+};
+
+/**
+ * @module catalog-store
+ * @description The upstream group list, written by the sync job and read by the web.
+ * 同期ジョブが書き、web が読む、上流のグループ一覧。
+ *
+ * ⚠️ **この表と、このモジュールが在る理由は境界である。** ドメイン全体委任の資格情報は組織の
+ * ディレクトリを丸ごと読めるため、外部からの要求を終端する web プロセスには置かない。上流へ
+ * 届くのは同期ジョブだけとし、web は「ジョブが書いた行」を読む。管理面の選択欄は利便のための
+ * 読み取りであり、その利便のために資格情報の置き場所を動かしてよい理由にはならない。
+ *
+ * ここには生産側 (`replace`) と消費側 (`read`) の両方が居る。プロセスを分ける仕掛けは
+ * import の可否ではなく **資格情報を持つかどうか** であり、`replace` を呼べても上流を
+ * 読めないプロセスは書くべき内容を持てない。
+ */
+
+/**
+ * One upstream group, as observed. 観測した上流グループ 1 件。
+ *
+ * ⚠️ 別名ではなく `@aiquants/auth-core` の型そのものである。層ごとに「同じ意味の別の型」を宣言すると、
+ * 構造的部分型のせいでどの境界も通ってしまい、上流へ足した欄が途中で黙って捨てられる。
+ */
+type DirectoryCatalogEntry = AuthDirectoryCatalogGroup;
+/** What the web reads. web が読む内容 ({@link AuthDirectoryCatalogSnapshot} の項目名違いではなく同一契約)。 */
+type DirectoryCatalogSnapshot = AuthDirectoryCatalogSnapshot;
+/** Options a reader needs. 読み手が必要とするオプション。 */
+type DirectoryCatalogReaderOptions = {
+    ensureConnection?: EnsureConnection;
+};
+/**
+ * Options a writer needs. 書き手が必要とするオプション。
+ *
+ * ⚠️ 読み手にこれを要求してはならない。読むだけの呼び出し側に時計と監査主体を持たせると、
+ * その場で `replace` を呼ぶ経路が「既に手元にあるもの」になり、上流を読めないプロセスが
+ * 観測時刻を詐称できてしまう。だから生成関数を 2 つに分けている。
+ */
+type DirectoryCatalogWriterOptions = DirectoryCatalogReaderOptions & {
+    /** Injected clock — one observation must carry one timestamp. 注入時計。 */
+    now: () => Date;
+    /** Who the audit columns record. 監査列に残す主体。 */
+    actor: string;
+};
+/**
+ * Creates the write side of the catalog. 候補一覧の **書き手** を生成する処理。
+ *
+ * ⚠️ これを呼べるのは上流の資格情報を持つプロセスだけであるべきである。読むだけの側は
+ * {@link createDirectoryCatalogReader} を使う — 分けているのは整理のためではなく、「読むだけの
+ * 呼び出し側の手元に `replace` が在る」状態そのものを作らないためである。
+ *
+ * @param dbUnknown - Drizzle database instance. drizzle のデータベースインスタンス。
+ * @param tables - Directory tables (owns the catalog). ディレクトリ表 (候補一覧の所有者)。
+ * @param opts - Connection, clock and actor. 接続・時計・監査主体。
+ * @returns The `replace` operation. 置き換え操作。
+ */
+declare function createDirectoryCatalogWriter(dbUnknown: unknown, tables: AuthDirectoryTables, opts: DirectoryCatalogWriterOptions): {
+    /**
+     * Replaces this tenant's catalog with what the upstream currently answers.
+     * このテナントの候補一覧を、上流の現在の答えで置き換える処理。
+     *
+     * ⚠️ 差分更新ではなく **全置換** である。消えたグループを残すと、管理面はそれを選ばせ続け、
+     * 選んだ運用者は 10 分後に「上流に無い」と言われる。1 つのトランザクションで消してから
+     * 書くことで、途中の状態を web に読ませない。
+     *
+     * @param tenantId - Owner tenant. 所有テナント。
+     * @param provider - Upstream provider key. 上流プロバイダのキー。
+     * @param entries - The upstream's current answer. 上流の現在の答え。
+     * @returns How many rows were written. 書き込んだ行数。
+     */
+    replace(tenantId: string, provider: string, entries: readonly DirectoryCatalogEntry[]): Promise<number>;
+};
+/**
+ * Creates the read side of the catalog. 候補一覧の **読み手** を生成する処理。
+ *
+ * 時計も監査主体も要らない。要らないものを求めないことが、この関数がここに在る理由である。
+ *
+ * @param dbUnknown - Drizzle database instance. drizzle のデータベースインスタンス。
+ * @param tables - Directory tables (owns the catalog). ディレクトリ表 (候補一覧の所有者)。
+ * @param opts - Connection handling. 接続の扱い。
+ * @returns The `read` operation. 読み取り操作。
+ */
+declare function createDirectoryCatalogReader(dbUnknown: unknown, tables: AuthDirectoryTables, opts?: DirectoryCatalogReaderOptions): {
+    /**
+     * Reads this tenant's catalog. このテナントの候補一覧を読む処理。
+     *
+     * ⚠️ **観測の有無は行数から導かない。** 上流を正しく読めて答えが 0 件だった配備 (借用先の
+     * 権限が狭い、対象 OU が空) と、同期が一度も走っていない配備は、候補一覧の行数ではどちらも
+     * 0 である。前者を「同期が動いていない」と診断すると、運用は健全な部品を調べに行く。
+     * `observedAt` は観測記録そのものから取り、`null` は **一度も観測していない** だけを意味する。
+     *
+     * @param tenantId - Owner tenant. 所有テナント。
+     * @param provider - Upstream provider key. 上流プロバイダのキー。
+     * @returns The groups and the observation time. グループと観測時刻。
+     */
+    read(tenantId: string, provider: string): Promise<DirectoryCatalogSnapshot>;
+};
+
+/**
+ * @module guards
+ * @description Keeps administrative roles off groups whose membership an upstream directory owns.
+ * 所属の所有者が上流ディレクトリにあるグループへ、管理ロールが付かないようにする。
+ *
+ * **不変条件は状態の性質であって、遷移の性質ではない。**
+ *
+ * 最初の実装は `assignGroupRole` だけを差し替えていた。しかしそれは「外部グループへ管理ロールを
+ * 割り当てる」という 1 つの遷移を塞いだにすぎず、**無害なロールを外部グループへ割り当ててから、
+ * そのロールを管理ロールへ昇格させる**という順序が開いたままだった。不変条件を守るには、それを
+ * 崩し得るすべての遷移を塞ぐ必要がある。
+ *
+ * 崩し得る遷移は 3 つある。
+ *
+ * | # | 遷移 | 塞ぐもの |
+ * | --- | --- | --- |
+ * | 1 | 外部グループが管理ロールを得る | `assignGroupRole` |
+ * | 2 | 外部グループが持つロールが管理ロールになる | `createGrant` |
+ * | 3 | 管理ロールを持つグループが外部連携される | `assertGroupMayBeLinked` |
+ * | 4 | 外部グループが持つロールの付与が差し替わって管理ロールになる | `updateGrant` |
+ *
+ * ⚠️ `updateGrant` を「塞ぐ必要がない」と読んではならない。行数だけを見る論法 —
+ * 「`(role_id, resource_id, action)` は一意だから、アクションを差し替えても集合は増えない」 —
+ * は **ロール 1 つの中でしか成り立たない**。判定はこのファイルのどの遷移でも
+ * **グループの全ロールの合併** で行う。ロール 1 が `{read, create}`、ロール 2 が
+ * `{read, update}` を持つ外部グループでは合併は 3 アクションで、どちらの割当も正当に通る。
+ * そこでロール 2 の `read` を `delete` へ差し替えると、ロール 2 の行数は 2 のままなのに
+ * 合併は 4 アクションに達し、上流のディレクトリ管理者がこの配備の管理者を決められるようになる。
+ *
+ * `setRoleActive` も塞ぐ必要がない。遷移 1 の判定はロールの有効・無効を見ないため、無効な管理
+ * ロールも外部グループへは割り当てられない。したがって「無効な管理ロールを外部グループが保持した
+ * まま有効化される」という状態には到達し得ない。
+ *
+ * **なぜ認可パッケージの中で判定しないのか。** 判定を `@aiquants/authz-drizzle` の管理ストアへ
+ * 埋め込むと、認可パッケージがグループの「出所」という identity 側の概念を知ることになる。依存の
+ * 向きは auth → authz の一方通行で保ちたいので、包む側 (identity 側) から課す。
+ *
+ * **なぜ禁止するのか。** 外部グループの所属は上流の管理者が変更できる。そこへ管理ロールを付けると、
+ * 上流側の 1 操作がこの配備の管理者を増やしたり、逆に最後の管理者を奪ったりする。ブレークグラス
+ * 経路は常にローカルに残しておく必要がある。
+ */
+
+/** The link lookup this guard needs. 本ガードが必要とするリンク参照。 */
+type ExternalLinkLookup = {
+    /**
+     * The upstream key of the group, or `null` when its membership is locally managed.
+     * そのグループの上流キー。ローカル管理なら `null`。
+     *
+     * 「外部かどうか」と「拒否メッセージに出す名前」を 1 回の照会で返す。判定のためだけに
+     * 引いて、名前のためにもう一度引く形にすると、拒否のたびに往復が 2 倍になる。
+     *
+     * ⚠️ `runner` を渡された実装は、**必ずその上で** 引くこと。別接続で引くと、この読み取りの
+     * 結果を前提に書き込む呼び出し側にとって前提が保たれない (読んだ後・書く前に連携が作られる)。
+     */
+    externalGroupKey(tenantId: string, groupId: number, runner?: unknown): Promise<string | null>;
+};
+/** Configuration of the guard. ガードの構成。 */
+type ExternalGroupGuardOptions = {
+    linkLookup: ExternalLinkLookup;
+    /** App key the administrative resource belongs to. 管理リソースが属するアプリキー。 */
+    adminAppKey: string;
+    /** Resource key that grants administration. 管理を与えるリソースキー。 */
+    adminResourceKey: string;
+    /**
+     * Refusal message. 拒否メッセージ。
+     *
+     * @param roleKey Role that would have conferred administration. 管理権を与えることになるロール。
+     * @param groupKey Group that would have held it. それを保持することになるグループ。
+     */
+    message: (roleKey: string, groupKey: string) => string;
+};
+/** Default refusal message (Japanese, matching the admin UI's locale). 既定の拒否メッセージ。 */
+declare const defaultExternalGroupGuardMessage: (roleKey: string, groupKey: string) => string;
+/**
+ * Wraps an authorization admin store so administrative power cannot reach an external group.
+ * 外部グループへ管理権が届かないよう認可管理ストアを包む処理。
+ *
+ * `assignGroupRole` と `createGrant` を差し替え、残りは透過的に委譲する。3 番目の方向
+ * (連携の開始) は {@link assertGroupMayBeLinked} が担い、リンクを作る側が必ず通す。
+ *
+ * @param store Store to wrap. 包む対象のストア。
+ * @param opts Link lookup and administrative resource identity. リンク参照と管理リソースの同定。
+ * @returns A store with the same surface. 同一表面のストア。
+ */
+declare function withExternalGroupGuards<R>(store: AuthzAdminStore<R>, opts: ExternalGroupGuardOptions): AuthzAdminStore<R>;
+/**
+ * Refuses to link a group that already holds an administrative role.
+ * 既に管理ロールを保持しているグループの外部連携を拒否する処理。
+ *
+ * 3 つ目の方向。これを通さずにリンクを作ると、ローカルで管理ロールを付けてから連携させる経路が
+ * 残る。{@link withExternalGroupGuards} と違って呼び出し側が忘れ得るため、リンクを作る側の
+ * 構成に必須ポートとして組み込むこと。
+ *
+ * @param store Authorization admin store used to read the grants. 付与を読む認可管理ストア。
+ * @param tenantId Tenant the group belongs to. グループが属するテナント。
+ * @param groupId Group about to be linked. 連携しようとしているグループ。
+ * @param opts Administrative resource identity and refusal message. 管理リソースの同定と文言。
+ * @returns Nothing; returns normally only when linking is allowed. 許可される場合のみ正常復帰。
+ * @throws {Error} When the group holds the administrative role. 管理ロールを保持している場合。
+ */
+declare function assertGroupMayBeLinked(store: AuthzAdminStore, tenantId: string, groupId: number, opts: Pick<ExternalGroupGuardOptions, "adminAppKey" | "adminResourceKey" | "message">): Promise<void>;
+
+/**
+ * Resolves which member-ledger rows belong to one identity.
+ * 台帳のどの行が 1 人の identity のものかを解決するモジュール。
+ *
+ * 台帳 (`TDGroupMemberEmail`) は「上流に居る人」を、ローカルユーザーへ解決できているかに
+ * 関わらず保持する。ここはその台帳から本人の行だけを取り出す唯一の場所であり、帰属証明
+ * (`listLedgerGroupIds`) と初回ログイン時の昇格 (`promoteLedgerForUser`) は同じ答えを見る。
+ * 突合規則が 2 箇所にあると、片方だけが「本人」と認めた瞬間に権限が食い違う。
+ */
+
+/** One ledger row attributed to an identity. identity に帰属した台帳 1 行。 */
+type LedgerIdentityRow = {
+    ledgerId: number;
+    groupId: number;
+    /** Inherited from the parent group — the ledger has no tenant column. 親グループ由来。 */
+    tenantId: string;
+};
+/** The two tables this resolution spans. この解決が跨る 2 表。 */
+type LedgerIdentityTables = {
+    /** `TDGroupMemberEmail`. */
+    ledger: AuthDirectoryTables["TDGroupMemberEmail"];
+    /** `TMGroup` — owns the tenant and the active flag. テナントと有効フラグの所有者。 */
+    group: AuthzTables["TMGroup"];
+};
+/**
+ * Finds every ledger row that belongs to the identity, within one tenant.
+ * 1 テナント内で、その identity に属する台帳行をすべて探す処理。
+ *
+ * 上流 ID の一致は無条件に本人。アドレスの一致は、その行が **別の** 上流 ID に紐付いていない
+ * ときだけ本人である。単純な `OR` にすると後者の条件が消え、退職者のアドレスを再利用した
+ * 新入社員が前任者の所属をそのまま継承する。
+ *
+ * ⚠️ この優先順位は **行ごと** に適用する。「ID で当たったらアドレスは見ない」という打ち切りは
+ * 誤りで、同じ人物の行が ID 付きと ID 無しに混在すると ID 無しの行が丸ごと落ちる。
+ *
+ * @param db - Connected database surface. 接続済みの DB 面。
+ * @param tables - The ledger and its parent group table. 台帳と親グループ表。
+ * @param args - Tenant scope and the identity to match. テナント範囲と突合対象の identity。
+ * @returns Matching rows, deduplicated and ordered by ledger id. 重複排除・台帳 ID 昇順の一致行。
+ */
+declare function findLedgerRowsForIdentity(db: DirectoryDb, tables: LedgerIdentityTables, args: {
+    tenantId: string;
+    externalUserId: string | null;
+    email: string;
+}): Promise<LedgerIdentityRow[]>;
+
+/**
+ * @module link-store
+ * @description Reads and writes the identity-side tables: external group links, the upstream member
+ * ledger, tenant membership proof, group-based login allowlist, and the sync request queue.
+ * identity 側テーブルの読み書き。外部グループリンク・上流メンバー台帳・テナント帰属証明・
+ * グループ単位のログイン許可・同期要求キュー。
+ *
+ * **テナントの扱いは 2 種類ある。混同すると事故になる。**
+ *
+ * - **絞り込み条件**: リンク・帰属証明グループ。読み書きの双方で SQL 述語になる。
+ * - **所有者**: グループ許可。管理 UI の編集スコープを決めるだけで、**ログイン判定では
+ *   述語にしない** — 認証はテナントの確定より前に起きるため、判定の時点でテナントは存在しない。
+ *   このモジュールでは {@link createDirectoryLinkStore} の `isEmailAllowedByGroup` だけが
+ *   その例外であり、意図的に全テナントを対象とする。
+ */
+
+/**
+ * Proves a group may become externally sourced. グループを外部供給にしてよいことの証明。
+ *
+ * `assertGroupMayBeLinked` を呼ぶだけのポートである。自由関数のままだと呼び出し側が忘れられ、
+ * 「ローカルで管理ロールを付けてから連携させる」経路が残る。必須の構成項目にすることで、
+ * 忘れることを構造的に不可能にする。
+ */
+type LinkableAssertion = {
+    /**
+     * Owns a transaction, proves the group may be linked on it, then runs `write` on the same runner.
+     * トランザクションを所有し、その上で連携可能であることを証明してから、同じランナーで `write` を実行する処理。
+     *
+     * ⚠️ **証明だけを返す形にしてはならない。** 証明と連携の作成が別のトランザクションだと、
+     * 証明を通った直後・リンクを作る前に、そのグループへ管理ロールを割り当てる操作が
+     * 割り込める。割り当て側の検査は「まだリンクが無い」と見て通り、連携側の検査は
+     * 「まだ管理ロールが無い」と見て通る — **どちらも単独では正しく、結果だけが不変条件を破る**。
+     *
+     * @param tenantId - Tenant that owns the group. グループを所有するテナント。
      * @param groupId - Group about to become externally sourced. 外部供給にしようとしているグループ。
      * @param write - The link creation, run on the proving transaction. 証明したトランザクション上で行う連携作成。
      * @returns Nothing. 戻り値なし。
@@ -1224,6 +1673,14 @@ type LinkGroupInput = {
     externalKey: string;
     membershipMode: AuthDirectoryMembershipMode;
 };
+/**
+ * What `requestSync` did. `requestSync` が行ったこと。
+ *
+ * ⚠️ `void` にしてはならない。同じ範囲の要求が既に待っているとき、積み増さないのは正しいが、
+ * それを成功と区別せずに返すと、押しても反応しない画面ができる — しかも詰まった 1 行が以後の
+ * 押下すべてを飲み込む。呼び出し側が運用者へ言えるだけの情報を返す。
+ */
+type SyncRequestOutcome = "queued" | "already-pending";
 /**
  * Creates the identity-side data store.
  * identity 側のデータストアを生成する処理。
@@ -1277,7 +1734,7 @@ declare function createDirectoryLinkStore(dbUnknown: unknown, tables: AuthDirect
      *
      * @param groupId `null` requests every group of the tenant. `null` はテナント全件。
      */
-    requestSync(tenantId: string, groupId: number | null, requestedBy: string): Promise<void>;
+    requestSync(tenantId: string, groupId: number | null, requestedBy: string): Promise<SyncRequestOutcome>;
     /**
      * Summarizes synchronization health for the admin header.
      * 管理ヘッダー向けに同期の健全性を要約する処理。
@@ -1312,8 +1769,10 @@ declare function createDirectoryLinkStore(dbUnknown: unknown, tables: AuthDirect
      * @param isBreakGlass - True for the locally-managed recovery path. 復帰経路なら true。
      * @param actor - Who performed it. 実行者。
      * @returns Nothing. 戻り値なし。
-     * @throws {Error} When the group is not in the tenant, or a break-glass group is linked.
-     *   自テナントに無い場合、または break-glass に連携済みグループを指定した場合。
+     * @throws {Error} When the group is not in the tenant, when a break-glass group is linked,
+     *   or when the result would be a proof with no break-glass path.
+     *   自テナントに無い場合、break-glass に連携済みグループを指定した場合、または結果が
+     *   「証明はあるが復帰経路が無い」方針になる場合。
      */
     setTenantMembershipGroup(tenantId: string, groupId: number, isBreakGlass: boolean, actor: string): Promise<void>;
     /**
@@ -1505,6 +1964,8 @@ declare function createPromotionRepository(dbUnknown: unknown, tables: AuthDirec
  * 述語) が使うため、分割の基準にはここから余裕を引いた値を用いる。
  */
 declare const MAX_PARAMETERS = 2100;
+/** Parameters reserved for the statement's own scalar values. 文自身のスカラー値のための予約枠。 */
+declare const RESERVED_PARAMETERS = 100;
 /**
  * Maximum ids per `IN` list of single-column predicates. 単列述語の `IN` 句 1 回あたりの最大 ID 数。
  *
@@ -1548,18 +2009,47 @@ declare function chunkByParameters<T>(items: readonly T[], parametersPerItem: nu
  * 既定は日本語 (このリポジトリの管理 UI に合わせる)。
  */
 
+/**
+ * Why a read or a write failed, classified for display. 読み書きが失敗した理由 (表示用の分類)。
+ *
+ * ⚠️ **例外文をそのまま `sync_error` へ入れてはならない。** この列は管理 UI のバナーとして
+ * **全タブに** 出るため、閲覧権限しか持たない主体が上流の生の応答本文 (サービスアカウントの
+ * アドレス、内部 URL、資格情報の断片) や DB の接続文字列・スキーマ名を読めてしまう。しかも
+ * それは、候補一覧の **グループ名すら** 見せないと決めた相手である。原文はログへ、画面へは分類を。
+ */
+type SyncFailureCause = "denied" | "rateLimited" | "upstreamError" | "timeout" | "localWriteError" | "unknown";
+/**
+ * Classifies a thrown value without quoting it. 投げられた値を、引用せずに分類する処理。
+ *
+ * 上流アダプタの型に依存しないよう、`status` という数値プロパティの有無だけで判定する。
+ * 判別できないものは `unknown` へ倒す (推測した分類を出すより、判らないと言う方が正しい)。
+ *
+ * @param error - The thrown value. 投げられた値。
+ * @returns The display classification. 表示用の分類。
+ */
+declare function classifySyncFailure(error: unknown): SyncFailureCause;
 /** The messages one synchronization can produce. 同期が生成し得る文言。 */
 type SyncMessages = {
     /** The upstream could not be read at all. 上流をまったく読めなかった。 */
-    upstreamUnreadable: (reason: string) => string;
+    upstreamUnreadable: (cause: SyncFailureCause) => string;
     /** The local write failed. ローカルへの書込が失敗した。 */
-    localWriteFailed: (reason: string) => string;
+    localWriteFailed: (cause: SyncFailureCause) => string;
     /** The resolver returned fewer members than the upstream listed. 突合が件数を減らした。 */
     resolverIncomplete: (upstream: number, resolved: number) => string;
     /** The group is missing upstream but not yet deactivated. 消滅の観測 (未確定)。 */
     groupMissing: (externalKey: string, observations: number, threshold: number) => string;
     /** The group has been deactivated after repeated absence. 消滅確定・無効化。 */
     groupVanished: (externalKey: string, observations: number) => string;
+    /**
+     * Removals whose write failed for a transient reason. 一時的な理由で書けなかった削除。
+     *
+     * ⚠️ 拒否とは別の文言にする。「最後の管理者ガードが止めた」は人手を呼ぶ答えであり、
+     * デッドロックや接続断に対して同じ文言を出すと、待てば直る事象に人を動かすことになる。
+     */
+    removalWritesFailed: (failures: readonly {
+        userId: number;
+        cause: SyncFailureCause;
+    }[]) => string;
     /** The reconciler refused the plan. 突合が plan を拒否した。 */
     planRefused: (abort: SyncAbort) => string;
     /** The lockout guard refused some removals. ロックアウトガードが一部の削除を拒否した。 */
@@ -1570,7 +2060,6 @@ type SyncMessages = {
     /** The link belongs to a different provider. 他 provider のリンクだった。 */
     foreignProvider: (linkProvider: string, runnerProvider: string) => string;
 };
-/** Default Japanese messages. 既定の日本語文言。 */
 declare const defaultSyncMessages: SyncMessages;
 
 /**
@@ -1607,6 +2096,21 @@ type SyncLink = {
      */
     vanishedObservations: number;
 };
+/**
+ * Which links a run covers. 1 回の実行が対象にするリンクの範囲。
+ *
+ * ⚠️ `tenantId` は **必須** である。1 つのジョブが持つ上流の資格情報は 1 つのテナントに対応する。
+ * 範囲を絞らないと、別テナントのリンクを読んだうえで **自分の資格情報で得た結果をその別テナントへ
+ * 書き込む**。上流が 404 を返せば (借用先の外にあるグループでは通常そうなる) 消滅と判定して
+ * 相手のグループを無効化し、外部 ID が偶然一致すれば相手のグループへ自分の所属を射影する。
+ * 要求した側の権限は一切関係しないため、既定値 1 つで越境が成立する形にしてはならない。
+ * 同じ理由で `createSyncRequestQueue` も構築時にテナントを固定する。
+ */
+type SyncScope = {
+    tenantId: string;
+    /** Restrict further to one group within the tenant. テナント内の 1 グループへさらに絞る。 */
+    groupId?: number;
+};
 /** Why one group's synchronization ended the way it did. 1 グループの同期がどう終わったか。 */
 type SyncOutcome = {
     kind: "applied";
@@ -1635,6 +2139,17 @@ type SyncOutcome = {
     kind: "vanished";
     link: SyncLink;
 }
+/**
+ * Still missing, and already deactivated on an earlier run. 消滅済みで、以前の実行で無効化済み。
+ *
+ * ⚠️ `vanished` と分ける理由は、**運用通知が状態ではなく変化に反応するべき** だからである。
+ * 同じ 1 件の消滅を掃引のたびに通知すると、本当に新しい消滅がその中に埋もれる。この結末は
+ * 「今回の掃引では何も変わっていない」ことの表明であり、健全ではないが新規でもない。
+ */
+ | {
+    kind: "already-vanished";
+    link: SyncLink;
+}
 /** Reading upstream failed. 上流の読み取りが失敗した。 */
  | {
     kind: "upstream-failed";
@@ -1651,7 +2166,30 @@ type SyncOutcome = {
  | {
     kind: "foreign-provider";
     link: SyncLink;
+}
+/**
+ * The plan was applied only in part. plan の一部しか適用できなかった。
+ *
+ * ⚠️ `applied` と分ける。拒否や書込失敗が残ったまま「適用済み」と答えると、上流が外した人物が
+ * グループに残っているのに、鮮度は健全・通知は無音・要求キューの結果は成功になる — 収束して
+ * いないことを示す信号がどこにも出ない。
+ */
+ | {
+    kind: "not-converged";
+    link: SyncLink;
+    plan: GroupSyncPlan;
+    refusals: RemovalOutcome[];
+    failures: RemovalFailure[];
 };
+/**
+ * Outcomes that mean something changed for the worse on this run. この実行で新たに悪化した結末。
+ *
+ * ⚠️ **状態ではなく変化を数える。** `already-vanished` は不健全な状態ではあるが、以前の実行で
+ * 既に記録・通知済みであり、今回の掃引では何も変わっていない。ここに入れると同じ 1 件が周期ぶん
+ * 通知され、本当に新しい消滅が埋もれる。「今どれだけ壊れているか」を数えたい呼び出し側は
+ * {@link UNHEALTHY_SYNC_OUTCOMES} を使う。
+ */
+declare const NEWLY_UNHEALTHY_SYNC_OUTCOMES: readonly SyncOutcome["kind"][];
 /** Outcomes that mean the group is not in a healthy, converged state. 健全でない結末。 */
 declare const UNHEALTHY_SYNC_OUTCOMES: readonly SyncOutcome["kind"][];
 /** What happened to one guarded removal. ガード付き削除 1 件の結末。 */
@@ -1660,10 +2198,24 @@ type RemovalOutcome = {
     applied: boolean;
     refusal?: string;
 };
+/**
+ * One removal the write itself could not complete. 書き込み自体が完了しなかった削除 1 件。
+ *
+ * ⚠️ **拒否とは別に数える。** 「最後の管理者を失う」はガードの判断であり、運用者への答えは
+ * 「別の管理者を立てよ」である。一方でデッドロックの犠牲や接続断は待てば直るものであり、
+ * 答えは「再試行せよ」である。両方を同じ袋に入れると、待てば直る事象に対して人手を呼び、
+ * 人手が要る事象を放置することになる。
+ */
+type RemovalFailure = {
+    userId: number;
+    cause: SyncFailureCause;
+};
 /** What `applyPlan` actually managed to do. `applyPlan` が実際に行えたこと。 */
 type ApplyReport = {
     /** Removals the administrator lockout guard refused. ロックアウトガードが拒否した削除。 */
     refusals: RemovalOutcome[];
+    /** Removals whose write failed for a transient reason. 一時的な理由で書けなかった削除。 */
+    failures: RemovalFailure[];
 };
 /**
  * Storage operations the synchronization performs.
@@ -1678,10 +2230,7 @@ type DirectorySyncRepository = {
      *
      * @param scope Restrict to one tenant, or one group within it. テナント、または特定グループへ限定。
      */
-    listSyncableLinks(scope: {
-        tenantId?: string;
-        groupId?: number;
-    }): Promise<SyncLink[]>;
+    listSyncableLinks(scope: SyncScope): Promise<SyncLink[]>;
     /** Reads the local ledger and the real membership for one group. 台帳と実所属を読む処理。 */
     loadGroupSnapshot(link: SyncLink): Promise<LocalGroupSnapshot>;
     /**
@@ -1708,6 +2257,23 @@ type DirectorySyncRepository = {
      */
     applyPlan(link: SyncLink, plan: GroupSyncPlan, observedAt: Date): Promise<ApplyReport>;
     /** Records a successful run and reactivates the group if it was deactivated. 成功の記録。 */
+    /**
+     * Persists the upstream's stable identity before any membership is applied.
+     * 所属を適用する **前** に、上流の安定 ID を確定させる処理。
+     *
+     * ⚠️ **順序がこの操作の意味である。** 管理面は、候補一覧が引けない配備ではアドレスを暫定の
+     * 安定 ID として保存する。同じ上流グループを別の綴り (アドレスと別名、あるいは本当の ID) で
+     * 2 回リンクできてしまい、`UNIQUE (tenant, provider, external_id)` も文字列が違うので通る。
+     * 確定を所属の適用より前に置くことで、重複したリンクは **何も投影しないまま** 一意制約に
+     * 当たって落ちる。後に置くと、二重の所属が先に commit され、両方のロールが配られてから
+     * 書き戻しだけが失敗し続ける。
+     *
+     * @param link - The link being synchronized. 同期中のリンク。
+     * @param upstreamGroup - What the upstream answered. 上流が答えた内容。
+     * @returns Nothing. 戻り値なし。
+     * @throws When another link already owns this upstream group. 同じ上流を別のリンクが持つ場合。
+     */
+    resolveExternalIdentity(link: SyncLink, upstreamGroup: DirectoryGroup): Promise<void>;
     recordSuccess(link: SyncLink, group: DirectoryGroup, syncedAt: Date): Promise<void>;
     /** Records a failure reason against the link, leaving membership untouched. 失敗を記録する処理。 */
     recordFailure(link: SyncLink, reason: string): Promise<void>;
@@ -1778,6 +2344,14 @@ type DirectorySyncRunResult = {
      * 最も重い結末であり、それを「0 unhealthy」と報告しては監視の意味がない。
      */
     unhealthyCount: number;
+    /**
+     * Links that became unhealthy on this run. この実行で新たに不健全になったリンク数。
+     *
+     * ⚠️ 通知はこちらで判断する。`unhealthyCount` は状態の量なので、消滅済みのグループが 1 つ
+     * 残っているだけで毎周期 1 以上になり、同じ 1 件を周期ぶん通知し続ける — 本当に新しい
+     * 消滅がその中に埋もれる。数えるのは状態、知らせるのは変化である。
+     */
+    newlyUnhealthyCount: number;
 };
 /**
  * Creates a synchronization runner. 同期ランナーを生成する処理。
@@ -1795,13 +2369,10 @@ declare function createDirectorySync(config: DirectorySyncConfig): {
      * 弾かれたグループだけが失敗して部分的に古い状態が残る。1 グループの失敗は他へ
      * 波及させず、実行自体は最後まで続ける。
      *
-     * @param scope Restrict to one tenant, or one group within it. 対象範囲。
+     * @param scope Which tenant (and optionally which group) to cover. 対象テナントと範囲。
      * @returns Every outcome, and how many ended unhealthy. 全結果と不健全件数。
      */
-    run(scope?: {
-        tenantId?: string;
-        groupId?: number;
-    }): Promise<DirectorySyncRunResult>;
+    run(scope: SyncScope): Promise<DirectorySyncRunResult>;
 };
 
 /** One claimed request. 取得済みの要求 1 件。 */
@@ -1812,6 +2383,23 @@ type ClaimedSyncRequest = {
     groupId: number | null;
     requestedBy: string;
 };
+/**
+ * Requests that are not progressing. 進んでいない要求。
+ *
+ * ⚠️ 2 つを分けて数える。`stranded` は「掴まれたが終わっていない」— ジョブが落ちた跡である。
+ * `unclaimed` は「誰にも掴まれていない」— **そのテナントを担当するジョブが居ない** 跡であり、
+ * 掴まれた行だけを見ていると丸ごと見落とす。重複抑止が在るため、後者は 1 行で以後の要求すべてを
+ * 黙って捨てる。
+ */
+type StrandedRequests = {
+    stranded: number[];
+    unclaimed: number[];
+};
+/**
+ * Recorded when a request is closed because the process that claimed it never finished it.
+ * 掴んだプロセスが終わりを書かなかったために閉じた要求へ記録される理由。
+ */
+declare const STRANDED_REASON = "The job that claimed this request ended without recording an outcome; whether the synchronization ran is unknown.";
 /** How a claimed request ended. 取得した要求の終わり方。 */
 type SyncRequestResult = {
     result: "succeeded" | "failed";
@@ -1820,8 +2408,30 @@ type SyncRequestResult = {
 /** Options for {@link createSyncRequestQueue}. キュー消費側の生成オプション。 */
 type SyncRequestQueueOptions = {
     ensureConnection?: EnsureConnection;
+    /**
+     * The only tenant this consumer may claim for. この消費側が取得してよい唯一のテナント。
+     *
+     * ⚠️ **必須である。** 1 つのジョブが持つ上流の資格情報は 1 つのテナントに対応する。範囲を
+     * 絞らないと、別テナントの要求を掴んだジョブが **自分の資格情報で読んだ結果を、その別テナントへ
+     * 書き込む**。要求を出した側の権限は一切関係しないため、これは要求 1 つで越境が起きる形になる。
+     *
+     * ⚠️ その代償として、**担当ジョブの居ないテナントの要求は誰にも観測されない**。`listStranded`
+     * もこのテナントに絞られる以上、消費側が存在しないテナントを数える主体はどこにも居ない。
+     * 見えるのは web 側だけである — `getStatus().pendingRequestCount` が管理面のバナーに出て、
+     * `requestSync` は 2 度目以降を `already-pending` として返す。配備時は、リンクを持つ
+     * すべてのテナントにジョブを 1 つずつ立てること。
+     */
+    tenantId: string;
     /** Injected clock — the run's timestamps must all come from one source. 注入時計。 */
     now: () => Date;
+    /**
+     * Reports a request that could not be closed. 閉じられなかった要求を報告する処理。
+     *
+     * ⚠️ {@link createSyncRequestQueue.abandonStranded} は 1 件の失敗で残りを諦めない。
+     * 諦めない以上、失敗そのものが黙って消える経路になってはならない — 記録の宛先は
+     * 呼び出し側が持っているので、ここから渡す。省略時は何もしない。
+     */
+    onCloseFailed?: (id: number, error: unknown) => void;
     /**
      * Longest an error message may be, matching the column. 列に合わせたエラー文の上限長。
      *
@@ -1859,15 +2469,39 @@ declare function createSyncRequestQueue(dbUnknown: unknown, tables: AuthDirector
      */
     finish(id: number, outcome: SyncRequestResult): Promise<void>;
     /**
-     * Lists requests claimed long ago but never finished. 取得後に完了しなかった要求の一覧。
+     * Lists requests that are not progressing. 進んでいない要求の一覧。
      *
      * ジョブが落ちると、行は取得済みのまま完了しない。放置すると要求した人はいつまでも
      * 結果を見られないので、運用が拾えるよう明示的に数えられる形にしておく。
      *
-     * @param olderThan - Cutoff for `picked_at`. `picked_at` の締切時刻。
-     * @returns The stranded request ids. 取り残された要求の ID。
+     * ⚠️ **掴まれていない古い行も数える。** 取得済みだけを見ると、そのテナントを担当する
+     * ジョブが居ない場合が丸ごと盲点になる — その行は永久に処理されないのに、重複抑止の
+     * せいで以後の「今すぐ同期」まで黙って捨てられる。
+     *
+     * @param olderThan - Cutoff for both timestamps. 両方の時刻に対する締切時刻。
+     * @returns Stranded and unclaimed request ids. 取り残された要求と、掴まれていない要求の ID。
+     */
+    listStranded(olderThan: Date): Promise<StrandedRequests>;
+    /**
+     * Closes stranded requests as failed, so the queue can move again.
+     * 取り残された要求を失敗として閉じ、キューを再び動かす処理。
+     *
+     * ⚠️ **掴んだ行を未処理へ戻さない。** 戻すと `UQ_..._pending` (未処理行の一意制約) に
+     * 衝突し得る — 同じ範囲の新しい要求が既に並んでいれば、戻す操作そのものが失敗する。
+     * 失敗として閉じれば、監査記録は残り、要求した人は結果 (失敗) を見られ、次の「今すぐ
+     * 同期」は重複抑止に掛からない。
+     *
+     * ⚠️ **走ったかどうかは分からない。** 記録する理由も、成否ではなく「掴んだプロセスが
+     * 終わりを書かなかった」という観測事実だけにする。推測を記録に混ぜない。
+     *
+     * ⚠️ 掴まれていない行 (`unclaimed`) には触れない。あれはジョブが落ちた跡ではなく
+     * **担当ジョブが居ない** 跡であり、閉じると原因が消えて再発し続ける。
+     *
+     * @param olderThan - Requests picked before this are considered abandoned.
+     *   これより前に掴まれた要求を放棄と見なす締切時刻。
+     * @returns The ids closed. 閉じた要求の ID。
      */
-    listStranded(olderThan: Date): Promise<number[]>;
+    abandonStranded(olderThan: Date): Promise<number[]>;
 };
 
 /**
@@ -1886,6 +2520,15 @@ type MemberResolverPort = {
 /** Options for the synchronization repository. 同期リポジトリの構成。 */
 type SyncRepositoryOptions = {
     ensureConnection?: EnsureConnection;
+    /**
+     * Wall-clock supplier. 実行の時刻を供給する処理。
+     *
+     * ⚠️ 走査側 (`createDirectorySync`) は時計を注入されており、「1 回の実行の中で観測時刻と
+     * 同期時刻が別々に進むと、どの行がどの実行で書かれたのか後から辿れなくなる」という理由が
+     * 書いてある。記憶域側だけが `new Date()` を直に読むと、**同じ実行の中で 2 つの時計が進む** —
+     * 失敗の記録と成功の記録が別の時刻を持ち、その理由は誰にも判らない。省略時は実時計。
+     */
+    now?: () => Date;
     memberResolver: MemberResolverPort;
     /** Lockout guard from `@aiquants/authz-drizzle`. 認可側のロックアウトガード。 */
     lockoutGuard: ReturnType<typeof createAdminLockoutGuard>;
@@ -1910,4 +2553,4 @@ type SyncRepositoryOptions = {
  */
 declare function createDirectorySyncRepository(dbUnknown: unknown, tables: AuthDirectoryTables, authzTables: AuthzTables, opts: SyncRepositoryOptions): DirectorySyncRepository;
 
-export { AUTH_DIRECTORY_PROVIDER_COLUMN, AUTH_DIRECTORY_TENANT_SCOPED_TABLES, type ApplyReport, type AuthDirectoryTables, type ClaimedSyncRequest, type DeleteChain, type DirectoryDb, type DirectoryLinkRow, type DirectoryLinkStoreOptions, type DirectorySyncConfig, type DirectorySyncRepository, type DirectorySyncRunResult, type EnsureConnection, type ExternalGroupGuardOptions, type ExternalLinkLookup, type InsertChain, type LedgerIdentityRow, type LedgerIdentityTables, type LinkGroupInput, type LinkableAssertion, MAX_IN_LIST, MAX_PARAMETERS, MEMBERSHIP_MODES, type MemberResolverPort, type PromotionRepository, type PromotionRepositoryOptions, type PromotionResult, type ReferencedTable, type RemovalOutcome, type SelectChain, type SyncLink, type SyncLoggerPort, type SyncMessages, type SyncOutcome, type SyncRepositoryOptions, type SyncRequestQueueOptions, type SyncRequestResult, UNHEALTHY_SYNC_OUTCOMES, type UpdateChain, assertGroupMayBeLinked, assertMembershipMode, chunk, chunkByParameters, createDirectoryLinkStore, createDirectorySync, createDirectorySyncRepository, createPromotionRepository, createSyncRequestQueue, defaultExternalGroupGuardMessage, defaultSyncMessages, defineAuthDirectorySchema, findLedgerRowsForIdentity, promoteLedgerForUser, withExternalGroupGuards };
+export { AUTH_DIRECTORY_PROVIDER_COLUMN, AUTH_DIRECTORY_TENANT_SCOPED_TABLES, type ApplyReport, type AuthDirectoryTables, type ClaimedSyncRequest, type DeleteChain, type DirectoryCatalogEntry, type DirectoryCatalogReaderOptions, type DirectoryCatalogSnapshot, type DirectoryCatalogWriterOptions, type DirectoryDb, type DirectoryLinkRow, type DirectoryLinkStoreOptions, type DirectorySyncConfig, type DirectorySyncRepository, type DirectorySyncRunResult, type EnsureConnection, type ExternalGroupGuardOptions, type ExternalLinkLookup, type InsertChain, type LedgerIdentityRow, type LedgerIdentityTables, type LinkGroupInput, type LinkableAssertion, MAX_IN_LIST, MAX_PARAMETERS, MEMBERSHIP_MODES, type MemberResolverPort, NEWLY_UNHEALTHY_SYNC_OUTCOMES, type PromotionRepository, type PromotionRepositoryOptions, type PromotionResult, RESERVED_PARAMETERS, type ReferencedTable, type RemovalFailure, type RemovalOutcome, STRANDED_REASON, type SelectChain, type StrandedRequests, type SyncFailureCause, type SyncLink, type SyncLoggerPort, type SyncMessages, type SyncOutcome, type SyncRepositoryOptions, type SyncRequestOutcome, type SyncRequestQueueOptions, type SyncRequestResult, type SyncScope, UNHEALTHY_SYNC_OUTCOMES, type UpdateChain, assertGroupMayBeLinked, assertMembershipMode, chunk, chunkByParameters, classifySyncFailure, createDirectoryCatalogReader, createDirectoryCatalogWriter, createDirectoryLinkStore, createDirectorySync, createDirectorySyncRepository, createPromotionRepository, createSyncRequestQueue, defaultExternalGroupGuardMessage, defaultSyncMessages, defineAuthDirectorySchema, findLedgerRowsForIdentity, promoteLedgerForUser, toInstant, withExternalGroupGuards };