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

package/dist/strategy/index.d.ts

@@ -1,2 +1,3 @@
 export * from './strategyPoint.js';
-export * from './experiment.js';
+export * from './experiment.js';
+export * from './constraintAblation.js';

package/dist/strategy/index.js

@@ -1,2 +1,3 @@
 export * from './strategyPoint.js';
-export * from './experiment.js';
+export * from './experiment.js';
+export * from './constraintAblation.js';

package/dist/trace/trajectoryExport.js

@@ -1558,7 +1558,7 @@ function runtimeSessionId(input) {
         return explicit;
     const sourcePath = stringValue(input.sourcePath);
     const base = sourcePath.split(/[\\/]/).filter(Boolean).pop() ?? '';
-    return base.replace(/\.jsonl?$/i, '') || 'unknown';
+    return redactString(base.replace(/\.jsonl?$/i, '')) || 'unknown';
 }
 function nativeCallHasField(call, key) {
     return Object.prototype.hasOwnProperty.call(call, key);
@@ -1704,7 +1704,7 @@ export function buildCodingTrajectoryFromSessionLog(input) {
         session_id: sessionId,
         source_kind: 'runtime_session',
         source_agent: sourceAgent,
-        source_path: sourcePath,
+        source_path: redactString(sourcePath),
         ...(sessionModel ? { session_model: sessionModel } : {}),
         ...(provider !== sourceAgent ? { session_provider: provider } : {}),
         ...(sessionTools !== undefined ? { session_tools: redactRuntimeStructuredValue(sessionTools) } : {}),

package/dist/util/fetchPort.d.ts

@@ -0,0 +1 @@
+export declare function isFetchForbiddenPort(port: number): boolean;

package/dist/util/fetchPort.js

@@ -0,0 +1,11 @@
+// https://fetch.spec.whatwg.org/#port-blocking
+const FETCH_FORBIDDEN_PORTS = new Set([
+    1, 7, 9, 11, 13, 15, 17, 19, 20, 21, 22, 23, 25, 37, 42, 43, 53, 69, 77, 79, 87, 95,
+    101, 102, 103, 104, 109, 110, 111, 113, 115, 117, 119, 123, 135, 137, 139, 143, 161, 179,
+    389, 427, 465, 512, 513, 514, 515, 526, 530, 531, 532, 540, 548, 554, 556, 563, 587, 601,
+    636, 989, 990, 993, 995, 1719, 1720, 1723, 2049, 3659, 4045, 4190, 5060, 5061, 6000,
+    6566, 6665, 6666, 6667, 6668, 6669, 6679, 6697, 10080,
+]);
+export function isFetchForbiddenPort(port) {
+    return Number.isInteger(port) && FETCH_FORBIDDEN_PORTS.has(port);
+}

package/dist/util/fileLock.d.ts

@@ -1,8 +1,15 @@
 export declare function syncSleep(ms: number): void;
 export declare class LockTimeoutError extends Error {
     readonly code = "LOCK_TIMEOUT";
-    constructor(lockPath: string);
+    constructor(_lockPath?: string);
 }
+export type UnsafeLockPathReason = 'symlink' | 'not_regular_file' | 'owner_too_large' | 'path_changed' | 'permission_denied' | 'invalid_owner';
+export declare class UnsafeLockPathError extends Error {
+    readonly reason: UnsafeLockPathReason;
+    readonly code = "UNSAFE_LOCK_PATH";
+    constructor(reason: UnsafeLockPathReason);
+}
+export declare const MAX_LOCK_OWNER_BYTES = 4096;
 export interface AcquireLockOptions {
     maxTries?: number;
     waitMs?: number;
@@ -13,12 +20,24 @@ export interface AcquireLockOptions {
  * 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.
+ * is removed by hand. Empty or truncated locks are reclaimed only after the same inode and contents
+ * remain malformed for a grace period, so a live creator can finish publishing its owner payload.
+ * Acquisition stays atomic (O_EXCL), and stale reclaim moves the old lock aside under a mutation
+ * guard, then verifies the inode snapshot before deletion. 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;
+export type ReleaseLockReason = 'released' | 'missing' | 'ownership_changed' | 'not_owned' | 'released_with_cleanup_error' | UnsafeLockPathReason | 'release_failed';
+export interface ReleaseLockResult {
+    released: boolean;
+    reason: ReleaseLockReason;
+}
+export declare function releaseLock(lockPath: string): ReleaseLockResult;
+export declare class LockReleaseError extends Error {
+    readonly reason: ReleaseLockReason;
+    readonly code = "LOCK_RELEASE_FAILED";
+    constructor(reason: ReleaseLockReason);
+}

package/dist/util/fileLock.js

@@ -1,17 +1,29 @@
 import { randomUUID } from 'node:crypto';
-import { readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { closeSync, constants, existsSync, fstatSync, linkSync, lstatSync, openSync, readSync, 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 MALFORMED_LOCK_GRACE_NS = 1000000000n;
 const ownedLocks = new Map();
+const malformedLockObservations = new Map();
 export class LockTimeoutError extends Error {
     code = 'LOCK_TIMEOUT';
-    constructor(lockPath) {
-        super(`获取文件锁超时: ${lockPath}`);
+    constructor(_lockPath) {
+        super('获取文件锁超时');
         this.name = 'LockTimeoutError';
     }
 }
+export class UnsafeLockPathError extends Error {
+    reason;
+    code = 'UNSAFE_LOCK_PATH';
+    constructor(reason) {
+        super(`不安全的文件锁路径: ${reason}`);
+        this.reason = reason;
+        this.name = 'UnsafeLockPathError';
+    }
+}
+export const MAX_LOCK_OWNER_BYTES = 4096;
 function lockKey(lockPath) {
     return resolve(lockPath);
 }
@@ -24,6 +36,86 @@ function serializeOwner(owner) {
 function isErrno(error, code) {
     return typeof error === 'object' && error !== null && error.code === code;
 }
+function noFollowFlag() {
+    return constants['O_NOFOLLOW'] ?? 0;
+}
+function assertRegularOwnerStat(stat) {
+    if (stat.isSymbolicLink())
+        throw new UnsafeLockPathError('symlink');
+    if (!stat.isFile())
+        throw new UnsafeLockPathError('not_regular_file');
+    if (stat.size > BigInt(MAX_LOCK_OWNER_BYTES))
+        throw new UnsafeLockPathError('owner_too_large');
+}
+function currentOwnerStat(path) {
+    try {
+        const stat = lstatSync(path, { bigint: true });
+        assertRegularOwnerStat(stat);
+        return stat;
+    }
+    catch (error) {
+        if (isErrno(error, 'ENOENT'))
+            return null;
+        if (isErrno(error, 'EACCES') || isErrno(error, 'EPERM')) {
+            throw new UnsafeLockPathError('permission_denied');
+        }
+        throw error;
+    }
+}
+function readOwnerFileBounded(path) {
+    const before = currentOwnerStat(path);
+    if (before === null)
+        return null;
+    let fd;
+    try {
+        fd = openSync(path, constants.O_RDONLY | noFollowFlag());
+    }
+    catch (error) {
+        if (isErrno(error, 'ENOENT'))
+            return null;
+        if (isErrno(error, 'ELOOP'))
+            throw new UnsafeLockPathError('symlink');
+        if (isErrno(error, 'EACCES') || isErrno(error, 'EPERM')) {
+            throw new UnsafeLockPathError('permission_denied');
+        }
+        throw error;
+    }
+    try {
+        const opened = fstatSync(fd, { bigint: true });
+        assertRegularOwnerStat(opened);
+        const current = currentOwnerStat(path);
+        if (current === null || current.dev !== opened.dev || current.ino !== opened.ino) {
+            throw new UnsafeLockPathError('path_changed');
+        }
+        const buffer = Buffer.alloc(MAX_LOCK_OWNER_BYTES + 1);
+        let total = 0;
+        while (total < buffer.length) {
+            const read = readSync(fd, buffer, total, buffer.length - total, total);
+            if (read === 0)
+                break;
+            total += read;
+        }
+        if (total > MAX_LOCK_OWNER_BYTES)
+            throw new UnsafeLockPathError('owner_too_large');
+        const settled = fstatSync(fd, { bigint: true });
+        assertRegularOwnerStat(settled);
+        const settledPath = currentOwnerStat(path);
+        if (settledPath === null
+            || settledPath.dev !== settled.dev
+            || settledPath.ino !== settled.ino
+            || settledPath.size !== settled.size
+            || settledPath.mtimeNs !== settled.mtimeNs) {
+            throw new UnsafeLockPathError('path_changed');
+        }
+        return { raw: buffer.subarray(0, total).toString('utf8'), stat: settled };
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function readOwnerBounded(path) {
+    return readOwnerFileBounded(path)?.raw ?? null;
+}
 /** 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)
@@ -70,17 +162,53 @@ function parseOwner(raw) {
         return null;
     return parseJsonOwner(trimmed) ?? parseLegacyOwner(trimmed);
 }
-/** Owner recorded in the lock file; null if missing/unparseable. */
-function lockOwner(lockPath) {
+/** Snapshot of the lock inode and its owner payload; null if the path disappeared. */
+function lockSnapshot(lockPath) {
     try {
-        return parseOwner(readFileSync(lockPath, 'utf8'));
+        const read = readOwnerFileBounded(lockPath);
+        if (read === null)
+            return null;
+        return {
+            owner: parseOwner(read.raw),
+            dev: read.stat.dev,
+            ino: read.stat.ino,
+            size: read.stat.size,
+            mtimeNs: read.stat.mtimeNs,
+        };
     }
     catch (error) {
-        if (isErrno(error, 'ENOENT'))
+        // A valid owner can release and another waiter can acquire between lstat/open/fstat. Treat that snapshot as
+        // transiently unavailable: callers remain conservative (no steal/delete) and the acquire loop retries.
+        if (error instanceof UnsafeLockPathError && error.reason === 'path_changed')
             return null;
         throw error;
     }
 }
+function sameInode(left, right) {
+    return left !== null && right !== null && left.dev === right.dev && left.ino === right.ino;
+}
+function sameSnapshot(left, right) {
+    return sameInode(left, right)
+        && left?.size === right?.size
+        && left?.mtimeNs === right?.mtimeNs;
+}
+function forgetMalformedObservation(lockPath) {
+    malformedLockObservations.delete(lockKey(lockPath));
+}
+function reclaimableSnapshot(lockPath, snapshot) {
+    if (snapshot.owner !== null) {
+        forgetMalformedObservation(lockPath);
+        return snapshot.owner.pid !== process.pid && !pidAlive(snapshot.owner.pid);
+    }
+    const key = lockKey(lockPath);
+    const now = process.hrtime.bigint();
+    const observed = malformedLockObservations.get(key);
+    if (observed === undefined || !sameSnapshot(observed.snapshot, snapshot)) {
+        malformedLockObservations.set(key, { snapshot, firstSeenAtNs: now });
+        return false;
+    }
+    return now - observed.firstSeenAtNs >= MALFORMED_LOCK_GRACE_NS;
+}
 function sameOwner(parsed, owner) {
     return parsed?.pid === owner.pid && parsed.token === owner.token;
 }
@@ -99,73 +227,112 @@ function removeFileIfExists(path) {
             throw error;
     }
 }
-function createLockFile(lockPath, owner, trackOwnership) {
+function pathExists(path) {
+    return existsSync(path);
+}
+function restoreMovedFile(lockPath, movedPath, moved) {
     try {
-        writeFileSync(lockPath, serializeOwner(owner), { flag: 'wx', mode: 0o600 });
-        if (trackOwnership)
-            ownedLocks.set(lockKey(lockPath), owner);
-        return true;
+        linkSync(movedPath, lockPath);
+        removeFileIfExists(movedPath);
+        forgetMalformedObservation(lockPath);
+        return;
     }
     catch (error) {
-        if (isErrno(error, 'EEXIST'))
+        if (!isErrno(error, 'EEXIST'))
+            throw error;
+    }
+    const current = lockSnapshot(lockPath);
+    if (sameInode(current, moved)) {
+        removeFileIfExists(movedPath);
+        forgetMalformedObservation(lockPath);
+        return;
+    }
+    throw new Error(`文件锁在安全回收期间被替换，已保留候选文件: ${movedPath}`);
+}
+function removeUnchangedLock(lockPath, expected, kind) {
+    const movedPath = sidecarPath(lockPath, kind);
+    try {
+        renameSync(lockPath, movedPath);
+    }
+    catch (error) {
+        if (isErrno(error, 'ENOENT'))
             return false;
         throw error;
     }
+    const moved = lockSnapshot(movedPath);
+    if (!sameSnapshot(moved, expected)) {
+        if (moved !== null)
+            restoreMovedFile(lockPath, movedPath, moved);
+        return false;
+    }
+    removeFileIfExists(movedPath);
+    forgetMalformedObservation(lockPath);
+    return true;
+}
+function removeFileIfOwned(lockPath, owner) {
+    const snapshot = lockSnapshot(lockPath);
+    if (snapshot === null || !sameOwner(snapshot.owner, owner))
+        return false;
+    return removeUnchangedLock(lockPath, snapshot, 'released');
+}
+function createLockFile(lockPath, owner, trackOwnership) {
+    const guardPath = mutationGuardPath(lockPath);
+    if (trackOwnership && pathExists(guardPath))
+        return false;
+    for (let permissionAttempt = 0; permissionAttempt < 2; permissionAttempt++) {
+        try {
+            writeFileSync(lockPath, serializeOwner(owner), { flag: 'wx', mode: 0o600 });
+            if (trackOwnership && pathExists(guardPath)) {
+                removeFileIfOwned(lockPath, owner);
+                return false;
+            }
+            if (trackOwnership)
+                ownedLocks.set(lockKey(lockPath), { owner, releasePending: false });
+            forgetMalformedObservation(lockPath);
+            return true;
+        }
+        catch (error) {
+            if (isErrno(error, 'EEXIST'))
+                return false;
+            if (isErrno(error, 'EACCES') || isErrno(error, 'EPERM')) {
+                // Windows can report EPERM instead of EEXIST during contention. A regular owner is busy; if the owner
+                // disappeared before lstat, retry create once to distinguish that release race from a persistent ACL
+                // failure. Unsafe/inaccessible paths still throw from currentOwnerStat and remain fail closed.
+                if (currentOwnerStat(lockPath) !== null)
+                    return false;
+                if (permissionAttempt === 0)
+                    continue;
+                throw new UnsafeLockPathError('permission_denied');
+            }
+            throw error;
+        }
+    }
+    throw new UnsafeLockPathError('permission_denied');
 }
 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))
+    const snapshot = lockSnapshot(guardPath);
+    if (snapshot === null || !reclaimableSnapshot(guardPath, snapshot))
+        return null;
+    if (!removeUnchangedLock(guardPath, snapshot, 'stale'))
         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);
+    removeFileIfOwned(mutationGuardPath(lockPath), guard);
 }
 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))
+        const snapshot = lockSnapshot(lockPath);
+        if (snapshot === null || !reclaimableSnapshot(lockPath, snapshot))
             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;
+        return removeUnchangedLock(lockPath, snapshot, 'stale');
     }
     finally {
         releaseMutationGuard(lockPath, guard);
@@ -177,14 +344,22 @@ function reclaimStaleLock(lockPath) {
  * 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.
+ * is removed by hand. Empty or truncated locks are reclaimed only after the same inode and contents
+ * remain malformed for a grace period, so a live creator can finish publishing its owner payload.
+ * Acquisition stays atomic (O_EXCL), and stale reclaim moves the old lock aside under a mutation
+ * guard, then verifies the inode snapshot before deletion. 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 pending = ownedLocks.get(lockKey(lockPath));
+    if (pending?.releasePending) {
+        const released = releaseLock(lockPath);
+        if (!released.released)
+            throw new LockReleaseError(released.reason);
+    }
     const maxTries = opts.maxTries ?? 300;
     const waitMs = opts.waitMs ?? 10;
     for (let i = 0; i < maxTries; i++) {
@@ -192,36 +367,77 @@ export function acquireLock(lockPath, opts = {}) {
         if (createLockFile(lockPath, owner, true)) {
             return;
         }
-        const current = lockOwner(lockPath);
-        if (current !== null && current.pid !== process.pid && !pidAlive(current.pid)) {
+        const current = lockSnapshot(lockPath);
+        if (current !== null && reclaimableSnapshot(lockPath, current)) {
             if (!reclaimStaleLock(lockPath))
                 syncSleep(waitMs);
             continue;
         }
+        if (current === null && pathExists(mutationGuardPath(lockPath))) {
+            const guard = tryAcquireMutationGuard(lockPath);
+            if (guard !== null)
+                releaseMutationGuard(lockPath, guard);
+        }
         syncSleep(waitMs);
     }
-    throw new LockTimeoutError(lockPath);
+    throw new LockTimeoutError();
 }
 export function releaseLock(lockPath) {
     const key = lockKey(lockPath);
-    const owner = ownedLocks.get(key);
-    if (owner === undefined)
-        return;
+    const owned = ownedLocks.get(key);
+    if (owned === undefined)
+        return { released: true, reason: 'not_owned' };
+    const failed = (reason) => {
+        owned.releasePending = true;
+        return { released: false, reason };
+    };
+    // Release must not use lockOwner(): that helper intentionally folds path_changed into a conservative null
+    // for acquire retries. Here, an inconclusive read marks a pending release so the next acquire can retry or
+    // surface LOCK_RELEASE_FAILED instead of silently timing out behind this process's own PID.
+    let raw;
     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;
+        raw = readOwnerBounded(lockPath);
+    }
+    catch (error) {
+        return failed(error instanceof UnsafeLockPathError ? error.reason : 'release_failed');
+    }
+    if (raw === null) {
+        ownedLocks.delete(key);
+        return { released: true, reason: 'missing' };
+    }
+    const current = parseOwner(raw);
+    if (current === null)
+        return failed('invalid_owner');
+    if (!sameOwner(current, owned.owner)) {
+        ownedLocks.delete(key);
+        return { released: true, reason: 'ownership_changed' };
+    }
+    const releasedPath = sidecarPath(lockPath, 'released');
+    try {
+        renameSync(lockPath, releasedPath);
+    }
+    catch (error) {
+        if (isErrno(error, 'ENOENT')) {
+            ownedLocks.delete(key);
+            return { released: true, reason: 'missing' };
         }
+        return failed('release_failed');
+    }
+    ownedLocks.delete(key);
+    try {
         removeFileIfExists(releasedPath);
     }
-    finally {
-        ownedLocks.delete(key);
+    catch {
+        return { released: true, reason: 'released_with_cleanup_error' };
+    }
+    return { released: true, reason: 'released' };
+}
+export class LockReleaseError extends Error {
+    reason;
+    code = 'LOCK_RELEASE_FAILED';
+    constructor(reason) {
+        super(`文件锁释放未完成: ${reason}`);
+        this.reason = reason;
+        this.name = 'LockReleaseError';
     }
 }

package/dist/util/index.d.ts

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

package/dist/util/index.js

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

package/dist/wire/geneHints.d.ts

@@ -34,13 +34,45 @@ export interface GeneToolPolicy {
     deny?: string[];
     severity?: ToolPolicySeverity;
 }
+/**
+ * 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 declare const GENERATION_SOURCES: readonly ["evolved", "distilled", "manual"];
+export type GenerationSource = (typeof GENERATION_SOURCES)[number];
+export interface GeneGenerationHeuristics {
+    strategy_steps?: number;
+    avoid_count?: number;
+    validation_declared_count?: number;
+    validation_runnable_count?: number;
+    signals_extracted?: number;
+    preconditions_extracted?: number;
+    trajectory_depth?: number;
+    has_corrective_insight?: boolean;
+}
+/**
+ * The full provenance + quality metadata block (V1 `gene._source`). Lives on Gene as the v2-delta field
+ * `generation_meta`. `source` is the only required key; the rest is descriptive for reviewers / future
+ * governance. `quality_score` is a coarse [0,1] tier-anchored score (evolved 0.7 / distilled 0.4 / manual 0.3
+ * baseline + bonuses); `overcame_errors` is the mutation_log copy that the trajectory overcame.
+ */
+export interface GenerationMeta {
+    source: GenerationSource;
+    quality_score?: number;
+    quality_heuristics?: GeneGenerationHeuristics;
+    overcame_errors?: string[];
+}
 /**
  * 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 declare const GENE_HINT_FIELDS: readonly ["routing_hint", "tool_policy"];
+export declare const GENE_HINT_FIELDS: readonly ["routing_hint", "tool_policy", "generation_meta"];
 /**
  * Normalize an arbitrary routing_hint fragment to a strict { tier?, reasoning_level? } object, or null.
  * Unknown enum values are dropped (a stray tier would fail the consumer's exhaustive match and route as if
@@ -60,5 +92,14 @@ export declare function normalizeRoutingHint(raw: unknown): GeneRoutingHint | nu
  * defaults to 'warn' when a list is present; the whole object collapses to null when neither list survives.
  */
 export declare function normalizeToolPolicy(raw: unknown): GeneToolPolicy | null;
+/**
+ * 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 declare function normalizeGenerationMeta(raw: unknown): GenerationMeta | null;
 /** Strip the v2-delta hint fields from a gene-shaped object (used to validate the gep-sdk-known core). */
 export declare function stripGeneHints(gene: Record<string, unknown>): Record<string, unknown>;