@evomap/evolver-core 2.0.0-beta.0

package/dist/verify/rollback.js

@@ -0,0 +1,33 @@
+import { resolve, relative, isAbsolute, sep } from 'node:path';
+function isUnder(root, p) {
+    const r = resolve(root);
+    const ap = resolve(p);
+    const rel = relative(r, ap);
+    return rel === '' || (!rel.startsWith(`..${sep}`) && rel !== '..' && !isAbsolute(rel));
+}
+/**
+ * 规划回滚(M4A-4, 批注#20). 三条铁律, 全部满足才回滚:
+ * - opt-in: optIn=false 时一律不回滚.
+ * - 只动 evolver-owned: 路径必须在 ownedRoots 之内(绝不 reset 主仓 working tree / 仓外文件).
+ * - 不删 untracked: 未跟踪文件不回滚(避免破坏用户未提交工作).
+ */
+export function planRollback(targets, cfg) {
+    const willRollback = [];
+    const skipped = [];
+    for (const t of targets) {
+        if (!cfg.optIn) {
+            skipped.push({ target: t, reason: 'rollback 未 opt-in' });
+            continue;
+        }
+        if (!cfg.ownedRoots.some((root) => isUnder(root, t.path))) {
+            skipped.push({ target: t, reason: '非 evolver-owned 路径' });
+            continue;
+        }
+        if (!t.tracked) {
+            skipped.push({ target: t, reason: 'untracked 文件, 不回滚' });
+            continue;
+        }
+        willRollback.push(t);
+    }
+    return { willRollback, skipped };
+}

package/dist/verify/sandboxRunner.d.ts

@@ -0,0 +1,39 @@
+import { type CommandRunner } from './validation.js';
+export interface SandboxOptions {
+    /** Per-command timeout (ms); clamped to 120s. Default 60s. */
+    timeoutMs?: number;
+    /** Working directory; default = a fresh temp dir, wiped after the command. */
+    cwd?: string;
+    /** Env keys that reach the child (default = a minimal safe set). */
+    envAllowKeys?: readonly string[];
+    /**
+     * Run the command in a fresh network namespace (no network) — a validation command shouldn't need the net,
+     * and cutting it blocks exfiltration (#26). Uses `unshare -r -n` (unprivileged user+net namespace). FAIL-SAFE:
+     * if unshare/userns is unavailable, the command is DENIED rather than run with network. Default off.
+     */
+    noNetwork?: boolean;
+    /**
+     * Hide the user's credential directories from the command via a mount namespace (#26 FS half): a validation
+     * command runs in a fresh temp cwd and has no business reading ~/.evomap (node_secret), ~/.ssh, ~/.aws, etc.
+     * — an empty tmpfs is mounted over each (inside the ns only; the host is untouched). FAIL-SAFE: denied if
+     * unprivileged mount namespaces are unavailable. Binaries live outside these dirs, so the command still runs.
+     */
+    hideHomeSecrets?: boolean;
+    /** Injected unshare-availability probe (test seam). Default: a real `unshare -r -m -n true` check (cached). */
+    unshareCheck?: () => boolean;
+}
+/** Wrap an (executable,args) in unprivileged namespaces per the requested isolation (pure — testable). */
+export declare function isolationCommand(bin: string, args: readonly string[], opts: {
+    noNetwork?: boolean;
+    hideHomeSecrets?: boolean;
+}): {
+    cmd: string;
+    args: string[];
+};
+/** Whether unprivileged user+mount+net namespaces (`unshare -r -m -n`) work here (cached) — covers both isolation modes. */
+export declare function unshareNetAvailable(): boolean;
+/**
+ * Build a hardened CommandRunner. The executable allowlist is the ValidationPlan's job (runValidation);
+ * this only hardens how an allowed command runs.
+ */
+export declare function makeSandboxRunner(opts?: SandboxOptions): CommandRunner;

package/dist/verify/sandboxRunner.js

@@ -0,0 +1,116 @@
+// Hardened sandbox CommandRunner (ported from v1 src/gep/validator/sandboxExecutor.js). Fills the
+// CommandRunner seam in validation.ts so the validator role can actually EXECUTE validation commands
+// (e.g. `node test.js`) to verify an evolution — safely, without trusting the caller. The executable
+// allowlist stays data-driven in the ValidationPlan (runValidation checks it before calling this); this
+// module hardens EXECUTION: blocked node eval-flags, shell-metachar rejection, a fresh wiped temp cwd,
+// a scrubbed env (no secrets leak in), and a SIGKILL timeout. Output is folded + truncated.
+import { spawn, spawnSync } from 'node:child_process';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { isNodeExecutable, nodeFlagViolation, SHELL_METACHARS } from './validation.js';
+const DEFAULT_TIMEOUT_MS = 60_000;
+const MAX_TIMEOUT_MS = 120_000;
+const MAX_OUTPUT_CHARS = 4000;
+// Env scrub: only these keys reach the child, so node-secrets/tokens in the parent env cannot leak into validation.
+const DEFAULT_ENV_ALLOW = ['PATH', 'HOME', 'LANG', 'LC_ALL', 'TMPDIR', 'SYSTEMROOT'];
+/** Credential dirs hidden under $HOME when hideHomeSecrets is set (dirs only — never where binaries live). */
+const SECRET_HOME_DIRS = ['.evomap', '.ssh', '.aws', '.gnupg', '.docker', '.kube'];
+// Fixed setup run inside the mount ns: tmpfs over each existing secret dir, then exec the command. The command
+// is passed as POSITIONAL args (`exec "$@"`), never interpolated into the script — no shell-injection vector.
+const HIDE_SECRETS_SCRIPT = `for d in ${SECRET_HOME_DIRS.map((d) => `"$HOME/${d}"`).join(' ')}; do [ -d "$d" ] && mount -t tmpfs none "$d" 2>/dev/null; done; exec "$@"`;
+/** Wrap an (executable,args) in unprivileged namespaces per the requested isolation (pure — testable). */
+export function isolationCommand(bin, args, opts) {
+    const flags = ['-r'];
+    if (opts.hideHomeSecrets)
+        flags.push('-m');
+    if (opts.noNetwork)
+        flags.push('-n');
+    if (!opts.noNetwork && !opts.hideHomeSecrets)
+        return { cmd: bin, args: [...args] };
+    const base = [...flags, '--fork', '--kill-child', '--'];
+    // Mount setup needs a launcher (sh runs the FIXED script then exec "$@"); net-only needs no shell.
+    return opts.hideHomeSecrets
+        ? { cmd: 'unshare', args: [...base, 'sh', '-c', HIDE_SECRETS_SCRIPT, 'sh', bin, ...args] }
+        : { cmd: 'unshare', args: [...base, bin, ...args] };
+}
+let unshareCache;
+/** Whether unprivileged user+mount+net namespaces (`unshare -r -m -n`) work here (cached) — covers both isolation modes. */
+export function unshareNetAvailable() {
+    if (unshareCache === undefined) {
+        try {
+            unshareCache = spawnSync('unshare', ['-r', '-m', '-n', 'true'], { timeout: 5000 }).status === 0;
+        }
+        catch {
+            unshareCache = false;
+        }
+    }
+    return unshareCache;
+}
+function parse(cmd) {
+    const tokens = cmd.trim().split(/\s+/).filter(Boolean);
+    return { executable: tokens[0] ?? '', args: tokens.slice(1) };
+}
+function scrubEnv(allow) {
+    const out = {};
+    for (const k of allow) {
+        const v = process.env[k];
+        if (v !== undefined)
+            out[k] = v;
+    }
+    return out;
+}
+/**
+ * Build a hardened CommandRunner. The executable allowlist is the ValidationPlan's job (runValidation);
+ * this only hardens how an allowed command runs.
+ */
+export function makeSandboxRunner(opts = {}) {
+    const timeout = Math.min(opts.timeoutMs ?? DEFAULT_TIMEOUT_MS, MAX_TIMEOUT_MS);
+    const envAllow = opts.envAllowKeys ?? DEFAULT_ENV_ALLOW;
+    return (cmd) => new Promise((resolve) => {
+        const deny = (msg, code = 126) => resolve({ exitCode: code, stdout: `[sandbox] ${msg}` });
+        const { executable, args } = parse(cmd);
+        if (!executable)
+            return deny('empty command', 1);
+        if (SHELL_METACHARS.test(cmd))
+            return deny('rejected: shell metacharacter (no shell is provided; split compound commands)');
+        const badFlag = nodeFlagViolation(executable, args);
+        if (badFlag)
+            return deny(`rejected: blocked node flag ${badFlag}`);
+        // Isolation (#26): fail-safe — if we can't actually create the namespaces, refuse rather than run un-isolated.
+        if ((opts.noNetwork || opts.hideHomeSecrets) && !(opts.unshareCheck ?? unshareNetAvailable)()) {
+            return deny('rejected: isolation (noNetwork/hideHomeSecrets) requested but unprivileged namespaces (unshare -r -m -n) are unavailable here');
+        }
+        const ownTemp = !opts.cwd;
+        let cwd;
+        try {
+            cwd = opts.cwd ?? mkdtempSync(join(tmpdir(), 'evo-sbx-'));
+        }
+        catch (e) {
+            return deny(`temp dir failed: ${e instanceof Error ? e.message : 'err'}`, 1);
+        }
+        const cleanup = () => { if (ownTemp) {
+            try {
+                rmSync(cwd, { recursive: true, force: true });
+            }
+            catch { /* best effort */ }
+        } };
+        // Resolve 'node' to the running binary so spawn(shell:false) works on Windows too (where bare 'node' would ENOENT).
+        const bin = isNodeExecutable(executable) ? process.execPath : executable;
+        try {
+            const { cmd: spawnCmd, args: spawnArgs } = isolationCommand(bin, args, { noNetwork: opts.noNetwork, hideHomeSecrets: opts.hideHomeSecrets });
+            const child = spawn(spawnCmd, spawnArgs, { shell: false, cwd, env: scrubEnv(envAllow), timeout, killSignal: 'SIGKILL', stdio: ['ignore', 'pipe', 'pipe'] });
+            let out = '';
+            const cap = (d) => { if (out.length < MAX_OUTPUT_CHARS)
+                out += String(d); };
+            child.stdout?.on('data', cap);
+            child.stderr?.on('data', cap);
+            child.on('error', (err) => { cleanup(); resolve({ exitCode: 127, stdout: `[sandbox] spawn error: ${err.message}` }); });
+            child.on('close', (code, signal) => { cleanup(); resolve({ exitCode: code ?? (signal ? 137 : 1), stdout: out.slice(0, MAX_OUTPUT_CHARS) }); });
+        }
+        catch (e) {
+            cleanup();
+            resolve({ exitCode: 127, stdout: `[sandbox] spawn failed: ${e instanceof Error ? e.message : 'err'}` });
+        }
+    });
+}

package/dist/verify/sandboxedValidation.d.ts

@@ -0,0 +1,35 @@
+import { type ValidationResult } from './validation.js';
+export interface SandboxedValidationSkippedCommand {
+    cmd: string;
+    script: string;
+    reason: 'missing_script';
+}
+export interface SandboxedValidationResult {
+    passed: boolean;
+    /** Convenience score for cycle outcomes: 0.95 pass / 0.2 fail (matches the prior inline hook). */
+    score: number;
+    results: ValidationResult[];
+    /** Declared repo-relative validation scripts that were absent from this checkout. */
+    skipped: SandboxedValidationSkippedCommand[];
+    /**
+     * Whether OS-namespace isolation (no-network + hidden home secrets) was applied. TRUE only where unprivileged
+     * namespaces exist (Linux today). FALSE on Windows/macOS, where commands still get the non-namespace hardening
+     * but CAN reach the network and read home files — the caller should surface this so the weaker guarantee on
+     * those platforms is not silent.
+     */
+    isolated: boolean;
+}
+export interface SandboxedValidationOptions {
+    /** Per-command timeout (ms), forwarded to the sandbox runner. */
+    timeoutMs?: number;
+    /** Test seam: override the unprivileged-namespace availability probe. */
+    unshareCheck?: () => boolean;
+}
+/**
+ * Run validation commands in the hardened sandbox. Isolation (no-network + hidden home secrets) is requested only
+ * when unprivileged namespaces are available; elsewhere (Windows/macOS) it degrades to the non-namespace hardening
+ * rather than denying every command. The allowlist is derived from the declared commands' own executables, so this
+ * runs exactly the commands the caller asked for — just hardened. An EMPTY command set passes (nothing to verify),
+ * preserving prior behavior; note this differs from runValidation's own "no commands = not verified" stance.
+ */
+export declare function runSandboxedValidation(cmds: readonly string[], cwd: string, opts?: SandboxedValidationOptions): Promise<SandboxedValidationResult>;

package/dist/verify/sandboxedValidation.js

@@ -0,0 +1,56 @@
+// The trusted external verifier (wires the hardened sandbox runner to the validation plan). A cycle's validate
+// step should run its validation commands through HERE rather than a bare spawn: each command runs with shell-
+// metachar rejection, node-eval-flag blocking, a scrubbed env, a SIGKILL timeout, and — where unprivileged
+// namespaces exist — no network + hidden home secrets, so a validation command cannot phone home / exfiltrate to
+// game the pass/fail. This is the "verifier outside the repo, untrusted caller" half the safety model relies on.
+import { existsSync } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
+import { makeSandboxRunner, unshareNetAvailable } from './sandboxRunner.js';
+import { runValidation, validationScriptPath } from './validation.js';
+/**
+ * Run validation commands in the hardened sandbox. Isolation (no-network + hidden home secrets) is requested only
+ * when unprivileged namespaces are available; elsewhere (Windows/macOS) it degrades to the non-namespace hardening
+ * rather than denying every command. The allowlist is derived from the declared commands' own executables, so this
+ * runs exactly the commands the caller asked for — just hardened. An EMPTY command set passes (nothing to verify),
+ * preserving prior behavior; note this differs from runValidation's own "no commands = not verified" stance.
+ */
+export async function runSandboxedValidation(cmds, cwd, opts = {}) {
+    const isolated = (opts.unshareCheck ?? unshareNetAvailable)();
+    // ONLY a truly empty command set is a vacuous pass (nothing to verify). A non-empty set with blank entries is a
+    // malformed plan, NOT a pass: blanks are kept (trimmed to '') so they fall outside the allowlist and fail, rather
+    // than being silently dropped into a pass (Bugbot).
+    if (cmds.length === 0)
+        return { passed: true, score: 0.95, results: [], skipped: [], isolated };
+    const runner = makeSandboxRunner({
+        cwd,
+        noNetwork: isolated,
+        hideHomeSecrets: isolated,
+        ...(opts.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}),
+        ...(opts.unshareCheck ? { unshareCheck: opts.unshareCheck } : {}),
+    });
+    const list = cmds.map((c) => String(c ?? '').trim());
+    // Validation plans may reference repo-relative scripts that do not exist in this checkout; skip only those.
+    const skipped = [];
+    const runnable = [];
+    for (const cmd of list) {
+        const script = validationScriptPath(cmd);
+        if (script && !isAbsolute(script) && !existsSync(resolve(cwd, script))) {
+            skipped.push({ cmd, script, reason: 'missing_script' });
+            console.warn(`[Validation] Skipping validation command (script not in repoRoot): ${script}`);
+            continue;
+        }
+        runnable.push(cmd);
+    }
+    if (runnable.length === 0)
+        return { passed: false, score: 0.2, results: [], skipped, isolated };
+    const allowlist = [...new Set(runnable.map((c) => c.split(/\s+/)[0] ?? '').filter(Boolean))];
+    const { results, passed } = await runValidation({ commands: runnable.map((cmd) => ({ cmd })), allowlist }, runner);
+    const complete = skipped.length === 0;
+    return {
+        passed: passed && complete,
+        score: passed && complete ? 0.95 : 0.2,
+        results,
+        skipped,
+        isolated,
+    };
+}

package/dist/verify/validation.d.ts

@@ -0,0 +1,41 @@
+export interface ValidationCommand {
+    cmd: string;
+    label?: string;
+}
+/** 校验计划. allowlist **由用户项目声明**(批注#21), 不再内置 ['node']. */
+export interface ValidationPlan {
+    commands: readonly ValidationCommand[];
+    allowlist: readonly string[];
+}
+export interface ValidationResult {
+    label: string;
+    cmd: string;
+    allowed: boolean;
+    exitCode: number | null;
+    stdoutSummary: string;
+    passed: boolean;
+}
+export interface RunOutput {
+    exitCode: number;
+    stdout: string;
+}
+export type CommandRunner = (cmd: string) => Promise<RunOutput> | RunOutput;
+export declare const SHELL_METACHARS: RegExp;
+export declare const BLOCKED_NODE_FLAGS: Set<string>;
+export declare function normalizeExecutableName(executable: string): string;
+export declare function isNodeExecutable(executable: string): boolean;
+export declare function nodeFlagViolation(executable: string, args: readonly string[]): string | null;
+/** 命令首 token(可执行名)是否在项目声明的 allowlist 内. */
+export declare function isAllowed(cmd: string, allowlist: readonly string[]): boolean;
+/** Extract the local script targeted by `node <script> ...`, or null for non-script node commands. */
+export declare function validationScriptPath(cmd: string): string | null;
+/** stdout 摘要 = 首行 + 末行(去 canary.js 隐形约定: 不找魔法字符串, 只留可读摘要). */
+export declare function summarizeStdout(stdout: string): string;
+/**
+ * 跑校验(M4A-4). 判价值 = **exit code + stdout 摘要**, 不依赖 canary.js 魔法字符串(批注#22).
+ * 不在 allowlist 的命令 auto-deny(不执行, allowed=false), 守无人值守安全.
+ */
+export declare function runValidation(plan: ValidationPlan, run: CommandRunner): Promise<{
+    results: ValidationResult[];
+    passed: boolean;
+}>;

package/dist/verify/validation.js

@@ -0,0 +1,85 @@
+// With shell:false these are passed literally (harmless), but their presence means an injection attempt
+// or a command that wrongly assumes a shell (e.g. `a && b`) — reject loudly so it is split, not silently mis-run.
+export const SHELL_METACHARS = /[;&|`$<>\n\r]/;
+// Node flags that turn `node` into an arbitrary-code evaluator or preload hook. A legit validation command is
+// `node <script> [args]`; these flags must be denied by the sandbox and must never be hidden by missing-script skip.
+export const BLOCKED_NODE_FLAGS = new Set([
+    '-e', '--eval', '-p', '--print', '-i', '--interactive', '-r', '--require',
+    '--loader', '--experimental-loader', '--import', '--env-file',
+    // Inspector: opens an UNAUTHENTICATED Node debug port (a remote-code-execution channel) for the command's
+    // lifetime — never needed by a light `node <script>` validation. (`=value` forms are covered by the
+    // split('=') in nodeFlagViolation below.) Hardens both the distill light-validation filter and the sandbox.
+    '--inspect', '--inspect-brk', '--inspect-port', '--inspect-publish-uid',
+    // Watch: keeps the process alive past its work → hangs validation until the sandbox SIGKILLs it (DoS).
+    '--watch', '--watch-path', '--watch-preserve-output',
+    // Module-resolution override: can redirect imports/requires to attacker-chosen code paths.
+    '--conditions', '-C',
+]);
+export function normalizeExecutableName(executable) {
+    const trimmed = String(executable ?? '').trim();
+    const unquoted = trimmed.replace(/^["']|["']$/g, '');
+    const base = unquoted.split(/[\\/]/).pop() ?? unquoted;
+    return base.toLowerCase().replace(/\.exe$/, '');
+}
+export function isNodeExecutable(executable) {
+    return normalizeExecutableName(executable) === 'node';
+}
+export function nodeFlagViolation(executable, args) {
+    if (!isNodeExecutable(executable))
+        return null;
+    for (const a of args) {
+        const flag = a.split('=')[0] ?? a;
+        if (BLOCKED_NODE_FLAGS.has(flag))
+            return flag;
+    }
+    return null;
+}
+/** 命令首 token(可执行名)是否在项目声明的 allowlist 内. */
+export function isAllowed(cmd, allowlist) {
+    const head = cmd.trim().split(/\s+/)[0] ?? '';
+    return allowlist.includes(head);
+}
+/** Extract the local script targeted by `node <script> ...`, or null for non-script node commands. */
+export function validationScriptPath(cmd) {
+    const tokens = String(cmd ?? '').trim().split(/\s+/);
+    const executable = tokens[0] ?? '';
+    if (tokens.length < 2 || !isNodeExecutable(executable))
+        return null;
+    if (SHELL_METACHARS.test(cmd) || nodeFlagViolation(executable, tokens.slice(1)))
+        return null;
+    for (let i = 1; i < tokens.length; i += 1) {
+        const token = tokens[i];
+        if (token.startsWith('-'))
+            continue;
+        return /\.(?:c|m)?js$/.test(token) ? token : null;
+    }
+    return null;
+}
+/** stdout 摘要 = 首行 + 末行(去 canary.js 隐形约定: 不找魔法字符串, 只留可读摘要). */
+export function summarizeStdout(stdout) {
+    const lines = stdout.split('\n').map((l) => l.trim()).filter(Boolean);
+    if (lines.length === 0)
+        return '';
+    if (lines.length <= 2)
+        return lines.join(' | ');
+    return `${lines[0]} … ${lines[lines.length - 1]}`;
+}
+/**
+ * 跑校验(M4A-4). 判价值 = **exit code + stdout 摘要**, 不依赖 canary.js 魔法字符串(批注#22).
+ * 不在 allowlist 的命令 auto-deny(不执行, allowed=false), 守无人值守安全.
+ */
+export async function runValidation(plan, run) {
+    const results = [];
+    for (const c of plan.commands) {
+        const label = c.label ?? c.cmd;
+        if (!isAllowed(c.cmd, plan.allowlist)) {
+            results.push({ label, cmd: c.cmd, allowed: false, exitCode: null, stdoutSummary: '', passed: false });
+            continue;
+        }
+        const out = await run(c.cmd);
+        results.push({ label, cmd: c.cmd, allowed: true, exitCode: out.exitCode, stdoutSummary: summarizeStdout(out.stdout), passed: out.exitCode === 0 });
+    }
+    // 全部 allowed 的命令都 exit 0 才算通过; 有命令被 deny 视为未通过(校验不完整)
+    const passed = results.length > 0 && results.every((r) => r.allowed && r.passed);
+    return { results, passed };
+}

package/dist/wire/canonicalize.golden.d.ts

@@ -0,0 +1,23 @@
+/**
+ * canonicalize 黄金向量 (M3-0). asset_id = SHA256(canonicalize(asset 去 asset_id)) 是跨 Go/JS/Rust
+ * 逐字节一致的命门; 任何实现必须复现下列 canonical 字节, 否则互相 reject 资产 (硬化 A5).
+ *
+ * 三陷阱(必须照 JS 语义实现, 非各语言原生):
+ *  1. number = JS Number→String 最短往返 (1.0→"1", 1e21→"1e+21", -0→"0", 非有限→"null").
+ *  2. string = JSON.stringify, **不转义 HTML** (`<`/`>`/`&`/`/` 原样). Go 必须 json Encoder.SetEscapeHTML(false).
+ *  3. object 键排序 = **UTF-16 码元序** (JS Array.sort 默认), 非 UTF-8 字节/码点序.
+ *     非 BMP 字符(emoji)按 surrogate 首单元 0xD800–0xDBFF 排, 排在 U+E000–U+FFFF 之前 — 见 key-order-divergent.
+ */
+export interface CanonicalVector {
+    name: string;
+    input: unknown;
+    canonical: string;
+}
+export declare const CANONICAL_VECTORS: readonly CanonicalVector[];
+/** asset_id 黄金: 固定资产 → 固定 sha256. excludeFields 默认 ['asset_id']. */
+export interface AssetIdVector {
+    name: string;
+    asset: Record<string, unknown>;
+    assetId: string;
+}
+export declare const ASSET_ID_VECTORS: readonly AssetIdVector[];

package/dist/wire/canonicalize.golden.js

@@ -0,0 +1,46 @@
+/**
+ * canonicalize 黄金向量 (M3-0). asset_id = SHA256(canonicalize(asset 去 asset_id)) 是跨 Go/JS/Rust
+ * 逐字节一致的命门; 任何实现必须复现下列 canonical 字节, 否则互相 reject 资产 (硬化 A5).
+ *
+ * 三陷阱(必须照 JS 语义实现, 非各语言原生):
+ *  1. number = JS Number→String 最短往返 (1.0→"1", 1e21→"1e+21", -0→"0", 非有限→"null").
+ *  2. string = JSON.stringify, **不转义 HTML** (`<`/`>`/`&`/`/` 原样). Go 必须 json Encoder.SetEscapeHTML(false).
+ *  3. object 键排序 = **UTF-16 码元序** (JS Array.sort 默认), 非 UTF-8 字节/码点序.
+ *     非 BMP 字符(emoji)按 surrogate 首单元 0xD800–0xDBFF 排, 排在 U+E000–U+FFFF 之前 — 见 key-order-divergent.
+ */
+export const CANONICAL_VECTORS = [
+    { name: 'null', input: null, canonical: 'null' },
+    { name: 'bool-true', input: true, canonical: 'true' },
+    { name: 'int', input: 42, canonical: '42' },
+    { name: 'float', input: 0.1, canonical: '0.1' },
+    { name: 'float-trailing-zero', input: 1.0, canonical: '1' }, // 陷阱1: 无 ".0"
+    { name: 'big-exp', input: 1e21, canonical: '1e+21' }, // 陷阱1: 指数形式
+    { name: 'neg-zero', input: -0, canonical: '0' }, // 陷阱1: -0→"0"
+    { name: 'str-basic', input: 'hello', canonical: '"hello"' },
+    { name: 'str-html', input: 'a<b>&"/', canonical: '"a<b>&\\"/"' }, // 陷阱2: HTML 不转义, 仅 \" 转义
+    { name: 'str-unicode', input: '认证 \u{1F9EC}', canonical: '"认证 \u{1F9EC}"' },
+    { name: 'empty-array', input: [], canonical: '[]' },
+    { name: 'empty-object', input: {}, canonical: '{}' },
+    { name: 'nested', input: { b: 2, a: [1, { z: 'x', a: null }] }, canonical: '{"a":[1,{"a":null,"z":"x"}],"b":2}' },
+    // 陷阱3: 键 UTF-16 序 — 'a'(0x61) < emoji(surrogate 0xD83E) < U+F8FF(0xF8FF). 码点序会把 emoji 排最后.
+    { name: 'key-order-divergent', input: { a: 3, '\u{1F9EC}': 2, '': 1 }, canonical: '{"a":3,"\u{1F9EC}":2,"":1}' },
+];
+export const ASSET_ID_VECTORS = [
+    {
+        name: 'gene',
+        asset: {
+            type: 'Gene', schema_version: '1.11.0', id: 'gene-1', category: 'repair',
+            signals_match: ['auth', '401'], strategy: ['s1'], constraints: { max_files: 3, forbidden_paths: [] },
+            validation: ['v'], asset_id: 'IGNORED',
+        },
+        assetId: 'sha256:402ea1911984bd7b24ffa3faf18c5679cdb5f0c5215700cbdd1519705f9b9453',
+    },
+    {
+        name: 'capsule',
+        asset: {
+            type: 'Capsule', schema_version: '1.11.0', id: 'cap-1', trigger: ['t'], gene: 'gene-1', summary: 's',
+            confidence: 0.9, blast_radius: { files: 1, lines: 10 }, outcome: { status: 'success', score: 0.8 }, asset_id: 'IGNORED',
+        },
+        assetId: 'sha256:fa352d440ace8505f4e06d6cf9d215c9b03b9799cd34f0afb6eec18a5878ee60',
+    },
+];

package/dist/wire/geneHints.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Gene routing / tool hints — OPTIONAL EvoX-side annotations a Gene MAY carry to bias the model-tier
+ * router (routing_hint) or restrict tools (tool_policy). Ported from v1 src/gep/schemas/gene.js (PR #93,
+ * "wire routing_hint and tool_policy into Gene schema").
+ *
+ * v2-delta (feature-gate): these fields are NOT yet in @evomap/gep-sdk's gene.schema.json
+ * (additionalProperties:false), so a Gene carrying them is not a schema-valid gep-sdk asset until a
+ * gep-sdk gene-schema bump — exactly how Capsule's proof_of_work / resolution_status were v2-delta before
+ * the 1.11.0 bump made them first-class. That invalidity is surfaced ONLY by the advisory validateWire
+ * (wire/schemaGate) — at intake on the hint-stripped core, and via the evolver_gep_build pre-publish
+ * preview — plus the hub's own schema check on receipt; there is NO enforced local egress gate (the
+ * publish/egress path is sanitize-only and does not call validateWire). Until a bump the hints ride along
+ * LOCALLY (intake pool + v1→v2 import fidelity); nothing in this repo wires them to a runtime consumer yet
+ * (the proxy model router's `gene_hint` seam is the eventual tier consumer — see
+ * packages/evolver-proxy/src/router/modelRouter.ts).
+ *
+ * Enum strings are matched case-sensitively by the consuming router / tool-gate — keep them EXACT. The
+ * router tier set (proxy/modelRouter.ts `Tier`) is the consumer-side mirror of ROUTING_TIERS; the two MUST
+ * agree. Normalization is deliberately lossy: unknown enum members are dropped (not coerced to a default),
+ * mirroring the consumer's exhaustive match where a stray value is simply ignored rather than mis-routed.
+ */
+export declare const ROUTING_TIERS: readonly ["cheap", "mid", "expensive"];
+export type RoutingTier = (typeof ROUTING_TIERS)[number];
+export declare const REASONING_LEVELS: readonly ["off", "low", "medium", "high"];
+export type ReasoningLevel = (typeof REASONING_LEVELS)[number];
+export declare const TOOL_POLICY_SEVERITIES: readonly ["warn", "block"];
+export type ToolPolicySeverity = (typeof TOOL_POLICY_SEVERITIES)[number];
+export interface GeneRoutingHint {
+    tier?: RoutingTier;
+    reasoning_level?: ReasoningLevel;
+}
+export interface GeneToolPolicy {
+    allow_only?: string[];
+    deny?: string[];
+    severity?: ToolPolicySeverity;
+}
+/**
+ * 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"];
+/**
+ * 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
+ * no hint existed, so we mirror that here rather than emit JSON that misleads). Empty result → null
+ * ("no opinion — let the router take its default path").
+ */
+export declare function normalizeRoutingHint(raw: unknown): GeneRoutingHint | null;
+/**
+ * Normalize an arbitrary tool_policy fragment. allow_only / deny are TOOL-NAME lists: only non-empty STRING
+ * entries are kept — non-string entries (objects, numbers, null, booleans) are DROPPED, not String()-coerced.
+ * This is a deliberate tightening over v1 (which did `.map(String)` and leaked garbage like "[object Object]"
+ * into a tool-name list); it mirrors the case-sensitive typeguards used for tier/severity here, and never
+ * drops a LEGITIMATE restriction — a partly-garbage list keeps its valid names, and an all-garbage list
+ * collapses exactly like an all-empty one. A list is kept only if something survives: a raw
+ * { allow_only: ['', ''] } must NOT leak through as allow_only:[], which a consuming tool-gate reads as
+ * "allow zero tools" and would block every tool call when the gene only meant to carry a deny list. severity
+ * 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;
+/** 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>;

package/dist/wire/geneHints.js

@@ -0,0 +1,100 @@
+/**
+ * Gene routing / tool hints — OPTIONAL EvoX-side annotations a Gene MAY carry to bias the model-tier
+ * router (routing_hint) or restrict tools (tool_policy). Ported from v1 src/gep/schemas/gene.js (PR #93,
+ * "wire routing_hint and tool_policy into Gene schema").
+ *
+ * v2-delta (feature-gate): these fields are NOT yet in @evomap/gep-sdk's gene.schema.json
+ * (additionalProperties:false), so a Gene carrying them is not a schema-valid gep-sdk asset until a
+ * gep-sdk gene-schema bump — exactly how Capsule's proof_of_work / resolution_status were v2-delta before
+ * the 1.11.0 bump made them first-class. That invalidity is surfaced ONLY by the advisory validateWire
+ * (wire/schemaGate) — at intake on the hint-stripped core, and via the evolver_gep_build pre-publish
+ * preview — plus the hub's own schema check on receipt; there is NO enforced local egress gate (the
+ * publish/egress path is sanitize-only and does not call validateWire). Until a bump the hints ride along
+ * LOCALLY (intake pool + v1→v2 import fidelity); nothing in this repo wires them to a runtime consumer yet
+ * (the proxy model router's `gene_hint` seam is the eventual tier consumer — see
+ * packages/evolver-proxy/src/router/modelRouter.ts).
+ *
+ * Enum strings are matched case-sensitively by the consuming router / tool-gate — keep them EXACT. The
+ * router tier set (proxy/modelRouter.ts `Tier`) is the consumer-side mirror of ROUTING_TIERS; the two MUST
+ * agree. Normalization is deliberately lossy: unknown enum members are dropped (not coerced to a default),
+ * mirroring the consumer's exhaustive match where a stray value is simply ignored rather than mis-routed.
+ */
+export const ROUTING_TIERS = ['cheap', 'mid', 'expensive'];
+export const REASONING_LEVELS = ['off', 'low', 'medium', 'high'];
+export const TOOL_POLICY_SEVERITIES = ['warn', 'block'];
+/**
+ * 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'];
+function includesEnum(set, v) {
+    return typeof v === 'string' && set.includes(v);
+}
+/**
+ * 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
+ * no hint existed, so we mirror that here rather than emit JSON that misleads). Empty result → null
+ * ("no opinion — let the router take its default path").
+ */
+export function normalizeRoutingHint(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const r = raw;
+    const out = {};
+    const tier = r['tier'];
+    if (includesEnum(ROUTING_TIERS, tier))
+        out.tier = tier;
+    const reasoning = r['reasoning_level'];
+    if (includesEnum(REASONING_LEVELS, reasoning))
+        out.reasoning_level = reasoning;
+    return Object.keys(out).length > 0 ? out : null;
+}
+/**
+ * Normalize an arbitrary tool_policy fragment. allow_only / deny are TOOL-NAME lists: only non-empty STRING
+ * entries are kept — non-string entries (objects, numbers, null, booleans) are DROPPED, not String()-coerced.
+ * This is a deliberate tightening over v1 (which did `.map(String)` and leaked garbage like "[object Object]"
+ * into a tool-name list); it mirrors the case-sensitive typeguards used for tier/severity here, and never
+ * drops a LEGITIMATE restriction — a partly-garbage list keeps its valid names, and an all-garbage list
+ * collapses exactly like an all-empty one. A list is kept only if something survives: a raw
+ * { allow_only: ['', ''] } must NOT leak through as allow_only:[], which a consuming tool-gate reads as
+ * "allow zero tools" and would block every tool call when the gene only meant to carry a deny list. severity
+ * defaults to 'warn' when a list is present; the whole object collapses to null when neither list survives.
+ */
+export function normalizeToolPolicy(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const r = raw;
+    const out = {};
+    const allow = cleanToolList(r['allow_only']);
+    if (allow)
+        out.allow_only = allow;
+    const deny = cleanToolList(r['deny']);
+    if (deny)
+        out.deny = deny;
+    if (out.allow_only === undefined && out.deny === undefined)
+        return null;
+    const severity = r['severity'];
+    out.severity = includesEnum(TOOL_POLICY_SEVERITIES, severity) ? severity : 'warn';
+    return out;
+}
+/**
+ * A tool-name list survives only as its non-empty string members. Non-strings are dropped (not coerced) —
+ * see normalizeToolPolicy. Returns undefined when nothing survives, so the caller omits the field entirely.
+ */
+function cleanToolList(raw) {
+    if (!Array.isArray(raw))
+        return undefined;
+    const cleaned = raw.filter((x) => typeof x === 'string' && x.length > 0);
+    return cleaned.length > 0 ? cleaned : undefined;
+}
+/** 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;
+    const out = {};
+    for (const [k, v] of Object.entries(gene))
+        if (!hidden.includes(k))
+            out[k] = v;
+    return out;
+}