@evomap/evolver-core 2.0.0-beta.0

package/dist/trigger/budget.d.ts

@@ -0,0 +1,16 @@
+/** 进化预算 (军杰§5.4): 日 cycle/token 上限 + per-pattern 上限. */
+export interface BudgetConfig {
+    maxCyclesPerDay: number;
+    maxTokensPerDay: number;
+    perPatternCap: number;
+}
+export declare class Budget {
+    private readonly cfg;
+    private cycles;
+    private tokens;
+    private readonly perPattern;
+    constructor(cfg: BudgetConfig);
+    available(patternId: string): boolean;
+    consume(patternId: string, tokens?: number): void;
+    reset(): void;
+}

package/dist/trigger/budget.js

@@ -0,0 +1,20 @@
+export class Budget {
+    cfg;
+    cycles = 0;
+    tokens = 0;
+    perPattern = new Map();
+    constructor(cfg) {
+        this.cfg = cfg;
+    }
+    available(patternId) {
+        return this.cycles < this.cfg.maxCyclesPerDay
+            && this.tokens < this.cfg.maxTokensPerDay
+            && (this.perPattern.get(patternId) ?? 0) < this.cfg.perPatternCap;
+    }
+    consume(patternId, tokens = 0) {
+        this.cycles += 1;
+        this.tokens += tokens;
+        this.perPattern.set(patternId, (this.perPattern.get(patternId) ?? 0) + 1);
+    }
+    reset() { this.cycles = 0; this.tokens = 0; this.perPattern.clear(); }
+}

package/dist/trigger/engine.d.ts

@@ -0,0 +1,12 @@
+import type { Ingestor } from '../events/ingest.js';
+import type { ProblemPattern } from '../schema/problem.js';
+import { type TriggerConfig, type TriggerDecision } from './trigger.js';
+import type { Budget } from './budget.js';
+/** 触发引擎: 评估 → 经 ingest 落 decision.* 事件(human.why 必填) → 消费 budget. */
+export declare class TriggerEngine {
+    private readonly ingestor;
+    private readonly cfg;
+    private readonly budget;
+    constructor(ingestor: Ingestor, cfg: TriggerConfig, budget: Budget);
+    evaluate(p: ProblemPattern, now: number): Promise<TriggerDecision>;
+}

package/dist/trigger/engine.js

@@ -0,0 +1,23 @@
+import { evaluateTrigger } from './trigger.js';
+/** 触发引擎: 评估 → 经 ingest 落 decision.* 事件(human.why 必填) → 消费 budget. */
+export class TriggerEngine {
+    ingestor;
+    cfg;
+    budget;
+    constructor(ingestor, cfg, budget) {
+        this.ingestor = ingestor;
+        this.cfg = cfg;
+        this.budget = budget;
+    }
+    async evaluate(p, now) {
+        const d = evaluateTrigger(p, this.cfg, this.budget, now);
+        await this.ingestor.ingest({
+            type: d.trigger ? 'decision.triggered' : 'decision.suppressed',
+            human: { title: `${d.trigger ? '触发' : '抑制'} ${p.id}`, why: d.reasons.join('; ') },
+            payload: { patternId: p.id, value: d.value.score, factors: d.value.factors, threshold: d.thresholdUsed, reasons: d.reasons },
+        });
+        if (d.trigger)
+            this.budget.consume(p.id);
+        return d;
+    }
+}

package/dist/trigger/index.d.ts

@@ -0,0 +1,6 @@
+export * from './valueModel.js';
+export * from './budget.js';
+export * from './trigger.js';
+export * from './wfq.js';
+export * from './engine.js';
+export * from './problemBuilder.js';

package/dist/trigger/index.js

@@ -0,0 +1,6 @@
+export * from './valueModel.js';
+export * from './budget.js';
+export * from './trigger.js';
+export * from './wfq.js';
+export * from './engine.js';
+export * from './problemBuilder.js';

package/dist/trigger/problemBuilder.d.ts

@@ -0,0 +1,24 @@
+import type { ProblemPattern } from '../schema/problem.js';
+export interface ProblemPatternInput {
+    problemKind: string;
+    failureMode?: string;
+    domainTags?: readonly string[];
+    affectedSurface?: string;
+    occurrences: number;
+    firstSeenAt: string;
+    lastSeenAt: string;
+    linkedSignals?: readonly string[];
+    /** 0..1 severity hint (caller maps its failure-mode taxonomy → a number). Default 0.5. */
+    severity?: number;
+    /** Override the classified heuristic; default: true unless kind is 'general' or failureMode is 'unknown'. */
+    classified?: boolean;
+    /** Override the derived id/signature. */
+    id?: string;
+    signature?: string;
+}
+/**
+ * Assemble a triggerable ProblemPattern. The value factors come from {@link deriveValueFactors} so a vague
+ * high-volume catch-all cannot out-trigger a specific, actionable problem by sheer volume (observation tuning,
+ * #53). `classified` is auto-detected from the kind/failureMode being specific.
+ */
+export declare function buildProblemPattern(input: ProblemPatternInput): ProblemPattern;

package/dist/trigger/problemBuilder.js

@@ -0,0 +1,32 @@
+import { problemSignature, SIGNATURE_V } from '../signatures/signatures.js';
+import { deriveValueFactors } from './valueModel.js';
+/**
+ * Assemble a triggerable ProblemPattern. The value factors come from {@link deriveValueFactors} so a vague
+ * high-volume catch-all cannot out-trigger a specific, actionable problem by sheer volume (observation tuning,
+ * #53). `classified` is auto-detected from the kind/failureMode being specific.
+ */
+export function buildProblemPattern(input) {
+    const sigInput = {
+        problemKind: input.problemKind,
+        ...(input.domainTags ? { domainTags: input.domainTags } : {}),
+        ...(input.affectedSurface ? { affectedSurface: input.affectedSurface } : {}),
+        ...(input.failureMode ? { failureMode: input.failureMode } : {}),
+    };
+    const signature = input.signature ?? problemSignature(sigInput);
+    const classified = input.classified ?? (input.problemKind !== 'general' && (input.failureMode ?? 'unknown') !== 'unknown');
+    return {
+        id: input.id ?? signature,
+        signature,
+        signatureV: SIGNATURE_V,
+        firstSeenAt: input.firstSeenAt,
+        lastSeenAt: input.lastSeenAt,
+        occurrences: input.occurrences,
+        linkedSignals: [...(input.linkedSignals ?? [])],
+        resolvedBy: null,
+        status: 'open',
+        value: deriveValueFactors({ occurrences: input.occurrences, classified, ...(input.severity !== undefined ? { severity: input.severity } : {}) }),
+        consecutiveFailures: 0,
+        cooldownUntil: null,
+        extensions: {},
+    };
+}

package/dist/trigger/trigger.d.ts

@@ -0,0 +1,22 @@
+import type { ProblemPattern } from '../schema/problem.js';
+import { type ValueResult } from './valueModel.js';
+import type { Budget } from './budget.js';
+export interface PersistenceConfig {
+    minOccurrences: number;
+    minOpenDurationMs: number;
+}
+export interface TriggerConfig {
+    persistence: PersistenceConfig;
+    valueThreshold: number;
+    dynamicThreshold?: () => number;
+}
+export interface TriggerDecision {
+    trigger: boolean;
+    patternId: string;
+    value: ValueResult;
+    thresholdUsed: number;
+    reasons: string[];
+}
+export declare function persistenceOk(p: ProblemPattern, cfg: PersistenceConfig, now: number): boolean;
+/** 触发判定 = persistence ∧ value ∧ budget (军杰§5.5). */
+export declare function evaluateTrigger(p: ProblemPattern, cfg: TriggerConfig, budget: Budget, now: number): TriggerDecision;

package/dist/trigger/trigger.js

@@ -0,0 +1,27 @@
+import { computeValue } from './valueModel.js';
+export function persistenceOk(p, cfg, now) {
+    const openDuration = now - Date.parse(p.firstSeenAt);
+    return p.status === 'open'
+        && p.occurrences >= cfg.minOccurrences
+        && openDuration >= cfg.minOpenDurationMs
+        && (p.cooldownUntil === null || Date.parse(p.cooldownUntil) < now);
+}
+/** 触发判定 = persistence ∧ value ∧ budget (军杰§5.5). */
+export function evaluateTrigger(p, cfg, budget, now) {
+    const value = computeValue(p.value);
+    const threshold = cfg.dynamicThreshold ? cfg.dynamicThreshold() : cfg.valueThreshold;
+    const reasons = [];
+    const persist = persistenceOk(p, cfg.persistence, now);
+    if (!persist)
+        reasons.push(`persistence 未达(occ=${p.occurrences}/${cfg.persistence.minOccurrences}, status=${p.status})`);
+    const valueOk = value.score >= threshold;
+    if (!valueOk)
+        reasons.push(`value ${value.score.toFixed(3)} < 阈值 ${threshold}`);
+    const budgetOk = budget.available(p.id);
+    if (!budgetOk)
+        reasons.push('budget 耗尽');
+    const trigger = persist && valueOk && budgetOk;
+    if (trigger)
+        reasons.push(`触发: value=${value.score.toFixed(3)}≥${threshold}, persistence ok, budget ok`);
+    return { trigger, patternId: p.id, value, thresholdUsed: threshold, reasons };
+}

package/dist/trigger/valueModel.d.ts

@@ -0,0 +1,26 @@
+import type { ValueFactors } from '../schema/problem.js';
+export interface ValueResult {
+    score: number;
+    factors: ValueFactors;
+}
+/** value = severity × reach × strategicFit × (1+novelty)/(1+costEst). 命名因子, 禁黑盒 (军杰§5.3). */
+export declare function computeValue(f: ValueFactors): ValueResult;
+/** Observation stats for one problem pattern, used to derive its value factors. */
+export interface ProblemValueStats {
+    occurrences: number;
+    /** false for vague catch-all buckets (e.g. 'general'/'unknown') — they should NOT out-rank specific problems by sheer volume. */
+    classified?: boolean;
+    /** 0..1 hint from the failure-mode severity (caller maps its taxonomy → a number); default 0.5. */
+    severity?: number;
+    novelty?: number;
+    costEst?: number;
+}
+/** occurrences that earn full reach — a FIXED scale, deliberately NOT normalized to the biggest bucket. */
+export declare const REACH_FULL_AT = 30;
+/**
+ * Derive value factors from a problem's observation stats — the tuning learned from observing real agent logs
+ * (evolver-v2-observation): a vague high-volume catch-all should not out-trigger specific, actionable problems.
+ * So `reach` is on a FIXED occurrence scale (not normalized to the largest bucket, which crushes everything
+ * specific), and `strategicFit` is reduced for unclassified problems. Feed the result to {@link computeValue}.
+ */
+export declare function deriveValueFactors(stats: ProblemValueStats): ValueFactors;

package/dist/trigger/valueModel.js

@@ -0,0 +1,25 @@
+/** value = severity × reach × strategicFit × (1+novelty)/(1+costEst). 命名因子, 禁黑盒 (军杰§5.3). */
+export function computeValue(f) {
+    const score = (f.severity * f.reach * f.strategicFit * (1 + f.novelty)) / (1 + f.costEst);
+    return { score, factors: { ...f } };
+}
+/** occurrences that earn full reach — a FIXED scale, deliberately NOT normalized to the biggest bucket. */
+export const REACH_FULL_AT = 30;
+const UNCLASSIFIED_FIT = 0.35;
+const CLASSIFIED_FIT = 0.9;
+const clamp01 = (n) => Math.max(0, Math.min(1, n));
+/**
+ * Derive value factors from a problem's observation stats — the tuning learned from observing real agent logs
+ * (evolver-v2-observation): a vague high-volume catch-all should not out-trigger specific, actionable problems.
+ * So `reach` is on a FIXED occurrence scale (not normalized to the largest bucket, which crushes everything
+ * specific), and `strategicFit` is reduced for unclassified problems. Feed the result to {@link computeValue}.
+ */
+export function deriveValueFactors(stats) {
+    return {
+        severity: clamp01(stats.severity ?? 0.5),
+        reach: clamp01(Math.max(0, stats.occurrences) / REACH_FULL_AT),
+        strategicFit: stats.classified === false ? UNCLASSIFIED_FIT : CLASSIFIED_FIT,
+        novelty: stats.novelty ?? 0,
+        costEst: stats.costEst ?? 0.2,
+    };
+}

package/dist/trigger/wfq.d.ts

@@ -0,0 +1,13 @@
+export interface WfqItem {
+    id: string;
+    weight: number;
+    enqueuedAt: number;
+}
+/** 加权公平队列骨架 (军杰§7): 防单一高频霸占, age_boost 防饿死. */
+export declare class WeightedFairQueue {
+    private items;
+    enqueue(item: WfqItem): void;
+    size(): number;
+    /** pick = argmax(weight + age_boost); age_boost = min(log2(1+waitMin), 4). */
+    pick(now: number): WfqItem | undefined;
+}

package/dist/trigger/wfq.js

@@ -0,0 +1,25 @@
+/** 加权公平队列骨架 (军杰§7): 防单一高频霸占, age_boost 防饿死. */
+export class WeightedFairQueue {
+    items = [];
+    enqueue(item) { if (!this.items.some((i) => i.id === item.id))
+        this.items.push(item); }
+    size() { return this.items.length; }
+    /** pick = argmax(weight + age_boost); age_boost = min(log2(1+waitMin), 4). */
+    pick(now) {
+        let best;
+        let bestScore = -Infinity;
+        for (const it of this.items) {
+            const waitMin = (now - it.enqueuedAt) / 60000;
+            const score = it.weight + Math.min(Math.log2(1 + Math.max(0, waitMin)), 4);
+            if (score > bestScore) {
+                bestScore = score;
+                best = it;
+            }
+        }
+        if (best) {
+            const id = best.id;
+            this.items = this.items.filter((i) => i.id !== id);
+        }
+        return best;
+    }
+}

package/dist/util/fileLock.d.ts

@@ -0,0 +1,24 @@
+export declare function syncSleep(ms: number): void;
+export declare class LockTimeoutError extends Error {
+    readonly code = "LOCK_TIMEOUT";
+    constructor(lockPath: string);
+}
+export interface AcquireLockOptions {
+    maxTries?: number;
+    waitMs?: number;
+}
+/**
+ * Cross-process O_EXCL file lock with crashed-owner recovery.
+ *
+ * The lock file records the owner pid and token. If a waiter finds the lock held by a pid that is no longer
+ * alive (the owner crashed without releaseLock), it reclaims the stale lock instead of spinning
+ * until timeout — otherwise one crashed process would deadlock every future writer until the file
+ * is removed by hand. Acquisition stays atomic (O_EXCL), and stale reclaim moves the old lock aside
+ * under a mutation guard before deletion so waiters cannot delete each other's newly-created locks.
+ * A live owner's lock (including this process's own) is never stolen.
+ *
+ * NOTE: still synchronous (blocks the event loop while waiting) by design — it guards short
+ * synchronous critical sections (append-only writes).
+ */
+export declare function acquireLock(lockPath: string, opts?: AcquireLockOptions): void;
+export declare function releaseLock(lockPath: string): void;

package/dist/util/fileLock.js

@@ -0,0 +1,227 @@
+import { randomUUID } from 'node:crypto';
+import { readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+export function syncSleep(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+const ownedLocks = new Map();
+export class LockTimeoutError extends Error {
+    code = 'LOCK_TIMEOUT';
+    constructor(lockPath) {
+        super(`获取文件锁超时: ${lockPath}`);
+        this.name = 'LockTimeoutError';
+    }
+}
+function lockKey(lockPath) {
+    return resolve(lockPath);
+}
+function newOwner() {
+    return { pid: process.pid, token: randomUUID() };
+}
+function serializeOwner(owner) {
+    return `${JSON.stringify({ v: 1, pid: owner.pid, token: owner.token })}\n`;
+}
+function isErrno(error, code) {
+    return typeof error === 'object' && error !== null && error.code === code;
+}
+/** True if pid is a live process (cross-platform via signal 0; EPERM = exists but owned by another user). */
+function pidAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code === 'EPERM';
+    }
+}
+function parseJsonOwner(raw) {
+    try {
+        const value = JSON.parse(raw);
+        if (typeof value !== 'object' || value === null)
+            return null;
+        const record = value;
+        if (typeof record.pid !== 'number'
+            || !Number.isInteger(record.pid)
+            || record.pid <= 0
+            || typeof record.token !== 'string'
+            || record.token.length === 0) {
+            return null;
+        }
+        return { pid: record.pid, token: record.token };
+    }
+    catch (error) {
+        if (error instanceof SyntaxError)
+            return null;
+        throw error;
+    }
+}
+function parseLegacyOwner(raw) {
+    const first = raw.trim().split(/\s+/, 1)[0];
+    if (first === undefined)
+        return null;
+    const pid = Number(first);
+    return Number.isInteger(pid) && pid > 0 ? { pid, token: null } : null;
+}
+function parseOwner(raw) {
+    const trimmed = raw.trim();
+    if (trimmed.length === 0)
+        return null;
+    return parseJsonOwner(trimmed) ?? parseLegacyOwner(trimmed);
+}
+/** Owner recorded in the lock file; null if missing/unparseable. */
+function lockOwner(lockPath) {
+    try {
+        return parseOwner(readFileSync(lockPath, 'utf8'));
+    }
+    catch (error) {
+        if (isErrno(error, 'ENOENT'))
+            return null;
+        throw error;
+    }
+}
+function sameOwner(parsed, owner) {
+    return parsed?.pid === owner.pid && parsed.token === owner.token;
+}
+function sidecarPath(lockPath, kind) {
+    return join(dirname(lockPath), `.${basename(lockPath)}.${kind}.${process.pid}.${randomUUID()}`);
+}
+function mutationGuardPath(lockPath) {
+    return join(dirname(lockPath), `.${basename(lockPath)}.mutation`);
+}
+function removeFileIfExists(path) {
+    try {
+        unlinkSync(path);
+    }
+    catch (error) {
+        if (!isErrno(error, 'ENOENT'))
+            throw error;
+    }
+}
+function createLockFile(lockPath, owner, trackOwnership) {
+    try {
+        writeFileSync(lockPath, serializeOwner(owner), { flag: 'wx', mode: 0o600 });
+        if (trackOwnership)
+            ownedLocks.set(lockKey(lockPath), owner);
+        return true;
+    }
+    catch (error) {
+        if (isErrno(error, 'EEXIST'))
+            return false;
+        throw error;
+    }
+}
+function tryAcquireMutationGuard(lockPath) {
+    const guardPath = mutationGuardPath(lockPath);
+    const guard = newOwner();
+    if (createLockFile(guardPath, guard, false))
+        return guard;
+    const owner = lockOwner(guardPath);
+    if (owner === null || owner.pid === process.pid || pidAlive(owner.pid))
+        return null;
+    const stalePath = sidecarPath(guardPath, 'stale');
+    try {
+        renameSync(guardPath, stalePath);
+    }
+    catch (error) {
+        if (isErrno(error, 'ENOENT'))
+            return null;
+        throw error;
+    }
+    removeFileIfExists(stalePath);
+    return createLockFile(guardPath, guard, false) ? guard : null;
+}
+function releaseMutationGuard(lockPath, guard) {
+    const guardPath = mutationGuardPath(lockPath);
+    if (!sameOwner(lockOwner(guardPath), guard))
+        return;
+    const releasedPath = sidecarPath(guardPath, 'released');
+    try {
+        renameSync(guardPath, releasedPath);
+    }
+    catch (error) {
+        if (isErrno(error, 'ENOENT'))
+            return;
+        throw error;
+    }
+    removeFileIfExists(releasedPath);
+}
+function reclaimStaleLock(lockPath) {
+    const guard = tryAcquireMutationGuard(lockPath);
+    if (guard === null)
+        return false;
+    try {
+        const owner = lockOwner(lockPath);
+        if (owner === null || owner.pid === process.pid || pidAlive(owner.pid))
+            return false;
+        const stalePath = sidecarPath(lockPath, 'stale');
+        try {
+            renameSync(lockPath, stalePath);
+        }
+        catch (error) {
+            if (isErrno(error, 'ENOENT'))
+                return false;
+            throw error;
+        }
+        removeFileIfExists(stalePath);
+        return true;
+    }
+    finally {
+        releaseMutationGuard(lockPath, guard);
+    }
+}
+/**
+ * Cross-process O_EXCL file lock with crashed-owner recovery.
+ *
+ * The lock file records the owner pid and token. If a waiter finds the lock held by a pid that is no longer
+ * alive (the owner crashed without releaseLock), it reclaims the stale lock instead of spinning
+ * until timeout — otherwise one crashed process would deadlock every future writer until the file
+ * is removed by hand. Acquisition stays atomic (O_EXCL), and stale reclaim moves the old lock aside
+ * under a mutation guard before deletion so waiters cannot delete each other's newly-created locks.
+ * A live owner's lock (including this process's own) is never stolen.
+ *
+ * NOTE: still synchronous (blocks the event loop while waiting) by design — it guards short
+ * synchronous critical sections (append-only writes).
+ */
+export function acquireLock(lockPath, opts = {}) {
+    const maxTries = opts.maxTries ?? 300;
+    const waitMs = opts.waitMs ?? 10;
+    for (let i = 0; i < maxTries; i++) {
+        const owner = newOwner();
+        if (createLockFile(lockPath, owner, true)) {
+            return;
+        }
+        const current = lockOwner(lockPath);
+        if (current !== null && current.pid !== process.pid && !pidAlive(current.pid)) {
+            if (!reclaimStaleLock(lockPath))
+                syncSleep(waitMs);
+            continue;
+        }
+        syncSleep(waitMs);
+    }
+    throw new LockTimeoutError(lockPath);
+}
+export function releaseLock(lockPath) {
+    const key = lockKey(lockPath);
+    const owner = ownedLocks.get(key);
+    if (owner === undefined)
+        return;
+    try {
+        if (!sameOwner(lockOwner(lockPath), owner))
+            return;
+        const releasedPath = sidecarPath(lockPath, 'released');
+        try {
+            renameSync(lockPath, releasedPath);
+        }
+        catch (error) {
+            if (isErrno(error, 'ENOENT'))
+                return;
+            throw error;
+        }
+        removeFileIfExists(releasedPath);
+    }
+    finally {
+        ownedLocks.delete(key);
+    }
+}

package/dist/util/index.d.ts

@@ -0,0 +1,2 @@
+export * from './fileLock.js';
+export * from './version.js';

package/dist/util/index.js

@@ -0,0 +1,2 @@
+export * from './fileLock.js';
+export * from './version.js';

package/dist/util/version.d.ts

@@ -0,0 +1,12 @@
+export interface PackageMetadata {
+    readonly name?: string;
+    readonly version?: string;
+    readonly bin?: string | Record<string, string>;
+}
+export interface ResolveRuntimeVersionOptions {
+    readonly startDir: string;
+    readonly isPackage: (pkg: PackageMetadata) => boolean;
+    readonly fallback?: string;
+    readonly execGit?: (args: readonly string[], cwd: string) => string;
+}
+export declare function resolveRuntimeVersion(opts: ResolveRuntimeVersionOptions): string;

package/dist/util/version.js

@@ -0,0 +1,51 @@
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+const PLACEHOLDER_VERSIONS = new Set(['', '0.0.0']);
+const GIT_SHA_RE = /^[0-9a-f]{7,40}$/i;
+export function resolveRuntimeVersion(opts) {
+    const fallback = opts.fallback ?? '0.0.0';
+    const found = findRuntimePackage(opts.startDir, opts.isPackage);
+    const packageVersion = found?.pkg.version?.trim() ?? '';
+    if (!PLACEHOLDER_VERSIONS.has(packageVersion))
+        return packageVersion;
+    const gitVersion = resolveGitVersion(found?.dir ?? opts.startDir, opts.execGit);
+    return gitVersion ?? fallback;
+}
+function findRuntimePackage(startDir, isPackage) {
+    let dir = startDir;
+    for (let i = 0; i < 8; i += 1) {
+        try {
+            const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
+            if (isPackage(pkg))
+                return { dir, pkg };
+        }
+        catch {
+            // Source and built layouts put package.json at different depths.
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
+function resolveGitVersion(startDir, execGit = defaultExecGit) {
+    const sha = safeGit(['rev-parse', '--short=12', 'HEAD'], startDir, execGit);
+    if (!sha || !GIT_SHA_RE.test(sha))
+        return null;
+    const dirty = safeGit(['status', '--porcelain'], startDir, execGit);
+    return `0.0.0+git.${sha.toLowerCase()}${dirty ? '.dirty' : ''}`;
+}
+function safeGit(args, cwd, execGit) {
+    try {
+        const out = execGit(args, cwd).trim();
+        return out.length > 0 ? out : null;
+    }
+    catch {
+        return null;
+    }
+}
+function defaultExecGit(args, cwd) {
+    return execFileSync('git', [...args], { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+}

package/dist/verify/index.d.ts

@@ -0,0 +1,4 @@
+export * from './validation.js';
+export * from './rollback.js';
+export * from './sandboxRunner.js';
+export * from './sandboxedValidation.js';

package/dist/verify/index.js

@@ -0,0 +1,4 @@
+export * from './validation.js';
+export * from './rollback.js';
+export * from './sandboxRunner.js';
+export * from './sandboxedValidation.js';

package/dist/verify/rollback.d.ts

@@ -0,0 +1,22 @@
+export interface RollbackConfig {
+    ownedRoots: readonly string[];
+    optIn: boolean;
+}
+export interface RollbackTarget {
+    path: string;
+    tracked: boolean;
+}
+export interface RollbackPlan {
+    willRollback: RollbackTarget[];
+    skipped: Array<{
+        target: RollbackTarget;
+        reason: string;
+    }>;
+}
+/**
+ * 规划回滚(M4A-4, 批注#20). 三条铁律, 全部满足才回滚:
+ * - opt-in: optIn=false 时一律不回滚.
+ * - 只动 evolver-owned: 路径必须在 ownedRoots 之内(绝不 reset 主仓 working tree / 仓外文件).
+ * - 不删 untracked: 未跟踪文件不回滚(避免破坏用户未提交工作).
+ */
+export declare function planRollback(targets: readonly RollbackTarget[], cfg: RollbackConfig): RollbackPlan;