@evomap/evolver-core 2.0.0-beta.0 → 2.0.0-beta.10

package/dist/wire/geneHints.js

@@ -22,13 +22,22 @@
 export const ROUTING_TIERS = ['cheap', 'mid', 'expensive'];
 export const REASONING_LEVELS = ['off', 'low', 'medium', 'high'];
 export const TOOL_POLICY_SEVERITIES = ['warn', 'block'];
+/**
+ * Provenance classification (V1 #302 classifyProvenance, aligned with TaskGenome Bench §3.1): a Gene's value
+ * depends on WHERE it came from, not on being short. The three tiers:
+ *   evolved   -- distilled from a real solve -> fail -> mutate -> pass trajectory; beats Skills (+8.7..+15.5pp)
+ *   distilled -- transcribed from reference/teacher text with no real failing trajectory; WORSE than Skills (-3.2..-11.2pp)
+ *   manual    -- pure human transcription, no execution evidence at all
+ * The high-value payload of an evolved Gene is the corrective_insight that flipped the outcome.
+ */
+export const GENERATION_SOURCES = ['evolved', 'distilled', 'manual'];
 /**
  * The v2-delta hint field names, in one place — the intake gate strips these before the gep-sdk schema check.
  * IMPORTANT: when a gep-sdk gene-schema bump makes one of these first-class, REMOVE it from this list in the
  * same change. Otherwise intakeGene keeps stripping a now-validated field before validateWire (fail-open — the
  * field's new schema constraints go unchecked at intake) while asset_id still commits it.
  */
-export const GENE_HINT_FIELDS = ['routing_hint', 'tool_policy'];
+export const GENE_HINT_FIELDS = ['routing_hint', 'tool_policy', 'generation_meta'];
 function includesEnum(set, v) {
     return typeof v === 'string' && set.includes(v);
 }
@@ -89,6 +98,48 @@ function cleanToolList(raw) {
     const cleaned = raw.filter((x) => typeof x === 'string' && x.length > 0);
     return cleaned.length > 0 ? cleaned : undefined;
 }
+/**
+ * Normalize an arbitrary generation_meta fragment to a strict { source, quality_score?, quality_heuristics?,
+ * overcame_errors? } object, or null. Lossy (mirrors normalizeRoutingHint / normalizeToolPolicy): unknown source
+ * values are dropped (the whole block collapses to null — a generation_meta with no recognized source carries no
+ * usable provenance signal); quality_score is clamped to [0,1]; heuristics keeps only its numeric/boolean fields;
+ * overcame_errors keeps only non-empty strings. A block with a valid source but all-else-empty still survives (source
+ * alone is a meaningful provenance tag); only a missing/unknown source yields null.
+ */
+export function normalizeGenerationMeta(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const r = raw;
+    const source = r['source'];
+    if (!includesEnum(GENERATION_SOURCES, source))
+        return null;
+    const out = { source };
+    const qs = r['quality_score'];
+    if (typeof qs === 'number' && Number.isFinite(qs))
+        out.quality_score = Math.max(0, Math.min(1, qs));
+    const eh = r['quality_heuristics'];
+    if (eh && typeof eh === 'object') {
+        const h = eh;
+        const heuristics = {};
+        const numFields = [
+            'strategy_steps', 'avoid_count', 'validation_declared_count', 'validation_runnable_count',
+            'signals_extracted', 'preconditions_extracted', 'trajectory_depth',
+        ];
+        for (const k of numFields) {
+            const v = h[k];
+            if (typeof v === 'number' && Number.isFinite(v))
+                heuristics[k] = v;
+        }
+        if (typeof h['has_corrective_insight'] === 'boolean')
+            heuristics.has_corrective_insight = h['has_corrective_insight'];
+        if (Object.keys(heuristics).length > 0)
+            out.quality_heuristics = heuristics;
+    }
+    const errs = cleanToolList(r['overcame_errors']);
+    if (errs)
+        out.overcame_errors = errs;
+    return out;
+}
 /** Strip the v2-delta hint fields from a gene-shaped object (used to validate the gep-sdk-known core). */
 export function stripGeneHints(gene) {
     const hidden = GENE_HINT_FIELDS;

package/dist/wire/index.d.ts

@@ -2,12 +2,18 @@
  * 资产 wire 层. SSOT = @evomap/gep-sdk/schemas/*.schema.json (D19).
  * 字段一律 snake_case 锁定 (asset_id 跨实现契约); 本仓不发明 wire 字段, 只镜像 + 重导出工具.
  */
-import type { GeneRoutingHint, GeneToolPolicy } from './geneHints.js';
+import type { GeneRoutingHint, GeneToolPolicy, GenerationMeta } from './geneHints.js';
 export { SCHEMA_VERSION, canonicalize, computeAssetId, verifyAssetId } from '@evomap/gep-sdk';
 export type GepCategory = typeof import('@evomap/gep-sdk').GEP_GENE_CATEGORIES[number];
 export type OutcomeStatus = typeof import('@evomap/gep-sdk').GEP_OUTCOME_STATUSES[number];
 export type SourceType = typeof import('@evomap/gep-sdk').GEP_SOURCE_TYPES[number];
 export type RiskLevel = typeof import('@evomap/gep-sdk').GEP_RISK_LEVELS[number];
+export type CapsuleVisibility = typeof import('@evomap/gep-sdk').GEP_CAPSULE_VISIBILITIES[number];
+export type CapsuleCostTier = typeof import('@evomap/gep-sdk').GEP_CAPSULE_COST_TIERS[number];
+export interface CapsuleAuthor {
+    handle: string;
+    evox_install_id: string;
+}
 /** Gene = 基因型/方法论 (gene.schema.json). */
 export interface Gene {
     type: 'Gene';
@@ -28,6 +34,7 @@ export interface Gene {
     anti_patterns?: unknown[];
     routing_hint?: GeneRoutingHint | null;
     tool_policy?: GeneToolPolicy | null;
+    generation_meta?: GenerationMeta | null;
     asset_id: string;
 }
 /** Capsule = 表现型/纯进化产物 (capsule.schema.json). */
@@ -49,6 +56,11 @@ export interface Capsule {
     };
     resolution_status?: 'pending' | 'suppressed_observationally' | 'resolved_by_evidence' | 'regressed' | 'inconclusive';
     proof_of_work?: unknown;
+    visibility?: CapsuleVisibility | null;
+    scope?: string[] | null;
+    cost_tier?: CapsuleCostTier | null;
+    pack_of?: string[] | null;
+    author?: CapsuleAuthor | null;
     execution_trace?: unknown[];
     trigger_context?: unknown;
     asset_id: string;
@@ -88,4 +100,4 @@ export interface Mutation {
     risk_level: RiskLevel;
 }
 export { validateWire, schemaProperties, type WireValidation } from './schemaGate.js';
-export { ROUTING_TIERS, REASONING_LEVELS, TOOL_POLICY_SEVERITIES, GENE_HINT_FIELDS, normalizeRoutingHint, normalizeToolPolicy, stripGeneHints, type RoutingTier, type ReasoningLevel, type ToolPolicySeverity, type GeneRoutingHint, type GeneToolPolicy, } from './geneHints.js';
+export { ROUTING_TIERS, REASONING_LEVELS, TOOL_POLICY_SEVERITIES, GENERATION_SOURCES, GENE_HINT_FIELDS, normalizeRoutingHint, normalizeToolPolicy, normalizeGenerationMeta, stripGeneHints, type RoutingTier, type ReasoningLevel, type ToolPolicySeverity, type GenerationSource, type GeneRoutingHint, type GeneToolPolicy, type GeneGenerationHeuristics, type GenerationMeta, } from './geneHints.js';

package/dist/wire/index.js

@@ -1,3 +1,3 @@
 export { SCHEMA_VERSION, canonicalize, computeAssetId, verifyAssetId } from '@evomap/gep-sdk';
 export { validateWire, schemaProperties } from './schemaGate.js';
-export { ROUTING_TIERS, REASONING_LEVELS, TOOL_POLICY_SEVERITIES, GENE_HINT_FIELDS, normalizeRoutingHint, normalizeToolPolicy, stripGeneHints, } from './geneHints.js';
+export { ROUTING_TIERS, REASONING_LEVELS, TOOL_POLICY_SEVERITIES, GENERATION_SOURCES, GENE_HINT_FIELDS, normalizeRoutingHint, normalizeToolPolicy, normalizeGenerationMeta, stripGeneHints, } from './geneHints.js';

package/dist/workflow/dsl.d.ts

@@ -14,13 +14,26 @@ export interface CoreCall {
     fn: string;
     args: Value[];
 }
-export interface ScriptStep {
+export type WorkflowErrorClass = 'transient' | 'permanent' | 'safety' | 'unknown';
+export declare function containsWorkflowSensitiveText(value: string): boolean;
+export interface WorkflowRetryPolicy {
+    maxAttempts: number;
+    initialDelayMs?: number;
+    maxDelayMs?: number;
+    multiplier?: number;
+}
+export interface DurableStepOptions {
+    /** Agent steps default to non-idempotent; script steps default to idempotent. */
+    idempotency?: 'idempotent' | 'non_idempotent';
+    retry?: WorkflowRetryPolicy;
+}
+export interface ScriptStep extends DurableStepOptions {
     id: string;
     kind: 'script';
     setOutput: string;
     call: CoreCall;
 }
-export interface AgentStep {
+export interface AgentStep extends DurableStepOptions {
     id: string;
     kind: 'agent';
     prompt: string;
@@ -42,8 +55,16 @@ export interface IfStep {
     then: WorkflowStep[];
     else?: WorkflowStep[];
 }
-export type WorkflowStep = ScriptStep | AgentStep | ForeachStep | IfStep;
+/** Durable human gate. Execution stops before subsequent steps until an operator approves or rejects it. */
+export interface ApprovalStep {
+    id: string;
+    kind: 'approval';
+    label?: string;
+}
+export type WorkflowStep = ScriptStep | AgentStep | ForeachStep | IfStep | ApprovalStep;
 export interface WorkflowSpec {
+    /** Stable caller-supplied identity. If omitted, the durable runtime derives one from the definition. */
+    workflowId?: string;
     name: string;
     input?: Record<string, unknown>;
     steps: WorkflowStep[];

package/dist/workflow/dsl.js

@@ -3,6 +3,10 @@
  * 表达式表示为**结构化对象**(非字符串解析): 引用 Ref + 白名单 core 调用, 安全 by-construction.
  */
 export function isRef(v) { return typeof v === 'object' && v !== null && 'ref' in v; }
+const WORKFLOW_SENSITIVE_TEXT_RE = /(?:\bBearer\s+[A-Za-z0-9._~+/=-]{8,}|\bsk-[A-Za-z0-9_-]{12,}|\b(?:gh[oprsu]|npm)_[A-Za-z0-9_-]{8,}|\bgithub_pat_[A-Za-z0-9_]{8,}|\b(?:AKIA|ASIA)[0-9A-Z]{16}\b|\bAIza[0-9A-Za-z_-]{35}\b|-----BEGIN [A-Z ]*PRIVATE KEY-----|\b(?:password|passwd|secret|token|api[_-]?key|accountkey)\s*[:=]\s*\S+)/i;
+export function containsWorkflowSensitiveText(value) {
+    return WORKFLOW_SENSITIVE_TEXT_RE.test(value);
+}
 export const CORE_WHITELIST = {
     list_len: (a) => (Array.isArray(a) ? a.length : 0),
     filter_by_mask: (items, mask) => (Array.isArray(items) && Array.isArray(mask) ? items.filter((_, i) => Boolean(mask[i])) : []),

package/dist/workflow/engine.d.ts

@@ -4,8 +4,12 @@ export interface WorkflowContext {
     steps: Record<string, unknown>;
     item?: unknown;
 }
+export interface AgentBridgeOptions {
+    /** Cooperative cancellation for the current durable attempt. */
+    signal?: AbortSignal;
+}
 /** agent step 桥(注入 runtime; 孵化期可注 stub). */
-export type AgentBridge = (prompt: string, ctx: WorkflowContext) => Promise<unknown> | unknown;
+export type AgentBridge = (prompt: string, ctx: WorkflowContext, options?: AgentBridgeOptions) => Promise<unknown> | unknown;
 export interface WorkflowEngineDeps {
     core?: Record<string, CoreFn>;
     agent: AgentBridge;

package/dist/workflow/engine.js

@@ -68,6 +68,9 @@ export class WorkflowEngine {
                 await this.runSteps(branch, ctx);
                 return;
             }
+            case 'approval': {
+                throw new WorkflowError('approval steps require DurableWorkflowRuntime');
+            }
             case 'foreach': {
                 const items = resolveRef(step.over.ref, ctx);
                 if (!Array.isArray(items))

package/dist/workflow/index.d.ts

@@ -1,2 +1,4 @@
 export * from './dsl.js';
-export * from './engine.js';
+export * from './engine.js';
+export * from './stateStore.js';
+export * from './runtime.js';

package/dist/workflow/index.js

@@ -1,2 +1,4 @@
 export * from './dsl.js';
-export * from './engine.js';
+export * from './engine.js';
+export * from './stateStore.js';
+export * from './runtime.js';

package/dist/workflow/runtime.d.ts

@@ -0,0 +1,110 @@
+import { type CoreFn, type WorkflowErrorClass, type WorkflowSpec } from './dsl.js';
+import type { AgentBridge, WorkflowContext } from './engine.js';
+import { WorkflowStateError, WorkflowStateStore, type WorkflowControlState, type WorkflowOperatorOptions, type WorkflowRunState, type WorkflowStateStoreOptions, type WorkflowStepState } from './stateStore.js';
+export declare const MAX_WORKFLOW_DEFINITION_STEPS = 256;
+export declare const MAX_WORKFLOW_NESTING_DEPTH = 16;
+export declare const MAX_WORKFLOW_FOREACH_ITEMS = 1000;
+export interface WorkflowRuntimeDeps {
+    agent: AgentBridge;
+    stateDir?: string;
+    core?: Record<string, CoreFn>;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+    classifyError?: (error: unknown) => WorkflowErrorClass;
+    generateRunId?: () => string;
+    maxConcurrentRuns?: number;
+    maxQueuedRuns?: number;
+    maxStepExecutions?: number;
+    /** Test/embedding seam invoked only after a durable checkpoint has completed. */
+    afterCheckpoint?: (state: Readonly<WorkflowRunState>) => void | Promise<void>;
+    /** Synchronous fault-injection seam invoked under the commit lock; callbacks must not re-enter the store. */
+    onTransactionPhase?: WorkflowStateStoreOptions['onTransactionPhase'];
+    /** Bounded startup-recovery diagnostic; raw errors are never exposed. */
+    onRecoveryFailure?: (failure: WorkflowRecoveryFailure) => void;
+    lock?: {
+        maxTries?: number;
+        waitMs?: number;
+    };
+}
+export interface WorkflowRecoveryFailure {
+    runId: string;
+    code: WorkflowStateError['code'] | 'RUN_FAILED' | 'RECOVERY_FAILED';
+}
+export interface WorkflowRunResult {
+    runId: string;
+    workflowId: string;
+    status: WorkflowRunState['status'];
+    output: unknown;
+    ctx: WorkflowContext;
+}
+export declare class WorkflowRuntimeError extends Error {
+    readonly code: 'SENSITIVE_STATE' | 'INVALID_STATE' | 'UNSUPPORTED_PARALLELISM' | 'RUN_NOT_RESUMABLE' | 'INVALID_RETRY' | 'INVALID_CONCURRENCY' | 'RESOURCE_LIMIT';
+    constructor(message: string, code: 'SENSITIVE_STATE' | 'INVALID_STATE' | 'UNSUPPORTED_PARALLELISM' | 'RUN_NOT_RESUMABLE' | 'INVALID_RETRY' | 'INVALID_CONCURRENCY' | 'RESOURCE_LIMIT');
+}
+export declare class WorkflowRunFailedError extends Error {
+    readonly runId: string;
+    readonly status: 'failed' | 'unsafe_to_resume';
+    readonly errorClass: WorkflowStepState['lastErrorClass'];
+    constructor(runId: string, status: 'failed' | 'unsafe_to_resume', errorClass: WorkflowStepState['lastErrorClass']);
+}
+export declare class ClassifiedWorkflowError extends Error {
+    readonly errorClass: WorkflowErrorClass;
+    constructor(errorClass: WorkflowErrorClass, message?: string);
+}
+export declare function defaultWorkflowStateDir(): string;
+export declare function deriveWorkflowId(spec: WorkflowSpec): string;
+export declare function assertValidWorkflowSpec(value: unknown): asserts value is WorkflowSpec;
+export declare class DurableWorkflowRuntime {
+    private readonly deps;
+    readonly store: WorkflowStateStore;
+    private readonly core;
+    private readonly now;
+    private readonly sleep;
+    private readonly classifyError;
+    private readonly generateRunId;
+    private readonly scheduler;
+    private readonly maxConcurrentRuns;
+    private readonly maxStepExecutions;
+    private readonly inFlight;
+    constructor(deps: WorkflowRuntimeDeps);
+    start(spec: WorkflowSpec, options?: {
+        runId?: string;
+    } | string): Promise<WorkflowRunResult>;
+    resume(runId: string, options?: WorkflowOperatorOptions): Promise<WorkflowRunResult>;
+    operatorResume(runId: string, options: WorkflowOperatorOptions): Promise<WorkflowRunResult>;
+    pause(runId: string, options: WorkflowOperatorOptions): Promise<WorkflowRunResult>;
+    cancel(runId: string, options: WorkflowOperatorOptions): Promise<WorkflowRunResult>;
+    approve(runId: string, gateId: string, options: WorkflowOperatorOptions): Promise<WorkflowRunResult>;
+    reject(runId: string, gateId: string, options: WorkflowOperatorOptions): Promise<WorkflowRunResult>;
+    status(runId: string): WorkflowRunState;
+    history(runId: string): ReturnType<WorkflowStateStore['readHistory']>;
+    recoverPending(): Promise<WorkflowRunResult[]>;
+    protected isRecoveryCandidate(state: WorkflowRunState, control: WorkflowControlState): boolean;
+    protected recoverRuns(shouldRecover: (runId: string) => boolean | Promise<boolean>, reportFailure: (runId: string, error: unknown) => void): Promise<WorkflowRunResult[]>;
+    private scheduleRecoveryRun;
+    private scheduleRun;
+    private resumeLocked;
+    private withLockedRun;
+    private withConcurrencySlot;
+    private validateResumeStateOrFail;
+    private execute;
+    private runSteps;
+    private runStep;
+    private lastStepOutput;
+    private failState;
+    private runApproval;
+    private runLeaf;
+    private runAgentAttempt;
+    private observeCancellation;
+    private checkpointCompletion;
+    private enforceControlBoundary;
+    private finalizeCancellation;
+    private checkpoint;
+    private safetyCheckpoint;
+    private ensureApprovalDecisionHistory;
+    private appendHistoryUnlessUnavailable;
+    private historyEvent;
+    private timestamp;
+    private result;
+    private reportRecoveryFailure;
+}