sneakoscope 7.1.0 → 7.3.0

package/dist/core/routes.js

@@ -249,7 +249,7 @@ export const ROUTES = [
         command: '$Naruto',
         mode: 'NARUTO',
         route: 'Codex official subagent workflow',
-        description: '$Naruto prepares a lightweight Codex official subagent workflow. The Sol Max parent owns decomposition, delegates only defensible direct-child slices, reuses bounded query-aware TriWiki attention anchors, waits for every requested thread, integrates the results, and reports scoped verification. Automatic fan-out starts at two for bounded work, four for explicit parallel work, and six for large-scale work, then is capped dynamically by ready DAG width, disjoint ownership, verifier/tool capacity, reserved thread slots, and positive marginal usefulness; explicit --agents remains authoritative.',
+        description: '$Naruto prepares a lightweight Codex official subagent workflow. The Sol Max parent owns decomposition, delegates only defensible direct-child slices, reuses bounded query-aware TriWiki attention anchors, waits for every requested thread, integrates the results, and reports scoped verification. Automatic fan-out starts at four for bounded work, six for explicit parallel work, and eight for large-scale work, may expand up to twelve while independent useful slices and healthy host capacity remain, then is capped dynamically by ready DAG width, disjoint ownership, verifier/tool capacity, reserved thread slots, and positive marginal usefulness; explicit --agents remains authoritative.',
         requiredSkills: ['naruto', 'pipeline-runner', 'prompt-pipeline', 'honest-mode'],
         dollarAliases: ['$Work'],
         appSkillAliases: ['work', 'from-chat-img'],
@@ -387,7 +387,7 @@ export const ROUTES = [
         mode: 'RESEARCH',
         route: 'research mission',
         description: 'Frontier discovery with named xhigh persona-lens agents, Eureka ideas, vigorous evidence-bound debate, layered public source retrieval, falsification, a paper manuscript, a final genius-opinion summary, and testable predictions.',
-        requiredSkills: ['research', 'research-discovery', 'pipeline-runner', REFLECTION_SKILL_NAME, 'honest-mode'],
+        requiredSkills: ['research', 'pipeline-runner', REFLECTION_SKILL_NAME, 'honest-mode'],
         lifecycle: ['research_plan', 'source_skill', 'layered_source_ledger', 'xhigh_agent_council', 'eureka_moments', 'debate_ledger', 'report', 'paper', 'genius_opinion_summary', 'novelty_ledger', 'falsification_ledger', 'research_gate', 'post_route_reflection', 'honest_mode'],
         context7Policy: 'if_external_docs',
         reasoningPolicy: 'xhigh',
@@ -443,9 +443,9 @@ export const ROUTES = [
         command: '$DB',
         mode: 'DB',
         route: 'database safety',
-        description: 'Database, Supabase, migration, SQL, or MCP safety checks.',
+        description: 'Database, Supabase, migration, SQL, or MCP safety checks with canonical data-access, pool lifecycle, query-efficiency, and transaction-integrity evidence.',
         requiredSkills: ['db', 'db-safety-guard', 'pipeline-runner', 'context7-docs', REFLECTION_SKILL_NAME, 'honest-mode'],
-        lifecycle: ['db_scan', 'safe_mcp_policy', 'destructive_operation_zero', 'context7_docs', 'post_route_reflection', 'honest_mode'],
+        lifecycle: ['db_scan', 'canonical_db_access_scan', 'pool_lifecycle_review', 'n_plus_one_review', 'transaction_integrity_review', 'manual_sql_or_mad_sks_sql_plane', 'safe_mcp_policy', 'destructive_operation_zero', 'context7_docs', 'post_route_reflection', 'honest_mode'],
         context7Policy: 'required',
         reasoningPolicy: 'high',
         stopGate: 'db-review.json',
@@ -554,7 +554,6 @@ const PACKAGED_MANAGED_SUPPORT_SKILL_NAMES = [
     'sks-prompt-pipeline',
     'sks-reasoning-router',
     'sks-reflection',
-    'sks-research-discovery',
     'sks-solution-scout',
     'sks-turbo-context-pack'
 ];
@@ -618,7 +617,7 @@ export const COMMAND_CATALOG = [
     { name: 'commands', usage: 'sks commands [--json]', description: 'List every user-facing command with a short description.' },
     { name: 'check', usage: 'sks check --tier instant|affected|confidence|release|real-check [--sla 5m] [--changed-since auto] [--json]', description: 'Run build-once proof-bank checks: affected/confidence use incremental build and cached proof reuse; release keeps full clean proof for publish readiness.' },
     { name: 'task', usage: 'sks task run [--sla 5m] [--json]', description: 'Run the normal affected-scope, release-equivalent task verification path.' },
-    { name: 'release', usage: 'sks release affected|full|background [--json]', description: 'Run affected release proof, full release proof, or background release proof explicitly.' },
+    { name: 'release', usage: 'sks release affected|full|background|stage [--json]', description: 'Run affected release proof, full release proof, or background release proof explicitly, or drive the staged npm publish up to the human approval step.' },
     { name: 'triwiki', usage: 'sks triwiki index|affected|proof-bank [--json]', description: 'Inspect TriWiki module cards, gate impact maps, affected graphs, and proof bank status.' },
     { name: 'daemon', usage: 'sks daemon status|warm|stop [--json]', description: 'Inspect or warm the local SKS daemon cache state for build/proof reuse.' },
     { name: 'run', usage: 'sks run "task" [--visual|--research|--db] [--json]', description: 'Classify a plain-language task, materialize a mission, and route it through the SKS trust kernel.' },
@@ -638,7 +637,7 @@ export const COMMAND_CATALOG = [
     { name: 'hooks', usage: 'sks hooks explain|status|trust-report|replay|codex-validate|warning-check ... [--json]', description: 'Explain Codex hook events, validate vendored latest 10-event output schemas, replay fixtures, and enforce warning-zero SKS hook policies under the 0.134 compatibility matrix.' },
     { name: 'codex-lb', usage: 'sks codex-lb status|health|metrics|doctor|circuit|repair|setup ...', description: 'Configure, health-check, repair, and record circuit evidence for codex-lb provider auth without confusing ChatGPT OAuth and proxy keys.' },
     { name: 'remote', usage: 'sks remote readiness|machines|worker ... [--json]', description: 'Inspect official Codex Remote readiness and the allowlisted proof-aware SSH stdio worker surface.' },
-    { name: 'telegram', usage: 'sks telegram status|config|hub ... [--json]', description: 'Inspect and run the single-owner private Telegram Hub without exposing hidden reasoning or raw credentials.' },
+    { name: 'telegram', usage: 'sks telegram status|setup|validate-config|hub [run|start|stop|restart|status] ... [--json]', description: 'Securely pair a private Telegram bot, register a dedicated local Codex session, and manage its single-owner LaunchAgent Hub.' },
     { name: 'zellij', usage: 'sks zellij status|repair [--json] | sks --mad', description: 'Inspect Zellij runtime status, explain repair (no auto-install), and open the SKS Zellij runtime used by MAD. Zellij panes are not official Naruto subagent evidence.' },
     { name: 'mad-sks', usage: 'sks mad-sks plan|run|apply|sql|apply-migration|status|close|rollback-apply ... | sks --mad [--high]', description: 'Open or inspect MAD-SKS scoped permission workflows, merged SQL-plane execution, and the Zellij permission launcher.' },
     { name: 'auto-review', usage: 'sks auto-review status|enable|start [--high] | sks --Auto-review --high', description: 'Enable Codex automatic approval review and launch SKS Zellij with the auto-review profile.' },
@@ -654,6 +653,7 @@ export const COMMAND_CATALOG = [
     { name: 'computer-use', usage: 'sks computer-use import|status|smoke|require ... [--json]', description: 'Record native Mac/non-web Computer Use visual evidence while keeping web verification on the Chrome Extension path.' },
     { name: 'context7', usage: 'sks context7 check|setup|tools|resolve|docs|evidence ...', description: 'Check, configure, and call the local Context7 MCP requirement.' },
     { name: 'super-search', usage: 'sks super-search doctor|run|x|fetch|status|inspect|sources|claims|cache|bench', description: 'Run Super-Search provider-independent source intelligence.' },
+    { name: 'search', usage: 'sks search status|files|text|structure|symbol|context|benchmark|doctor [--json]', description: 'Local SearchProvider engines for files/text/structure/symbol/context (no required rg/ast-grep/fd).' },
     { name: 'recallpulse', usage: 'sks recallpulse run|status|eval|governance|checklist <mission-id|latest>', description: 'Run report-only RecallPulse active recall, durable status, proof capsule, evidence envelope, and governance checks.' },
     { name: 'pipeline', usage: 'sks pipeline status|resume|plan|answer ...', description: 'Inspect the active skill-first route, materialized execution plan, ambiguity gates, and completion gates.' },
     { name: 'guard', usage: 'sks guard check [--json]', description: 'Check SKS harness self-protection lock, fingerprints, and source-repo exception state.' },
@@ -683,7 +683,7 @@ export const COMMAND_CATALOG = [
     { name: 'proof-field', usage: 'sks proof-field scan [--json] [--intent "task"] [--changed file1,file2]', description: 'Analyze Potential Proof Field cones, negative-work cache, and fast-lane eligibility for a change set.' },
     { name: 'skill-dream', usage: 'sks skill-dream status|run|record [--json]', description: 'Track generated-skill usage in lightweight JSON and periodically report keep, merge, prune, and improvement candidates without deleting skills automatically.' },
     { name: 'code-structure', usage: 'sks code-structure scan [--json]', description: 'Scan handwritten source files for 1000/2000/3000-line structure gates and split-review exceptions.' },
-    { name: 'rust', usage: 'sks rust status|smoke [--json] [--require-native]', description: 'Inspect optional Rust accelerator availability and verify JS fallback parity for image hash, voxel validation, and secret scanning.' },
+    { name: 'rust', usage: 'sks rust status|smoke [--json] [--require-native]', description: 'Inspect optional Rust accelerator availability and verify JS fallback parity for image hash, voxel validation, secret scanning, and search files/text/batch.' },
     { name: 'validate-artifacts', usage: 'sks validate-artifacts [mission-id|latest] [--json]', description: 'Validate schema-backed mission artifacts for work orders, official subagent evidence, visual maps, dogfood reports, skills, mistake memory, and Honest Mode.' },
     { name: 'wiki', usage: 'sks wiki coords|pack|refresh|publish|rebuild-index|validate|validate-shared|wrongness ...', description: 'Build, refresh, publish shared shards, rebuild ignored indexes, validate, and attach wrongness-memory context to RGBA/trig LLM Wiki packs with attention.use_first and attention.hydrate_first for compact recall plus source hydration.' },
     { name: 'memory', usage: 'sks memory build [--json] | sks memory gc [--dry-run]', description: 'Project TriWiki context-pack memory into managed AGENTS.md blocks or run bounded memory cleanup.' },

package/dist/core/rust-accelerator.js

@@ -11,7 +11,10 @@ export const RUST_ACCELERATOR_CAPABILITIES = Object.freeze([
     'image-hash',
     'image-voxel-index',
     'voxel-validate',
-    'image-voxel-validate-fast'
+    'image-voxel-validate-fast',
+    'search-files',
+    'search-text',
+    'search-batch'
 ]);
 export function rustBuildHint() {
     return 'cargo build --release --manifest-path crates/sks-core/Cargo.toml';
@@ -23,9 +26,16 @@ export async function findRustAccelerator() {
     const global = await which(process.platform === 'win32' ? 'sks-rs.exe' : 'sks-rs');
     if (global)
         return global;
-    const candidate = path.join(packageRoot(), 'crates', 'sks-core', 'target', 'release', process.platform === 'win32' ? 'sks-rs.exe' : 'sks-rs');
+    const binName = process.platform === 'win32' ? 'sks-rs.exe' : 'sks-rs';
+    const candidate = path.join(packageRoot(), 'crates', 'sks-core', 'target', 'release', binName);
     if (await exists(candidate))
         return candidate;
+    const cargoTarget = process.env.CARGO_TARGET_DIR;
+    if (cargoTarget) {
+        const redirected = path.join(cargoTarget, 'release', binName);
+        if (await exists(redirected))
+            return redirected;
+    }
     return null;
 }
 export async function runRustOrFallback(command, args = [], fallbackFn = async () => null) {

package/dist/core/safety/ssot-guard.js

@@ -1,4 +1,5 @@
 import { nowIso } from '../fsx.js';
+import { isRecord } from '../json/records.js';
 export const SSOT_GUARD_SCHEMA = 'sks.ssot-guard.v1';
 export const SSOT_GUARD_ARTIFACT = 'ssot-guard.json';
 export function buildSsotGuard(input = {}) {
@@ -111,9 +112,6 @@ export function validateSsotGuardArtifact(value) {
         issues.push('gate_rule');
     return { ok: issues.length === 0, issues };
 }
-function isRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
 function stringArray(value) {
     return Array.isArray(value) ? value.filter((item) => typeof item === 'string') : [];
 }

package/dist/core/search/benchmark.js

@@ -0,0 +1,358 @@
+import { performance } from 'node:perf_hooks';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { ensureDir, projectRoot, which, writeJsonAtomic } from '../fsx.js';
+import { search, searchBatch, searchCapabilities } from './provider.js';
+import { SEARCH_SCHEMA_VERSION } from './types.js';
+function percentile(sorted, p) {
+    if (!sorted.length)
+        return 0;
+    const idx = Math.min(sorted.length - 1, Math.max(0, Math.ceil((p / 100) * sorted.length) - 1));
+    return sorted[idx] || 0;
+}
+async function timeRuns(n, fn) {
+    const runs = [];
+    let last;
+    for (let i = 0; i < n; i += 1) {
+        const t0 = performance.now();
+        last = await fn();
+        runs.push(performance.now() - t0);
+    }
+    runs.sort((a, b) => a - b);
+    return { runs, last };
+}
+function summarize(id, name, runs, last, accuracy) {
+    const row = {
+        id,
+        name,
+        ok: last.ok,
+        engine: last.engine,
+        provider: last.provider,
+        wallMs: runs.reduce((a, b) => a + b, 0),
+        p50Ms: percentile(runs, 50),
+        p95Ms: percentile(runs, 95),
+        p99Ms: percentile(runs, 99),
+        processSpawns: last.processSpawns,
+        scannedFiles: last.scanned.files,
+        scannedBytes: last.scanned.bytes,
+        matchCount: last.matches.length,
+        cacheHit: last.cacheHit,
+        errors: last.errors
+    };
+    if (accuracy)
+        row.accuracy = accuracy;
+    return row;
+}
+export async function runSearchEngineBenchmark(opts = {}) {
+    const root = path.resolve(opts.root || (await projectRoot(process.cwd())));
+    const caps = await searchCapabilities(root);
+    const scenarios = [];
+    const rgBin = await which('rg');
+    {
+        const { runs, last } = await timeRuns(1, () => search({ schemaVersion: SEARCH_SCHEMA_VERSION, mode: 'files', root, limits: { maxMatches: 50_000 } }));
+        scenarios.push(summarize(1, 'files_cold', runs, last));
+    }
+    {
+        const { runs, last } = await timeRuns(3, () => search({ schemaVersion: SEARCH_SCHEMA_VERSION, mode: 'files', root, limits: { maxMatches: 50_000 } }));
+        scenarios.push(summarize(2, 'files_warm', runs, last));
+    }
+    {
+        const { runs, last } = await timeRuns(3, () => search({
+            schemaVersion: SEARCH_SCHEMA_VERSION,
+            mode: 'text',
+            root,
+            pattern: 'SearchProvider',
+            include: ['src/**'],
+            limits: { maxMatches: 200 }
+        }));
+        scenarios.push(summarize(3, 'text_simple', runs, last, {
+            tp: last.matches.length > 0 ? 1 : 0,
+            fp: 0,
+            fn: last.matches.length > 0 ? 0 : 1,
+            note: 'expects hits in src/core/search'
+        }));
+    }
+    {
+        const { runs, last } = await timeRuns(2, () => search({
+            schemaVersion: SEARCH_SCHEMA_VERSION,
+            mode: 'text',
+            root,
+            pattern: '검색|Search',
+            include: ['docs/**', 'src/core/search/**'],
+            limits: { maxMatches: 50 }
+        }));
+        scenarios.push(summarize(4, 'text_unicode_korean', runs, last));
+    }
+    {
+        const { runs, last } = await timeRuns(2, () => search({
+            schemaVersion: SEARCH_SCHEMA_VERSION,
+            mode: 'text',
+            root,
+            pattern: 'searchprovider',
+            caseSensitive: false,
+            include: ['src/core/search/**'],
+            limits: { maxMatches: 50 }
+        }));
+        scenarios.push(summarize(5, 'text_case_insensitive', runs, last));
+    }
+    {
+        const { runs, last } = await timeRuns(1, () => search({
+            schemaVersion: SEARCH_SCHEMA_VERSION,
+            mode: 'text',
+            root,
+            pattern: '.',
+            include: ['package.json'],
+            limits: { maxMatches: 5, maxBytes: 1024 * 1024 }
+        }));
+        scenarios.push(summarize(6, 'text_bounded_bytes', runs, last));
+    }
+    {
+        const { runs, last } = await timeRuns(1, () => search({
+            schemaVersion: SEARCH_SCHEMA_VERSION,
+            mode: 'files',
+            root,
+            query: 'node_modules',
+            limits: { maxMatches: 20 }
+        }));
+        const fp = last.matches.filter((m) => m.path.includes('node_modules/')).length;
+        scenarios.push(summarize(7, 'files_ignore_node_modules', runs, last, { tp: 0, fp, fn: 0, note: 'node_modules path hits should be 0' }));
+    }
+    {
+        const { runs, last } = await timeRuns(2, () => search({
+            schemaVersion: SEARCH_SCHEMA_VERSION,
+            mode: 'structure',
+            root,
+            pattern: 'function_declaration search',
+            language: 'typescript',
+            include: ['src/core/search/**'],
+            limits: { maxMatches: 20 }
+        }));
+        scenarios.push(summarize(8, 'structure_function_declaration', runs, last));
+    }
+    {
+        const { runs, last } = await timeRuns(1, () => search({
+            schemaVersion: SEARCH_SCHEMA_VERSION,
+            mode: 'structure',
+            root,
+            pattern: 'function_declaration foo',
+            language: 'python',
+            limits: { maxMatches: 5 }
+        }));
+        const ok = !last.ok && last.errors.some((e) => e.includes('structure_unsupported_language'));
+        scenarios.push({
+            ...summarize(9, 'structure_unsupported_language', runs, last),
+            ok
+        });
+    }
+    {
+        const { runs, last } = await timeRuns(1, () => search({
+            schemaVersion: SEARCH_SCHEMA_VERSION,
+            mode: 'symbol',
+            root,
+            query: 'search',
+            include: ['src/core/search/**'],
+            limits: { maxMatches: 100 }
+        }));
+        const bad = last.matches.filter((m) => m.confidence === 'exact_reference' && m.meta?.note).length;
+        scenarios.push(summarize(10, 'symbol_confidence', runs, last, {
+            tp: last.matches.filter((m) => m.confidence === 'exact_definition' || m.confidence === 'syntactic_reference' || m.confidence === 'text_candidate').length,
+            fp: bad,
+            fn: 0,
+            note: 'no text hits labeled exact_reference'
+        }));
+    }
+    {
+        const { runs, last } = await timeRuns(1, () => search({
+            schemaVersion: SEARCH_SCHEMA_VERSION,
+            mode: 'context',
+            root,
+            query: 'SearchProvider',
+            why: 'benchmark',
+            limits: { maxMatches: 40 }
+        }));
+        scenarios.push(summarize(11, 'context_triwiki', runs, last));
+    }
+    {
+        const t0 = performance.now();
+        const batch = await searchBatch({
+            schemaVersion: SEARCH_SCHEMA_VERSION,
+            root,
+            requests: Array.from({ length: 20 }, (_, i) => ({
+                schemaVersion: SEARCH_SCHEMA_VERSION,
+                mode: 'text',
+                root,
+                pattern: i % 2 === 0 ? 'export' : 'import',
+                include: ['src/core/search/**'],
+                limits: { maxMatches: 10 }
+            }))
+        });
+        const wall = performance.now() - t0;
+        scenarios.push({
+            id: 12,
+            name: 'batch_20_text',
+            ok: batch.ok,
+            engine: 'batch',
+            provider: batch.provider,
+            wallMs: wall,
+            p50Ms: wall / 20,
+            p95Ms: wall / 20,
+            p99Ms: wall / 20,
+            processSpawns: batch.processSpawns,
+            scannedFiles: batch.responses.reduce((n, r) => n + r.scanned.files, 0),
+            scannedBytes: batch.responses.reduce((n, r) => n + r.scanned.bytes, 0),
+            matchCount: batch.responses.reduce((n, r) => n + r.matches.length, 0),
+            cacheHit: batch.responses.some((r) => r.cacheHit),
+            errors: []
+        });
+    }
+    {
+        if (rgBin) {
+            const t0 = performance.now();
+            const r = spawnSync(rgBin, ['-n', '--glob', 'src/**', 'SearchProvider', '.'], {
+                cwd: root,
+                encoding: 'utf8',
+                maxBuffer: 8 * 1024 * 1024
+            });
+            const wall = performance.now() - t0;
+            const count = String(r.stdout || '')
+                .split('\n')
+                .filter(Boolean).length;
+            scenarios.push({
+                id: 13,
+                name: 'rg_cli_compare',
+                ok: r.status === 0 || r.status === 1,
+                engine: 'rg-cli',
+                provider: 'external',
+                wallMs: wall,
+                p50Ms: wall,
+                p95Ms: wall,
+                p99Ms: wall,
+                processSpawns: 1,
+                scannedFiles: -1,
+                scannedBytes: -1,
+                matchCount: count,
+                cacheHit: false,
+                errors: r.status === 0 || r.status === 1 ? [] : [String(r.stderr || 'rg_failed')]
+            });
+        }
+        else {
+            scenarios.push({
+                id: 13,
+                name: 'rg_cli_compare',
+                ok: true,
+                engine: 'rg-cli',
+                provider: 'external',
+                wallMs: 0,
+                p50Ms: 0,
+                p95Ms: 0,
+                p99Ms: 0,
+                processSpawns: 0,
+                scannedFiles: 0,
+                scannedBytes: 0,
+                matchCount: 0,
+                cacheHit: false,
+                errors: [],
+                accuracy: { tp: 0, fp: 0, fn: 0, note: 'rg not installed; comparison skipped' }
+            });
+        }
+    }
+    {
+        const { runs, last } = await timeRuns(1, () => search({
+            schemaVersion: SEARCH_SCHEMA_VERSION,
+            mode: 'files',
+            root,
+            query: '.git',
+            limits: { maxMatches: 5 }
+        }));
+        scenarios.push(summarize(14, 'files_skip_dot_git_objects', runs, last));
+    }
+    {
+        const last = await search({
+            schemaVersion: SEARCH_SCHEMA_VERSION,
+            mode: 'context',
+            root,
+            query: 'triwiki',
+            limits: { maxMatches: 10 }
+        });
+        scenarios.push({
+            id: 15,
+            name: 'context_token_budget',
+            ok: last.ok,
+            engine: last.engine,
+            provider: last.provider,
+            wallMs: last.durationMs,
+            p50Ms: last.durationMs,
+            p95Ms: last.durationMs,
+            p99Ms: last.durationMs,
+            processSpawns: last.processSpawns,
+            scannedFiles: last.scanned.files,
+            scannedBytes: last.scanned.bytes,
+            matchCount: last.matches.length,
+            cacheHit: last.cacheHit,
+            accuracy: {
+                tp: last.context?.tokenBudgetOmissions ?? 0,
+                fp: 0,
+                fn: 0,
+                note: 'tp field reused as tokenBudgetOmissions count'
+            },
+            errors: last.errors
+        });
+    }
+    const rss = process.memoryUsage().rss;
+    const report = {
+        schema: 'sks.search-engine-benchmark.v1',
+        generated_at: new Date().toISOString(),
+        root,
+        package_version: process.env.npm_package_version || null,
+        capabilities: caps,
+        scenarios,
+        summary: {
+            scenario_count: scenarios.length,
+            ok_count: scenarios.filter((s) => s.ok).length,
+            total_process_spawns: scenarios.reduce((n, s) => n + s.processSpawns, 0),
+            batch_spawns: scenarios.find((s) => s.id === 12)?.processSpawns ?? null,
+            rss_bytes: rss,
+            notes: [
+                'JS fallback is valid when sks-rs is not built.',
+                'rg CLI comparison is optional and not a core dependency.',
+                'Structure never falls back silently to text.'
+            ]
+        }
+    };
+    if (opts.writeArtifacts !== false) {
+        const outJson = path.join(root, '.sneakoscope/reports/search-engine-benchmark.json');
+        await ensureDir(path.dirname(outJson));
+        await writeJsonAtomic(outJson, report);
+        const md = renderBenchmarkMarkdown(report);
+        const outMd = path.join(root, 'docs/performance/search-engine-benchmark.md');
+        await ensureDir(path.dirname(outMd));
+        await fsp.writeFile(outMd, md, 'utf8');
+    }
+    return report;
+}
+function renderBenchmarkMarkdown(report) {
+    const lines = [
+        '# Search Engine Benchmark',
+        '',
+        `Generated: ${report.generated_at}`,
+        `Root: ${report.root}`,
+        '',
+        '| ID | Scenario | OK | Provider | p50ms | p95ms | Spawns | Matches |',
+        '|----|----------|----|----------|-------|-------|--------|---------|'
+    ];
+    for (const s of report.scenarios) {
+        lines.push(`| ${s.id} | ${s.name} | ${s.ok} | ${s.provider}/${s.engine} | ${s.p50Ms.toFixed(1)} | ${s.p95Ms.toFixed(1)} | ${s.processSpawns} | ${s.matchCount} |`);
+    }
+    lines.push('');
+    lines.push('## Summary');
+    lines.push('');
+    lines.push(`- OK: ${report.summary.ok_count}/${report.summary.scenario_count}`);
+    lines.push(`- Total process spawns across scenarios: ${report.summary.total_process_spawns}`);
+    lines.push(`- Batch-20 process spawns: ${report.summary.batch_spawns}`);
+    lines.push(`- RSS bytes: ${report.summary.rss_bytes}`);
+    for (const note of report.summary.notes)
+        lines.push(`- ${note}`);
+    lines.push('');
+    return lines.join('\n');
+}

package/dist/core/search/cache.js

@@ -0,0 +1,65 @@
+import crypto from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+const CACHE = new Map();
+const DEFAULT_TTL_MS = 30_000;
+export function searchCacheKey(kind, req) {
+    const head = gitHead(req.root);
+    const dirty = gitDirtyFingerprint(req.root);
+    const payload = {
+        kind,
+        schema: 1,
+        engine: 'sks.search.v1',
+        root: req.root,
+        head,
+        dirty,
+        mode: req.mode,
+        query: req.query || '',
+        pattern: req.pattern || '',
+        include: req.include || [],
+        exclude: req.exclude || [],
+        language: req.language || '',
+        caseSensitive: req.caseSensitive !== false,
+        extra: req.extra || ''
+    };
+    return crypto.createHash('sha256').update(JSON.stringify(payload)).digest('hex');
+}
+export function cacheGet(key) {
+    const hit = CACHE.get(key);
+    if (!hit)
+        return undefined;
+    if (Date.now() > hit.expires) {
+        CACHE.delete(key);
+        return undefined;
+    }
+    return hit.value;
+}
+export function cacheSet(key, value, ttlMs = DEFAULT_TTL_MS) {
+    CACHE.set(key, { expires: Date.now() + ttlMs, value });
+}
+export function cacheClear() {
+    CACHE.clear();
+}
+function gitHead(root) {
+    try {
+        const r = spawnSync('git', ['rev-parse', 'HEAD'], { cwd: root, encoding: 'utf8' });
+        if (r.status === 0)
+            return String(r.stdout || '').trim() || 'nohead';
+    }
+    catch {
+    }
+    return 'nohead';
+}
+function gitDirtyFingerprint(root) {
+    try {
+        const r = spawnSync('git', ['status', '--porcelain', '-uall'], { cwd: root, encoding: 'utf8', maxBuffer: 8 * 1024 * 1024 });
+        if (r.status !== 0)
+            return 'unknown';
+        const text = String(r.stdout || '');
+        if (!text.trim())
+            return 'clean';
+        return crypto.createHash('sha256').update(text).digest('hex').slice(0, 16);
+    }
+    catch {
+        return 'unknown';
+    }
+}