@sovovs/bycli 2.1.40 → 2.1.41

package/cli-manifest.json

@@ -29080,7 +29080,11 @@
     "type": "js",
     "modulePath": "weixin/download.js",
     "sourceFile": "weixin/download.js",
-    "navigateBefore": "https://mp.weixin.qq.com"
+    "navigateBefore": "https://mp.weixin.qq.com",
+    "adapterConcurrency": {
+      "isolatedTabs": true,
+      "maxParallel": 3
+    }
   },
   {
     "site": "weixin",
@@ -29159,7 +29163,11 @@
     "type": "js",
     "modulePath": "weixin/download-publish-data.js",
     "sourceFile": "weixin/download-publish-data.js",
-    "navigateBefore": false
+    "navigateBefore": false,
+    "adapterConcurrency": {
+      "isolatedTabs": true,
+      "maxParallel": 3
+    }
   },
   {
     "site": "weixin",

package/clis/weixin/_wechat/article-artifact.js

@@ -0,0 +1,55 @@
+import { constants } from 'node:fs';
+import { access, readFile, realpath, stat } from 'node:fs/promises';
+import { dirname, extname, relative, resolve } from 'node:path';
+import { CommandExecutionError } from '@sovovs/bycli/errors';
+
+function isContained(parent, child) {
+  const rel = relative(parent, child);
+  return rel === '' || (!rel.startsWith('..') && !rel.startsWith('/') && !rel.startsWith('\\'));
+}
+
+async function validateRegularNonEmptyFile(path, label) {
+  await access(path, constants.R_OK);
+  const info = await stat(path);
+  if (!info.isFile() || info.size <= 0) throw new Error(`${label} is empty or not a regular file`);
+  return realpath(path);
+}
+
+function localMarkdownImageTargets(markdown) {
+  const targets = [];
+  for (const match of markdown.matchAll(/!\[[^\]]*\]\(([^)]+)\)/g)) {
+    let target = match[1].trim();
+    if (target.startsWith('<') && target.endsWith('>')) target = target.slice(1, -1);
+    target = target.split(/\s+["']/u, 1)[0];
+    if (!target || /^(?:https?:|data:|#|\/\/)/iu.test(target)) continue;
+    targets.push(decodeURI(target));
+  }
+  return targets;
+}
+
+export async function validateDownloadedArticleRows(rows, outputDir) {
+  try {
+    const successfulRows = rows.filter(row => row && String(row.status).toLowerCase() === 'success');
+    if (successfulRows.length === 0) return rows;
+    const resolvedOutput = await realpath(resolve(outputDir));
+    for (const row of successfulRows) {
+      if (typeof row.saved !== 'string' || extname(row.saved).toLowerCase() !== '.md') {
+        throw new Error('successful article row returned no Markdown path');
+      }
+      const saved = await validateRegularNonEmptyFile(resolve(row.saved), 'saved Markdown');
+      if (!isContained(resolvedOutput, saved)) throw new Error('saved Markdown escaped the output directory');
+      const articleDir = dirname(saved);
+      const markdown = await readFile(saved, 'utf8');
+      for (const target of localMarkdownImageTargets(markdown)) {
+        const image = await validateRegularNonEmptyFile(resolve(articleDir, target), 'local Markdown image');
+        if (!isContained(articleDir, image)) throw new Error('local Markdown image escaped the article directory');
+      }
+    }
+    return rows;
+  } catch (error) {
+    if (error instanceof CommandExecutionError) throw error;
+    throw new CommandExecutionError(
+      `Downloaded Weixin article artifact validation failed: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+}

package/clis/weixin/_wechat/article-identity.js

@@ -0,0 +1,27 @@
+import { createHash } from 'node:crypto';
+
+export function hashResourceValue(value) {
+  return createHash('sha256').update(String(value)).digest('hex');
+}
+
+export function canonicalWechatArticleIdentity(rawUrl) {
+  const url = new URL(rawUrl);
+  url.hash = '';
+  const host = url.hostname.toLowerCase();
+  let canonical;
+  if (url.pathname.startsWith('/s/')) {
+    canonical = `${host}${url.pathname}`;
+  } else {
+    const tupleNames = ['__biz', 'mid', 'idx', 'sn'];
+    const hasTuple = tupleNames.every(name => url.searchParams.has(name));
+    if (url.pathname === '/s' && hasTuple) {
+      canonical = `${host}/s?${tupleNames.map(name => `${name}=${url.searchParams.get(name)}`).join('&')}`;
+    } else {
+      const sorted = [...url.searchParams.entries()]
+        .sort(([leftKey, leftValue], [rightKey, rightValue]) => leftKey.localeCompare(rightKey) || leftValue.localeCompare(rightValue));
+      const query = new URLSearchParams(sorted).toString();
+      canonical = `${host}${url.pathname}${query ? `?${query}` : ''}`;
+    }
+  }
+  return hashResourceValue(canonical);
+}

package/clis/weixin/_wechat/publish-analysis.js

@@ -427,7 +427,7 @@ function safeFilename(title) {
   return `${name}.md`;
 }
 
-async function publishMarkdown(outputDir, filename, content) {
+async function publishMarkdown(outputDir, filename, content, beforePublish) {
   await mkdir(outputDir, { recursive: true });
   const temporary = resolve(outputDir, `.bycli-publish-analysis-${randomUUID()}.tmp`);
   await writeFile(temporary, content, { encoding: 'utf8', flag: 'wx' });
@@ -436,13 +436,17 @@ async function publishMarkdown(outputDir, filename, content) {
     const stem = filename.slice(0, -extension.length);
     for (let index = 0; index <= 9999; index += 1) {
       const path = resolve(outputDir, index === 0 ? filename : `${stem}-${index}${extension}`);
-      try { await link(temporary, path); return path; } catch (error) { if (error?.code !== 'EEXIST') throw error; }
+      try {
+        await beforePublish?.();
+        await link(temporary, path);
+        return path;
+      } catch (error) { if (error?.code !== 'EEXIST') throw error; }
     }
     throw new CommandExecutionError('WeChat publish analysis could not allocate a report filename');
   } finally { await unlink(temporary).catch(() => {}); }
 }
 
-export async function collectPublishAnalysis(page, { detailUrl, title, publishedAt, outputDir }) {
+export async function collectPublishAnalysis(page, { detailUrl, title, publishedAt, outputDir, beforePublish }) {
   if (typeof page?.goto !== 'function' || typeof page?.readNetworkCapture !== 'function') {
     throw new CommandExecutionError('WeChat publish analysis requires browser network capture support');
   }
@@ -480,7 +484,7 @@ export async function collectPublishAnalysis(page, { detailUrl, title, published
   }
   if (Object.keys(data).length === 0) throw new CommandExecutionError('WeChat publish analysis returned no readable analysis data');
   const content = formatAnalysisMarkdown({ title, publishedAt, data });
-  const path = await publishMarkdown(resolve(outputDir), safeFilename(title), content);
+  const path = await publishMarkdown(resolve(outputDir), safeFilename(title), content, beforePublish);
   const info = await stat(path);
   return { status: 'saved', path, size: info.size, metrics };
 }

package/clis/weixin/_wechat/publish-download.js

@@ -37,7 +37,7 @@ function safeFilename(title) {
   return name;
 }
 
-async function publishExclusively(source, outputDir, filename) {
+async function publishExclusively(source, outputDir, filename, beforePublish) {
   const extension = extname(filename);
   const stem = filename.slice(0, -extension.length);
   const temporary = resolve(outputDir, `.bycli-publish-data-${randomUUID()}.tmp`);
@@ -61,6 +61,7 @@ async function publishExclusively(source, outputDir, filename) {
     for (let index = 0; index <= 9999; index += 1) {
       const candidate = resolve(outputDir, index === 0 ? filename : `${stem}-${index}${extension}`);
       try {
+        await beforePublish?.();
         await link(temporary, candidate);
         return candidate;
       } catch (error) {
@@ -151,6 +152,7 @@ export async function downloadPublishData(page, options) {
     downloaded.filename,
     outputDir,
     safeFilename(options.title),
+    options.beforePublish,
   );
   try {
     await unlink(downloaded.filename);

package/clis/weixin/download-publish-data.js

@@ -3,6 +3,7 @@ import { access, stat } from 'node:fs/promises';
 import { extname, resolve } from 'node:path';
 import { ArgumentError, CommandExecutionError } from '@sovovs/bycli/errors';
 import { cli, Strategy } from '@sovovs/bycli/registry';
+import { assertCurrentAdapterLease, withAdapterResourceLocks } from '@sovovs/bycli/adapter-coordination';
 import { resolveBrowserCredentials } from './_wechat/auth-session.js';
 import { buildSecretSet, redactText } from './_wechat/redact.js';
 import { collectPublishAnalysis } from './_wechat/publish-analysis.js';
@@ -15,6 +16,7 @@ import {
   validatePublishDate,
   validatePublishedQuery,
 } from './_wechat/publish-records.js';
+import { canonicalWechatArticleIdentity, hashResourceValue } from './_wechat/article-identity.js';
 
 const METRIC_COLUMNS = [
   'readUsers', 'avgReadMinutes', 'finishedReadRatio', 'newFollowers', 'listenUsers',
@@ -35,6 +37,13 @@ function sanitizedError(error, secrets, fallback) {
     .replace(/https?:\/\/mp\.weixin\.qq\.com\/\S*/giu, '[REDACTED]');
 }
 
+function rethrowStopError(error) {
+  const code = error && typeof error === 'object' ? error.code : undefined;
+  if (code === 'AUTH_REQUIRED' || code === 'RATE_LIMITED' || code === 'CAPTCHA' || code === 'MFA_REQUIRED' || code === 'ADAPTER_LEASE_LOST') {
+    throw error;
+  }
+}
+
 async function validateArtifact(result, { label, expectedStatus, expectedExtension }) {
   if (!result || result.status !== expectedStatus) {
     throw new CommandExecutionError(`${label} returned an invalid status`);
@@ -71,6 +80,7 @@ export const downloadPublishDataCommand = cli({
   strategy: Strategy.INTERCEPT,
   browser: true,
   navigateBefore: false,
+  adapterConcurrency: { isolatedTabs: true, maxParallel: 3 },
   args: [
     { name: 'query', positional: true, required: true, help: 'Exact article URL or title text' },
     { name: 'date', help: 'Optional publication date in YYYY-MM-DD' },
@@ -104,9 +114,16 @@ export const downloadPublishDataCommand = cli({
       title: record.title,
       outputDir,
       timeoutSeconds,
+      beforePublish: assertCurrentAdapterLease,
     };
     const secrets = buildSecretSet({ token, cookie });
 
+    return withAdapterResourceLocks([
+      `article:${canonicalWechatArticleIdentity(record.url)}`,
+      `data:${hashResourceValue(`${record.msgid}:${record.publishDate ?? record.publishedAt}`)}`,
+      `output:${hashResourceValue(resolve(outputDir))}`,
+    ], async () => {
+
     let dataResult = null;
     let markdownResult = null;
     const errors = [];
@@ -118,6 +135,7 @@ export const downloadPublishDataCommand = cli({
         expectedExtension: '.xls',
       });
     } catch (error) {
+      rethrowStopError(error);
       errors.push(`Excel download failed: ${sanitizedError(error, secrets, 'Excel download failed')}`);
     }
     try {
@@ -131,6 +149,7 @@ export const downloadPublishDataCommand = cli({
         expectedExtension: '.md',
       });
     } catch (error) {
+      rethrowStopError(error);
       errors.push(`Markdown analysis failed: ${sanitizedError(error, secrets, 'Markdown analysis failed')}`);
     }
 
@@ -175,5 +194,6 @@ export const downloadPublishDataCommand = cli({
       detailLikes: metrics?.likes ?? null,
       detailComments: metrics?.comments ?? null,
     }];
+    });
   },
 });

package/clis/weixin/download.js

@@ -9,6 +9,8 @@
 import { cli, Strategy } from '@sovovs/bycli/registry';
 import { downloadArticle } from '@sovovs/bycli/download/article-download';
 import { AuthRequiredError } from '@sovovs/bycli/errors';
+import { assertCurrentAdapterLease, withAdapterResourceLocks } from '@sovovs/bycli/adapter-coordination';
+import { resolve } from 'node:path';
 import { buildExtractWechatArticleContentJs } from './_wechat/article-content.js';
 import {
     isTrustedSogouRedirectUrl,
@@ -16,6 +18,8 @@ import {
     normalizeWechatUrl,
     resolveWechatArticleUrl,
 } from './_wechat/article-link.js';
+import { canonicalWechatArticleIdentity, hashResourceValue } from './_wechat/article-identity.js';
+import { validateDownloadedArticleRows } from './_wechat/article-artifact.js';
 export { extractWechatArticleContent } from './_wechat/article-content.js';
 export {
     isTrustedSogouRedirectUrl,
@@ -152,6 +156,7 @@ cli({
     description: '下载微信公众号文章为 Markdown 格式',
     domain: 'mp.weixin.qq.com',
     strategy: Strategy.COOKIE,
+    adapterConcurrency: { isolatedTabs: true, maxParallel: 3 },
     args: [
         { name: 'url', required: true, help: 'WeChat article URL (mp.weixin.qq.com/s/xxx)' },
         { name: 'output', default: './weixin-articles', help: 'Output directory' },
@@ -160,6 +165,11 @@ cli({
     columns: ['title', 'author', 'publish_time', 'status', 'size', 'saved', 'source_url', 'resolved_url'],
     func: async (page, kwargs) => {
         const { sourceUrl, resolvedUrl, alreadyNavigated } = await resolveWechatArticleUrl(page, kwargs.url);
+        const outputDir = resolve(kwargs.output ?? './weixin-articles');
+        return withAdapterResourceLocks([
+            `article:${canonicalWechatArticleIdentity(resolvedUrl)}`,
+            `output:${hashResourceValue(outputDir)}`,
+        ], async () => {
         // Navigate and wait for content to load. Sogou resolution already lands on the article.
         if (!alreadyNavigated)
             await page.goto(resolvedUrl);
@@ -235,7 +245,7 @@ cli({
             codeBlocks: data?.codeBlocks,
             imageUrls: data?.imageUrls,
         }, {
-            output: kwargs.output,
+            output: outputDir,
             downloadImages: kwargs['download-images'],
             imageHeaders: { Referer: 'https://mp.weixin.qq.com/' },
             frontmatterLabels: { author: '公众号' },
@@ -244,7 +254,10 @@ cli({
                 return m ? m[1] : 'png';
             },
             secureMarkdown: true,
+            beforePublish: assertCurrentAdapterLease,
+        });
+        const validatedRows = await validateDownloadedArticleRows(rows, outputDir);
+        return validatedRows.map(row => ({ ...row, source_url: sourceUrl, resolved_url: resolvedUrl }));
         });
-        return rows.map(row => ({ ...row, source_url: sourceUrl, resolved_url: resolvedUrl }));
     },
 });

package/dist/src/adapter-coordination.d.ts

@@ -0,0 +1,26 @@
+import type { AdapterLease, AdapterLeaseRelease, AdapterLeaseRequest, AdapterResourceGrant } from './adapter-scheduler.js';
+export interface AdapterCoordinationDependencies {
+    acquire?: (request: AdapterLeaseRequest) => Promise<AdapterLease>;
+    heartbeat?: (lease: AdapterLease) => Promise<AdapterLease>;
+    release?: (release: AdapterLeaseRelease) => Promise<boolean>;
+    heartbeatIntervalMs?: number;
+    onLeaseLost?: () => Promise<void>;
+    warn?: (message: string) => void;
+}
+export declare function getCurrentAdapterLease(): AdapterLease | undefined;
+/**
+ * Renew the active lease immediately before an irreversible local publication.
+ * A restarted daemon or reclaimed lease rejects this fencing check.
+ */
+export declare function assertCurrentAdapterLease(dependencies?: {
+    heartbeat?: (lease: AdapterLease) => Promise<AdapterLease>;
+}): Promise<void>;
+export interface AdapterResourceDependencies {
+    acquire?: (lease: AdapterLease, keys: string[], timeoutMs: number) => Promise<AdapterResourceGrant>;
+    release?: (lease: AdapterLease, grantId: string) => Promise<boolean>;
+    timeoutMs?: number;
+    warn?: (message: string) => void;
+}
+export declare function settleAdapterOperationAfterTimeout<T>(operation: Promise<T>, timeoutMs: number, timeoutError: Error, stop: () => Promise<void>): Promise<T>;
+export declare function withAdapterResourceLocks<T>(keys: string[], operation: () => Promise<T>, dependencies?: AdapterResourceDependencies): Promise<T>;
+export declare function withAdapterCommandLease<T>(request: AdapterLeaseRequest, operation: () => Promise<T>, dependencies?: AdapterCoordinationDependencies): Promise<T>;

package/dist/src/adapter-coordination.js

@@ -0,0 +1,183 @@
+import { acquireAdapterLease, heartbeatAdapterLease, releaseAdapterLease, acquireAdapterResources, releaseAdapterResources, } from './browser/daemon-client.js';
+import { log } from './logger.js';
+import { AdapterCoordinationError } from './errors.js';
+import { getAdapterExecutionContext, runWithAdapterExecutionContext, } from './adapter-execution-context.js';
+export function getCurrentAdapterLease() {
+    return getAdapterExecutionContext()?.lease;
+}
+/**
+ * Renew the active lease immediately before an irreversible local publication.
+ * A restarted daemon or reclaimed lease rejects this fencing check.
+ */
+export async function assertCurrentAdapterLease(dependencies = {}) {
+    const context = getAdapterExecutionContext();
+    if (!context)
+        return;
+    try {
+        context.lease = await (dependencies.heartbeat ?? heartbeatAdapterLease)(context.lease);
+    }
+    catch (error) {
+        if (error instanceof AdapterCoordinationError && error.code === 'ADAPTER_LEASE_LOST')
+            throw error;
+        throw new AdapterCoordinationError('ADAPTER_LEASE_LOST', 'Adapter lease fencing failed before artifact publication.', true);
+    }
+}
+export async function settleAdapterOperationAfterTimeout(operation, timeoutMs, timeoutError, stop) {
+    const outcome = operation.then(value => ({ kind: 'value', value }), error => ({ kind: 'error', error }));
+    let timeout;
+    const first = await Promise.race([
+        outcome,
+        new Promise(resolve => {
+            timeout = setTimeout(() => resolve({ kind: 'timeout' }), timeoutMs);
+        }),
+    ]);
+    if (first.kind !== 'timeout') {
+        if (timeout)
+            clearTimeout(timeout);
+        if (first.kind === 'error')
+            throw first.error;
+        return first.value;
+    }
+    try {
+        await stop();
+    }
+    finally {
+        await outcome;
+    }
+    throw timeoutError;
+}
+export async function withAdapterResourceLocks(keys, operation, dependencies = {}) {
+    const lease = getCurrentAdapterLease();
+    if (!lease)
+        return operation();
+    const acquire = dependencies.acquire ?? acquireAdapterResources;
+    const release = dependencies.release ?? releaseAdapterResources;
+    const warn = dependencies.warn ?? ((message) => log.warn(message));
+    const scopedKeys = keys.map(key => key.startsWith('article:') || key.startsWith('data:')
+        ? `profile:${lease.contextId}:${key}`
+        : key);
+    const grant = await acquire(lease, scopedKeys, dependencies.timeoutMs ?? 300_000);
+    try {
+        return await operation();
+    }
+    finally {
+        let released = false;
+        let lastError;
+        for (let attempt = 0; attempt < 2 && !released; attempt++) {
+            try {
+                await release(lease, grant.grantId);
+                released = true;
+            }
+            catch (error) {
+                lastError = error;
+            }
+        }
+        if (!released) {
+            warn(`Adapter resource release acknowledgement failed for ${grant.grantId}: ${lastError instanceof Error ? lastError.message : String(lastError)}`);
+        }
+    }
+}
+export async function withAdapterCommandLease(request, operation, dependencies = {}) {
+    const acquire = dependencies.acquire ?? acquireAdapterLease;
+    const heartbeat = dependencies.heartbeat ?? heartbeatAdapterLease;
+    const release = dependencies.release ?? releaseAdapterLease;
+    const warn = dependencies.warn ?? ((message) => log.warn(message));
+    const heartbeatIntervalMs = dependencies.heartbeatIntervalMs ?? 10_000;
+    const context = { lease: await acquire(request) };
+    let releaseReason = 'error';
+    let leaseLost;
+    let stopAfterLeaseLoss;
+    let heartbeatTask;
+    const heartbeatTimer = setInterval(() => {
+        if (heartbeatTask || leaseLost)
+            return;
+        heartbeatTask = heartbeat(context.lease)
+            .then(next => { context.lease = next; })
+            .catch(error => {
+            const code = error && typeof error === 'object' ? error.code : undefined;
+            if (code === 'ADAPTER_LEASE_LOST') {
+                leaseLost = error;
+                stopAfterLeaseLoss = (dependencies.onLeaseLost?.() ?? Promise.resolve()).catch(stopError => {
+                    warn(`Adapter operation stop failed after lease loss for ${context.lease.requestId}: ${stopError instanceof Error ? stopError.message : String(stopError)}`);
+                });
+            }
+            else {
+                warn(`Adapter lease heartbeat failed for ${context.lease.requestId}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        })
+            .finally(() => { heartbeatTask = undefined; });
+    }, heartbeatIntervalMs);
+    heartbeatTimer.unref?.();
+    try {
+        let result;
+        try {
+            result = await runWithAdapterExecutionContext(context, operation);
+        }
+        catch (error) {
+            if (heartbeatTask)
+                await heartbeatTask;
+            if (stopAfterLeaseLoss)
+                await stopAfterLeaseLoss;
+            if (leaseLost)
+                throw leaseLost;
+            throw error;
+        }
+        if (heartbeatTask)
+            await heartbeatTask;
+        if (stopAfterLeaseLoss)
+            await stopAfterLeaseLoss;
+        if (leaseLost)
+            throw leaseLost;
+        releaseReason = classifyAdapterResult(result);
+        return result;
+    }
+    catch (error) {
+        releaseReason = classifyAdapterError(error);
+        throw error;
+    }
+    finally {
+        clearInterval(heartbeatTimer);
+        const payload = { ...context.lease, reason: releaseReason };
+        let released = false;
+        let lastError;
+        for (let attempt = 0; attempt < 2 && !released; attempt++) {
+            try {
+                await release(payload);
+                released = true;
+            }
+            catch (error) {
+                lastError = error;
+            }
+        }
+        if (!released) {
+            warn(`Adapter lease release acknowledgement failed for ${payload.requestId}: ${lastError instanceof Error ? lastError.message : String(lastError)}`);
+        }
+    }
+}
+function classifyAdapterError(error) {
+    const code = error && typeof error === 'object' && typeof error.code === 'string'
+        ? error.code
+        : '';
+    if (code === 'AUTH_REQUIRED' || /CAPTCHA|MFA|VERIFICATION/.test(code))
+        return 'auth_gate';
+    if (code === 'RATE_LIMITED')
+        return 'rate_limited';
+    if (code === 'TIMEOUT')
+        return 'timeout';
+    return 'error';
+}
+function classifyAdapterResult(result) {
+    const rows = Array.isArray(result) ? result : [result];
+    const statuses = rows
+        .filter(row => row && typeof row === 'object')
+        .map(row => String(row.status ?? '').toLowerCase());
+    if (statuses.some(status => /auth|login|captcha|verification|mfa/.test(status)))
+        return 'auth_gate';
+    if (statuses.some(status => /rate.?limit/.test(status)))
+        return 'rate_limited';
+    if (statuses.some(status => status === 'partial'))
+        return 'partial';
+    if (statuses.length > 0 && statuses.every(status => status.startsWith('failed') || status.startsWith('failure')))
+        return 'failed';
+    return 'success';
+}

package/dist/src/adapter-coordination.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/adapter-execution-context.d.ts

@@ -0,0 +1,6 @@
+import type { AdapterLease } from './adapter-scheduler.js';
+export interface AdapterExecutionContext {
+    lease: AdapterLease;
+}
+export declare function getAdapterExecutionContext(): AdapterExecutionContext | undefined;
+export declare function runWithAdapterExecutionContext<T>(context: AdapterExecutionContext, operation: () => Promise<T>): Promise<T>;

package/dist/src/adapter-execution-context.js

@@ -0,0 +1,8 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+const storage = new AsyncLocalStorage();
+export function getAdapterExecutionContext() {
+    return storage.getStore();
+}
+export function runWithAdapterExecutionContext(context, operation) {
+    return storage.run(context, operation);
+}

package/dist/src/adapter-scheduler.d.ts

@@ -0,0 +1,86 @@
+export type AdapterPoolCloseReason = 'auth_gate' | 'rate_limited';
+export type AdapterReleaseReason = 'success' | 'partial' | 'failed' | AdapterPoolCloseReason | 'timeout' | 'error' | 'cancelled';
+export interface AdapterLeaseRequest {
+    requestId: string;
+    contextId: string;
+    surface: 'adapter';
+    site: string;
+    adapterSession: string;
+    sessionKey: string;
+    queueTimeoutMs: number;
+    maxParallel: number;
+}
+export interface AdapterLease {
+    leaseId: string;
+    requestId: string;
+    poolKey: string;
+    contextId: string;
+    surface: 'adapter';
+    site: string;
+    adapterSession: string;
+    sessionKey: string;
+    generation: number;
+    grantedAt: number;
+    heartbeatDeadline: number;
+}
+export interface AdapterLeaseRelease extends AdapterLease {
+    reason: AdapterReleaseReason;
+}
+export declare class AdapterSchedulerError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export interface AdapterResourceGrant {
+    grantId: string;
+    leaseId: string;
+    keys: string[];
+}
+export interface AdapterSchedulerOptions {
+    now?: () => number;
+    leaseExpiryMs?: number;
+    runtimeCeiling?: number;
+    releasedLeaseRetentionMs?: number;
+}
+export declare class AdapterScheduler {
+    private readonly now;
+    private readonly leaseExpiryMs;
+    private readonly runtimeCeiling;
+    private readonly releasedLeaseRetentionMs;
+    private readonly pools;
+    private readonly releasedLeaseIds;
+    private readonly generations;
+    private readonly resourceOwners;
+    private readonly resourceGrants;
+    private readonly resourceQueue;
+    private sequence;
+    constructor(options?: AdapterSchedulerOptions);
+    acquire(request: AdapterLeaseRequest): Promise<AdapterLease>;
+    heartbeat(identity: AdapterLease): AdapterLease;
+    assertLease(identity: AdapterLease): AdapterLease;
+    release(release: AdapterLeaseRelease): boolean;
+    acquireResources(leaseIdentity: AdapterLease, rawKeys: string[], timeoutMs: number): Promise<AdapterResourceGrant>;
+    releaseResources(leaseIdentity: AdapterLease, grantId: string): boolean;
+    cancel(requestId: string, code?: string): boolean;
+    sweepExpired(): void;
+    reset(): void;
+    snapshot(): {
+        running: number;
+        queued: number;
+        pools: number;
+    };
+    resourceSnapshot(): {
+        locked: number;
+        queued: number;
+        grants: number;
+    };
+    private schedule;
+    private scheduleResources;
+    private releaseAllResourcesForLease;
+    private pruneReleasedLeaseIds;
+    private rejectResourceWaitersForLease;
+    private requireLease;
+    private getOrCreatePool;
+    private removeDrainedPool;
+    private poolClosedError;
+    private validateRequest;
+}