@akemi-mio/creativity 0.1.0 → 0.1.1

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;

package/dist/WhenThenRunner.d.ts

@@ -0,0 +1,135 @@
+/**
+ * WhenThenRunner — 声明式 WHEN/THEN 受限 DSL 运行器（机制涌现 P2a，定案 D5/R5/A2）
+ *
+ * 候选执行不写任意代码：DSL 查表求值（阈值比较 + 字段存在性 + 枚举匹配，禁 JS eval）。
+ * 步骤依赖执行 + 显式 named outputs（无隐式上下文注入）。
+ * resourceBudget 编译为 CapabilityToken.constraints。
+ * 求值器输入输出全白名单序列化（JSON number/boolean/string）。
+ * 条件字符串长度上限，解析失败 = fail-closed（步骤跳过 + 记 guardrail 事件，不中断实验、不泄漏沙箱内部）。
+ */
+/**
+ * Token constraints — structural alias for CapabilityToken['constraints'].
+ * Defined locally to avoid a cross-package type dependency in the build (tsconfig.build.json is allowlist-based).
+ */
+export interface TokenConstraints {
+    maxCalls?: number;
+    maxTokens?: number;
+    expiryMs?: number;
+    allowedValues?: Record<string, string[]>;
+}
+/** 比较操作符（白名单，禁自由表达式） */
+export type CompareOp = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'nin' | 'exists' | 'notExists';
+/** WHEN 条件（查表求值，无 JS eval） */
+export interface WhenCondition {
+    /** 数据源路径（点分，如 `metrics.latency` 或 `capabilities.publishing.outcome`） */
+    field: string;
+    op: CompareOp;
+    /** 比较值（number/boolean/string 白名单；in/nin 时为 string[]） */
+    value?: number | boolean | string | string[];
+}
+/** THEN 动作 */
+export interface ThenAction {
+    /** 步骤 id（图内唯一） */
+    id: string;
+    /** capability id（执行时 resolve） */
+    capabilityId: string;
+    /** 显式 named inputs：来自上游 named outputs 或初始 context 的白名单路径 */
+    inputs?: Record<string, string>;
+    /** 显式 named outputs：本步骤产出名（下游可引用） */
+    outputs?: string[];
+    /** 资源预算（编译为 CapabilityToken.constraints） */
+    resourceBudget?: ResourceBudgetSpec;
+    /** 依赖的上游步骤 id（显式 DAG，无隐式顺序） */
+    dependsOn?: string[];
+    /** WHEN 条件为空则无条件执行；条件不满足 = 本步骤跳过 */
+    when?: WhenCondition[];
+}
+/** 单步资源预算 */
+export interface ResourceBudgetSpec {
+    maxCalls?: number;
+    maxTokens?: number;
+    expiryMs?: number;
+    allowedValues?: Record<string, string[]>;
+}
+/** 完整 WHEN/THEN 规则（一个候选实验的声明式执行计划） */
+export interface WhenThenRule {
+    id: string;
+    /** 假设 id（回溯） */
+    hypothesisId?: string;
+    /** 规则描述 */
+    description?: string;
+    /** 步骤列表（依赖 DAG） */
+    steps: ThenAction[];
+    /** 规则级资源预算（步骤级覆盖规则级） */
+    resourceBudget?: ResourceBudgetSpec;
+}
+/** 条件字符串长度上限（防超长注入） */
+export declare const MAX_CONDITION_FIELD_LEN = 128;
+export declare const MAX_CONDITION_STRING_VALUE_LEN = 512;
+export declare const MAX_CONDITION_LIST_LEN = 32;
+/** 按点分路径从 context 取值；中间路径不存在返回 undefined。不深入数组索引（防原型链）。 */
+export declare function lookupField(context: Record<string, unknown>, field: string): unknown;
+/** 求值单个 WHEN 条件；解析失败（非法字段/值/操作符）返回 null（调用方 fail-closed）。 */
+export declare function evaluateCondition(context: Record<string, unknown>, cond: WhenCondition): boolean | null;
+/** 求值全部 WHEN 条件（AND）；任一解析失败返回 null（fail-closed）。 */
+export declare function evaluateWhen(context: Record<string, unknown>, when: WhenCondition[] | undefined): boolean | null;
+/** 把 ResourceBudgetSpec 编译为 CapabilityToken.constraints（白名单字段）。 */
+export declare function compileBudgetToConstraints(budget: ResourceBudgetSpec | undefined, ruleBudget?: ResourceBudgetSpec): TokenConstraints | undefined;
+/** 单步执行输入（全白名单序列化） */
+export interface StepExecInput {
+    stepId: string;
+    capabilityId: string;
+    /** 显式 named inputs（路径解析后的值） */
+    inputs: Record<string, unknown>;
+    /** 编译后的 token constraints */
+    constraints?: TokenConstraints;
+}
+/** 单步执行结果 */
+export interface StepExecResult {
+    success: boolean;
+    /** 显式 named outputs（本步骤产出） */
+    outputs?: Record<string, unknown>;
+    error?: string;
+}
+/** 步骤执行器接口（由 CreativityExecutor / CapabilityService 实现） */
+export type StepExecutor = (input: StepExecInput) => Promise<StepExecResult>;
+/** 运行器事件（guardrail 事件 sink） */
+export interface RunnerEvent {
+    event_type: 'whenthen.step.skipped' | 'whenthen.step.failed' | 'whenthen.rule.complete' | 'whenthen.rule.failed';
+    rule_id: string;
+    step_id?: string;
+    /** 公开原因（不泄漏沙箱内部） */
+    reason?: string;
+    outcome?: string;
+    timestamp: number;
+}
+export type RunnerEventSink = (ev: RunnerEvent) => void;
+/** 拓扑排序步骤；环路/未知依赖返回 null（fail-closed）。 */
+export declare function topologicalOrder(steps: readonly ThenAction[]): ThenAction[] | null;
+export interface RunRuleResult {
+    success: boolean;
+    /** 各步骤 named outputs 汇总（key = stepId.outputName 或 outputName） */
+    namedOutputs: Record<string, unknown>;
+    /** 各步骤状态 */
+    steps: Array<{
+        id: string;
+        status: 'ok' | 'skipped' | 'failed' | 'blocked';
+        reason?: string;
+        outputs?: Record<string, unknown>;
+    }>;
+    events: RunnerEvent[];
+}
+/**
+ * 执行一条 WHEN/THEN 规则。
+ *
+ * - 按 DAG 拓扑顺序调度
+ * - 每步先求值 WHEN（解析失败 → fail-closed skip + guardrail 事件）
+ * - 输入从初始 context + 上游 named outputs 显式解析（无隐式注入）
+ * - 预算编译为 CapabilityToken.constraints 传给 executor
+ * - 任一步失败不中断实验：后续依赖步骤 blocked，独立步骤继续
+ */
+export declare function runWhenThenRule(rule: WhenThenRule, context: Record<string, unknown>, executeStep: StepExecutor, options?: {
+    /** 初始 named outputs（可选）；与 context 不同：context 只用于 WHEN 求值 */
+    initialOutputs?: Record<string, unknown>;
+    onEvent?: RunnerEventSink;
+}): Promise<RunRuleResult>;