@akemi-mio/creativity 0.1.0 → 0.2.0

package/dist/FeedbackEvents.js

@@ -0,0 +1,133 @@
+"use strict";
+/**
+ * HypothesisFeedbackEvent — 正向反馈闭环证据层（设计 v1.0，P0）
+ *
+ * 只做三件事：类型契约、规范化校验、幂等键构建。
+ * 不做聚合/权重/快照（P1 的 FeedbackLearningService），
+ * 不写 Memory、不改 Hypothesis.status、不进晋级门输入。
+ *
+ * 双轴落点：
+ * - CLI/MCP 生产端 → JSONL `feedback-events.jsonl`（交换格式，见 JsonlFeedbackEventStore）
+ * - 主进程权威侧 → SQLite `hypothesis_feedback_events`（见 DrizzleFeedbackEventStore）
+ * 唯一真相源方向：CLI 只追加 JSONL，主进程 ingest 单向导入（spec §九 R3）。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FEEDBACK_SOURCE_TYPES = exports.FEEDBACK_EVENT_TYPES = exports.FEEDBACK_EVENT_SCHEMA_VERSION = void 0;
+exports.buildFeedbackIdempotencyKey = buildFeedbackIdempotencyKey;
+exports.normalizeFeedbackEvent = normalizeFeedbackEvent;
+exports.feedbackEvidenceDimension = feedbackEvidenceDimension;
+exports.FEEDBACK_EVENT_SCHEMA_VERSION = 1;
+exports.FEEDBACK_EVENT_TYPES = [
+    'validated',
+    'adopted',
+    'implemented',
+    'rejected',
+    'regression_failed',
+];
+exports.FEEDBACK_SOURCE_TYPES = [
+    'experiment',
+    'memory',
+    'adoption',
+    'commit',
+    'manual',
+];
+function toEpochMs(value, now) {
+    if (value === undefined || value === null || value === '')
+        return now;
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (typeof value === 'string') {
+        const parsed = Date.parse(value);
+        if (Number.isFinite(parsed))
+            return parsed;
+    }
+    return null;
+}
+/**
+ * 幂等键 = 自然键拼接。同 hypothesisId+eventType+sourceType+sourceId(+commitSha/experimentRunId)
+ * 的重复提交会得到同键，存储层靠唯一约束去重。
+ */
+function buildFeedbackIdempotencyKey(parts) {
+    return [
+        parts.hypothesisId,
+        parts.eventType,
+        parts.sourceType,
+        parts.sourceId,
+        parts.commitSha || '',
+        parts.experimentRunId || '',
+    ].join(':');
+}
+function newEventId() {
+    return `fbe_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+}
+/**
+ * 规范化 + 校验。不合格事件不丢弃、不生效——调用方写入隔离队列。
+ * 注意：本函数不校验 hypothesisId 是否指向真实假设（那需要 store 查询），
+ * 由生产者/ingest 在调用前或调用后单独把关（spec §五.1）。
+ */
+function normalizeFeedbackEvent(raw, now = Date.now()) {
+    if (!raw || typeof raw !== 'object') {
+        return { ok: false, reason: 'missing_hypothesis_id', raw };
+    }
+    const input = raw;
+    const hypothesisId = typeof input.hypothesisId === 'string' ? input.hypothesisId.trim() : '';
+    if (!hypothesisId) {
+        return { ok: false, reason: 'missing_hypothesis_id', raw };
+    }
+    if (!exports.FEEDBACK_EVENT_TYPES.includes(input.eventType)) {
+        return { ok: false, reason: 'invalid_event_type', raw };
+    }
+    if (!exports.FEEDBACK_SOURCE_TYPES.includes(input.sourceType)) {
+        return { ok: false, reason: 'invalid_source_type', raw };
+    }
+    const sourceId = typeof input.sourceId === 'string' ? input.sourceId.trim() : '';
+    if (!sourceId) {
+        return { ok: false, reason: 'missing_source_id', raw };
+    }
+    const commitSha = typeof input.commitSha === 'string' && input.commitSha.trim() ? input.commitSha.trim() : undefined;
+    if (input.eventType === 'implemented' && !commitSha) {
+        return { ok: false, reason: 'missing_commit_sha_for_implemented', raw };
+    }
+    const experimentRunId = typeof input.experimentRunId === 'string' && input.experimentRunId.trim() ? input.experimentRunId.trim() : undefined;
+    const sourceVersion = typeof input.sourceVersion === 'string' && input.sourceVersion.trim() ? input.sourceVersion.trim() : undefined;
+    const evidenceRef = typeof input.evidenceRef === 'string' && input.evidenceRef.trim() ? input.evidenceRef.trim() : undefined;
+    const occurredAt = toEpochMs(input.occurredAt, now);
+    if (occurredAt === null) {
+        return { ok: false, reason: 'invalid_occurred_at', raw };
+    }
+    const idempotencyKey = typeof input.idempotencyKey === 'string' && input.idempotencyKey.trim()
+        ? input.idempotencyKey.trim()
+        : buildFeedbackIdempotencyKey({ hypothesisId, eventType: input.eventType, sourceType: input.sourceType, sourceId, commitSha, experimentRunId });
+    const event = {
+        id: typeof input.id === 'string' && input.id.trim() ? input.id.trim() : newEventId(),
+        hypothesisId,
+        eventType: input.eventType,
+        sourceType: input.sourceType,
+        sourceId,
+        ...(sourceVersion ? { sourceVersion } : {}),
+        ...(commitSha ? { commitSha } : {}),
+        ...(experimentRunId ? { experimentRunId } : {}),
+        ...(evidenceRef ? { evidenceRef } : {}),
+        occurredAt,
+        ingestedAt: now,
+        idempotencyKey,
+        schemaVersion: exports.FEEDBACK_EVENT_SCHEMA_VERSION,
+    };
+    return { ok: true, event };
+}
+/** 证据维度归类（spec §五.0）：选择 / 质量 / 落地。聚合时分维度累计，不合并成"成功次数"。 */
+function feedbackEvidenceDimension(eventType) {
+    switch (eventType) {
+        case 'adopted':
+            return 'selection';
+        case 'validated':
+            return 'quality';
+        case 'implemented':
+            return 'landing';
+        case 'rejected':
+        case 'regression_failed':
+            return 'negative';
+        default:
+            return 'negative';
+    }
+}

package/dist/FeedbackLearning.d.ts

@@ -0,0 +1,195 @@
+/**
+ * FeedbackLearning — 正向反馈闭环离线学习核心（设计 v1.0，P1）
+ *
+ * 纯计算，不碰 DB、不写 Memory、不改假设状态、不进晋级门输入。
+ * 输入规范化证据事件 + 假设 provenance，输出：
+ *   - ConceptPairWeight：概念对 × 三维度（选择/质量/落地）加权证据
+ *   - FeedbackSnapshot：不可变 + 版本号（sha256 前 12 位）
+ *   - 离线回放：原始 vs 反馈策略的逐对调整与证据追溯
+ *
+ * 评审决议（spec §十三）落地：
+ *   §13.2 带权 Beta 变体：衰减后计数为小数，不取整（取整顺序相关会破坏 reproducibility）。
+ *   §13.3 三维度归一分母 = 该维度 S_d + F_d，不跨维度、不用假设数；无事件维度取先验均值。
+ *   §13.1 batch 身份：experimentRunId 优先，否则 hypothesisId（或 implemented 的 commitSha）。
+ *   §13.4 快照只带结构化字段，禁止 raw 事件正文。
+ */
+import { type HypothesisFeedbackEvent, type HypothesisFeedbackEventType } from './FeedbackEvents';
+import type { FeedbackMixerInput } from './ConceptMixer';
+export type FeedbackDimension = 'selection' | 'quality' | 'landing' | 'negative';
+export declare const POSITIVE_DIMENSIONS: readonly FeedbackDimension[];
+export interface DimensionEstimate {
+    /** 衰减后的正向证据计数（小数，带权 Beta 变体） */
+    positiveCount: number;
+    /** 衰减后的负向证据计数（小数） */
+    negativeCount: number;
+    /** 原始事件数（未衰减，用于追溯） */
+    evidenceCount: number;
+    /** Beta 后验均值 θ_d = (α0+S_d)/(α0+β0+S_d+F_d)；无事件时 = 先验均值 */
+    posteriorMean: number;
+    /** 置信度 = (S+F)/(S+F+α0+β0)，先验信息之外的占比 */
+    confidence: number;
+    /** 该维度最近证据时间，epoch ms */
+    lastEvidenceAt: number;
+}
+export type AttributionKind = 'pair' | 'hypothesis_only';
+export interface ConceptPairWeight {
+    conceptAId: string;
+    conceptBId: string;
+    /** 规范化 pair key（已排序），用于跨实现稳定对齐 */
+    pairKey: string;
+    /** 归因级别：pair=可归因到概念对；hypothesis_only=provenance 缺失 */
+    attribution: AttributionKind;
+    selection: DimensionEstimate;
+    quality: DimensionEstimate;
+    landing: DimensionEstimate;
+    negative: DimensionEstimate;
+    lastEvidenceAt: number;
+    /** 产出该权重的快照版本（由 buildFeedbackSnapshot 回填） */
+    feedbackSnapshotVersion?: string;
+}
+export interface FeedbackLearningConfig {
+    /** 时间衰减半衰期（天），w(t)=2^(-Δt/H) */
+    halfLifeDays: number;
+    /** Beta 先验参数 */
+    alpha0: number;
+    beta0: number;
+    /** 置信度下限所需的最小样本数（参考量） */
+    minSamples: number;
+    /** 每类事件的证据权重上限（初始实验参数，spec §五.0/§13.3） */
+    weightCaps: {
+        validated: number;
+        adopted: number;
+        implemented: number;
+        rejected: number;
+        regression_failed: number;
+    };
+    /** 归因覆盖率低于此值时，只启用假设级归因（R5） */
+    attributionMinCoverage: number;
+    /** 探索预算比例（P2 消费，快照 hash 必须含） */
+    explorationBudget: number;
+    /** λ clamp 占总评分范围百分比（P2 消费，快照 hash 必须含） */
+    lambdaClampPct: number;
+}
+export declare const DEFAULT_FEEDBACK_LEARNING_CONFIG: FeedbackLearningConfig;
+export interface HypothesisProvenanceLike {
+    sources?: Array<{
+        name: string;
+        type: string;
+        origin?: string;
+        timestamp?: string;
+    }>;
+}
+/** 单条事件对某维度的贡献权重（未衰减）。负向事件归 negative 维度。 */
+export declare function evidenceWeight(eventType: HypothesisFeedbackEventType, caps: FeedbackLearningConfig['weightCaps']): number;
+export declare function isNegativeEvent(eventType: HypothesisFeedbackEventType): boolean;
+/** 时间衰减 w(t) = 2^(-Δt/H)，Δt 以天为单位；未来事件不放大。 */
+export declare function timeDecay(occurredAt: number, now: number, halfLifeDays: number): number;
+/** 概念身份：取 origin（稳定字段），缺失时回退 name 并标记 hypothesis_only。 */
+export declare function conceptIdOf(source: {
+    name: string;
+    origin?: string;
+}): string;
+export declare function pairKeyOf(a: string, b: string): string;
+/** 稳定序列化：对象键排序、数组保序，保证跨平台 hash 一致。 */
+export declare function canonicalJson(value: unknown): string;
+export declare function hashPrefix(input: string, length?: number): string;
+export interface EvidenceTraceEntry {
+    hypothesisId: string;
+    eventType: HypothesisFeedbackEventType;
+    sourceId: string;
+    pairKey: string;
+    dimension: FeedbackDimension;
+    weight: number;
+    batchKey: string;
+    duplicate: boolean;
+}
+export interface AggregateResult {
+    pairs: ConceptPairWeight[];
+    /** 正向事件中可归因到概念对的比例（R5） */
+    attributionCoverage: number;
+    /** 重复事件造成的重复加权比例（去重后为 0；验收指标） */
+    duplicateApplicationRate: number;
+    appliedCount: number;
+    /** 被去重抑制的重复事件数（可观测，非验收指标） */
+    dedupedEventCount: number;
+    /** 逐事件证据追溯 */
+    trace: EvidenceTraceEntry[];
+}
+/**
+ * 聚合概念对权重。
+ *
+ * @param events 规范化后的证据事件（可乱序；内部稳定排序）
+ * @param hypotheses hypothesisId → provenance（用于概念对归因）
+ * @param config 学习配置
+ * @param now 评估时刻，epoch ms
+ */
+export declare function aggregateConceptPairWeights(events: HypothesisFeedbackEvent[], hypotheses: Record<string, HypothesisProvenanceLike | undefined>, config?: FeedbackLearningConfig, now?: number): AggregateResult;
+export interface FeedbackSnapshot {
+    /** 不可变版本号 = sha256(排序后规范化事件窗口 + 配置 + schemaVersion) 前 12 位 */
+    version: string;
+    configHash: string;
+    generatedAt: number;
+    eventCount: number;
+    attributionCoverage: number;
+    duplicateApplicationRate: number;
+    /** 被去重抑制的重复事件数（可观测） */
+    dedupedEventCount: number;
+    pairs: ConceptPairWeight[];
+}
+/**
+ * 构建不可变快照。同输入 + 同配置 + 同版本 → 同 hash（100% 可复现）。
+ */
+export declare function buildFeedbackSnapshot(events: HypothesisFeedbackEvent[], hypotheses: Record<string, HypothesisProvenanceLike | undefined>, config?: FeedbackLearningConfig, now?: number): FeedbackSnapshot;
+export interface FeedbackAdjustment {
+    pairKey: string;
+    /** 综合调整 ∈ [-1, 1] */
+    adjustment: number;
+    evidenceCount: number;
+    posteriorMean: number;
+    confidence: number;
+    /** λ clamp 后的调整（占总评分范围的比例上限） */
+    clampedAdjustment: number;
+}
+/**
+ * 离线回放：给定概念对权重，计算有界反馈调整（λ clamp）。
+ * 不读 DB、不写任何状态；供 P2 接入 ConceptMixer 前做离线对比。
+ */
+export declare function replayFeedbackAdjustment(weight: ConceptPairWeight, config?: FeedbackLearningConfig): FeedbackAdjustment;
+export type FeedbackBand = 'low' | 'medium' | 'high';
+export interface FeedbackPromptSource {
+    pairKey: string;
+    conceptA: string;
+    conceptB: string;
+    dimension: FeedbackDimension;
+    evidenceCount: number;
+    posteriorBand: FeedbackBand;
+    confidenceBand: FeedbackBand;
+    scope: string;
+    limits: string;
+}
+export interface FeedbackPromptFailure {
+    pairKey: string;
+    conceptA: string;
+    conceptB: string;
+    dimension: FeedbackDimension;
+    evidenceCount: number;
+    scope: string;
+    limits: string;
+}
+export interface FeedbackPromptBlock {
+    version: string;
+    verified: FeedbackPromptSource[];
+    failures: FeedbackPromptFailure[];
+}
+/** 确定性裁剪：字符串上限 120 字符（§13.4）。 */
+export declare function clipPromptText(s: string, limit?: number): string;
+/**
+ * 从不可变快照构建结构化提示块。只带结构化字段，永不回灌 raw 事件正文
+ * 或 provenance.origin 自由文本（§13.4，红队注入面）。
+ */
+export declare function buildFeedbackPromptBlock(snapshot: FeedbackSnapshot): FeedbackPromptBlock;
+/**
+ * 快照 → ConceptMixer 有界消费输入（spec §六.2）。
+ * pairAdjustments 用快照 pairKey（conceptId 对齐）；λ clamp 由 mixer 再兜底。
+ */
+export declare function buildMixerInputFromSnapshot(snapshot: FeedbackSnapshot, config?: FeedbackLearningConfig): FeedbackMixerInput;