dsh-file-activity 0.5.7 → 0.5.9

package/lib/parts/view.part.js

@@ -1,7 +1,38 @@
+'use strict'
 // ── view component ────────────────────────────────────────────────────
 /** Shared empty bucket for sessions that have never loaded data (stable ref). */
 const EMPTY_SESSION = { recent: [], counts: {}, loading: true }
-
+/** tab.visible out of the host's SidebarRightTabInfo; undefined when the
+ *  information (or its shape) is unavailable. */
+function readSeatVisible(info) {
+  if (info === null || typeof info !== 'object') return undefined
+  const tab = info.tab
+  if (tab === null || typeof tab !== 'object') return undefined
+  const visible = tab.visible
+  return typeof visible === 'boolean' ? visible : undefined
+}
+/**
+ * Resolve whether this seat is on screen.
+ *
+ * The native seat hands the component **no** `visible` prop: the host dispatches
+ * it as `renderSlot('sidebar.right.pane.tab', {}, { hookContext })`, so the owner
+ * props share is empty and everything live arrives through the injected
+ * `useTabInfo()` hook (SidebarRightTabInfo.tab.visible). Reading `props.visible`
+ * alone is therefore always `undefined` — the pre-#266 (`if (!visible) return`)
+ * guard was constant-true, so an opened panel never loaded and never polled
+ * (it only showed data after a manual Refresh).
+ *
+ * Order: the host hook first, then the legacy prop, then visible by default.
+ * Defaulting to visible is the deliberate failure direction (issue #266): if the
+ * hook is unavailable or the host shape changes again, the panel must still
+ * load — the cost is one polling panel, the alternative is a blank one.
+ */
+function useSeatVisible(useTabInfo, legacyVisible) {
+  const info = typeof useTabInfo === 'function' ? useTabInfo() : undefined
+  const seatVisible = readSeatVisible(info)
+  if (seatVisible !== undefined) return seatVisible
+  return legacyVisible !== false
+}
 /**
  * Polling loader for one session: fetches stats on mount and on a fixed
  * interval while visible, prefers the sidebar's authoritative session.cwd
@@ -44,7 +75,6 @@ function useSessionLoader(visible, sessionId, scope, dataStore, setCwd, setError
     }
   }, [visible, sessionId, dataStore])
 }
-
 /** Error banner element, or null when the last load succeeded. */
 function renderError(error) {
   if (!error) return null
@@ -60,7 +90,6 @@ function renderError(error) {
     strings.loadError(),
   )
 }
-
 /** "最近访问" section: collapsible head with refresh/clear actions. */
 function renderRecentSection(recent, recentOpen, onToggle, onRefresh, onClear, onOpen) {
   return createElement(
@@ -116,7 +145,6 @@ function renderRecentSection(recent, recentOpen, onToggle, onRefresh, onClear, o
           ),
   )
 }
-
 /** "文件统计" section: the directory tree, or an empty hint. */
 function renderStatsSection(tree, collapsedDirs, onToggleDir, onOpen) {
   return createElement(
@@ -132,20 +160,31 @@ function renderStatsSection(tree, collapsedDirs, onToggleDir, onOpen) {
         ),
   )
 }
-
 /**
  * The file-activity tab. Each session renders only its own store bucket:
  * a fresh conversation shows an empty list immediately, with no residue
  * from the previous session. Clicking any file opens a FLOATING preview
  * that reuses the sidebar's NATIVE viewer via matchFileViewer.
  */
-function FileActivityView({ ctx, store, scope, visible, dataStore }) {
+function FileActivityView({
+  ctx,
+  store,
+  scope,
+  sessionId: seatSessionId,
+  visible: legacyVisible,
+  useTabInfo,
+  dataStore,
+}) {
   const data = useSyncExternalStore(dataStore.subscribe, dataStore.getSnapshot)
   const [cwd, setCwd] = useState(scope?.cwd || '')
   const [error, setError] = useState(false)
   const [recentOpen, setRecentOpen] = useState(true)
   const [collapsedDirs, setCollapsedDirs] = useState(() => new Set())
-  const sessionId = scope?.sessionId ?? ''
+  // Native seats pass sessionId directly; the legacy scope object still works.
+  const sessionId = seatSessionId ?? scope?.sessionId ?? ''
+  // issue #266 A: the native seat passes NO visible prop — visibility comes
+  // from the injected useTabInfo() (see useSeatVisible).
+  const visible = useSeatVisible(useTabInfo, legacyVisible)
   const sessionData = (data.bySession ?? {})[sessionId] ?? EMPTY_SESSION
   const tree = useMemo(() => buildTree(sessionData.counts ?? {}), [sessionData.counts])
   useEffect(() => {
@@ -164,8 +203,10 @@ function FileActivityView({ ctx, store, scope, visible, dataStore }) {
     closePreviewOnHidden(visible, dataStore)
   }, [visible, dataStore])
   const toggleDir = (path) => setCollapsedDirs((prev) => toggleInSet(prev, path))
-  const openPreview = (path) => dataStore.set({ preview: { abs: path, name: basenameOf(path) } })
-  const closePreview = () => dataStore.set({ preview: null })
+  // The floating preview itself lives in the root-scoped 'shell.overlay' seat
+  // (registered by registerPreviewOverlay), so this view only publishes the
+  // target — together with the owning session, which authorizes the routes.
+  const openPreview = (path) => dataStore.set({ preview: { abs: path, name: basenameOf(path), sessionId } })
   const onClear = () => clearSessionData(dataStore, sessionId)
   const onRefresh = () => refreshSessionData(dataStore, sessionId, setCwd, setError)
   const recent = sessionData.recent ?? []
@@ -173,16 +214,29 @@ function FileActivityView({ ctx, store, scope, visible, dataStore }) {
     'div',
     { className: 'dfa' },
     renderError(error),
+    renderDegraded(),
     renderRecentSection(recent, recentOpen, () => setRecentOpen((v) => !v), onRefresh, onClear, openPreview),
     renderStatsSection(tree, collapsedDirs, toggleDir, openPreview),
-    data.preview
-      ? createElement(FloatingPreview, {
-          ctx,
-          store,
-          scope,
-          preview: data.preview,
-          onClose: closePreview,
-        })
-      : null,
+  )
+}
+/**
+ * Degradation notice: shown when this activation failed to register one of the
+ * host extension points (registerTabType / documentPreviews / auto-open). The
+ * panel is also marked with data-dfa-degraded so the e2e suite can assert the
+ * failure instead of hunting a missing tab.
+ * @returns the notice element, or null when nothing degraded.
+ */
+function renderDegraded() {
+  try {
+    const markers = typeof document === 'undefined' ? undefined : document.documentElement?.dataset
+    if (markers === undefined || markers === null || markers.dfaDegraded === undefined) return null
+  } catch {
+    return null
+  }
+  return createElement(
+    'div',
+    { className: 'dfa-degraded', 'data-dfa-degraded': '1' },
+    createElement('div', { className: 'dfa-degraded-title' }, strings.tabUnavailable()),
+    createElement('div', { className: 'dfa-degraded-hint' }, strings.tabUnavailableHint()),
   )
 }

package/lib/persist.js

@@ -0,0 +1,137 @@
+/**
+ * dsh-file-activity — JSON Lines 增量持久化（issue #197 写放大整改）。
+ *
+ * 为什么是增量 append（方案 A）而不是「节流后的全量快照」：本插件状态是
+ * 累积字典，旧实现每次防抖落盘都 JSON.stringify 整个状态（审计实测单次
+ * 1,396,407 B / 写放大 3,665×）。一次记录的信息量恰好等于状态增量（一条
+ * 事件 = 一次 fold），所以增量落盘字节 ≈ 事件本体字节。
+ *
+ * 数据不丢的论证：
+ *  - 事件行 `{s,p,o,t}` 携带重放所需的全部信息（会话 / 路径 / 操作 / 时间）；
+ *    冷启动按行序重放 = 运行时状态的精确重现（delete 行同样可重放）；
+ *  - 行阈值触发 compact：用**当前内存态**生成快照行（元信息行 + 每会话一行
+ *    `{s,d}` + 结束行）并原子重写（tmp+rename），文件大小有界、启动不回归；
+ *  - 崩溃安全：append 是 O(新增) 的，最坏丢最后一个防抖窗口（≤ flushMs）；
+ *    compact 由 rename 保证原子（旧文件或新文件，不会半截）。
+ *
+ * 护栏（显式，不再裸奔）：
+ *  - `minIntervalMs`：快照超过阈值体积后生效的最小写间隔（分级节流）；
+ *  - `maxBytes`：快照字节硬上限（超限拒绝写 + warn，不静默）；
+ *  - `compactLines`：追加行阈值（按状态体积自适应，文件大小因此有界）。
+ */
+import { jsonlAppender } from 'dsh-shared';
+import { LOG_PREFIX } from './quota.js';
+/** 追加落盘的防抖窗口（高频突发合并成一次 append）。 */
+const FLUSH_MS = 500;
+/** 追加行数阈值（默认；createStore 按状态体积自适应上调）。 */
+const COMPACT_LINES = 3000;
+/** compact 快照字节硬上限（状态上界 ~2MB；超限拒绝写并告警）。 */
+const SNAPSHOT_MAX_BYTES = 8 * 1024 * 1024;
+/** 快照超过该体积后才启用最小写间隔（小快照高频重写成本可忽略）。 */
+const SNAPSHOT_THROTTLE_MIN_BYTES = 64 * 1024;
+/** 快照最小写间隔：体积每翻倍 +1s（大快照低频重写，写放大有界）。 */
+const SNAPSHOT_MIN_INTERVAL_MS = 1000;
+/** 一条记录 → 事件行（键序固定 s/p/o/t：落盘字节 = 事件本体字节）。 */
+function eventLine(record) {
+    return JSON.stringify({ s: record.sessionId, p: record.path, o: record.op, t: record.time });
+}
+/** compact 快照行组：元信息行（含统计）+ 每会话一行 + 结束行（结束行让尾部事件区显式开始）。 */
+function snapshotLines(state) {
+    const lines = [JSON.stringify({ m: 1, v: state.version, t: Date.now(), stats: state.stats })];
+    for (const [sessionId, session] of Object.entries(state.sessions)) {
+        lines.push(JSON.stringify({ s: sessionId, d: session }));
+    }
+    lines.push('=');
+    return lines;
+}
+/**
+ * 建立持久化编排：append 走 jsonl 增量；达行阈值时 appender 调 onCompact，
+ * 宿主用**实时 state**（stateOf 回调）生成快照行并原子重写。
+ */
+export function createPersist(options, stateOf) {
+    const logger = options.ctx.logger;
+    const guard = {
+        file: options.file,
+        minIntervalMs: options.snapshotMinIntervalMs ?? SNAPSHOT_MIN_INTERVAL_MS,
+        maxBytes: options.snapshotMaxBytes ?? SNAPSHOT_MAX_BYTES,
+        logger,
+    };
+    let handle;
+    handle = (options.factory ?? defaultAppender)(options.file, {
+        flushMs: options.flushMs ?? FLUSH_MS,
+        compactLines: options.compactLines ?? COMPACT_LINES,
+        logger,
+        prefix: LOG_PREFIX,
+        onCompact: () => writeSnapshot(handle, stateOf(), guard),
+    });
+    return {
+        file: options.file,
+        appender: handle,
+        append: (record) => handle.append(JSON.parse(eventLine(record))),
+        compact: (state) => writeSnapshot(handle, state, guard),
+        flush: () => handle.flush(),
+        dispose: () => handle.dispose(),
+    };
+}
+/** 文件最近一次成功快照时间（节流窗口用）。 */
+const lastSnapshotAt = new Map();
+/** 分级节流：小快照不受最小间隔约束（否则 compact 会被自己节流掉）。 */
+function throttleFor(file, bytes, guard) {
+    if (bytes <= SNAPSHOT_THROTTLE_MIN_BYTES)
+        return 0;
+    const factor = Math.max(1, Math.ceil(Math.log2(bytes / SNAPSHOT_THROTTLE_MIN_BYTES)));
+    return guard.minIntervalMs * factor;
+}
+/** 护栏判定：被拦时 warn 并返回 true（调用方跳过写盘，不静默）。 */
+function guarded(guard, bytes, now) {
+    if (bytes > guard.maxBytes) {
+        guard.logger?.warn(LOG_PREFIX + ' compact rejected (' + bytes + 'B > maxBytes=' + guard.maxBytes + '): ' + guard.file);
+        return true;
+    }
+    const window = throttleFor(guard.file, bytes, guard);
+    if (window > 0 && now - (lastSnapshotAt.get(guard.file) ?? 0) < window) {
+        guard.logger?.warn(LOG_PREFIX + ' compact throttled (minIntervalMs=' + window + '): ' + guard.file);
+        return true;
+    }
+    return false;
+}
+/**
+ * 原子 compact 快照：走 dsh-shared jsonlAppender 的 snapshot（tmp+rename 原子
+ * 重写 + 清挂起队列 + 计入 stats）；护栏由本层显式判定，拦截/失败均返回 false
+ * 并告警（不静默）。
+ */
+async function writeSnapshot(handle, state, guard) {
+    const lines = snapshotLines(state);
+    const bytes = Buffer.byteLength(lines.join('\n') + '\n', 'utf8');
+    if (guarded(guard, bytes, Date.now()))
+        return false;
+    lastSnapshotAt.set(guard.file, Date.now());
+    try {
+        await handle.snapshot(lines);
+        return true;
+    }
+    catch (error) {
+        guard.logger?.warn(LOG_PREFIX + ' compact failed: ' + (error instanceof Error ? error.message : String(error)));
+        return false;
+    }
+}
+/** appender 统计（缺接口/字段名差异时回退 0，绝不产生 NaN —— NaN 会让预算判断失效）。 */
+export function readAppenderStats(appender) {
+    const num = (value) => (typeof value === 'number' && Number.isFinite(value) ? value : 0);
+    try {
+        const stats = appender.stats();
+        // dsh-shared jsonlAppender 暴露 total（累计追加行数），兼容 events 命名。
+        return {
+            bytesWritten: num(stats.bytesWritten),
+            writes: num(stats.writes),
+            events: num(stats.total ?? stats.events),
+        };
+    }
+    catch {
+        return { bytesWritten: 0, writes: 0, events: 0 };
+    }
+}
+/** 默认 appender：dsh-shared 的 jsonlAppender（增量 append + 防抖 + compact 回调）。 */
+function defaultAppender(file, options) {
+    return jsonlAppender(file, options);
+}

package/lib/quota-trim.js

@@ -0,0 +1,121 @@
+/**
+ * dsh-file-activity — 加载规整与配额收敛（issue #197）。
+ *
+ * 旧状态文件（全量 JSON 快照）可能远超新上限：首次升级启动即按配额收敛，
+ * 淘汰动作同样计数 + warn，不做静默丢弃。
+ */
+import { RECENT_LIMIT, countPaths, emptyEvicted, enforceSessionLimit, enforceSessionPathLimit, enforceTotalPathLimit, } from './quota.js';
+/** NUL 字符（路径合法性判定，禁止内嵌空字节）。 */
+const NUL = String.fromCharCode(0);
+/** 计数器规整：非法值归零、时间戳可选保留。 */
+function sanitizeCounters(raw) {
+    if (raw === null || typeof raw !== 'object')
+        return null;
+    const num = (value) => typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : 0;
+    const counters = { read: num(raw.read), create: num(raw.create), modify: num(raw.modify) };
+    if (typeof raw.firstSeen === 'number')
+        counters.firstSeen = raw.firstSeen;
+    if (typeof raw.lastSeen === 'number')
+        counters.lastSeen = raw.lastSeen;
+    return counters;
+}
+/** recent 规整：过滤非法条目 → 时间降序 → 按 path 去重 → 截断到 RECENT_LIMIT。 */
+function normalizeRecent(raw) {
+    const seen = new Set();
+    const valid = raw.filter((entry) => typeof entry?.path === 'string' && entry.path !== '' && !entry.path.includes(NUL));
+    valid.sort((a, b) => (typeof b.time === 'number' ? b.time : 0) - (typeof a.time === 'number' ? a.time : 0));
+    const out = [];
+    for (const entry of valid) {
+        if (seen.has(entry.path))
+            continue;
+        seen.add(entry.path);
+        out.push({
+            path: entry.path,
+            op: String(entry.op ?? 'read'),
+            time: typeof entry.time === 'number' ? entry.time : 0,
+        });
+        if (out.length >= RECENT_LIMIT)
+            break;
+    }
+    return out;
+}
+/** counts 规整：非法 path / 非法计数器丢弃。 */
+function normalizeCounts(raw) {
+    const counts = {};
+    let dropped = 0;
+    for (const [path, rawCounters] of Object.entries(raw ?? {})) {
+        if (typeof path !== 'string' || path === '' || path.includes(NUL)) {
+            dropped += 1;
+            continue;
+        }
+        const counters = sanitizeCounters(rawCounters);
+        if (counters === null) {
+            dropped += 1;
+            continue;
+        }
+        counts[path] = counters;
+    }
+    return { counts, dropped };
+}
+/** known 与 counts 对齐（非法条目丢弃、缺失项按 firstSeen 补齐）。 */
+function alignKnown(raw, counts) {
+    const known = {};
+    let changed = false;
+    for (const [path, at] of Object.entries(raw ?? {})) {
+        if (typeof at === 'number' && path !== '' && !path.includes(NUL))
+            known[path] = at;
+        else
+            changed = true;
+    }
+    if (Object.keys(known).length !== Object.keys(counts).length)
+        changed = true;
+    for (const path of Object.keys(counts)) {
+        if (typeof known[path] === 'number')
+            continue;
+        known[path] = counts[path].firstSeen ?? 0;
+    }
+    return { known, changed };
+}
+/** 会话规整：recent 去重截断 → counts 过滤 → known 与 counts 对齐 → 单会话 LRU 上限。 */
+function trimSession(raw, sessionId, limits, evicted, logger) {
+    const rawRecent = Array.isArray(raw.recent) ? raw.recent : [];
+    const recent = normalizeRecent(rawRecent);
+    const { counts, dropped } = normalizeCounts(raw.counts);
+    const { known, changed } = alignKnown(raw.known, counts);
+    const session = { known, counts, recent };
+    const before = Object.keys(counts).length;
+    enforceSessionPathLimit(session, sessionId, limits, evicted, logger);
+    const trimmed = recent.length !== rawRecent.length || dropped > 0 || changed || Object.keys(session.counts).length !== before;
+    return { session, trimmed };
+}
+/**
+ * 加载后按配额规整（旧状态文件可能远超上限：首次升级启动即收敛到边界）。
+ * 顺序：逐会话规整 → 会话数上限 → 全局路径上限。
+ */
+export function trimToQuota(loaded, limits, logger) {
+    const evicted = emptyEvicted();
+    let trimmed = false;
+    const sessions = {};
+    for (const [sessionId, raw] of Object.entries(loaded.sessions ?? {})) {
+        if (raw === null || typeof raw !== 'object' || sessionId === '') {
+            trimmed = true;
+            continue;
+        }
+        const result = trimSession(raw, sessionId, limits, evicted, logger);
+        if (result.trimmed)
+            trimmed = true;
+        sessions[sessionId] = result.session;
+    }
+    const state = { version: 1, sessions, stats: { evicted } };
+    const sessionsBefore = Object.keys(sessions).length;
+    enforceSessionLimit(state, limits, evicted, logger);
+    if (Object.keys(state.sessions).length !== sessionsBefore)
+        trimmed = true;
+    const pathsBefore = countPaths(state);
+    enforceTotalPathLimit(state, limits, evicted, logger);
+    if (countPaths(state) !== pathsBefore)
+        trimmed = true;
+    if (evicted.sessions + evicted.paths + evicted.pathsTotal > 0)
+        trimmed = true;
+    return { state, trimmed, evicted };
+}

package/lib/quota.js

@@ -0,0 +1,164 @@
+/** 每会话路径上限（LRU：超限淘汰最久未活动路径）。 */
+const MAX_PATHS_PER_SESSION = 300;
+/** 全局路径上限（跨会话总条目数）。 */
+const MAX_PATHS_TOTAL = 20000;
+/** 会话数上限（淘汰最久未活动会话）。 */
+const MAX_SESSIONS = 64;
+/** 每会话 recent 历史条目上限（LRU，保持既有语义）。 */
+export const RECENT_LIMIT = 5;
+/** 日志前缀（淘汰 warn 可见）。 */
+export const LOG_PREFIX = '[dsh-file-activity]';
+/** 默认配额。 */
+export function defaultLimits() {
+    return { maxPathsPerSession: MAX_PATHS_PER_SESSION, maxPathsTotal: MAX_PATHS_TOTAL, maxSessions: MAX_SESSIONS };
+}
+/** 用默认值补齐（undefined / 非有限值回退默认）。 */
+export function normalizeLimits(input) {
+    const pick = (value, fallback) => typeof value === 'number' && Number.isFinite(value) && value > 0 ? Math.floor(value) : fallback;
+    return {
+        maxPathsPerSession: pick(input?.maxPathsPerSession, MAX_PATHS_PER_SESSION),
+        maxPathsTotal: pick(input?.maxPathsTotal, MAX_PATHS_TOTAL),
+        maxSessions: pick(input?.maxSessions, MAX_SESSIONS),
+    };
+}
+/** 空淘汰计数。 */
+export function emptyEvicted() {
+    return { sessions: 0, paths: 0, pathsTotal: 0 };
+}
+/** 空会话桶。 */
+export function createSession() {
+    return { known: {}, counts: {}, recent: [] };
+}
+/** 计数器最近活动时间（lastSeen → firstSeen → 0）。 */
+function lastSeenOf(counters) {
+    if (counters === undefined || counters === null)
+        return 0;
+    if (typeof counters.lastSeen === 'number')
+        return counters.lastSeen;
+    if (typeof counters.firstSeen === 'number')
+        return counters.firstSeen;
+    return 0;
+}
+/** 会话最近活动时间：recent 最新条目时间与所有计数器 lastSeen 的最大值。 */
+function activityOf(session) {
+    let newest = 0;
+    if (Array.isArray(session.recent)) {
+        for (const entry of session.recent) {
+            if (typeof entry?.time === 'number' && entry.time > newest)
+                newest = entry.time;
+        }
+    }
+    for (const counters of Object.values(session.counts ?? {})) {
+        const at = lastSeenOf(counters);
+        if (at > newest)
+            newest = at;
+    }
+    return newest;
+}
+/** 淘汰日志节流：首次 + 每 10 次（避免长会话下 warn 刷屏，但绝不静默）。 */
+function shouldLogEvicted(total) {
+    return total === 1 || total % 10 === 0;
+}
+/** 全局路径总数。 */
+export function countPaths(state) {
+    let total = 0;
+    for (const session of Object.values(state.sessions))
+        total += Object.keys(session.counts).length;
+    return total;
+}
+/** 单个会话内路径超限：LRU 淘汰 lastSeen 最旧者（known/counts 同步）。 */
+export function enforceSessionPathLimit(session, sessionId, limits, evicted, logger) {
+    const overflow = Object.keys(session.counts).length - limits.maxPathsPerSession;
+    if (overflow <= 0)
+        return;
+    const oldest = Object.entries(session.counts)
+        .map(([path, counters]) => ({ path, lastSeen: lastSeenOf(counters) }))
+        .sort((a, b) => a.lastSeen - b.lastSeen)
+        .slice(0, overflow);
+    for (const item of oldest) {
+        delete session.counts[item.path];
+        delete session.known[item.path];
+    }
+    evicted.paths += overflow;
+    if (shouldLogEvicted(evicted.paths)) {
+        logger?.warn(LOG_PREFIX +
+            ' evict path: ' +
+            overflow +
+            ' LRU path(s) from session ' +
+            sessionId +
+            ' (cap=' +
+            limits.maxPathsPerSession +
+            ', evicted=' +
+            evicted.paths +
+            ')');
+    }
+}
+/** 全局路径超限：LRU 淘汰全局 lastSeen 最旧者（跨会话扫描，known/counts 同步）。 */
+export function enforceTotalPathLimit(state, limits, evicted, logger) {
+    const overflow = countPaths(state) - limits.maxPathsTotal;
+    if (overflow <= 0)
+        return;
+    const candidates = [];
+    for (const [sessionId, session] of Object.entries(state.sessions)) {
+        for (const [path, counters] of Object.entries(session.counts)) {
+            candidates.push({ sessionId, path, lastSeen: lastSeenOf(counters) });
+        }
+    }
+    candidates.sort((a, b) => a.lastSeen - b.lastSeen);
+    let removed = 0;
+    for (const item of candidates) {
+        if (removed >= overflow)
+            break;
+        const session = state.sessions[item.sessionId];
+        if (session === undefined || session.counts[item.path] === undefined)
+            continue;
+        delete session.counts[item.path];
+        delete session.known[item.path];
+        removed += 1;
+    }
+    evicted.pathsTotal += removed;
+    if (shouldLogEvicted(evicted.pathsTotal)) {
+        logger?.warn(LOG_PREFIX +
+            ' evict path: ' +
+            removed +
+            ' LRU path(s) globally (cap=' +
+            limits.maxPathsTotal +
+            ', evicted=' +
+            evicted.pathsTotal +
+            ')');
+    }
+}
+/** 会话数超限：淘汰最久未活动会话（整会话桶删除，known/counts/recent 一并释放）。 */
+export function enforceSessionLimit(state, limits, evicted, logger) {
+    const overflow = Object.keys(state.sessions).length - limits.maxSessions;
+    if (overflow <= 0)
+        return;
+    const oldest = Object.entries(state.sessions)
+        .map(([sessionId, session]) => ({ sessionId, activity: activityOf(session) }))
+        .sort((a, b) => a.activity - b.activity)
+        .slice(0, overflow);
+    for (const item of oldest)
+        delete state.sessions[item.sessionId];
+    evicted.sessions += overflow;
+    if (shouldLogEvicted(evicted.sessions)) {
+        logger?.warn(LOG_PREFIX +
+            ' evict session: ' +
+            overflow +
+            ' least-recently-active session(s) (cap=' +
+            limits.maxSessions +
+            ', evicted=' +
+            evicted.sessions +
+            ')');
+    }
+}
+/**
+ * 运行时记录后的配额执行顺序：全局路径 → 单会话路径 → 会话数。
+ * 淘汰计数累加到 evicted（调用方负责写入 state.stats 并落日志）。
+ */
+export function enforceQuota(state, sessionId, limits, evicted, logger) {
+    enforceTotalPathLimit(state, limits, evicted, logger);
+    const session = state.sessions[sessionId];
+    if (session !== undefined)
+        enforceSessionPathLimit(session, sessionId, limits, evicted, logger);
+    enforceSessionLimit(state, limits, evicted, logger);
+}