@akemi-mio/creativity 0.1.1 → 0.3.0

package/dist/FeedbackMetrics.d.ts

@@ -0,0 +1,90 @@
+/**
+ * FeedbackMetrics — 正向反馈闭环验证指标（spec §八，P3 收官）
+ *
+ * 把"三类验证指标"里能在本地数据上回答的部分落成纯函数：
+ *   - Pair Precision@K：快照中反馈调整幅度最大的 K 个概念对里，
+ *     已有终局（validated/rejected）假设的对的通过率（无终局样本 → null，
+ *     无样本 ≠ 0；hypothesis_only 键不是概念对，不参与排名）。
+ *   - Novelty@K：top-K 概念对里未被窗口内假设探索过的比例。
+ *   - Validation Pass Rate：窗口内终局假设的通过率。
+ *   - Event Ingestion Completeness：JSONL 原始行 vs 可解析行（损坏行=丢失）。
+ *
+ * 身份规则与快照一致（types.ts sourceConceptId/conceptPairKey）：
+ * 概念对键 = conceptPairKey(sourceConceptId)，hypothesis_only 键带
+ * `hypothesis:` 前缀被排除；无 provenance 的假设回退 sourceLabels 的
+ * `name:` 键（与 sourceConceptId 的无 origin 回退同空间）。
+ *
+ * 纯函数：不读写文件、不碰 DB、不进 checkPromotionGate/checkSubmitGate
+ * 输入（spec §二.2 反馈权限隔离）。
+ */
+import { type FeedbackLearningConfig, type FeedbackSnapshot } from './FeedbackLearning';
+export interface FeedbackMetricsConfig {
+    /** Pair Precision@K / Novelty@K 的 K */
+    precisionK: number;
+    /** 通过率与探索集的回看窗口（天） */
+    windowDays: number;
+}
+export declare const DEFAULT_FEEDBACK_METRICS_CONFIG: FeedbackMetricsConfig;
+/** 解析并校验指标配置；两个字段都缺失返回 null（fail-closed，调用方回退默认）。 */
+export declare function parseFeedbackMetricsConfig(raw: unknown): FeedbackMetricsConfig | null;
+/** 从环境变量解析（MIO_FEEDBACK_PRECISION_K / MIO_FEEDBACK_WINDOW_DAYS，缺省全默认）。 */
+export declare function resolveFeedbackMetricsConfig(env?: Record<string, string | undefined>): FeedbackMetricsConfig;
+/** 结构子集：主进程 Hypothesis 与 CLI store 行都满足（只要求用到的字段）。 */
+export interface FeedbackMetricsHypothesis {
+    id: string;
+    status?: string;
+    createdAt?: number;
+    sourceLabels?: readonly string[];
+    provenance?: {
+        sources?: ReadonlyArray<{
+            name: string;
+            origin?: string;
+        }>;
+    };
+}
+/** 证据事件 JSONL 的行统计（调用方做原始扫描；本模块纯计算）。 */
+export interface FeedbackIngestionCounts {
+    /** 非空行总数 */
+    rawLines: number;
+    /** 可 JSON 解析的行数 */
+    validRows: number;
+}
+export interface FeedbackTopPair {
+    pairKey: string;
+    /** λ clamp 后的调整量（排名依据取绝对值） */
+    adjustment: number;
+    validated: number;
+    rejected: number;
+    /** 无终局样本 → null（无样本 ≠ 0） */
+    precision: number | null;
+    /** 是否未被窗口内假设探索过 */
+    novel: boolean;
+}
+export interface FeedbackGenerationMetrics {
+    precisionK: number;
+    windowDays: number;
+    snapshotVersion: string | null;
+    pairPrecisionAtK: number | null;
+    evaluatedPairs: number;
+    noveltyAtK: number | null;
+    validationPassRate: number | null;
+    /** 窗口内终局假设数（validationPassRate 的分母） */
+    terminalHypotheses: number;
+    ingestion: {
+        rawLines: number;
+        validRows: number;
+        droppedRows: number;
+        completeness: number | null;
+    };
+    topPairs: FeedbackTopPair[];
+}
+export interface ComputeFeedbackGenerationMetricsArgs {
+    snapshot?: FeedbackSnapshot | null;
+    hypotheses?: readonly FeedbackMetricsHypothesis[];
+    ingestion?: FeedbackIngestionCounts;
+    config?: FeedbackMetricsConfig;
+    /** 缺省 Date.now()；测试可注入固定时间 */
+    now?: number;
+    learningConfig?: FeedbackLearningConfig;
+}
+export declare function computeFeedbackGenerationMetrics(args?: ComputeFeedbackGenerationMetricsArgs): FeedbackGenerationMetrics;

package/dist/FeedbackMetrics.js

@@ -0,0 +1,193 @@
+"use strict";
+/**
+ * FeedbackMetrics — 正向反馈闭环验证指标（spec §八，P3 收官）
+ *
+ * 把"三类验证指标"里能在本地数据上回答的部分落成纯函数：
+ *   - Pair Precision@K：快照中反馈调整幅度最大的 K 个概念对里，
+ *     已有终局（validated/rejected）假设的对的通过率（无终局样本 → null，
+ *     无样本 ≠ 0；hypothesis_only 键不是概念对，不参与排名）。
+ *   - Novelty@K：top-K 概念对里未被窗口内假设探索过的比例。
+ *   - Validation Pass Rate：窗口内终局假设的通过率。
+ *   - Event Ingestion Completeness：JSONL 原始行 vs 可解析行（损坏行=丢失）。
+ *
+ * 身份规则与快照一致（types.ts sourceConceptId/conceptPairKey）：
+ * 概念对键 = conceptPairKey(sourceConceptId)，hypothesis_only 键带
+ * `hypothesis:` 前缀被排除；无 provenance 的假设回退 sourceLabels 的
+ * `name:` 键（与 sourceConceptId 的无 origin 回退同空间）。
+ *
+ * 纯函数：不读写文件、不碰 DB、不进 checkPromotionGate/checkSubmitGate
+ * 输入（spec §二.2 反馈权限隔离）。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_FEEDBACK_METRICS_CONFIG = void 0;
+exports.parseFeedbackMetricsConfig = parseFeedbackMetricsConfig;
+exports.resolveFeedbackMetricsConfig = resolveFeedbackMetricsConfig;
+exports.computeFeedbackGenerationMetrics = computeFeedbackGenerationMetrics;
+const FeedbackLearning_1 = require("./FeedbackLearning");
+const types_1 = require("./types");
+exports.DEFAULT_FEEDBACK_METRICS_CONFIG = {
+    precisionK: 10,
+    windowDays: 30,
+};
+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，调用方回退默认）。 */
+function parseFeedbackMetricsConfig(raw) {
+    if (raw === null || typeof raw !== 'object')
+        return null;
+    const obj = raw;
+    const hasAny = ['precisionK', 'windowDays'].some((k) => obj[k] !== undefined);
+    if (!hasAny)
+        return null;
+    return {
+        precisionK: Math.floor(clampNumber(obj.precisionK, 1, 1000, exports.DEFAULT_FEEDBACK_METRICS_CONFIG.precisionK)),
+        windowDays: Math.floor(clampNumber(obj.windowDays, 1, 3650, exports.DEFAULT_FEEDBACK_METRICS_CONFIG.windowDays)),
+    };
+}
+/** 从环境变量解析（MIO_FEEDBACK_PRECISION_K / MIO_FEEDBACK_WINDOW_DAYS，缺省全默认）。 */
+function resolveFeedbackMetricsConfig(env = process.env) {
+    return (parseFeedbackMetricsConfig({
+        precisionK: env.MIO_FEEDBACK_PRECISION_K,
+        windowDays: env.MIO_FEEDBACK_WINDOW_DAYS,
+    }) ?? exports.DEFAULT_FEEDBACK_METRICS_CONFIG);
+}
+const TERMINAL_STATUSES = new Set(['validated', 'rejected']);
+const DAY_MS = 86_400_000;
+const HYPOTHESIS_ONLY_PREFIX = 'hypothesis:';
+/** 由 provenance 来源推导概念对键（与 buildFeedbackSnapshot 的归因同一规则）。 */
+function pairKeysFromSources(sources) {
+    const ids = sources.map(types_1.sourceConceptId);
+    const keys = [];
+    for (let i = 0; i < ids.length; i++) {
+        for (let j = i + 1; j < ids.length; j++) {
+            if (ids[i] === ids[j])
+                continue;
+            keys.push((0, types_1.conceptPairKey)(ids[i], ids[j]));
+        }
+    }
+    return keys;
+}
+/** 无 provenance 假设的回退：sourceLabels 是原始名，等价于无 origin 的概念身份。 */
+function pairKeysFromLabels(labels) {
+    const ids = labels.map((l) => `name:${l}`);
+    const keys = [];
+    for (let i = 0; i < ids.length; i++) {
+        for (let j = i + 1; j < ids.length; j++) {
+            if (ids[i] === ids[j])
+                continue;
+            keys.push((0, types_1.conceptPairKey)(ids[i], ids[j]));
+        }
+    }
+    return keys;
+}
+function computeFeedbackGenerationMetrics(args = {}) {
+    const config = args.config ?? exports.DEFAULT_FEEDBACK_METRICS_CONFIG;
+    const now = args.now ?? Date.now();
+    const learningConfig = args.learningConfig ?? FeedbackLearning_1.DEFAULT_FEEDBACK_LEARNING_CONFIG;
+    const hypotheses = args.hypotheses ?? [];
+    const snapshot = args.snapshot ?? null;
+    const cutoff = now - config.windowDays * DAY_MS;
+    // ── Validation Pass Rate（窗口内终局假设） ──
+    let validatedTotal = 0;
+    let rejectedTotal = 0;
+    for (const h of hypotheses) {
+        if (!h.status || !TERMINAL_STATUSES.has(h.status))
+            continue;
+        if (typeof h.createdAt !== 'number' || h.createdAt < cutoff)
+            continue;
+        if (h.status === 'validated')
+            validatedTotal++;
+        else
+            rejectedTotal++;
+    }
+    const terminalHypotheses = validatedTotal + rejectedTotal;
+    const validationPassRate = terminalHypotheses > 0 ? validatedTotal / terminalHypotheses : null;
+    // ── 终局假设 → 概念对链接（全量：配对证据来自快照，不受窗口裁剪） ──
+    const pairToTerminal = new Map();
+    for (const h of hypotheses) {
+        if (!h.status || !TERMINAL_STATUSES.has(h.status))
+            continue;
+        const sources = h.provenance?.sources;
+        if (!sources || sources.length < 2)
+            continue;
+        for (const key of pairKeysFromSources(sources)) {
+            let counts = pairToTerminal.get(key);
+            if (!counts) {
+                counts = { validated: 0, rejected: 0 };
+                pairToTerminal.set(key, counts);
+            }
+            if (h.status === 'validated')
+                counts.validated++;
+            else
+                counts.rejected++;
+        }
+    }
+    // ── 窗口内探索集（novelty 判定） ──
+    const explored = new Set();
+    for (const h of hypotheses) {
+        if (typeof h.createdAt !== 'number' || h.createdAt < cutoff)
+            continue;
+        const sources = h.provenance?.sources;
+        if (sources && sources.length >= 2) {
+            for (const key of pairKeysFromSources(sources))
+                explored.add(key);
+        }
+        else if (h.sourceLabels && h.sourceLabels.length >= 2) {
+            for (const key of pairKeysFromLabels(h.sourceLabels))
+                explored.add(key);
+        }
+    }
+    // ── top-K：快照概念对按 |clampedAdjustment| 排名（tie-break pairKey，稳定） ──
+    const conceptPairs = (snapshot?.pairs ?? []).filter((p) => !p.pairKey.startsWith(HYPOTHESIS_ONLY_PREFIX));
+    const topPairs = conceptPairs
+        .map((p) => {
+        const counts = pairToTerminal.get(p.pairKey);
+        const validated = counts?.validated ?? 0;
+        const rejected = counts?.rejected ?? 0;
+        const total = validated + rejected;
+        return {
+            pairKey: p.pairKey,
+            adjustment: (0, FeedbackLearning_1.replayFeedbackAdjustment)(p, learningConfig).clampedAdjustment,
+            validated,
+            rejected,
+            precision: total > 0 ? validated / total : null,
+            novel: !explored.has(p.pairKey),
+        };
+    })
+        .sort((a, b) => Math.abs(b.adjustment) - Math.abs(a.adjustment) || (a.pairKey < b.pairKey ? -1 : 1))
+        .slice(0, config.precisionK);
+    let evaluatedPairs = 0;
+    let precisionSum = 0;
+    let novelCount = 0;
+    for (const p of topPairs) {
+        if (p.precision !== null) {
+            evaluatedPairs++;
+            precisionSum += p.precision;
+        }
+        if (p.novel)
+            novelCount++;
+    }
+    const pairPrecisionAtK = evaluatedPairs > 0 ? precisionSum / evaluatedPairs : null;
+    const noveltyAtK = topPairs.length > 0 ? novelCount / topPairs.length : null;
+    // ── 事件摄取完整度（原始行 vs 可解析行） ──
+    const rawLines = args.ingestion?.rawLines ?? 0;
+    const validRows = args.ingestion?.validRows ?? 0;
+    const droppedRows = Math.max(0, rawLines - validRows);
+    const completeness = rawLines > 0 ? Math.max(0, Math.min(1, validRows / rawLines)) : null;
+    return {
+        precisionK: config.precisionK,
+        windowDays: config.windowDays,
+        snapshotVersion: snapshot?.version ?? null,
+        pairPrecisionAtK,
+        evaluatedPairs,
+        noveltyAtK,
+        validationPassRate,
+        terminalHypotheses,
+        ingestion: { rawLines, validRows, droppedRows, completeness },
+        topPairs,
+    };
+}

package/dist/FeedbackRollout.d.ts

@@ -0,0 +1,72 @@
+/**
+ * FeedbackRollout — 正向反馈闭环放量决策（设计 v1.0，P3 收尾）
+ *
+ * "离线回放 → 影子运行 → 小流量 → 正式启用，每阶段预固定基线、指标、回滚条件"（spec §八 P3）。
+ * 本模块把那张表落成可执行判定：
+ *   - rollback：安全不变量破坏（Duplicate Application Rate > 0）→ 立即建议回滚 off。
+ *   - advance：当前阶段的预固定门槛全部满足 → 建议进入下一阶段。
+ *   - hold：证据不足 → 保持当前阶段。
+ *
+ * 纯函数：不读写文件、不查 DB。阈值进配置 + 解析校验（R6 纪律）。
+ * 反馈永不进入 checkPromotionGate/checkSubmitGate；放量判定只决定"生成端消费档位"。
+ */
+import type { FeedbackSnapshot } from './FeedbackLearning';
+import { type FeedbackMode } from './FeedbackRuntime';
+export interface FeedbackRolloutThresholds {
+    /** 每阶段所需的最少运行观测数（shadow 或 canary） */
+    minStageRuns: number;
+    /** 升档所需的最小归因覆盖率（有 provenance 的正向事件占比） */
+    minAttributionCoverage: number;
+    /** canary → full 所允许的最大负向事件率（负向证据 / 全部证据） */
+    maxNegativeEventRate: number;
+}
+export declare const DEFAULT_FEEDBACK_ROLLOUT_THRESHOLDS: FeedbackRolloutThresholds;
+/** 解析并校验放量阈值；失败返回 null（fail-closed，调用方回退默认）。 */
+export declare function parseFeedbackRolloutThresholds(raw: unknown): FeedbackRolloutThresholds | null;
+/** 从环境变量解析（缺省全默认）。 */
+export declare function resolveFeedbackRolloutThresholds(env?: Record<string, string | undefined>): FeedbackRolloutThresholds;
+/** 一次观测模式下的生成运行摘要（shadow/canary/full；off 不观测不记录）。 */
+export interface FeedbackRuntimeRun {
+    at: number;
+    mode: Exclude<FeedbackMode, 'off'>;
+    snapshotVersion: string | null;
+    pairCount: number;
+    applied: boolean;
+}
+/** 阶梯：off → shadow → canary → full。 */
+export declare const FEEDBACK_MODE_LADDER: readonly FeedbackMode[];
+export declare function nextFeedbackMode(current: FeedbackMode): FeedbackMode | null;
+export interface FeedbackRolloutMetrics {
+    snapshotVersion: string | null;
+    shadowRuns: number;
+    canaryRuns: number;
+    attributionCoverage: number;
+    duplicateApplicationRate: number;
+    negativeEventRate: number;
+    eventCount: number;
+}
+export type FeedbackRolloutDecision = 'rollback' | 'advance' | 'hold';
+export interface FeedbackRolloutReport {
+    decision: FeedbackRolloutDecision;
+    from: FeedbackMode;
+    /** rollback → 'off'；advance → 下一阶段；hold → null */
+    to: FeedbackMode | null;
+    reasons: string[];
+    metrics: FeedbackRolloutMetrics;
+}
+/** 快照内负向事件率：负向证据 / 全部证据（无证据 → 0）。 */
+export declare function negativeEventRateOf(snapshot: FeedbackSnapshot | null): number;
+export interface BuildFeedbackRolloutReportArgs {
+    snapshot: FeedbackSnapshot | null;
+    runs: readonly FeedbackRuntimeRun[];
+    currentMode: FeedbackMode;
+    thresholds?: FeedbackRolloutThresholds;
+}
+/**
+ * 放量判定。判定顺序：
+ *   1. 安全不变量破坏（重复加权）→ rollback（无条件，压过一切）。
+ *   2. off → shadow：观测零风险，无条件 advance。
+ *   3. shadow → canary / canary → full：预固定门槛全部满足才 advance，否则 hold。
+ *   4. full：已到顶，hold。
+ */
+export declare function buildFeedbackRolloutReport(args: BuildFeedbackRolloutReportArgs): FeedbackRolloutReport;

package/dist/FeedbackRollout.js

@@ -0,0 +1,136 @@
+"use strict";
+/**
+ * FeedbackRollout — 正向反馈闭环放量决策（设计 v1.0，P3 收尾）
+ *
+ * "离线回放 → 影子运行 → 小流量 → 正式启用，每阶段预固定基线、指标、回滚条件"（spec §八 P3）。
+ * 本模块把那张表落成可执行判定：
+ *   - rollback：安全不变量破坏（Duplicate Application Rate > 0）→ 立即建议回滚 off。
+ *   - advance：当前阶段的预固定门槛全部满足 → 建议进入下一阶段。
+ *   - hold：证据不足 → 保持当前阶段。
+ *
+ * 纯函数：不读写文件、不查 DB。阈值进配置 + 解析校验（R6 纪律）。
+ * 反馈永不进入 checkPromotionGate/checkSubmitGate；放量判定只决定"生成端消费档位"。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FEEDBACK_MODE_LADDER = exports.DEFAULT_FEEDBACK_ROLLOUT_THRESHOLDS = void 0;
+exports.parseFeedbackRolloutThresholds = parseFeedbackRolloutThresholds;
+exports.resolveFeedbackRolloutThresholds = resolveFeedbackRolloutThresholds;
+exports.nextFeedbackMode = nextFeedbackMode;
+exports.negativeEventRateOf = negativeEventRateOf;
+exports.buildFeedbackRolloutReport = buildFeedbackRolloutReport;
+exports.DEFAULT_FEEDBACK_ROLLOUT_THRESHOLDS = {
+    minStageRuns: 5,
+    minAttributionCoverage: 0.3,
+    maxNegativeEventRate: 0.5,
+};
+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，调用方回退默认）。 */
+function parseFeedbackRolloutThresholds(raw) {
+    if (raw === null || typeof raw !== 'object')
+        return null;
+    const obj = raw;
+    const hasAny = ['minStageRuns', 'minAttributionCoverage', 'maxNegativeEventRate'].some((k) => obj[k] !== undefined);
+    if (!hasAny)
+        return null;
+    return {
+        minStageRuns: clampNumber(obj.minStageRuns, 1, 10_000, exports.DEFAULT_FEEDBACK_ROLLOUT_THRESHOLDS.minStageRuns),
+        minAttributionCoverage: clampNumber(obj.minAttributionCoverage, 0, 1, exports.DEFAULT_FEEDBACK_ROLLOUT_THRESHOLDS.minAttributionCoverage),
+        maxNegativeEventRate: clampNumber(obj.maxNegativeEventRate, 0, 1, exports.DEFAULT_FEEDBACK_ROLLOUT_THRESHOLDS.maxNegativeEventRate),
+    };
+}
+/** 从环境变量解析（缺省全默认）。 */
+function resolveFeedbackRolloutThresholds(env = process.env) {
+    return (parseFeedbackRolloutThresholds({
+        minStageRuns: env.MIO_FEEDBACK_MIN_STAGE_RUNS,
+        minAttributionCoverage: env.MIO_FEEDBACK_MIN_COVERAGE,
+        maxNegativeEventRate: env.MIO_FEEDBACK_MAX_NEGATIVE_RATE,
+    }) ?? exports.DEFAULT_FEEDBACK_ROLLOUT_THRESHOLDS);
+}
+// ══════════════════════════════════════════
+// 放量判定
+// ══════════════════════════════════════════
+/** 阶梯：off → shadow → canary → full。 */
+exports.FEEDBACK_MODE_LADDER = ['off', 'shadow', 'canary', 'full'];
+function nextFeedbackMode(current) {
+    const index = exports.FEEDBACK_MODE_LADDER.indexOf(current);
+    return index >= 0 && index < exports.FEEDBACK_MODE_LADDER.length - 1 ? exports.FEEDBACK_MODE_LADDER[index + 1] : null;
+}
+/** 快照内负向事件率：负向证据 / 全部证据（无证据 → 0）。 */
+function negativeEventRateOf(snapshot) {
+    if (!snapshot)
+        return 0;
+    let negative = 0;
+    let total = 0;
+    for (const pair of snapshot.pairs) {
+        for (const dimension of ['selection', 'quality', 'landing']) {
+            total += pair[dimension].evidenceCount;
+        }
+        negative += pair.negative.evidenceCount;
+        total += pair.negative.evidenceCount;
+    }
+    return total > 0 ? negative / total : 0;
+}
+function metricsOf(snapshot, runs) {
+    return {
+        snapshotVersion: snapshot?.version ?? null,
+        shadowRuns: runs.filter((r) => r.mode === 'shadow').length,
+        canaryRuns: runs.filter((r) => r.mode === 'canary').length,
+        attributionCoverage: snapshot?.attributionCoverage ?? 0,
+        duplicateApplicationRate: snapshot?.duplicateApplicationRate ?? 0,
+        negativeEventRate: negativeEventRateOf(snapshot),
+        eventCount: snapshot?.eventCount ?? 0,
+    };
+}
+/**
+ * 放量判定。判定顺序：
+ *   1. 安全不变量破坏（重复加权）→ rollback（无条件，压过一切）。
+ *   2. off → shadow：观测零风险，无条件 advance。
+ *   3. shadow → canary / canary → full：预固定门槛全部满足才 advance，否则 hold。
+ *   4. full：已到顶，hold。
+ */
+function buildFeedbackRolloutReport(args) {
+    const thresholds = args.thresholds ?? exports.DEFAULT_FEEDBACK_ROLLOUT_THRESHOLDS;
+    const metrics = metricsOf(args.snapshot, args.runs);
+    const reasons = [];
+    // 1) 安全不变量：重复加权率必须为 0（P1 验收不变量）
+    if (metrics.duplicateApplicationRate > 0) {
+        reasons.push(`duplicate_application_rate=${metrics.duplicateApplicationRate.toFixed(4)} > 0 (invariant broken)`);
+        return { decision: 'rollback', from: args.currentMode, to: 'off', reasons, metrics };
+    }
+    const next = nextFeedbackMode(args.currentMode);
+    if (args.currentMode === 'full' || next === null) {
+        reasons.push('already at full stage');
+        return { decision: 'hold', from: args.currentMode, to: null, reasons, metrics };
+    }
+    // 2) off → shadow：只增加观测，不改变生成行为
+    if (args.currentMode === 'off') {
+        reasons.push('observation adds no generation risk');
+        return { decision: 'advance', from: 'off', to: 'shadow', reasons, metrics };
+    }
+    // 3) shadow → canary / canary → full：预固定门槛
+    const stageRuns = args.currentMode === 'shadow' ? metrics.shadowRuns : metrics.canaryRuns;
+    const stageName = args.currentMode;
+    let ready = true;
+    if (stageRuns < thresholds.minStageRuns) {
+        ready = false;
+        reasons.push(`${stageName} runs ${stageRuns} < min ${thresholds.minStageRuns}`);
+    }
+    if (metrics.attributionCoverage < thresholds.minAttributionCoverage) {
+        ready = false;
+        reasons.push(`attribution coverage ${metrics.attributionCoverage.toFixed(4)} < min ${thresholds.minAttributionCoverage}`);
+    }
+    if (args.currentMode === 'canary' && metrics.negativeEventRate > thresholds.maxNegativeEventRate) {
+        ready = false;
+        reasons.push(`negative event rate ${metrics.negativeEventRate.toFixed(4)} > max ${thresholds.maxNegativeEventRate}`);
+    }
+    if (!ready) {
+        return { decision: 'hold', from: args.currentMode, to: null, reasons, metrics };
+    }
+    reasons.push(`all ${stageName} stage gates met`);
+    return { decision: 'advance', from: args.currentMode, to: next, reasons, metrics };
+}

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 并记录）。谓词形式让调用方在守卫内拿到非 `off` 收窄。 */
+export declare function isFeedbackObserved(mode: FeedbackMode): mode is Exclude<FeedbackMode, 'off'>;

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 并记录）。谓词形式让调用方在守卫内拿到非 `off` 收窄。 */
+function isFeedbackObserved(mode) {
+    return mode === 'shadow' || mode === 'canary' || mode === 'full';
+}

package/dist/FeedbackRuntimeRuns.d.ts

@@ -0,0 +1,14 @@
+import type { FeedbackRuntimeRun } from './FeedbackRollout';
+/**
+ * feedback-runtime-runs.jsonl 的唯一读写实现（append-only，供放量报告统计阶段门槛）。
+ *
+ * 双轴共用：CLI/MCP（CreativityEngine）与主进程（CreativityService）都经由本模块落盘，
+ * 因此两个入口写入的行格式与读取口径不可能各自漂移（同 memory-store/policy-store 模式）。
+ * 数据目录由调用方决定：CLI/MCP 是 `<MIO_HOME>/creativity`，主进程是
+ * `MIO_HOME/creativity`（未设置时回退 `WORKSPACE_ROOT/creativity`）。
+ */
+export declare const FEEDBACK_RUNTIME_RUNS_FILE = "feedback-runtime-runs.jsonl";
+/** 追加一条观测运行摘要。落盘失败由调用方 best-effort 兜底（不得阻断生成）。 */
+export declare function recordFeedbackRuntimeRun(dir: string, run: FeedbackRuntimeRun): void;
+/** 读取全部观测运行摘要。损坏行/非对象行/`off` 行跳过（同 JsonlFeedbackEventStore 策略）。 */
+export declare function readFeedbackRuntimeRuns(dir: string): FeedbackRuntimeRun[];

package/dist/FeedbackRuntimeRuns.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FEEDBACK_RUNTIME_RUNS_FILE = void 0;
+exports.recordFeedbackRuntimeRun = recordFeedbackRuntimeRun;
+exports.readFeedbackRuntimeRuns = readFeedbackRuntimeRuns;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const FeedbackRuntime_1 = require("./FeedbackRuntime");
+/**
+ * feedback-runtime-runs.jsonl 的唯一读写实现（append-only，供放量报告统计阶段门槛）。
+ *
+ * 双轴共用：CLI/MCP（CreativityEngine）与主进程（CreativityService）都经由本模块落盘，
+ * 因此两个入口写入的行格式与读取口径不可能各自漂移（同 memory-store/policy-store 模式）。
+ * 数据目录由调用方决定：CLI/MCP 是 `<MIO_HOME>/creativity`，主进程是
+ * `MIO_HOME/creativity`（未设置时回退 `WORKSPACE_ROOT/creativity`）。
+ */
+exports.FEEDBACK_RUNTIME_RUNS_FILE = 'feedback-runtime-runs.jsonl';
+/** 追加一条观测运行摘要。落盘失败由调用方 best-effort 兜底（不得阻断生成）。 */
+function recordFeedbackRuntimeRun(dir, run) {
+    if (!(0, fs_1.existsSync)(dir))
+        (0, fs_1.mkdirSync)(dir, { recursive: true });
+    (0, fs_1.appendFileSync)((0, path_1.join)(dir, exports.FEEDBACK_RUNTIME_RUNS_FILE), JSON.stringify(run) + '\n', 'utf8');
+}
+/** 读取全部观测运行摘要。损坏行/非对象行/`off` 行跳过（同 JsonlFeedbackEventStore 策略）。 */
+function readFeedbackRuntimeRuns(dir) {
+    const file = (0, path_1.join)(dir, exports.FEEDBACK_RUNTIME_RUNS_FILE);
+    if (!(0, fs_1.existsSync)(file))
+        return [];
+    const out = [];
+    for (const line of (0, fs_1.readFileSync)(file, 'utf8').split('\n')) {
+        if (!line.trim())
+            continue;
+        try {
+            const row = JSON.parse(line);
+            if (row &&
+                typeof row === 'object' &&
+                typeof row.mode === 'string' &&
+                row.mode !== 'off' &&
+                FeedbackRuntime_1.FEEDBACK_MODES.includes(row.mode)) {
+                out.push({
+                    at: Number(row.at) || 0,
+                    mode: row.mode,
+                    snapshotVersion: typeof row.snapshotVersion === 'string' ? row.snapshotVersion : null,
+                    pairCount: Number(row.pairCount) || 0,
+                    applied: !!row.applied,
+                });
+            }
+        }
+        catch (_) {
+            // 损坏行跳过
+        }
+    }
+    return out;
+}