@akemi-mio/creativity 0.1.0 → 0.2.0

package/dist/FeedbackRuntime.d.ts

@@ -0,0 +1,37 @@
+/**
+ * FeedbackRuntime — 正向反馈闭环受控启用（设计 v1.0，P3）
+ *
+ * 把"是否/如何消费反馈"从代码常量提升为可配置、可校验的运行时状态（R6 纪律）：
+ *   - off     关闭：生成行为与无反馈时逐字节一致（默认）。
+ *   - shadow  影子运行：计算反馈调整并记录 delta，但不应用到排序/prompt。
+ *   - canary 小流量：按比例应用反馈（λ 与探索预算生效）。
+ *   - full    正式启用：全部应用。
+ *
+ * 每阶段预固定基线、指标与回滚条件；回滚 = 切回 off（配置热切换，无需发版）。
+ * 反馈永不进入 checkPromotionGate/checkSubmitGate 输入（spec §二.2）。
+ */
+export type FeedbackMode = 'off' | 'shadow' | 'canary' | 'full';
+export interface FeedbackRuntimeConfig {
+    mode: FeedbackMode;
+    /** λ clamp：单对调整占总评分范围的比例上限 */
+    lambdaClampPct: number;
+    /** 探索预算：保留给低频/新组合的槽位比例 */
+    explorationBudget: number;
+    /** 证据时间衰减半衰期（天） */
+    halfLifeDays: number;
+    /** canary 模式应用反馈的比例 0..1 */
+    canaryFraction: number;
+}
+export declare const DEFAULT_FEEDBACK_RUNTIME: FeedbackRuntimeConfig;
+export declare const FEEDBACK_MODES: readonly FeedbackMode[];
+/**
+ * 解析并校验运行时配置；失败返回 null（fail-closed，调用方回退默认 off）。
+ * 未知字段忽略。
+ */
+export declare function parseFeedbackRuntime(raw: unknown): FeedbackRuntimeConfig | null;
+/** 从环境变量解析（缺省全 off）。 */
+export declare function resolveFeedbackRuntime(env?: Record<string, string | undefined>): FeedbackRuntimeConfig;
+/** 该模式下是否实际应用反馈到生成（shadow 只观测）。 */
+export declare function isFeedbackApplied(mode: FeedbackMode): boolean;
+/** 该模式下是否观测（计算 delta 并记录）。 */
+export declare function isFeedbackObserved(mode: FeedbackMode): boolean;

package/dist/FeedbackRuntime.js

@@ -0,0 +1,72 @@
+"use strict";
+/**
+ * FeedbackRuntime — 正向反馈闭环受控启用（设计 v1.0，P3）
+ *
+ * 把"是否/如何消费反馈"从代码常量提升为可配置、可校验的运行时状态（R6 纪律）：
+ *   - off     关闭：生成行为与无反馈时逐字节一致（默认）。
+ *   - shadow  影子运行：计算反馈调整并记录 delta，但不应用到排序/prompt。
+ *   - canary 小流量：按比例应用反馈（λ 与探索预算生效）。
+ *   - full    正式启用：全部应用。
+ *
+ * 每阶段预固定基线、指标与回滚条件；回滚 = 切回 off（配置热切换，无需发版）。
+ * 反馈永不进入 checkPromotionGate/checkSubmitGate 输入（spec §二.2）。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FEEDBACK_MODES = exports.DEFAULT_FEEDBACK_RUNTIME = void 0;
+exports.parseFeedbackRuntime = parseFeedbackRuntime;
+exports.resolveFeedbackRuntime = resolveFeedbackRuntime;
+exports.isFeedbackApplied = isFeedbackApplied;
+exports.isFeedbackObserved = isFeedbackObserved;
+exports.DEFAULT_FEEDBACK_RUNTIME = {
+    mode: 'off',
+    lambdaClampPct: 0.1,
+    explorationBudget: 0.2,
+    halfLifeDays: 30,
+    canaryFraction: 0.1,
+};
+exports.FEEDBACK_MODES = ['off', 'shadow', 'canary', 'full'];
+function clampNumber(value, min, max, fallback) {
+    const num = typeof value === 'string' ? Number(value) : value;
+    if (typeof num !== 'number' || !Number.isFinite(num))
+        return fallback;
+    return Math.max(min, Math.min(max, num));
+}
+/**
+ * 解析并校验运行时配置；失败返回 null（fail-closed，调用方回退默认 off）。
+ * 未知字段忽略。
+ */
+function parseFeedbackRuntime(raw) {
+    if (raw === null || typeof raw !== 'object')
+        return null;
+    const obj = raw;
+    const mode = obj.mode;
+    if (!exports.FEEDBACK_MODES.includes(mode))
+        return null;
+    return {
+        mode: mode,
+        lambdaClampPct: clampNumber(obj.lambdaClampPct, 0, 0.5, exports.DEFAULT_FEEDBACK_RUNTIME.lambdaClampPct),
+        explorationBudget: clampNumber(obj.explorationBudget, 0, 1, exports.DEFAULT_FEEDBACK_RUNTIME.explorationBudget),
+        halfLifeDays: clampNumber(obj.halfLifeDays, 1, 3650, exports.DEFAULT_FEEDBACK_RUNTIME.halfLifeDays),
+        canaryFraction: clampNumber(obj.canaryFraction, 0, 1, exports.DEFAULT_FEEDBACK_RUNTIME.canaryFraction),
+    };
+}
+/** 从环境变量解析（缺省全 off）。 */
+function resolveFeedbackRuntime(env = process.env) {
+    const parsed = parseFeedbackRuntime({
+        mode: env.MIO_FEEDBACK_MODE,
+        lambdaClampPct: env.MIO_FEEDBACK_LAMBDA_PCT,
+        explorationBudget: env.MIO_FEEDBACK_EXPLORATION,
+        halfLifeDays: env.MIO_FEEDBACK_HALF_LIFE_DAYS,
+        canaryFraction: env.MIO_FEEDBACK_CANARY_FRACTION,
+    });
+    // env 全缺省时 parse 返回 null（mode undefined）→ 回退默认 off
+    return parsed ?? exports.DEFAULT_FEEDBACK_RUNTIME;
+}
+/** 该模式下是否实际应用反馈到生成（shadow 只观测）。 */
+function isFeedbackApplied(mode) {
+    return mode === 'canary' || mode === 'full';
+}
+/** 该模式下是否观测（计算 delta 并记录）。 */
+function isFeedbackObserved(mode) {
+    return mode === 'shadow' || mode === 'canary' || mode === 'full';
+}

package/dist/HypothesisGenerator.d.ts

@@ -1,4 +1,5 @@
 import type { Hypothesis, ConceptCombo, CreativitySource, ExternalSignal } from './types';
+import type { FeedbackPromptBlock } from './FeedbackLearning';
 /**
  * HypothesisGenerator — 将概念组合转化为可验证的假设
  *
@@ -38,7 +39,9 @@ export declare class HypothesisGenerator {
     /** 外部信号 — 不参与配对，作为审视视角注入 LLM */
     externalSignals?: ExternalSignal[], 
     /** 显式技法；缺省走五技法轮换（rotationSeed + 调用次数） */
-    method?: string): Promise<Hypothesis[]>;
+    method?: string, 
+    /** 正向反馈闭环 P2：不可变快照的结构化提示块。缺省 = 提示词逐字节不变。 */
+    feedback?: FeedbackPromptBlock): Promise<Hypothesis[]>;
     /**
      * 调 LLM 生成创意
      */

package/dist/HypothesisGenerator.js

@@ -42,13 +42,15 @@ class HypothesisGenerator {
     /** 外部信号 — 不参与配对，作为审视视角注入 LLM */
     externalSignals = [], 
     /** 显式技法；缺省走五技法轮换（rotationSeed + 调用次数） */
-    method) {
+    method, 
+    /** 正向反馈闭环 P2：不可变快照的结构化提示块。缺省 = 提示词逐字节不变。 */
+    feedback) {
         if (combos.length === 0)
             return [];
         const technique = method ?? (0, CreativityPrompt_1.pickTechnique)(this.rotationSeed + this.callCount);
         this.callCount += 1;
         // 第一级：远程 LLM 驱动生成
-        const llmResults = await this.tryLLM(sources, combos, dreamMode, externalSignals, technique);
+        const llmResults = await this.tryLLM(sources, combos, dreamMode, externalSignals, technique, feedback);
         if (llmResults.length > 0) {
             return this.tag(llmResults.map((r) => ({
                 id: `hyp_${Date.now()}_${++this.idCounter}_${this.rng().toString(36).slice(2, 4)}`,
@@ -68,7 +70,7 @@ class HypothesisGenerator {
         // 第二级：本地 transformers.js 模型
         if (this.localModel.isEnabled) {
             (0, Logger_1.log)('INFO', 'hypothesis_fallback_local', { count: combos.length });
-            const localResults = await this.tryLocalModel(sources, combos, dreamMode, technique);
+            const localResults = await this.tryLocalModel(sources, combos, dreamMode, technique, feedback);
             if (localResults.length > 0) {
                 return this.tag(localResults.map((r) => ({
                     id: `hyp_local_${Date.now()}_${++this.idCounter}_${this.rng().toString(36).slice(2, 4)}`,
@@ -105,14 +107,14 @@ class HypothesisGenerator {
     /**
      * 调 LLM 生成创意
      */
-    async tryLLM(sources, combos, dreamMode, externalSignals = [], technique = '') {
+    async tryLLM(sources, combos, dreamMode, externalSignals = [], technique = '', feedback) {
         // 限制输入量，避免超 token
         const topCombos = combos.slice(0, dreamMode ? 5 : 3);
         const comboInfo = topCombos.map((c) => ({
             sources: c.sources,
             description: c.description,
         }));
-        const prompt = (0, CreativityPrompt_1.buildCreativityPrompt)(sources, comboInfo, externalSignals);
+        const prompt = (0, CreativityPrompt_1.buildCreativityPrompt)(sources, comboInfo, externalSignals, feedback);
         try {
             const result = await this.chatJson(prompt, {
                 system: (0, CreativityPrompt_1.buildSystemPrompt)(technique),
@@ -141,13 +143,13 @@ class HypothesisGenerator {
     /**
      * 调本地 transformers.js 模型生成创意
      */
-    async tryLocalModel(sources, combos, dreamMode, technique = '') {
+    async tryLocalModel(sources, combos, dreamMode, technique = '', feedback) {
         const topCombos = combos.slice(0, dreamMode ? 3 : 2);
         const comboInfo = topCombos.map((c) => ({
             sources: c.sources,
             description: c.description,
         }));
-        const prompt = (0, CreativityPrompt_1.buildCreativityPrompt)(sources, comboInfo);
+        const prompt = (0, CreativityPrompt_1.buildCreativityPrompt)(sources, comboInfo, [], feedback);
         const result = await this.localModel.generate(prompt, {
             system: (0, CreativityPrompt_1.buildSystemPrompt)(technique),
             temperature: dreamMode ? 0.8 : 0.6,

package/dist/IdeaGenerator.d.ts

@@ -1,4 +1,6 @@
 import type { CreativitySource, ConceptCombo, Hypothesis, CreativeIdea, Strategy, ExternalSignal } from './types';
+import { type FeedbackMixerInput } from './ConceptMixer';
+import type { FeedbackPromptBlock } from './FeedbackLearning';
 /**
  * IdeaGenerator — 创造力引擎的核心编排器
  *
@@ -29,7 +31,11 @@ export declare class IdeaGenerator {
      * 完整一轮"灵感涌现"流程
      * @param strategy 生成策略，约束 ConceptMixer 配对空间
      */
-    generateIdeas(sources: CreativitySource[], maxIdeas?: number, strategy?: Strategy, externalSignals?: ExternalSignal[], method?: string): Promise<CreativeIdea[]>;
+    generateIdeas(sources: CreativitySource[], maxIdeas?: number, strategy?: Strategy, externalSignals?: ExternalSignal[], method?: string, 
+    /** 正向反馈闭环 P2：结构化提示块（缺省 = 提示词逐字节不变）。 */
+    feedbackPrompt?: FeedbackPromptBlock, 
+    /** 正向反馈闭环 P2：mixer 有界修正 + 探索预算（缺省 = 配对排序逐字节不变）。 */
+    mixerFeedback?: FeedbackMixerInput): Promise<CreativeIdea[]>;
     /**
      * Dream Mode — 高随机性、跨时间跨度的"梦境"模式
      */

package/dist/IdeaGenerator.js

@@ -34,18 +34,22 @@ class IdeaGenerator {
      * 完整一轮"灵感涌现"流程
      * @param strategy 生成策略，约束 ConceptMixer 配对空间
      */
-    async generateIdeas(sources, maxIdeas = 5, strategy = 'explore', externalSignals = [], method) {
+    async generateIdeas(sources, maxIdeas = 5, strategy = 'explore', externalSignals = [], method, 
+    /** 正向反馈闭环 P2：结构化提示块（缺省 = 提示词逐字节不变）。 */
+    feedbackPrompt, 
+    /** 正向反馈闭环 P2：mixer 有界修正 + 探索预算（缺省 = 配对排序逐字节不变）。 */
+    mixerFeedback) {
         if (sources.length < 2)
             return [];
         // 1. 随机扰动：温度越高，来源选择越随机
         const activeSources = this.applyTemperature(sources);
-        // 2. 概念重组：按策略约束配对 + 打分
-        const scoredCombos = this.mixer.mix(activeSources, maxIdeas * 3, this.exploredPairs, strategy);
+        // 2. 概念重组：按策略约束配对 + 打分（可选反馈有界修正）
+        const scoredCombos = this.mixer.mix(activeSources, maxIdeas * 3, this.exploredPairs, strategy, mixerFeedback);
         const combos = scoredCombos.map((c) => c.combo);
         if (combos.length === 0)
             return [];
         // 3. 用 LLM 生成假设（外部信号作为审视视角注入，不参与配对）
-        const hypotheses = await this.hypothesisGen.generate(combos, activeSources, false, externalSignals, method);
+        const hypotheses = await this.hypothesisGen.generate(combos, activeSources, false, externalSignals, method, feedbackPrompt);
         // 4. 可行性/质量门禁（与 dream 模式同一套门槛）——此前只有梦境路径
         //    过 feasibilityGate，主路径仅按 novelty 筛，可行性 0 分也能入库。
         const feasible = this.feasibilityGate(hypotheses);

package/dist/InsightSamplingExperiment.d.ts

@@ -0,0 +1,82 @@
+/**
+ * InsightSamplingExperiment — insight 抽样策略 dogfood 实验（机制涌现 P3，定案 D4/R4）
+ *
+ * 首域 = insight 抽样策略（issue-6 P4 sourceQuota 有现成 before/after + 历史 observations 可重放）。
+ * 三组对照：现有 quota 抽样 / 变体 A / 变体 B + 消融（移除配额/移除时间序保持）+ 未见任务泛化。
+ * 产出 CapabilityDelta 报告；允许 inconclusive（不逼结论）。
+ * 硬前置 A1：MIO EXPERIMENT 标志路由 experiment-memory.jsonl（由 ExperimentRunStore 提供）。
+ */
+import type { ExperimentRun } from './ExperimentRunStore';
+/** Observation 最小形状（内联，避免跨包依赖） */
+interface ObservationLike {
+    id: string;
+    timestamp: string;
+    source: string;
+    content: string;
+}
+export type SamplingVariant = 'baseline' | 'variant_a' | 'variant_b' | 'ablation_no_quota' | 'ablation_no_time_order';
+/**
+ * baseline: 现有 quota 抽样（issue-6 P4 sampleBySourceQuota）。
+ * variant_a: 更高 minPerSource（保底提升，家族优先更强）。
+ * variant_b: 只用 Phase A 保底，不做 Phase B 余量补齐（纯家族公平）。
+ * ablation_no_quota: 移除配额 → 退化为 slice(0, limit)（issue-6 修复前）。
+ * ablation_no_time_order: 移除时间序保持 → 输出按 weight 降序。
+ */
+export declare function sampleVariant(observations: readonly ObservationLike[], variant: SamplingVariant, limit?: number): ObservationLike[];
+export interface SamplingMetrics {
+    /** 家族覆盖数（sourceFamily 去重） */
+    familyCoverage: number;
+    /** 最大家族占比（0-1；越低越公平） */
+    maxFamilyShare: number;
+    /** 时间序保持度：spearman 相关（0-1；1=完全保持） */
+    timeOrderPreservation: number;
+    /** 小源（len<quota）是否全部入选 */
+    smallSourceIncluded: boolean;
+    /** 样本量 */
+    sampleSize: number;
+}
+/** 计算抽样指标 */
+export declare function computeSamplingMetrics(original: readonly ObservationLike[], sampled: readonly ObservationLike[]): SamplingMetrics;
+export interface VariantResult {
+    variant: SamplingVariant;
+    metrics: SamplingMetrics;
+    runIds: string[];
+}
+export interface CapabilityDeltaReport {
+    experimentId: string;
+    hypothesisId?: string;
+    baselineVariant: SamplingVariant;
+    variants: VariantResult[];
+    /** 相对 baseline 的 delta（每指标：variant - baseline） */
+    deltas: Array<{
+        variant: SamplingVariant;
+        familyCoverageDelta: number;
+        maxFamilyShareDelta: number;
+        timeOrderPreservationDelta: number;
+        smallSourceIncludedDelta: number;
+    }>;
+    /** 泛化：在未见任务（held-out observations）上的表现 */
+    generalization?: {
+        heldOutSize: number;
+        baselineMetrics: SamplingMetrics;
+        bestVariant: SamplingVariant;
+        bestMetrics: SamplingMetrics;
+    };
+    /** 结论（允许 inconclusive） */
+    conclusion: 'variant_a_wins' | 'variant_b_wins' | 'baseline_wins' | 'inconclusive';
+    reason: string;
+    createdAt: number;
+}
+/**
+ * 运行 dogfood 实验：三组对照 + 消融，产出 CapabilityDelta 报告。
+ * observations 从历史重放；splitTrainTest 按时间切分（前 70% train，后 30% held-out）。
+ */
+export declare function runInsightSamplingExperiment(experimentId: string, observations: readonly ObservationLike[], options?: {
+    hypothesisId?: string;
+    limit?: number;
+    /** 每变体重复次数（取指标均值，降噪） */
+    repeats?: number;
+}): CapabilityDeltaReport;
+/** 把 CapabilityDelta 报告转成 ExperimentRun 列表（供 ExperimentRunStore.checkPromotionGate 使用） */
+export declare function reportToExperimentRuns(report: CapabilityDeltaReport, feedbackSnapshotVersion?: string): ExperimentRun[];
+export {};

package/dist/InsightSamplingExperiment.js

@@ -0,0 +1,309 @@
+"use strict";
+/**
+ * InsightSamplingExperiment — insight 抽样策略 dogfood 实验（机制涌现 P3，定案 D4/R4）
+ *
+ * 首域 = insight 抽样策略（issue-6 P4 sourceQuota 有现成 before/after + 历史 observations 可重放）。
+ * 三组对照：现有 quota 抽样 / 变体 A / 变体 B + 消融（移除配额/移除时间序保持）+ 未见任务泛化。
+ * 产出 CapabilityDelta 报告；允许 inconclusive（不逼结论）。
+ * 硬前置 A1：MIO EXPERIMENT 标志路由 experiment-memory.jsonl（由 ExperimentRunStore 提供）。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sampleVariant = sampleVariant;
+exports.computeSamplingMetrics = computeSamplingMetrics;
+exports.runInsightSamplingExperiment = runInsightSamplingExperiment;
+exports.reportToExperimentRuns = reportToExperimentRuns;
+/** RSS feedUrl 折叠（与 observer sourceQuota.sourceFamily 同语义） */
+function sourceFamily(source) {
+    return /^https?:\/\//.test(source) ? 'rss' : source;
+}
+/**
+ * baseline: 现有 quota 抽样（issue-6 P4 sampleBySourceQuota）。
+ * variant_a: 更高 minPerSource（保底提升，家族优先更强）。
+ * variant_b: 只用 Phase A 保底，不做 Phase B 余量补齐（纯家族公平）。
+ * ablation_no_quota: 移除配额 → 退化为 slice(0, limit)（issue-6 修复前）。
+ * ablation_no_time_order: 移除时间序保持 → 输出按 weight 降序。
+ */
+function sampleVariant(observations, variant, limit = 30) {
+    const obs = [...observations];
+    switch (variant) {
+        case 'baseline':
+            return sampleByQuota(obs, limit, 5);
+        case 'variant_a':
+            return sampleByQuota(obs, limit, 8);
+        case 'variant_b': {
+            // Phase A only: 每家族取 min(quota, len)，quota = floor(limit/家族数) 或 5
+            const byFamily = new Map();
+            for (const o of obs) {
+                const f = sourceFamily(o.source);
+                const g = byFamily.get(f) ?? [];
+                g.push(o);
+                byFamily.set(f, g);
+            }
+            const families = [...byFamily.keys()];
+            let quota = 5;
+            if (families.length * quota > limit)
+                quota = Math.max(1, Math.floor(limit / families.length));
+            const out = [];
+            for (const f of families)
+                out.push(...byFamily.get(f).slice(0, quota));
+            // 保持时间序
+            out.sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+            return out.slice(0, limit);
+        }
+        case 'ablation_no_quota':
+            return obs.slice(0, limit);
+        case 'ablation_no_time_order': {
+            const sampled = sampleByQuota(obs, limit, 5);
+            return sampled.sort((a, b) => sourceFamily(a.source).localeCompare(sourceFamily(b.source)));
+        }
+    }
+}
+/**
+ * 本地 quota 抽样（与 observer sourceQuota.sampleBySourceQuota 同语义的精简版）。
+ * Phase A 每家族保底 + Phase B 余量最大余数法 + 时间序保持。
+ */
+function sampleByQuota(observations, limit, minPerSource) {
+    if (limit <= 0)
+        return [];
+    if (observations.length <= limit)
+        return observations.slice();
+    const groups = new Map();
+    observations.forEach((obs, idx) => {
+        const family = sourceFamily(obs.source);
+        let g = groups.get(family);
+        if (!g) {
+            g = [];
+            groups.set(family, g);
+        }
+        g.push({ idx, obs });
+    });
+    const families = [...groups.keys()];
+    let quota = minPerSource;
+    if (families.length * quota > limit)
+        quota = Math.max(1, Math.floor(limit / families.length));
+    const picked = new Set();
+    const taken = new Map();
+    for (const family of families) {
+        const g = groups.get(family);
+        const take = Math.min(quota, g.length);
+        for (let i = 0; i < take; i++)
+            picked.add(g[i].idx);
+        taken.set(family, take);
+    }
+    const remaining = limit - picked.size;
+    if (remaining > 0) {
+        const shares = families.map((family) => {
+            const group = groups.get(family);
+            return { family, group, pool: group.length - taken.get(family), base: 0, frac: 0 };
+        });
+        const totalPool = shares.reduce((s, x) => s + x.pool, 0);
+        if (totalPool > 0) {
+            for (const s of shares) {
+                const exact = (remaining * s.pool) / totalPool;
+                s.base = Math.floor(exact);
+                s.frac = exact - s.base;
+            }
+            let leftover = remaining - shares.reduce((s, x) => s + x.base, 0);
+            const byFrac = [...shares].sort((a, b) => b.frac - a.frac);
+            for (const s of byFrac) {
+                if (leftover <= 0)
+                    break;
+                if (s.pool > s.base) {
+                    s.base++;
+                    leftover--;
+                }
+            }
+            for (const s of shares) {
+                const start = taken.get(s.family);
+                for (let i = start; i < start + s.base; i++)
+                    picked.add(s.group[i].idx);
+            }
+        }
+    }
+    return observations.filter((_, i) => picked.has(i));
+}
+/** 计算抽样指标 */
+function computeSamplingMetrics(original, sampled) {
+    const families = new Set(original.map((o) => sourceFamily(o.source)));
+    const sampledFamilies = new Set(sampled.map((o) => sourceFamily(o.source)));
+    const byFamily = new Map();
+    for (const s of sampled) {
+        const f = sourceFamily(s.source);
+        byFamily.set(f, (byFamily.get(f) ?? 0) + 1);
+    }
+    const maxCount = Math.max(0, ...byFamily.values());
+    const maxFamilyShare = sampled.length > 0 ? maxCount / sampled.length : 0;
+    // 时间序保持度：采样序列在原序列中的排名相关（简化为顺序单调比）
+    const idxMap = new Map();
+    original.forEach((o, i) => idxMap.set(o.id, i));
+    const ranks = sampled.map((s) => idxMap.get(s.id) ?? -1);
+    let concordant = 0;
+    let total = 0;
+    for (let i = 0; i < ranks.length; i++) {
+        for (let j = i + 1; j < ranks.length; j++) {
+            if (ranks[i] < 0 || ranks[j] < 0)
+                continue;
+            total++;
+            if (ranks[i] < ranks[j])
+                concordant++;
+        }
+    }
+    const timeOrderPreservation = total > 0 ? concordant / total : 1;
+    // 小源：len < 5 的家族是否全部入选
+    const origByFamily = new Map();
+    for (const o of original) {
+        const f = sourceFamily(o.source);
+        const g = origByFamily.get(f) ?? [];
+        g.push(o);
+        origByFamily.set(f, g);
+    }
+    const smallSourceIncluded = [...origByFamily.entries()].every(([f, g]) => {
+        if (g.length >= 5)
+            return true;
+        const inSample = sampled.filter((s) => sourceFamily(s.source) === f);
+        return inSample.length >= g.length;
+    });
+    return {
+        familyCoverage: sampledFamilies.size,
+        maxFamilyShare,
+        timeOrderPreservation,
+        smallSourceIncluded,
+        sampleSize: sampled.length,
+    };
+}
+/**
+ * 运行 dogfood 实验：三组对照 + 消融，产出 CapabilityDelta 报告。
+ * observations 从历史重放；splitTrainTest 按时间切分（前 70% train，后 30% held-out）。
+ */
+function runInsightSamplingExperiment(experimentId, observations, options) {
+    const limit = options?.limit ?? 30;
+    const repeats = options?.repeats ?? 1;
+    const sorted = [...observations].sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+    const split = Math.max(1, Math.floor(sorted.length * 0.7));
+    const train = sorted.slice(0, split);
+    const heldOut = sorted.slice(split);
+    const variants = ['baseline', 'variant_a', 'variant_b', 'ablation_no_quota', 'ablation_no_time_order'];
+    const variantResults = [];
+    for (const v of variants) {
+        let metricsAcc = null;
+        const runIds = [];
+        for (let r = 0; r < repeats; r++) {
+            const sampled = sampleVariant(train, v, limit);
+            const m = computeSamplingMetrics(train, sampled);
+            metricsAcc = metricsAcc
+                ? {
+                    familyCoverage: metricsAcc.familyCoverage + m.familyCoverage,
+                    maxFamilyShare: metricsAcc.maxFamilyShare + m.maxFamilyShare,
+                    timeOrderPreservation: metricsAcc.timeOrderPreservation + m.timeOrderPreservation,
+                    smallSourceIncluded: metricsAcc.smallSourceIncluded && m.smallSourceIncluded,
+                    sampleSize: metricsAcc.sampleSize + m.sampleSize,
+                }
+                : m;
+            runIds.push(`${experimentId}:${v}:${r}`);
+        }
+        const avg = metricsAcc
+            ? {
+                familyCoverage: Math.round(metricsAcc.familyCoverage / repeats),
+                maxFamilyShare: metricsAcc.maxFamilyShare / repeats,
+                timeOrderPreservation: metricsAcc.timeOrderPreservation / repeats,
+                smallSourceIncluded: metricsAcc.smallSourceIncluded,
+                sampleSize: Math.round(metricsAcc.sampleSize / repeats),
+            }
+            : { familyCoverage: 0, maxFamilyShare: 1, timeOrderPreservation: 0, smallSourceIncluded: false, sampleSize: 0 };
+        variantResults.push({ variant: v, metrics: avg, runIds });
+    }
+    const baseline = variantResults.find((r) => r.variant === 'baseline');
+    const deltas = variantResults
+        .filter((r) => r.variant !== 'baseline')
+        .map((r) => ({
+        variant: r.variant,
+        familyCoverageDelta: r.metrics.familyCoverage - baseline.metrics.familyCoverage,
+        maxFamilyShareDelta: r.metrics.maxFamilyShare - baseline.metrics.maxFamilyShare,
+        timeOrderPreservationDelta: r.metrics.timeOrderPreservation - baseline.metrics.timeOrderPreservation,
+        smallSourceIncludedDelta: (r.metrics.smallSourceIncluded ? 1 : 0) - (baseline.metrics.smallSourceIncluded ? 1 : 0),
+    }));
+    // 泛化：held-out 上 baseline vs best variant（按 familyCoverage + smallSourceIncluded 排序）
+    let generalization;
+    if (heldOut.length > 0) {
+        const baseSampled = sampleVariant(heldOut, 'baseline', limit);
+        const baseMetrics = computeSamplingMetrics(heldOut, baseSampled);
+        const scored = ['variant_a', 'variant_b'].map((v) => {
+            const s = sampleVariant(heldOut, v, limit);
+            return { v, m: computeSamplingMetrics(heldOut, s) };
+        });
+        const best = scored.sort((a, b) => {
+            const sc = (m) => m.familyCoverage * 10 + (m.smallSourceIncluded ? 5 : 0) - m.maxFamilyShare;
+            return sc(b.m) - sc(a.m);
+        })[0];
+        generalization = {
+            heldOutSize: heldOut.length,
+            baselineMetrics: baseMetrics,
+            bestVariant: best?.v ?? 'baseline',
+            bestMetrics: best?.m ?? baseMetrics,
+        };
+    }
+    // 结论：variant_a / variant_b 优于 baseline → 对应 wins；否则 baseline_wins；样本太少 → inconclusive
+    const aDelta = deltas.find((d) => d.variant === 'variant_a');
+    const bDelta = deltas.find((d) => d.variant === 'variant_b');
+    const aBetter = aDelta && (aDelta.familyCoverageDelta > 0 || aDelta.smallSourceIncludedDelta > 0);
+    const bBetter = bDelta && (bDelta.familyCoverageDelta > 0 || bDelta.smallSourceIncludedDelta > 0);
+    let conclusion;
+    let reason;
+    if (train.length < 10) {
+        conclusion = 'inconclusive';
+        reason = 'too_few_observations';
+    }
+    else if (aBetter && bBetter) {
+        // 双优 → inconclusive（需人工判断）
+        conclusion = 'inconclusive';
+        reason = 'both_variants_improve';
+    }
+    else if (aBetter) {
+        conclusion = 'variant_a_wins';
+        reason = 'higher_family_coverage_or_small_source';
+    }
+    else if (bBetter) {
+        conclusion = 'variant_b_wins';
+        reason = 'higher_family_coverage_or_small_source';
+    }
+    else {
+        conclusion = 'baseline_wins';
+        reason = 'no_improvement_over_baseline';
+    }
+    return {
+        experimentId,
+        hypothesisId: options?.hypothesisId,
+        baselineVariant: 'baseline',
+        variants: variantResults,
+        deltas,
+        generalization,
+        conclusion,
+        reason,
+        createdAt: Date.now(),
+    };
+}
+/** 把 CapabilityDelta 报告转成 ExperimentRun 列表（供 ExperimentRunStore.checkPromotionGate 使用） */
+function reportToExperimentRuns(report, feedbackSnapshotVersion) {
+    return report.variants.map((v) => ({
+        id: `${report.experimentId}:${v.variant}`,
+        hypothesisId: report.hypothesisId,
+        candidateId: v.variant,
+        baselineId: report.baselineVariant,
+        ...(feedbackSnapshotVersion ? { feedbackSnapshotVersion } : {}),
+        assignment: (v.variant === 'baseline'
+            ? 'baseline'
+            : v.variant.startsWith('ablation')
+                ? 'ablation'
+                : 'candidate'),
+        outcome: report.conclusion === 'inconclusive' ? 'inconclusive' : v.variant === report.conclusion.replace('_wins', '') ? 'success' : 'failure',
+        metrics: {
+            familyCoverage: v.metrics.familyCoverage,
+            maxFamilyShare: v.metrics.maxFamilyShare,
+            timeOrderPreservation: v.metrics.timeOrderPreservation,
+            smallSourceIncluded: v.metrics.smallSourceIncluded,
+            sampleSize: v.metrics.sampleSize,
+        },
+        evidenceIds: v.runIds,
+        createdAt: report.createdAt,
+    }));
+}

package/dist/JsonlFeedbackEventStore.d.ts

@@ -0,0 +1,32 @@
+/**
+ * JsonlFeedbackEventStore — CLI/MCP 侧证据事件追加存储（P0）
+ *
+ * 落盘：`<dataDir>/feedback-events.jsonl`（append-only）。
+ * 幂等：加载时建 idempotencyKey 集合，同键追加直接跳过（不抛错、不重复生效）。
+ * 这是交换/重放格式，不是权威真相源——主进程 ingest 单向导入 SQLite。
+ */
+import { type HypothesisFeedbackEvent, type HypothesisFeedbackEventInput, type NormalizeQuarantineReason } from './FeedbackEvents';
+export interface JsonlAppendResult {
+    /** 事件已追加并生效 */
+    appended: boolean;
+    /** 因 idempotencyKey 已存在而跳过 */
+    deduped: boolean;
+    event?: HypothesisFeedbackEvent;
+    /** 规范化失败（进隔离队列由调用方处理） */
+    quarantine?: {
+        reason: NormalizeQuarantineReason;
+        raw: unknown;
+    };
+}
+export declare class JsonlFeedbackEventStore {
+    readonly eventsPath: string;
+    private seenKeys;
+    constructor(dataDir: string);
+    /** 重读文件（长活 MCP 进程需看到外部追加；幂等键集合整体重建，成本可接受）。 */
+    private ensureLoaded;
+    /** 供长活进程在外部写入后强制重读。 */
+    invalidate(): void;
+    append(input: HypothesisFeedbackEventInput, now?: number): JsonlAppendResult;
+    /** 读取全部可解析事件（损坏行跳过，供 ingest/回放使用）。 */
+    list(): HypothesisFeedbackEvent[];
+}