@akemi-mio/creativity 0.1.0 → 0.2.0

package/dist/JsonlFeedbackEventStore.js

@@ -0,0 +1,79 @@
+"use strict";
+/**
+ * JsonlFeedbackEventStore — CLI/MCP 侧证据事件追加存储（P0）
+ *
+ * 落盘：`<dataDir>/feedback-events.jsonl`（append-only）。
+ * 幂等：加载时建 idempotencyKey 集合，同键追加直接跳过（不抛错、不重复生效）。
+ * 这是交换/重放格式，不是权威真相源——主进程 ingest 单向导入 SQLite。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JsonlFeedbackEventStore = void 0;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const FeedbackEvents_1 = require("./FeedbackEvents");
+class JsonlFeedbackEventStore {
+    eventsPath;
+    seenKeys = null;
+    constructor(dataDir) {
+        this.eventsPath = (0, path_1.join)(dataDir, 'feedback-events.jsonl');
+    }
+    /** 重读文件（长活 MCP 进程需看到外部追加；幂等键集合整体重建，成本可接受）。 */
+    ensureLoaded() {
+        if (this.seenKeys)
+            return this.seenKeys;
+        this.seenKeys = new Set();
+        if ((0, fs_1.existsSync)(this.eventsPath)) {
+            const lines = (0, fs_1.readFileSync)(this.eventsPath, 'utf-8').split('\n').filter(Boolean);
+            for (const line of lines) {
+                try {
+                    const row = JSON.parse(line);
+                    if (row && typeof row.idempotencyKey === 'string')
+                        this.seenKeys.add(row.idempotencyKey);
+                }
+                catch {
+                    // 损坏行不参与幂等集合；ingest 时会进隔离
+                }
+            }
+        }
+        return this.seenKeys;
+    }
+    /** 供长活进程在外部写入后强制重读。 */
+    invalidate() {
+        this.seenKeys = null;
+    }
+    append(input, now = Date.now()) {
+        const normalized = (0, FeedbackEvents_1.normalizeFeedbackEvent)(input, now);
+        if (!normalized.ok) {
+            return { appended: false, deduped: false, quarantine: { reason: normalized.reason, raw: normalized.raw } };
+        }
+        const event = normalized.event;
+        const keys = this.ensureLoaded();
+        if (keys.has(event.idempotencyKey)) {
+            return { appended: false, deduped: true, event };
+        }
+        const dir = (0, path_1.dirname)(this.eventsPath);
+        if (!(0, fs_1.existsSync)(dir))
+            (0, fs_1.mkdirSync)(dir, { recursive: true });
+        (0, fs_1.appendFileSync)(this.eventsPath, JSON.stringify(event) + '\n', 'utf-8');
+        keys.add(event.idempotencyKey);
+        return { appended: true, deduped: false, event };
+    }
+    /** 读取全部可解析事件（损坏行跳过，供 ingest/回放使用）。 */
+    list() {
+        if (!(0, fs_1.existsSync)(this.eventsPath))
+            return [];
+        const out = [];
+        for (const line of (0, fs_1.readFileSync)(this.eventsPath, 'utf-8').split('\n')) {
+            if (!line.trim())
+                continue;
+            try {
+                out.push(JSON.parse(line));
+            }
+            catch {
+                // skip corrupt
+            }
+        }
+        return out;
+    }
+}
+exports.JsonlFeedbackEventStore = JsonlFeedbackEventStore;

package/dist/MechanismGraph.d.ts

@@ -0,0 +1,46 @@
+import type { ProposedRelation } from './types';
+/**
+ * Mechanism Graph v0 — traces.jsonl 派生读模型（非独立图存储）。
+ *
+ * 定案 A6：confidence 由边的推断来源映射——identity=verified → high，
+ * inferred → low。聚合键为 (agent, capabilityId, outcome)。
+ * 持久化图后置到 P3 验证有产出之后。
+ */
+export interface TraceEventLike {
+    event_type?: string;
+    outcome?: string;
+    agent?: string;
+    payload?: Record<string, unknown>;
+}
+export interface MechanismEdge {
+    agent: string;
+    capabilityId: string;
+    outcome: string;
+    count: number;
+    /** A6: identity=verified→high / inferred→low */
+    confidence: 'high' | 'low';
+    /** 聚合中出现过的 inference 种类（identity 优先） */
+    inferences: Array<'identity' | 'inferred'>;
+}
+export interface MechanismGraph {
+    edges: MechanismEdge[];
+    /** 参与聚合的事件总数（仅计入含 agent+capabilityId 的 tool_call/task 类事件） */
+    eventCount: number;
+}
+/**
+ * 从 traces.jsonl 行事件聚合机制边。
+ *
+ * 规则：
+ * - 仅计入 payload.capabilityId 存在的事件（能力绑定相关）。
+ * - 每条边键 = `${agent}|${capabilityId}|${outcome}`，count 累加。
+ * - inference：payload.inference === 'identity' 或 event_type 含 identity
+ *   时记 identity；否则记 inferred。
+ * - confidence：边内出现过任一 identity → high，否则 low。
+ */
+export declare function deriveMechanismGraph(events: readonly TraceEventLike[]): MechanismGraph;
+/** 把机制假设的 proposedRelations 投影为与派生图同形状的边（供对照，confidence 走 inference 字段）。 */
+export declare function relationsToEdges(agent: string, relations: readonly ProposedRelation[]): MechanismEdge[];
+/** 是否为机制假设：带非空 proposedRelations 即机制假设，否则普通创意（一个 store 两种粒度）。 */
+export declare function isMechanismHypothesis(h: {
+    proposedRelations?: ProposedRelation[];
+}): boolean;

package/dist/MechanismGraph.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deriveMechanismGraph = deriveMechanismGraph;
+exports.relationsToEdges = relationsToEdges;
+exports.isMechanismHypothesis = isMechanismHypothesis;
+function asString(v, fallback = '') {
+    return typeof v === 'string' && v.length > 0 ? v : fallback;
+}
+/**
+ * 从 traces.jsonl 行事件聚合机制边。
+ *
+ * 规则：
+ * - 仅计入 payload.capabilityId 存在的事件（能力绑定相关）。
+ * - 每条边键 = `${agent}|${capabilityId}|${outcome}`，count 累加。
+ * - inference：payload.inference === 'identity' 或 event_type 含 identity
+ *   时记 identity；否则记 inferred。
+ * - confidence：边内出现过任一 identity → high，否则 low。
+ */
+function deriveMechanismGraph(events) {
+    const edgeMap = new Map();
+    let eventCount = 0;
+    for (const ev of events) {
+        const capabilityId = asString(ev.payload?.capabilityId);
+        if (!capabilityId)
+            continue;
+        const agent = asString(ev.agent, 'unknown');
+        const outcome = asString(ev.outcome, 'unknown');
+        eventCount++;
+        const key = `${agent}|${capabilityId}|${outcome}`;
+        let edge = edgeMap.get(key);
+        if (!edge) {
+            edge = {
+                agent,
+                capabilityId,
+                outcome,
+                count: 0,
+                confidence: 'low',
+                inferences: [],
+            };
+            edgeMap.set(key, edge);
+        }
+        edge.count++;
+        const rawInference = ev.payload?.inference;
+        const inference = rawInference === 'identity' || (typeof ev.event_type === 'string' && ev.event_type.includes('identity')) ? 'identity' : 'inferred';
+        if (!edge.inferences.includes(inference))
+            edge.inferences.push(inference);
+        if (inference === 'identity')
+            edge.confidence = 'high';
+    }
+    const edges = [...edgeMap.values()].sort((a, b) => {
+        const c = b.count - a.count;
+        if (c !== 0)
+            return c;
+        const k = `${a.agent}|${a.capabilityId}|${a.outcome}`.localeCompare(`${b.agent}|${b.capabilityId}|${b.outcome}`);
+        return k;
+    });
+    return { edges, eventCount };
+}
+/** 把机制假设的 proposedRelations 投影为与派生图同形状的边（供对照，confidence 走 inference 字段）。 */
+function relationsToEdges(agent, relations) {
+    return relations.map((r) => {
+        const inference = r.inference ?? 'inferred';
+        return {
+            agent,
+            capabilityId: r.from,
+            outcome: r.to,
+            count: 1,
+            confidence: inference === 'identity' ? 'high' : 'low',
+            inferences: [inference],
+        };
+    });
+}
+/** 是否为机制假设：带非空 proposedRelations 即机制假设，否则普通创意（一个 store 两种粒度）。 */
+function isMechanismHypothesis(h) {
+    return Array.isArray(h.proposedRelations) && h.proposedRelations.length > 0;
+}

package/dist/MechanismRegistry.d.ts

@@ -0,0 +1,118 @@
+/**
+ * MechanismRegistry — 机制版本注册表 + PromotionRequest 薄实现（机制涌现 P4，定案 D5/A5）
+ *
+ * 生产轴：mechanisms.jsonl 存 MechanismVersion（mechanismId/version/status active|rolled_back/
+ * rollbackTo/approvedBy/submittedBy）。A5 代码级校验：Registry 写入时断言批准者≠提交者。
+ * PromotionRequest：提交前硬闸复用 checkPromotionGate（stale / n<minSamples 禁止提交），
+ * 批准走 pending → approved|rejected，批准时激活新版本并标旧版本 rolled_back。
+ * 回滚：rolled_back 路径——当前 active 标 rolled_back（rollbackTo=目标版本），目标版本重新激活。
+ */
+import { type StoppingRuleConfig, type ExperimentRun } from './ExperimentRunStore';
+export type MechanismStatus = 'active' | 'rolled_back';
+export interface MechanismVersion {
+    mechanismId: string;
+    /** 单调递增版本号，从 1 开始 */
+    version: number;
+    status: MechanismStatus;
+    /** 回滚目标版本（仅 status=rolled_back 时可设，指回滚后应激活的版本） */
+    rollbackTo?: number;
+    /** A5：批准者 agent id（≠submittedBy） */
+    approvedBy: string;
+    /** 提交者 agent id */
+    submittedBy: string;
+    hypothesisId?: string;
+    experimentRunIds?: string[];
+    createdAt: number;
+}
+export type ApprovalStatus = 'pending' | 'approved' | 'rejected';
+export interface PromotionRequest {
+    id: string;
+    mechanismId: string;
+    version: number;
+    hypothesisId?: string;
+    experimentRunIds: string[];
+    submittedBy: string;
+    approvalStatus: ApprovalStatus;
+    approvedBy?: string;
+    /** 拒绝/批准的公开原因 */
+    reason?: string;
+    createdAt: number;
+    decidedAt?: number;
+}
+/** A5：批准者必须与提交者不同，且双方非空。 */
+export declare function canIndependentlyApprove(submittedBy: string, approvedBy: string): boolean;
+export interface SubmitGateResult {
+    allowed: boolean;
+    reason: string;
+}
+/** 提交 PromotionRequest 前的硬闸检查。stale 或 n<minSamples 一律禁止提交。 */
+export declare function checkSubmitGate(config: StoppingRuleConfig, runs: readonly ExperimentRun[], currentSnapshotId?: string): SubmitGateResult;
+export interface SubmitPromotionInput {
+    mechanismId: string;
+    version: number;
+    hypothesisId?: string;
+    experimentRunIds?: string[];
+    submittedBy: string;
+}
+export type SubmitResult = {
+    ok: true;
+    request: PromotionRequest;
+} | {
+    ok: false;
+    reason: string;
+};
+export type DecideResult = {
+    ok: true;
+    request: PromotionRequest;
+    activated?: MechanismVersion;
+} | {
+    ok: false;
+    reason: string;
+};
+export type RollbackResult = {
+    ok: true;
+    rolledBack: MechanismVersion;
+    restored: MechanismVersion;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * 薄 Registry：文件级 jsonl 存储（机制设计定稿 P4 首版，不必上数据库）。
+ * 状态机：
+ * - PromotionRequest: pending → approved | rejected（批准时激活版本）
+ * - MechanismVersion: active | rolled_back（rolled_back 可带 rollbackTo）
+ */
+export declare class MechanismRegistryStore {
+    private readonly versionsPath;
+    private readonly requestsPath?;
+    private versions;
+    private requests;
+    private requestSeq;
+    constructor(versionsPath: string, requestsPath?: string | undefined);
+    listVersions(mechanismId?: string): MechanismVersion[];
+    getActive(mechanismId: string): MechanismVersion | null;
+    getHistory(mechanismId: string): MechanismVersion[];
+    listRequests(status?: ApprovalStatus): PromotionRequest[];
+    getRequest(id: string): PromotionRequest | null;
+    /**
+     * 提交 PromotionRequest。
+     * 硬闸：stale / snapshot_mismatch / below_min_samples 一律拒绝（复用 checkSubmitGate）。
+     * A5 双人：提交时不做批准校验（批准时校验）。
+     */
+    submit(input: SubmitPromotionInput, gate: SubmitGateResult): SubmitResult;
+    /**
+     * 批准 PromotionRequest。
+     * A5 代码级校验：批准者必须≠提交者（写进代码不是文档）。
+     * 批准成功：写入 MechanismVersion active，旧 active 标 rolled_back。
+     */
+    approve(requestId: string, approvedBy: string, now?: number): DecideResult;
+    reject(requestId: string, approvedBy: string, reason: string, now?: number): DecideResult;
+    /**
+     * 回滚：当前 active 标 rolled_back（rollbackTo=目标版本），目标版本重新激活。
+     * 生产观察恶化触发重评估 → 调用本方法回到 rollbackTo 指定的历史版本。
+     */
+    rollback(mechanismId: string, now?: number): RollbackResult;
+    private persistVersions;
+    private persistRequests;
+}

package/dist/MechanismRegistry.js

@@ -0,0 +1,233 @@
+"use strict";
+/**
+ * MechanismRegistry — 机制版本注册表 + PromotionRequest 薄实现（机制涌现 P4，定案 D5/A5）
+ *
+ * 生产轴：mechanisms.jsonl 存 MechanismVersion（mechanismId/version/status active|rolled_back/
+ * rollbackTo/approvedBy/submittedBy）。A5 代码级校验：Registry 写入时断言批准者≠提交者。
+ * PromotionRequest：提交前硬闸复用 checkPromotionGate（stale / n<minSamples 禁止提交），
+ * 批准走 pending → approved|rejected，批准时激活新版本并标旧版本 rolled_back。
+ * 回滚：rolled_back 路径——当前 active 标 rolled_back（rollbackTo=目标版本），目标版本重新激活。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MechanismRegistryStore = void 0;
+exports.canIndependentlyApprove = canIndependentlyApprove;
+exports.checkSubmitGate = checkSubmitGate;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const ExperimentRunStore_1 = require("./ExperimentRunStore");
+// ══════════════════════════════════════════
+// A5 代码级校验（批准者≠提交者，写进代码不是文档）
+// ══════════════════════════════════════════
+/** A5：批准者必须与提交者不同，且双方非空。 */
+function canIndependentlyApprove(submittedBy, approvedBy) {
+    if (!submittedBy || !approvedBy)
+        return false;
+    return submittedBy !== approvedBy;
+}
+/** 提交 PromotionRequest 前的硬闸检查。stale 或 n<minSamples 一律禁止提交。 */
+function checkSubmitGate(config, runs, currentSnapshotId) {
+    const gate = (0, ExperimentRunStore_1.checkPromotionGate)(config, runs, currentSnapshotId);
+    if (!gate.allowed) {
+        return { allowed: false, reason: gate.reason };
+    }
+    return { allowed: true, reason: 'ok' };
+}
+// ══════════════════════════════════════════
+// 文件持久化（jsonl，append-only 语义，整文件重写）
+// ══════════════════════════════════════════
+function readJsonl(path) {
+    if (!(0, node_fs_1.existsSync)(path))
+        return [];
+    const raw = (0, node_fs_1.readFileSync)(path, 'utf8').trim();
+    if (!raw)
+        return [];
+    return raw
+        .split('\n')
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .map((line) => JSON.parse(line));
+}
+function writeJsonl(path, entries) {
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(path), { recursive: true });
+    const body = entries.map((e) => JSON.stringify(e)).join('\n');
+    (0, node_fs_1.writeFileSync)(path, body ? `${body}\n` : '', 'utf8');
+}
+/**
+ * 薄 Registry：文件级 jsonl 存储（机制设计定稿 P4 首版，不必上数据库）。
+ * 状态机：
+ * - PromotionRequest: pending → approved | rejected（批准时激活版本）
+ * - MechanismVersion: active | rolled_back（rolled_back 可带 rollbackTo）
+ */
+class MechanismRegistryStore {
+    versionsPath;
+    requestsPath;
+    versions = [];
+    requests = [];
+    requestSeq = 0;
+    constructor(versionsPath, requestsPath) {
+        this.versionsPath = versionsPath;
+        this.requestsPath = requestsPath;
+        this.versions = readJsonl(versionsPath);
+        const reqPath = requestsPath ?? versionsPath.replace(/mechanisms\.jsonl$/, 'promotion-requests.jsonl');
+        this.requests = readJsonl(reqPath);
+        // 恢复 requestSeq（幂等续号）
+        for (const r of this.requests) {
+            const m = /^pr-(\d+)$/.exec(r.id);
+            if (m)
+                this.requestSeq = Math.max(this.requestSeq, Number(m[1]));
+        }
+    }
+    // ── 查询 ──
+    listVersions(mechanismId) {
+        if (!mechanismId)
+            return [...this.versions];
+        return this.versions.filter((v) => v.mechanismId === mechanismId);
+    }
+    getActive(mechanismId) {
+        const actives = this.versions.filter((v) => v.mechanismId === mechanismId && v.status === 'active');
+        // 防御：多 active 取最高版本
+        if (actives.length === 0)
+            return null;
+        return actives.reduce((a, b) => (b.version > a.version ? b : a));
+    }
+    getHistory(mechanismId) {
+        return this.versions.filter((v) => v.mechanismId === mechanismId).sort((a, b) => a.version - b.version);
+    }
+    listRequests(status) {
+        if (!status)
+            return [...this.requests];
+        return this.requests.filter((r) => r.approvalStatus === status);
+    }
+    getRequest(id) {
+        return this.requests.find((r) => r.id === id) ?? null;
+    }
+    // ── 提交（Pending） ──
+    /**
+     * 提交 PromotionRequest。
+     * 硬闸：stale / snapshot_mismatch / below_min_samples 一律拒绝（复用 checkSubmitGate）。
+     * A5 双人：提交时不做批准校验（批准时校验）。
+     */
+    submit(input, gate) {
+        if (!gate.allowed) {
+            return { ok: false, reason: gate.reason };
+        }
+        if (!input.mechanismId || !input.submittedBy) {
+            return { ok: false, reason: 'invalid_input' };
+        }
+        if (!Number.isInteger(input.version) || input.version < 1) {
+            return { ok: false, reason: 'invalid_version' };
+        }
+        // 拒绝重复 pending（同 mechanismId+version）
+        const dup = this.requests.find((r) => r.mechanismId === input.mechanismId && r.version === input.version && r.approvalStatus === 'pending');
+        if (dup) {
+            return { ok: false, reason: 'duplicate_pending' };
+        }
+        this.requestSeq += 1;
+        const request = {
+            id: `pr-${this.requestSeq}`,
+            mechanismId: input.mechanismId,
+            version: input.version,
+            hypothesisId: input.hypothesisId,
+            experimentRunIds: input.experimentRunIds ?? [],
+            submittedBy: input.submittedBy,
+            approvalStatus: 'pending',
+            createdAt: Date.now(),
+        };
+        this.requests.push(request);
+        this.persistRequests();
+        return { ok: true, request };
+    }
+    // ── 批准（A5 双人校验 + 激活版本） ──
+    /**
+     * 批准 PromotionRequest。
+     * A5 代码级校验：批准者必须≠提交者（写进代码不是文档）。
+     * 批准成功：写入 MechanismVersion active，旧 active 标 rolled_back。
+     */
+    approve(requestId, approvedBy, now = Date.now()) {
+        const req = this.requests.find((r) => r.id === requestId);
+        if (!req)
+            return { ok: false, reason: 'request_not_found' };
+        if (req.approvalStatus !== 'pending') {
+            return { ok: false, reason: 'not_pending' };
+        }
+        // A5：批准者≠提交者（代码级）
+        if (!canIndependentlyApprove(req.submittedBy, approvedBy)) {
+            return { ok: false, reason: 'self_approval_forbidden' };
+        }
+        // 标记旧 active → rolled_back（回滚目标=本版本）
+        const previous = this.getActive(req.mechanismId);
+        if (previous) {
+            previous.status = 'rolled_back';
+            previous.rollbackTo = req.version;
+        }
+        // 写入新 active 版本
+        const version = {
+            mechanismId: req.mechanismId,
+            version: req.version,
+            status: 'active',
+            approvedBy,
+            submittedBy: req.submittedBy,
+            hypothesisId: req.hypothesisId,
+            experimentRunIds: req.experimentRunIds,
+            createdAt: now,
+        };
+        this.versions.push(version);
+        req.approvalStatus = 'approved';
+        req.approvedBy = approvedBy;
+        req.decidedAt = now;
+        this.persistVersions();
+        this.persistRequests();
+        return { ok: true, request: req, activated: version };
+    }
+    // ── 拒绝 ──
+    reject(requestId, approvedBy, reason, now = Date.now()) {
+        const req = this.requests.find((r) => r.id === requestId);
+        if (!req)
+            return { ok: false, reason: 'request_not_found' };
+        if (req.approvalStatus !== 'pending') {
+            return { ok: false, reason: 'not_pending' };
+        }
+        req.approvalStatus = 'rejected';
+        req.approvedBy = approvedBy;
+        req.reason = reason;
+        req.decidedAt = now;
+        this.persistRequests();
+        return { ok: true, request: req };
+    }
+    // ── 回滚 ──
+    /**
+     * 回滚：当前 active 标 rolled_back（rollbackTo=目标版本），目标版本重新激活。
+     * 生产观察恶化触发重评估 → 调用本方法回到 rollbackTo 指定的历史版本。
+     */
+    rollback(mechanismId, now = Date.now()) {
+        const current = this.getActive(mechanismId);
+        if (!current) {
+            return { ok: false, reason: 'no_active_version' };
+        }
+        const history = this.getHistory(mechanismId);
+        // 找目标：当前版本之前最高的历史版本
+        const target = history
+            .filter((v) => v.version < current.version)
+            .reduce((acc, v) => (!acc || v.version > acc.version ? v : acc), null);
+        if (!target) {
+            return { ok: false, reason: 'no_rollback_target' };
+        }
+        // 当前 → rolled_back
+        current.status = 'rolled_back';
+        current.rollbackTo = target.version;
+        // 目标 → 重新激活（更新 status；不动 createdAt 保留审计）
+        target.status = 'active';
+        target.approvedBy = current.approvedBy; // 沿用原批准者（审计不改）
+        this.persistVersions();
+        return { ok: true, rolledBack: current, restored: target };
+    }
+    // ── 持久化 ──
+    persistVersions() {
+        writeJsonl(this.versionsPath, this.versions);
+    }
+    persistRequests() {
+        const reqPath = this.requestsPath ?? this.versionsPath.replace(/mechanisms\.jsonl$/, 'promotion-requests.jsonl');
+        writeJsonl(reqPath, this.requests);
+    }
+}
+exports.MechanismRegistryStore = MechanismRegistryStore;