pi-pier 0.3.0 → 0.3.1

package/src/efficiency-config-core.ts

@@ -1,21 +1,17 @@
 /**
- * D100-D103 Efficiency Configuration Core.
+ * D100-D103 efficiency configuration: schema, validation, multi-tier resolution and the two files
+ * pier itself reads for it.
  *
- * Provides zero-dependency parsing, validation, and multi-tier resolution
- * for pier efficiency mechanisms (OCC, ObservationPack, EPR).
- *
- * Contract:
- *  - Unknown keys rejected to catch typos; all issues collected in one pass.
- *  - Project-level configuration requires `isProjectTrusted: true` (security boundary).
- *  - Workspace config shallow-replaces user config.
- *  - Fail-open: configuration parse/validation errors disable the affected mechanism
- *    and emit a single-line warning, never crashing normal agent sessions.
- *  - Environment variables (PI_HERDR_*) take highest precedence.
+ * Contract: unknown keys are rejected (typo guard — all issues collected in one pass); a project-level
+ * config requires `isProjectTrusted: true` (security boundary); workspace config shallow-replaces user
+ * config while env (`PI_HERDR_*` / `PIER_JEV_*`) wins over both; and a config that fails validation
+ * disables the affected mechanism with a one-line warning instead of crashing the session (an unknown
+ * top-level key disables every mechanism).
  */
 
+import { existsSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
-import { loadPiNativeCompactionSettings, readJsonConfig } from './efficiency-config-io.ts';
 
 export interface OnlineContextCompactConfig {
   enabled: boolean;
@@ -47,9 +43,8 @@ export interface EvidencePreservingReducerConfig {
 }
 
 /**
- * Jev decision layer (RFC docs/rfc-jev-integration.md). Optional System One
- * classification calls that upgrade hand-written heuristics; every call site
- * fails open to the existing heuristic on any error, timeout, or low confidence.
+ * Jev decision layer (RFC docs/rfc-jev-integration.md): optional System One classification calls that
+ * upgrade hand-written heuristics; every call site fails open on any error, timeout, or low confidence.
  */
 export interface JevConfig {
   enabled: boolean;
@@ -77,89 +72,141 @@ export interface EfficiencyConfig {
 export const DEFAULT_EFFICIENCY_CONFIG: EfficiencyConfig = Object.freeze({
   version: 1,
   onlineContextCompact: Object.freeze({
-    enabled: false,
-    logEnabled: false,
-    cacheWriteReadRatio: 'auto',
-    keepRecentTokens: 20000,
-    firstCompactionRequestScale: 2.0,
-    subsequentCompactionMargin: 1.5,
+    enabled: false, logEnabled: false, cacheWriteReadRatio: 'auto', keepRecentTokens: 20000,
+    firstCompactionRequestScale: 2.0, subsequentCompactionMargin: 1.5,
   }),
   observationPack: Object.freeze({
-    enabled: false,
-    logEnabled: false,
-    thresholdBytes: 10240,
-    fullSends: 2,
-    recallChunkBytes: 16384,
-    excerptBytes: 1024,
+    enabled: false, logEnabled: false, thresholdBytes: 10240, fullSends: 2,
+    recallChunkBytes: 16384, excerptBytes: 1024,
   }),
   evidencePreservingReducer: Object.freeze({
-    enabled: false,
-    logEnabled: false,
-    minBytes: 4096,
-    maxChars: 600000,
-    maxOutputTokens: 2048,
-    timeoutMs: 5000,
-    localOnly: false,
-  }),
-  jev: Object.freeze({
-    enabled: false,
-    logEnabled: false,
-    model: 'jev-1.13.0',
-    timeoutMs: 2000,
-    minConfidence: 0.6,
+    enabled: false, logEnabled: false, minBytes: 4096, maxChars: 600000,
+    maxOutputTokens: 2048, timeoutMs: 5000, localOnly: false,
   }),
+  jev: Object.freeze({ enabled: false, logEnabled: false, model: 'jev-1.13.0', timeoutMs: 2000, minConfidence: 0.6 }),
 });
 
 function isPlainObject(v: unknown): v is Record<string, unknown> {
   return typeof v === 'object' && v !== null && !Array.isArray(v);
 }
 
-const TOP_LEVEL_KEYS = new Set([
-  'version',
-  'onlineContextCompact',
-  'observationPack',
-  'evidencePreservingReducer',
-  'jev',
-]);
-
-const OCC_KEYS = new Set([
-  'enabled',
-  'logEnabled',
-  'cacheWriteReadRatio',
-  'keepRecentTokens',
-  'firstCompactionRequestScale',
-  'subsequentCompactionMargin',
-]);
-
-const OBS_KEYS = new Set([
-  'enabled',
-  'logEnabled',
-  'thresholdBytes',
-  'fullSends',
-  'recallChunkBytes',
-  'excerptBytes',
-]);
-
-const EPR_KEYS = new Set([
-  'enabled',
-  'logEnabled',
-  'model',
-  'minBytes',
-  'maxChars',
-  'maxOutputTokens',
-  'timeoutMs',
-  'localOnly',
-]);
-
-const JEV_KEYS: Record<string, true> = {
-  enabled: true,
-  logEnabled: true,
-  baseUrl: true,
-  model: true,
-  timeoutMs: true,
-  minConfidence: true,
-  apiKey: true,
-};
+type FieldKind = 'bool' | 'int' | 'number' | 'ratio' | 'string' | 'optionalString';
+
+interface FieldSpec {
+  readonly key: string;
+  readonly kind: FieldKind;
+  /** Lower bound for `int`/`number`; also printed in the issue message. */
+  readonly min?: number;
+  readonly max?: number;
+  /** Issue text for a bound that must not be printed as a plain JS number ("1.0"). */
+  readonly minText?: string;
+}
+
+/** A section is `{enabled, ...fields}`; field order fixes the order of reported issues. */
+interface SectionSpec {
+  readonly name: 'onlineContextCompact' | 'observationPack' | 'evidencePreservingReducer' | 'jev';
+  readonly fields: readonly FieldSpec[];
+}
+
+const SECTIONS: readonly SectionSpec[] = [
+  { name: 'onlineContextCompact', fields: [
+    { key: 'enabled', kind: 'bool' },
+    { key: 'logEnabled', kind: 'bool' },
+    { key: 'cacheWriteReadRatio', kind: 'ratio' },
+    { key: 'keepRecentTokens', kind: 'int', min: 1000 },
+    { key: 'firstCompactionRequestScale', kind: 'number', min: 1, minText: '1.0' },
+    { key: 'subsequentCompactionMargin', kind: 'number', min: 1, minText: '1.0' },
+  ] },
+  { name: 'observationPack', fields: [
+    { key: 'enabled', kind: 'bool' },
+    { key: 'logEnabled', kind: 'bool' },
+    { key: 'thresholdBytes', kind: 'int', min: 1024 },
+    { key: 'fullSends', kind: 'int', min: 1 },
+    { key: 'recallChunkBytes', kind: 'int', min: 1024 },
+    { key: 'excerptBytes', kind: 'int', min: 128 },
+  ] },
+  { name: 'evidencePreservingReducer', fields: [
+    { key: 'enabled', kind: 'bool' },
+    { key: 'logEnabled', kind: 'bool' },
+    { key: 'model', kind: 'optionalString' },
+    { key: 'minBytes', kind: 'int', min: 512 },
+    { key: 'maxChars', kind: 'int', min: 1000 },
+    { key: 'maxOutputTokens', kind: 'int', min: 128 },
+    { key: 'timeoutMs', kind: 'int', min: 500 },
+    { key: 'localOnly', kind: 'bool' },
+  ] },
+  { name: 'jev', fields: [
+    { key: 'enabled', kind: 'bool' },
+    { key: 'logEnabled', kind: 'bool' },
+    { key: 'baseUrl', kind: 'optionalString' },
+    { key: 'model', kind: 'string' },
+    { key: 'timeoutMs', kind: 'int', min: 500 },
+    { key: 'minConfidence', kind: 'number', min: 0, max: 1 },
+    { key: 'apiKey', kind: 'optionalString' },
+  ] },
+];
+
+function issueFor(section: string, field: FieldSpec): string {
+  const path = `${section}.${field.key}`;
+  switch (field.kind) {
+    case 'bool':
+      return `${path} 必须是 boolean`;
+    case 'int':
+      return `${path} 必须是 >= ${field.min} 的整数`;
+    case 'number':
+      return field.max === undefined
+        ? `${path} 必须是 >= ${field.minText ?? field.min} 的数字`
+        : `${path} 必须是 ${field.min} 到 ${field.max} 之间的数字`;
+    case 'ratio':
+      return `${path} 必须是 "auto" 或非负有限数`;
+    default:
+      return `${path} 必须是非空字符串`;
+  }
+}
+
+function applyField(target: Record<string, unknown>, field: FieldSpec, raw: unknown): boolean {
+  if (raw === undefined) return true;
+  const min = field.min ?? Number.NEGATIVE_INFINITY;
+  switch (field.kind) {
+    case 'bool':
+      if (typeof raw !== 'boolean') return false;
+      break;
+    case 'int':
+      if (typeof raw !== 'number' || !Number.isInteger(raw) || raw < min) return false;
+      break;
+    case 'number':
+      if (typeof raw !== 'number' || !Number.isFinite(raw) || raw < min) return false;
+      if (field.max !== undefined && raw > field.max) return false;
+      break;
+    case 'ratio':
+      if (raw !== 'auto' && (typeof raw !== 'number' || !Number.isFinite(raw) || raw < 0)) return false;
+      break;
+    case 'string':
+      if (typeof raw !== 'string' || !raw.trim()) return false;
+      target[field.key] = raw.trim();
+      return true;
+    case 'optionalString':
+      if (raw === '' || raw === null) {
+        target[field.key] = undefined;
+        return true;
+      }
+      if (typeof raw !== 'string' || !raw.trim()) return false;
+      target[field.key] = raw.trim();
+      return true;
+  }
+  target[field.key] = raw;
+  return true;
+}
+
+function defaults(): EfficiencyConfig {
+  return {
+    version: 1,
+    onlineContextCompact: { ...DEFAULT_EFFICIENCY_CONFIG.onlineContextCompact },
+    observationPack: { ...DEFAULT_EFFICIENCY_CONFIG.observationPack },
+    evidencePreservingReducer: { ...DEFAULT_EFFICIENCY_CONFIG.evidencePreservingReducer },
+    jev: { ...DEFAULT_EFFICIENCY_CONFIG.jev },
+  };
+}
 
 export interface ValidateConfigResult {
   ok: boolean;
@@ -168,301 +215,124 @@ export interface ValidateConfigResult {
 }
 
 export function validateEfficiencyConfig(raw: unknown): ValidateConfigResult {
+  const config = defaults();
   if (!isPlainObject(raw)) {
-    return {
-      ok: false,
-      config: {
-        version: 1,
-        onlineContextCompact: { ...DEFAULT_EFFICIENCY_CONFIG.onlineContextCompact, enabled: false },
-        observationPack: { ...DEFAULT_EFFICIENCY_CONFIG.observationPack, enabled: false },
-        evidencePreservingReducer: { ...DEFAULT_EFFICIENCY_CONFIG.evidencePreservingReducer, enabled: false },
-        jev: { ...DEFAULT_EFFICIENCY_CONFIG.jev, enabled: false },
-      },
-      issues: ['efficiency config 必须是 JSON 对象'],
-    };
+    for (const section of SECTIONS) config[section.name].enabled = false;
+    return { ok: false, config, issues: ['efficiency config 必须是 JSON 对象'] };
   }
 
-  const topIssues: string[] = [];
-  const occIssues: string[] = [];
-  const obsIssues: string[] = [];
-  const eprIssues: string[] = [];
-  const jevIssues: string[] = [];
-
-  for (const k of Object.keys(raw)) {
-    if (!TOP_LEVEL_KEYS.has(k)) {
-      topIssues.push(`未知顶层配置项: "${k}"`);
-    }
+  const issues: string[] = [];
+  for (const key of Object.keys(raw)) {
+    if (key !== 'version' && !SECTIONS.some((s) => s.name === key)) issues.push(`未知顶层配置项: "${key}"`);
   }
-
   if (raw.version !== undefined && raw.version !== 1) {
-    topIssues.push(`version 必须是 1 (当前: ${JSON.stringify(raw.version)})`);
-  }
-
-  // Section 1: onlineContextCompact
-  let occ: OnlineContextCompactConfig = { ...DEFAULT_EFFICIENCY_CONFIG.onlineContextCompact };
-  if (raw.onlineContextCompact !== undefined) {
-    if (!isPlainObject(raw.onlineContextCompact)) {
-      occIssues.push('onlineContextCompact 必须是 JSON 对象');
-    } else {
-      const o = raw.onlineContextCompact;
-      for (const k of Object.keys(o)) {
-        if (!OCC_KEYS.has(k)) occIssues.push(`onlineContextCompact 未知配置项: "${k}"`);
-      }
-      if (o.enabled !== undefined) {
-        if (typeof o.enabled !== 'boolean') occIssues.push('onlineContextCompact.enabled 必须是 boolean');
-        else occ.enabled = o.enabled;
-      }
-      if (o.logEnabled !== undefined) {
-        if (typeof o.logEnabled !== 'boolean') occIssues.push('onlineContextCompact.logEnabled 必须是 boolean');
-        else occ.logEnabled = o.logEnabled;
-      }
-      if (o.cacheWriteReadRatio !== undefined) {
-        if (o.cacheWriteReadRatio === 'auto') {
-          occ.cacheWriteReadRatio = 'auto';
-        } else if (typeof o.cacheWriteReadRatio === 'number' && Number.isFinite(o.cacheWriteReadRatio) && o.cacheWriteReadRatio >= 0) {
-          occ.cacheWriteReadRatio = o.cacheWriteReadRatio;
-        } else {
-          occIssues.push('onlineContextCompact.cacheWriteReadRatio 必须是 "auto" 或非负有限数');
-        }
-      }
-      if (o.keepRecentTokens !== undefined) {
-        if (typeof o.keepRecentTokens === 'number' && Number.isInteger(o.keepRecentTokens) && o.keepRecentTokens >= 1000) {
-          occ.keepRecentTokens = o.keepRecentTokens;
-        } else {
-          occIssues.push('onlineContextCompact.keepRecentTokens 必须是 >= 1000 的整数');
-        }
-      }
-      if (o.firstCompactionRequestScale !== undefined) {
-        if (typeof o.firstCompactionRequestScale === 'number' && Number.isFinite(o.firstCompactionRequestScale) && o.firstCompactionRequestScale >= 1.0) {
-          occ.firstCompactionRequestScale = o.firstCompactionRequestScale;
-        } else {
-          occIssues.push('onlineContextCompact.firstCompactionRequestScale 必须是 >= 1.0 的数字');
-        }
-      }
-      if (o.subsequentCompactionMargin !== undefined) {
-        if (typeof o.subsequentCompactionMargin === 'number' && Number.isFinite(o.subsequentCompactionMargin) && o.subsequentCompactionMargin >= 1.0) {
-          occ.subsequentCompactionMargin = o.subsequentCompactionMargin;
-        } else {
-          occIssues.push('onlineContextCompact.subsequentCompactionMargin 必须是 >= 1.0 的数字');
-        }
-      }
-    }
-  }
-
-  // Section 2: observationPack
-  let obs: ObservationPackConfig = { ...DEFAULT_EFFICIENCY_CONFIG.observationPack };
-  if (raw.observationPack !== undefined) {
-    if (!isPlainObject(raw.observationPack)) {
-      obsIssues.push('observationPack 必须是 JSON 对象');
-    } else {
-      const o = raw.observationPack;
-      for (const k of Object.keys(o)) {
-        if (!OBS_KEYS.has(k)) obsIssues.push(`observationPack 未知配置项: "${k}"`);
-      }
-      if (o.enabled !== undefined) {
-        if (typeof o.enabled !== 'boolean') obsIssues.push('observationPack.enabled 必须是 boolean');
-        else obs.enabled = o.enabled;
-      }
-      if (o.logEnabled !== undefined) {
-        if (typeof o.logEnabled !== 'boolean') obsIssues.push('observationPack.logEnabled 必须是 boolean');
-        else obs.logEnabled = o.logEnabled;
-      }
-      if (o.thresholdBytes !== undefined) {
-        if (typeof o.thresholdBytes === 'number' && Number.isInteger(o.thresholdBytes) && o.thresholdBytes >= 1024) {
-          obs.thresholdBytes = o.thresholdBytes;
-        } else {
-          obsIssues.push('observationPack.thresholdBytes 必须是 >= 1024 的整数');
-        }
-      }
-      if (o.fullSends !== undefined) {
-        if (typeof o.fullSends === 'number' && Number.isInteger(o.fullSends) && o.fullSends >= 1) {
-          obs.fullSends = o.fullSends;
-        } else {
-          obsIssues.push('observationPack.fullSends 必须是 >= 1 的整数');
-        }
-      }
-      if (o.recallChunkBytes !== undefined) {
-        if (typeof o.recallChunkBytes === 'number' && Number.isInteger(o.recallChunkBytes) && o.recallChunkBytes >= 1024) {
-          obs.recallChunkBytes = o.recallChunkBytes;
-        } else {
-          obsIssues.push('observationPack.recallChunkBytes 必须是 >= 1024 的整数');
-        }
-      }
-      if (o.excerptBytes !== undefined) {
-        if (typeof o.excerptBytes === 'number' && Number.isInteger(o.excerptBytes) && o.excerptBytes >= 128) {
-          obs.excerptBytes = o.excerptBytes;
-        } else {
-          obsIssues.push('observationPack.excerptBytes 必须是 >= 128 的整数');
-        }
-      }
-    }
-  }
-
-  // Section 3: evidencePreservingReducer
-  let epr: EvidencePreservingReducerConfig = { ...DEFAULT_EFFICIENCY_CONFIG.evidencePreservingReducer };
-  if (raw.evidencePreservingReducer !== undefined) {
-    if (!isPlainObject(raw.evidencePreservingReducer)) {
-      eprIssues.push('evidencePreservingReducer 必须是 JSON 对象');
-    } else {
-      const o = raw.evidencePreservingReducer;
-      for (const k of Object.keys(o)) {
-        if (!EPR_KEYS.has(k)) eprIssues.push(`evidencePreservingReducer 未知配置项: "${k}"`);
-      }
-      if (o.enabled !== undefined) {
-        if (typeof o.enabled !== 'boolean') eprIssues.push('evidencePreservingReducer.enabled 必须是 boolean');
-        else epr.enabled = o.enabled;
-      }
-      if (o.logEnabled !== undefined) {
-        if (typeof o.logEnabled !== 'boolean') eprIssues.push('evidencePreservingReducer.logEnabled 必须是 boolean');
-        else epr.logEnabled = o.logEnabled;
-      }
-      if (o.model !== undefined) {
-        if (typeof o.model === 'string' && o.model.trim()) {
-          epr.model = o.model.trim();
-        } else if (o.model === '' || o.model === null) {
-          epr.model = undefined;
-        } else {
-          eprIssues.push('evidencePreservingReducer.model 必须是非空字符串');
-        }
-      }
-      if (o.minBytes !== undefined) {
-        if (typeof o.minBytes === 'number' && Number.isInteger(o.minBytes) && o.minBytes >= 512) {
-          epr.minBytes = o.minBytes;
-        } else {
-          eprIssues.push('evidencePreservingReducer.minBytes 必须是 >= 512 的整数');
-        }
-      }
-      if (o.maxChars !== undefined) {
-        if (typeof o.maxChars === 'number' && Number.isInteger(o.maxChars) && o.maxChars >= 1000) {
-          epr.maxChars = o.maxChars;
-        } else {
-          eprIssues.push('evidencePreservingReducer.maxChars 必须是 >= 1000 的整数');
-        }
-      }
-      if (o.maxOutputTokens !== undefined) {
-        if (typeof o.maxOutputTokens === 'number' && Number.isInteger(o.maxOutputTokens) && o.maxOutputTokens >= 128) {
-          epr.maxOutputTokens = o.maxOutputTokens;
-        } else {
-          eprIssues.push('evidencePreservingReducer.maxOutputTokens 必须是 >= 128 的整数');
-        }
-      }
-      if (o.timeoutMs !== undefined) {
-        if (typeof o.timeoutMs === 'number' && Number.isInteger(o.timeoutMs) && o.timeoutMs >= 500) {
-          epr.timeoutMs = o.timeoutMs;
-        } else {
-          eprIssues.push('evidencePreservingReducer.timeoutMs 必须是 >= 500 的整数');
-        }
-      }
-      if (o.localOnly !== undefined) {
-        if (typeof o.localOnly !== 'boolean') eprIssues.push('evidencePreservingReducer.localOnly 必须是 boolean');
-        else epr.localOnly = o.localOnly;
-      }
-    }
+    issues.push(`version 必须是 1 (当前: ${JSON.stringify(raw.version)})`);
   }
-
-  // Section 4: jev decision layer
-  let jev: JevConfig = { ...DEFAULT_EFFICIENCY_CONFIG.jev };
-  if (raw.jev !== undefined) {
-    if (!isPlainObject(raw.jev)) {
-      jevIssues.push('jev 必须是 JSON 对象');
-    } else {
-      const o = raw.jev;
-      for (const k of Object.keys(o)) {
-        if (JEV_KEYS[k] !== true) jevIssues.push(`jev 未知配置项: "${k}"`);
-      }
-      if (o.enabled !== undefined) {
-        if (typeof o.enabled !== 'boolean') jevIssues.push('jev.enabled 必须是 boolean');
-        else jev.enabled = o.enabled;
-      }
-      if (o.logEnabled !== undefined) {
-        if (typeof o.logEnabled !== 'boolean') jevIssues.push('jev.logEnabled 必须是 boolean');
-        else jev.logEnabled = o.logEnabled;
-      }
-      if (o.baseUrl !== undefined) {
-        if (typeof o.baseUrl === 'string' && o.baseUrl.trim()) {
-          jev.baseUrl = o.baseUrl.trim();
-        } else if (o.baseUrl === '' || o.baseUrl === null) {
-          jev.baseUrl = undefined;
-        } else {
-          jevIssues.push('jev.baseUrl 必须是非空字符串');
-        }
-      }
-      if (o.model !== undefined) {
-        if (typeof o.model === 'string' && o.model.trim()) {
-          jev.model = o.model.trim();
-        } else {
-          jevIssues.push('jev.model 必须是非空字符串');
-        }
-      }
-      if (o.timeoutMs !== undefined) {
-        if (typeof o.timeoutMs === 'number' && Number.isInteger(o.timeoutMs) && o.timeoutMs >= 500) {
-          jev.timeoutMs = o.timeoutMs;
-        } else {
-          jevIssues.push('jev.timeoutMs 必须是 >= 500 的整数');
+  const topLevelInvalid = issues.length > 0;
+
+  for (const section of SECTIONS) {
+    const issueCountBefore = issues.length;
+    const target = config[section.name] as unknown as Record<string, unknown>;
+    const rawSection = raw[section.name];
+    if (rawSection !== undefined) {
+      if (!isPlainObject(rawSection)) {
+        issues.push(`${section.name} 必须是 JSON 对象`);
+      } else {
+        for (const key of Object.keys(rawSection)) {
+          if (!section.fields.some((f) => f.key === key)) issues.push(`${section.name} 未知配置项: "${key}"`);
         }
-      }
-      if (o.minConfidence !== undefined) {
-        if (typeof o.minConfidence === 'number' && Number.isFinite(o.minConfidence) && o.minConfidence >= 0 && o.minConfidence <= 1) {
-          jev.minConfidence = o.minConfidence;
-        } else {
-          jevIssues.push('jev.minConfidence 必须是 0 到 1 之间的数字');
-        }
-      }
-      if (o.apiKey !== undefined) {
-        if (typeof o.apiKey === 'string' && o.apiKey.trim()) {
-          jev.apiKey = o.apiKey.trim();
-        } else if (o.apiKey === '' || o.apiKey === null) {
-          jev.apiKey = undefined;
-        } else {
-          jevIssues.push('jev.apiKey 必须是非空字符串');
+        for (const field of section.fields) {
+          if (!applyField(target, field, rawSection[field.key])) issues.push(issueFor(section.name, field));
         }
       }
     }
+    // Fail-open: an invalid section (or an invalid top level) can never enable a mechanism.
+    if (topLevelInvalid || issues.length > issueCountBefore) config[section.name].enabled = false;
   }
 
-  // Fail-open: any section with validation issues has its enabled flag forced to false
-  if (topIssues.length > 0) {
-    occ.enabled = false;
-    obs.enabled = false;
-    epr.enabled = false;
-    jev.enabled = false;
-  }
-  if (occIssues.length > 0) {
-    occ.enabled = false;
-  }
-  if (obsIssues.length > 0) {
-    obs.enabled = false;
-  }
-  if (eprIssues.length > 0) {
-    epr.enabled = false;
-  }
-  if (jevIssues.length > 0) {
-    jev.enabled = false;
-  }
-
-  const issues = [...topIssues, ...occIssues, ...obsIssues, ...eprIssues, ...jevIssues];
-
-  return {
-    ok: issues.length === 0,
-    config: {
-      version: 1,
-      onlineContextCompact: occ,
-      observationPack: obs,
-      evidencePreservingReducer: epr,
-      jev,
-    },
-    issues,
-  };
+  return { ok: issues.length === 0, config, issues };
 }
 
-function parseEnvBool(val: string | undefined): boolean | undefined {
-  if (!val) return undefined;
+function parseEnvBool(val: string): boolean | undefined {
   const s = val.trim().toLowerCase();
   if (s === '1' || s === 'true' || s === 'on') return true;
   if (s === '0' || s === 'false' || s === 'off') return false;
   return undefined;
 }
 
+interface EnvOverride {
+  readonly env: string;
+  readonly section: SectionSpec['name'];
+  readonly key: string;
+  readonly kind: 'bool' | 'string' | 'ratio' | 'int' | 'unit';
+  readonly min?: number;
+  /** Set only when the config left the key unset (foreign-convention fallback). */
+  readonly fallbackOnly?: boolean;
+}
+
+/** Highest-precedence layer; an empty value counts as unset everywhere. */
+const ENV_OVERRIDES: readonly EnvOverride[] = [
+  { env: 'PI_HERDR_COMPACT_ENABLE', section: 'onlineContextCompact', key: 'enabled', kind: 'bool' },
+  { env: 'PI_HERDR_COMPACT_LOG', section: 'onlineContextCompact', key: 'logEnabled', kind: 'bool' },
+  { env: 'PI_HERDR_CACHE_RATIO', section: 'onlineContextCompact', key: 'cacheWriteReadRatio', kind: 'ratio' },
+  { env: 'PI_HERDR_OBS_PACK_ENABLE', section: 'observationPack', key: 'enabled', kind: 'bool' },
+  { env: 'PI_HERDR_OBS_PACK_LOG', section: 'observationPack', key: 'logEnabled', kind: 'bool' },
+  { env: 'PI_HERDR_REDUCER_ENABLE', section: 'evidencePreservingReducer', key: 'enabled', kind: 'bool' },
+  { env: 'PI_HERDR_REDUCER_LOG', section: 'evidencePreservingReducer', key: 'logEnabled', kind: 'bool' },
+  { env: 'PI_HERDR_REDUCER_MODEL', section: 'evidencePreservingReducer', key: 'model', kind: 'string' },
+  // jev has no legacy spelling: PIER_JEV_* is canonical from the start.
+  { env: 'PIER_JEV_ENABLE', section: 'jev', key: 'enabled', kind: 'bool' },
+  { env: 'PIER_JEV_LOG', section: 'jev', key: 'logEnabled', kind: 'bool' },
+  { env: 'PIER_JEV_MODEL', section: 'jev', key: 'model', kind: 'string' },
+  { env: 'PIER_JEV_BASE_URL', section: 'jev', key: 'baseUrl', kind: 'string' },
+  { env: 'PIER_JEV_TIMEOUT_MS', section: 'jev', key: 'timeoutMs', kind: 'int', min: 500 },
+  { env: 'PIER_JEV_MIN_CONFIDENCE', section: 'jev', key: 'minConfidence', kind: 'unit' },
+  { env: 'PIER_JEV_API_KEY', section: 'jev', key: 'apiKey', kind: 'string' },
+  // TYPESAFE_API_KEY is a foreign (SDK) convention, so it ranks below the config file too.
+  { env: 'TYPESAFE_API_KEY', section: 'jev', key: 'apiKey', kind: 'string', fallbackOnly: true },
+];
+
+function applyEnvOverrides(
+  config: EfficiencyConfig,
+  env: Record<string, string | undefined>,
+  warn: (message: string) => void,
+): void {
+  for (const override of ENV_OVERRIDES) {
+    const raw = env[override.env];
+    if (raw === undefined || raw === '') continue;
+    const target = config[override.section] as unknown as Record<string, unknown>;
+    if (override.fallbackOnly && target[override.key] !== undefined) continue;
+
+    if (override.kind === 'bool') {
+      const parsed = parseEnvBool(raw);
+      if (parsed !== undefined) target[override.key] = parsed;
+      continue;
+    }
+    if (override.kind === 'string') {
+      if (raw.trim()) target[override.key] = raw.trim();
+      continue;
+    }
+    if (override.kind === 'ratio' && raw.trim().toLowerCase() === 'auto') {
+      target[override.key] = 'auto';
+      continue;
+    }
+    const num = Number(raw);
+    const valid =
+      override.kind === 'ratio' ? Number.isFinite(num) && num >= 0
+      : override.kind === 'unit' ? Number.isFinite(num) && num >= 0 && num <= 1
+      : Number.isInteger(num) && num >= (override.min ?? 0);
+    if (valid) {
+      target[override.key] = num;
+      continue;
+    }
+    const requirement =
+      override.kind === 'unit' ? '（需 0 到 1）'
+      : override.kind === 'int' ? `（需 >= ${override.min} 的整数）`
+      : '';
+    warn(`无效环境变量 ${override.env}="${raw}"${requirement}，忽略`);
+  }
+}
+
 export interface ResolveConfigOptions {
   workspaceConfig?: unknown;
   userConfig?: unknown;
@@ -473,128 +343,28 @@ export interface ResolveConfigOptions {
 
 export function resolveEfficiencyConfig(opts: ResolveConfigOptions = {}): EfficiencyConfig {
   const env = opts.env ?? process.env;
-  const warn = opts.onWarning ?? ((msg) => console.warn(`[pi-herdr] efficiency config warning: ${msg}`));
+  const warn = opts.onWarning ?? ((msg: string) => console.warn(`[pi-herdr] efficiency config warning: ${msg}`));
   const isTrusted = opts.isProjectTrusted ?? false;
 
-  let baseRaw: unknown = undefined;
-
+  // An untrusted project's file is ignored wholesale (never merged with the user layer).
+  let baseRaw: unknown = opts.userConfig;
   if (opts.workspaceConfig !== undefined) {
-    if (isTrusted) {
-      baseRaw = opts.workspaceConfig;
-    } else {
-      warn('工作区能效配置未被信任（isProjectTrusted=false），已安全忽略工作区配置');
-      baseRaw = opts.userConfig;
-    }
-  } else {
-    baseRaw = opts.userConfig;
+    if (isTrusted) baseRaw = opts.workspaceConfig;
+    else warn('工作区能效配置未被信任（isProjectTrusted=false），已安全忽略工作区配置');
   }
 
-  let resolved: EfficiencyConfig;
+  let resolved = defaults();
   if (baseRaw !== undefined) {
     const validated = validateEfficiencyConfig(baseRaw);
-    if (!validated.ok) {
-      warn(`配置存在校验问题，已安全回退默认值: ${validated.issues.join('; ')}`);
-    }
+    if (!validated.ok) warn(`配置存在校验问题，已安全回退默认值: ${validated.issues.join('; ')}`);
     resolved = validated.config;
-  } else {
-    resolved = {
-      version: 1,
-      onlineContextCompact: { ...DEFAULT_EFFICIENCY_CONFIG.onlineContextCompact },
-      observationPack: { ...DEFAULT_EFFICIENCY_CONFIG.observationPack },
-      evidencePreservingReducer: { ...DEFAULT_EFFICIENCY_CONFIG.evidencePreservingReducer },
-      jev: { ...DEFAULT_EFFICIENCY_CONFIG.jev },
-    };
-  }
-
-  // Apply environment variable overrides (highest precedence)
-  const occEnabled = parseEnvBool(env.PI_HERDR_COMPACT_ENABLE);
-  if (occEnabled !== undefined) resolved.onlineContextCompact.enabled = occEnabled;
-
-  const occLog = parseEnvBool(env.PI_HERDR_COMPACT_LOG);
-  if (occLog !== undefined) resolved.onlineContextCompact.logEnabled = occLog;
-
-  const cacheRatioRaw = env.PI_HERDR_CACHE_RATIO;
-  if (cacheRatioRaw !== undefined) {
-    if (cacheRatioRaw.trim().toLowerCase() === 'auto') {
-      resolved.onlineContextCompact.cacheWriteReadRatio = 'auto';
-    } else {
-      const num = Number(cacheRatioRaw);
-      if (Number.isFinite(num) && num >= 0) {
-        resolved.onlineContextCompact.cacheWriteReadRatio = num;
-      } else {
-        warn(`无效环境变量 PI_HERDR_CACHE_RATIO="${cacheRatioRaw}"，忽略`);
-      }
-    }
-  }
-
-  const obsEnabled = parseEnvBool(env.PI_HERDR_OBS_PACK_ENABLE);
-  if (obsEnabled !== undefined) resolved.observationPack.enabled = obsEnabled;
-
-  const obsLog = parseEnvBool(env.PI_HERDR_OBS_PACK_LOG);
-  if (obsLog !== undefined) resolved.observationPack.logEnabled = obsLog;
-
-  const redEnabled = parseEnvBool(env.PI_HERDR_REDUCER_ENABLE);
-  if (redEnabled !== undefined) resolved.evidencePreservingReducer.enabled = redEnabled;
-
-  const redLog = parseEnvBool(env.PI_HERDR_REDUCER_LOG);
-  if (redLog !== undefined) resolved.evidencePreservingReducer.logEnabled = redLog;
-
-  const redModel = env.PI_HERDR_REDUCER_MODEL;
-  if (redModel !== undefined && redModel.trim()) {
-    resolved.evidencePreservingReducer.model = redModel.trim();
-  }
-
-  // jev decision layer (new mechanism: canonical PIER_JEV_* only, no legacy spelling exists).
-  // TYPESAFE_API_KEY is a foreign-convention fallback (TypeSafe SDK reads it), so it ranks
-  // below pier's own env and below an explicit config-file key.
-  const jevEnabled = parseEnvBool(env.PIER_JEV_ENABLE);
-  if (jevEnabled !== undefined) resolved.jev.enabled = jevEnabled;
-
-  const jevLog = parseEnvBool(env.PIER_JEV_LOG);
-  if (jevLog !== undefined) resolved.jev.logEnabled = jevLog;
-
-  const jevModel = env.PIER_JEV_MODEL;
-  if (jevModel !== undefined && jevModel.trim()) {
-    resolved.jev.model = jevModel.trim();
-  }
-
-  const jevBase = env.PIER_JEV_BASE_URL;
-  if (jevBase !== undefined && jevBase.trim()) {
-    resolved.jev.baseUrl = jevBase.trim();
-  }
-
-  const jevTimeoutRaw = env.PIER_JEV_TIMEOUT_MS;
-  if (jevTimeoutRaw !== undefined) {
-    const num = Number(jevTimeoutRaw);
-    if (Number.isInteger(num) && num >= 500) {
-      resolved.jev.timeoutMs = num;
-    } else {
-      warn(`无效环境变量 PIER_JEV_TIMEOUT_MS="${jevTimeoutRaw}"（需 >= 500 的整数），忽略`);
-    }
-  }
-
-  const jevMinConfRaw = env.PIER_JEV_MIN_CONFIDENCE;
-  if (jevMinConfRaw !== undefined) {
-    const num = Number(jevMinConfRaw);
-    if (Number.isFinite(num) && num >= 0 && num <= 1) {
-      resolved.jev.minConfidence = num;
-    } else {
-      warn(`无效环境变量 PIER_JEV_MIN_CONFIDENCE="${jevMinConfRaw}"（需 0 到 1），忽略`);
-    }
-  }
-
-  const jevKey = env.PIER_JEV_API_KEY;
-  if (jevKey !== undefined && jevKey.trim()) {
-    resolved.jev.apiKey = jevKey.trim();
-  }
-  if (!resolved.jev.apiKey && env.TYPESAFE_API_KEY && env.TYPESAFE_API_KEY.trim()) {
-    resolved.jev.apiKey = env.TYPESAFE_API_KEY.trim();
   }
 
+  applyEnvOverrides(resolved, env, warn);
   return resolved;
 }
 
-export function defaultUserEfficiencyConfigDir(): string {
+function defaultUserEfficiencyConfigDir(): string {
   return join(homedir(), '.pi', 'agent', 'herdr-pi');
 }
 
@@ -606,6 +376,44 @@ export function defaultUserEfficiencyConfigFile(): string {
   return join(defaultUserEfficiencyConfigDir(), 'config.json');
 }
 
+interface PiCompactionSettings {
+  enabled?: boolean;
+  keepRecentTokens?: number;
+}
+
+function readCompactionSettings(filePath: string): PiCompactionSettings {
+  const parsed = readJsonConfig(filePath);
+  if (!isPlainObject(parsed) || !isPlainObject(parsed.compaction)) return {};
+  const { compaction } = parsed;
+  const result: PiCompactionSettings = {};
+  if (typeof compaction.enabled === 'boolean') result.enabled = compaction.enabled;
+  if (typeof compaction.keepRecentTokens === 'number') result.keepRecentTokens = compaction.keepRecentTokens;
+  return result;
+}
+
+function readJsonConfig(filePath: string, onError?: (error: unknown) => void): unknown {
+  if (!existsSync(filePath)) return undefined;
+  try {
+    return JSON.parse(readFileSync(filePath, 'utf8')) as unknown;
+  } catch (error) {
+    onError?.(error);
+    return undefined;
+  }
+}
+
+/** Pi's own compaction settings: global, plus the project file when the project is trusted. */
+export function loadPiNativeCompactionSettings(opts: {
+  cwd?: string;
+  isProjectTrusted?: boolean;
+  agentDir?: string;
+} = {}): PiCompactionSettings {
+  const cwd = opts.cwd ?? process.cwd();
+  const agentDir = opts.agentDir ?? process.env.PI_CODING_AGENT_DIR ?? join(homedir(), '.pi', 'agent');
+  const globalSettings = readCompactionSettings(join(agentDir, 'settings.json'));
+  if (!opts.isProjectTrusted) return globalSettings;
+  return { ...globalSettings, ...readCompactionSettings(join(cwd, '.pi', 'settings.json')) };
+}
+
 export function loadEfficiencyConfigFromDisk(opts: {
   cwd?: string;
   isProjectTrusted?: boolean;
@@ -613,13 +421,11 @@ export function loadEfficiencyConfigFromDisk(opts: {
   onWarning?: (msg: string) => void;
   /** Override the Pi agent dir used to read native `settings.json` (tests/isolation). */
   agentDir?: string;
-  /** Override the user-level efficiency config file path (tests/isolation). */
   userConfigPath?: string;
 } = {}): EfficiencyConfig {
   const cwd = opts.cwd ?? process.cwd();
   const wsPath = defaultWorkspaceEfficiencyConfigFile(cwd);
   const userPath = opts.userConfigPath ?? defaultUserEfficiencyConfigFile();
-
   const warnFile = (label: string, filePath: string, error: unknown): void => {
     opts.onWarning?.(`${label} ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
   };
@@ -639,23 +445,20 @@ export function loadEfficiencyConfigFromDisk(opts: {
     agentDir: opts.agentDir,
   });
 
-  // If user disabled compaction globally in pi settings, and env didn't explicitly force OCC enable, respect it!
+  // pi's global compaction switch wins over an explicitly enabled OCC — only an env force overrides it.
   const env = opts.env ?? process.env;
   if (piSettings.enabled === false && !env.PI_HERDR_COMPACT_ENABLE) {
     resolved.onlineContextCompact.enabled = false;
   }
-
-  const hasExplicitKeepRecent = [
-    opts.isProjectTrusted ? workspaceConfig : undefined,
-    userConfig,
-  ].some((config) => isPlainObject(config)
-    && isPlainObject(config.onlineContextCompact)
-    && config.onlineContextCompact.keepRecentTokens !== undefined);
-
+  const hasExplicitKeepRecent = [opts.isProjectTrusted ? workspaceConfig : undefined, userConfig].some(
+    (config) =>
+      isPlainObject(config)
+      && isPlainObject(config.onlineContextCompact)
+      && config.onlineContextCompact.keepRecentTokens !== undefined,
+  );
+  // pi's keepRecentTokens is inherited only while the efficiency config does not set its own.
   if (!hasExplicitKeepRecent && typeof piSettings.keepRecentTokens === 'number') {
     resolved.onlineContextCompact.keepRecentTokens = piSettings.keepRecentTokens;
   }
-
   return resolved;
 }
-