dsh-analyze 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-analyze contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,109 @@
-# Temporary Holding Version
+# dsh-analyze
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[English](README.md) | [中文](README.zh.md)
+
+**Local dataset analysis tools for [DSH](https://github.com/deepseek-ai/deepseek-harness).**  
+Ingest a CSV/JSONL once, keep large tables on disk, and let the model work
+through small JSON tool calls instead of dumping entire files into context.
+
+```text
+Without dsh-analyze          With dsh-analyze
+─────────────────────        ─────────────────────────────
+paste whole CSV → tokens     dataset_ingest  → { datasetId }
+context blows up             dataset_head    → 5 sample rows
+no audit trail               stats_describe  → column stats
+                             transform_agg   → grouped result
+                             (full table stays on disk)
+```
+
+## What it is (and is not)
+
+| Is | Is not |
+|---|---|
+| Local **file** dataset handles (CSV / JSONL) | A SQL database connector |
+| Offline Rust CLI + DSH tool plugin | A Python/R scientific stack |
+| Session-workspace sandbox with hard limits | A multi-tenant cloud service |
+
+## Install
+
+```bash
+dsh plugin --profile web add dsh-analyze
+```
+
+Place the `dsh-analyze` binary on `PATH`, or set:
+
+```bash
+export DSH_ANALYZE_CLI_PATH=/path/to/dsh-analyze
+```
+
+### Prebuilt binaries
+
+Download from GitHub Releases and verify against `SHA256SUMS`:
+
+| Target | Artifact |
+|---|---|
+| `x86_64-pc-windows-msvc` | `dsh-analyze-x86_64-pc-windows-msvc.zip` |
+| `aarch64-apple-darwin` | `dsh-analyze-aarch64-apple-darwin.tar.gz` |
+| `x86_64-apple-darwin` | `dsh-analyze-x86_64-apple-darwin.tar.gz` |
+| `x86_64-unknown-linux-gnu` | `dsh-analyze-x86_64-unknown-linux-gnu.tar.gz` |
+
+CLI lookup order: `DSH_ANALYZE_CLI_PATH` → legacy `INV_ANALYSIS_CLI_PATH` →
+`dsh-analyze` on `PATH` → plugin logs a warning and registers nothing.
+
+### Build from source
+
+```bash
+cargo build --release -p dsh-analyze
+```
+
+The crate is pure-std and builds offline.
+
+## Tools
+
+| Tool | Purpose |
+|---|---|
+| `dataset_ingest` | Load a workspace CSV/JSONL → `datasetId` + schema summary |
+| `dataset_head` | Up to 20 sample rows |
+| `dataset_schema` | Column names, dtypes, row count |
+| `dataset_list` | All datasets in this workspace store |
+| `dataset_export` | Write full table to CSV under outputs/ |
+| `dataset_rm` | Permanently remove a dataset |
+| `stats_describe` | Null counts, min/max/mean/std/quartiles |
+| `transform_agg` | Filter / project / group-by / aggregate |
+
+## Limits & data root
+
+```text
+<workspace>/.dsh-analyze/{datasets,outputs,tmp}/
+```
+
+| Env | Default | Meaning |
+|---|---|---|
+| `DSH_ANALYZE_CLI_PATH` | — | CLI executable path |
+| `DSH_ANALYZE_WORKSPACE` | `process.cwd()` | Session workspace root |
+| `DSH_ANALYZE_MAX_ROWS` | 5,000,000 | Ingest row cap |
+| `DSH_ANALYZE_MAX_INGEST_BYTES` | 256 MiB | Ingest byte cap |
+| `DSH_ANALYZE_DEFAULT_ROW_LIMIT` | 1000 | Agg default row limit |
+
+Legacy `INV_ANALYSIS_*` names are still accepted (new name wins).
+
+Results returned to the model are intentionally small (samples ≤ 20 rows).
+Full tables go through `outLabel` / `dataset_export` and stay on disk.
+
+## Comparison
+
+| | dsh-analyze | SQL connectors | Notebook stacks (Python/R) |
+|---|---|---|---|
+| Input | Local CSV/JSONL | Live database | Anything |
+| Network | Never | Required | Often |
+| Model token cost | Small JSON per step | Query results | Kernel output |
+| Runtime | Single static binary | Drivers + server | Full interpreter |
+
+## Security
+
+Path confinement, credential-path deny lists, env whitelist, and hard
+limits — see [SECURITY.md](SECURITY.md) and [docs/security.md](docs/security.md).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: dsh-analyze
+      name: 'dsh-analyze'

package/dist/cli.d.ts

@@ -0,0 +1,55 @@
+import type { AnalysisLimits } from './limits.js';
+export interface AnalyzeCliResult {
+    ok: true;
+    data: Record<string, unknown>;
+}
+export declare class AnalyzeCliError extends Error {
+    readonly code: string;
+    readonly stderr: string;
+    constructor(code: string, message: string, stderr?: string);
+}
+export interface RunCliOptions {
+    workspaceRoot: string;
+    cliPath: string;
+    /** Extra argv inserted before analyze args (e.g. mock script path when cliPath is node). */
+    cliPrefixArgs?: readonly string[];
+    args: string[];
+    limits: AnalysisLimits;
+    signal?: AbortSignal;
+}
+export declare function runAnalyzeCli(options: RunCliOptions): Promise<AnalyzeCliResult>;
+/** Probe CLI version/capabilities (T0 §4.2). Does not require a real workspace file. */
+export declare function probeAnalyzeCli(options: {
+    workspaceRoot: string;
+    cliPath: string;
+    cliPrefixArgs?: readonly string[];
+    limits: AnalysisLimits;
+}): Promise<{
+    version: string;
+    capabilities: string[];
+}>;
+/** Sync probe for register-time gates (apply path is sync). */
+export type AnalyzeCliProbeResult = {
+    ok: true;
+    version: string;
+    capabilities: string[];
+} | {
+    ok: false;
+    error: string;
+};
+/** Clear probe cache (tests / after DSH_ANALYZE_CLI_PATH change). */
+export declare function clearAnalyzeCliProbeCache(): void;
+/**
+ * Resolve analysis CLI executable: `DSH_ANALYZE_CLI_PATH` → legacy
+ * `INV_ANALYSIS_CLI_PATH` (compat window) → bare `dsh-analyze` on PATH.
+ */
+export declare function resolveAnalysisCliPath(env?: Record<string, string | undefined>): string;
+export declare function probeAnalyzeCliSync(options: {
+    workspaceRoot: string;
+    cliPath: string;
+    cliPrefixArgs?: readonly string[];
+    timeoutMs?: number;
+    /** Bypass sticky cache (tests / forced re-probe). */
+    force?: boolean;
+}): AnalyzeCliProbeResult;
+export declare function rethrowAnalysis(e: unknown): never;

package/dist/cli.js

@@ -0,0 +1,221 @@
+import { spawn, spawnSync } from 'node:child_process';
+import { AnalysisPathError } from './paths.js';
+export class AnalyzeCliError extends Error {
+    code;
+    stderr;
+    constructor(code, message, stderr = '') {
+        super(message);
+        this.name = 'AnalyzeCliError';
+        this.code = code;
+        this.stderr = stderr;
+    }
+}
+/** Kill process tree on Windows; plain kill elsewhere. */
+function killChildTree(child) {
+    if (process.platform === 'win32' && typeof child.pid === 'number' && child.pid > 0) {
+        try {
+            const killer = spawn('taskkill', ['/pid', String(child.pid), '/T', '/F'], {
+                stdio: 'ignore',
+                windowsHide: true,
+            });
+            const maybeUnref = killer;
+            if (typeof maybeUnref.unref === 'function')
+                maybeUnref.unref();
+        }
+        catch { /* fall through to kill */ }
+    }
+    try {
+        child.kill();
+    }
+    catch { /* already dead */ }
+}
+function mapCliFailure(exitCode, stderr) {
+    const line = stderr.split(/\r?\n/).map(s => s.trim()).filter(Boolean).pop() ?? 'analysis failed';
+    if (line.startsWith('analysis/')) {
+        const code = line.split(':')[0] ?? 'analysis/cli-failed';
+        return new AnalyzeCliError(code, line, stderr);
+    }
+    if (exitCode === 5) {
+        return new AnalyzeCliError('analysis/unknown-dataset', line, stderr);
+    }
+    if (exitCode === 3) {
+        return new AnalyzeCliError('analysis/limit', line, stderr);
+    }
+    if (exitCode === 2) {
+        return new AnalyzeCliError('analysis/invalid-args', line, stderr);
+    }
+    return new AnalyzeCliError('analysis/cli-failed', line, stderr);
+}
+export async function runAnalyzeCli(options) {
+    const { workspaceRoot, cliPath, cliPrefixArgs, args, limits, signal } = options;
+    const argv = [...(cliPrefixArgs ?? []), '--workspace', workspaceRoot, ...args];
+    return await new Promise((resolvePromise, rejectPromise) => {
+        const child = spawn(cliPath, argv, {
+            cwd: workspaceRoot,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            signal,
+            windowsHide: true,
+            env: {
+                PATH: process.env.PATH,
+                DSH_ANALYZE_MAX_ROWS: String(limits.maxRows),
+                DSH_ANALYZE_MAX_INGEST_BYTES: String(limits.maxIngestBytes),
+                DSH_ANALYZE_DEFAULT_ROW_LIMIT: String(limits.defaultRowLimit),
+                ...(process.env.NODE_ENV ? { NODE_ENV: process.env.NODE_ENV } : {}),
+            },
+        });
+        let stdout = '';
+        let stderr = '';
+        let settled = false;
+        const timer = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            killChildTree(child);
+            rejectPromise(new AnalyzeCliError('analysis/limit', `analysis timed out after ${limits.timeoutMs}ms`));
+        }, limits.timeoutMs);
+        const timerLike = timer;
+        if (typeof timerLike.unref === 'function') {
+            timerLike.unref();
+        }
+        child.stdout.setEncoding('utf8');
+        child.stderr.setEncoding('utf8');
+        child.stdout.on('data', (chunk) => {
+            stdout += chunk;
+            if (stdout.length > limits.maxOutputBytes * 4) {
+                killChildTree(child);
+            }
+        });
+        child.stderr.on('data', (chunk) => {
+            stderr += chunk;
+            if (stderr.length > 64_000)
+                stderr = stderr.slice(-64_000);
+        });
+        child.on('error', (err) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            rejectPromise(new AnalyzeCliError('analysis/cli-missing', err.message));
+        });
+        child.on('close', (code) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (code !== 0) {
+                rejectPromise(mapCliFailure(code, stderr));
+                return;
+            }
+            try {
+                const trimmed = stdout.trim();
+                const data = JSON.parse(trimmed);
+                if (data.ok !== true) {
+                    rejectPromise(new AnalyzeCliError('analysis/cli-failed', trimmed.slice(0, 500), stderr));
+                    return;
+                }
+                resolvePromise({ ok: true, data });
+            }
+            catch {
+                rejectPromise(new AnalyzeCliError('analysis/cli-failed', 'invalid CLI JSON', stderr + '\n' + stdout.slice(0, 200)));
+            }
+        });
+    });
+}
+/** Probe CLI version/capabilities (T0 §4.2). Does not require a real workspace file. */
+export async function probeAnalyzeCli(options) {
+    const result = await runAnalyzeCli({
+        workspaceRoot: options.workspaceRoot,
+        cliPath: options.cliPath,
+        cliPrefixArgs: options.cliPrefixArgs,
+        args: ['version'],
+        limits: options.limits,
+    });
+    const data = result.data;
+    const version = typeof data.version === 'string' ? data.version : '';
+    const capabilities = Array.isArray(data.capabilities)
+        ? data.capabilities.filter((c) => typeof c === 'string')
+        : [];
+    if (!version || capabilities.length === 0) {
+        throw new AnalyzeCliError('analysis/cli-missing', 'CLI version probe returned incomplete capabilities');
+    }
+    return { version, capabilities };
+}
+/** Process-local probe cache: success is sticky; failure retries after TTL. */
+const probeCache = new Map();
+const PROBE_FAIL_TTL_MS = 30_000;
+/** Clear probe cache (tests / after DSH_ANALYZE_CLI_PATH change). */
+export function clearAnalyzeCliProbeCache() {
+    probeCache.clear();
+}
+/**
+ * Resolve analysis CLI executable: `DSH_ANALYZE_CLI_PATH` → legacy
+ * `INV_ANALYSIS_CLI_PATH` (compat window) → bare `dsh-analyze` on PATH.
+ */
+export function resolveAnalysisCliPath(env = process.env) {
+    const preferred = env.DSH_ANALYZE_CLI_PATH;
+    if (preferred && preferred.trim())
+        return preferred.trim();
+    const legacy = env.INV_ANALYSIS_CLI_PATH;
+    if (legacy && legacy.trim())
+        return legacy.trim();
+    return 'dsh-analyze';
+}
+function probeCacheKey(workspaceRoot, cliPath, prefix) {
+    return JSON.stringify([cliPath, workspaceRoot, ...(prefix ?? [])]);
+}
+export function probeAnalyzeCliSync(options) {
+    const key = probeCacheKey(options.workspaceRoot, options.cliPath, options.cliPrefixArgs);
+    if (!options.force) {
+        const hit = probeCache.get(key);
+        if (hit) {
+            if (hit.result.ok)
+                return hit.result;
+            if (Date.now() - hit.at < PROBE_FAIL_TTL_MS)
+                return hit.result;
+        }
+    }
+    const result = probeAnalyzeCliUncached(options);
+    probeCache.set(key, { result, at: Date.now() });
+    return result;
+}
+function probeAnalyzeCliUncached(options) {
+    const argv = [...(options.cliPrefixArgs ?? []), '--workspace', options.workspaceRoot, 'version'];
+    try {
+        const r = spawnSync(options.cliPath, argv, {
+            encoding: 'utf8',
+            timeout: options.timeoutMs ?? 10_000,
+            windowsHide: true,
+            env: {
+                PATH: process.env.PATH,
+                ...(process.env.NODE_ENV ? { NODE_ENV: process.env.NODE_ENV } : {}),
+            },
+        });
+        if (r.error) {
+            return { ok: false, error: r.error.message };
+        }
+        const stdout = r.stdout ?? '';
+        const stderr = r.stderr ?? '';
+        if (r.status !== 0) {
+            return { ok: false, error: stderr.slice(0, 200) || `exit ${String(r.status)}` };
+        }
+        const data = JSON.parse(stdout.trim());
+        if (data.ok !== true || typeof data.version !== 'string' || !Array.isArray(data.capabilities)) {
+            return { ok: false, error: 'invalid CLI version JSON' };
+        }
+        const capabilities = data.capabilities.filter((c) => typeof c === 'string');
+        if (!data.version || capabilities.length === 0) {
+            return { ok: false, error: 'CLI version probe returned incomplete capabilities' };
+        }
+        return { ok: true, version: data.version, capabilities };
+    }
+    catch (e) {
+        return { ok: false, error: e instanceof Error ? e.message : String(e) };
+    }
+}
+export function rethrowAnalysis(e) {
+    if (e instanceof AnalysisPathError || e instanceof AnalyzeCliError) {
+        throw e;
+    }
+    const msg = e instanceof Error ? e.message : String(e);
+    throw new AnalyzeCliError('analysis/cli-failed', msg);
+}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Host half of the dsh-analyze DSH plugin.
+ *
+ * Registers session-dataset analysis tools (`dataset_*`, `stats_describe`,
+ * `transform_agg`) on the global tool registry when the `dsh-analyze` CLI
+ * is discoverable. Fail-soft: a missing CLI logs a warning and registers
+ * nothing — the profile stays usable without analysis tools.
+ *
+ * Workspace: `DSH_ANALYZE_WORKSPACE` if set, else process cwd. Datasets live
+ * under `<workspace>/.dsh-analyze/{datasets,outputs,tmp}` and never leave it.
+ *
+ * CLI path: `DSH_ANALYZE_CLI_PATH` → legacy `INV_ANALYSIS_CLI_PATH` → PATH
+ * `dsh-analyze`.
+ * @module dsh-analyze
+ */
+import type { Context } from '@deepseek-ai/cordis';
+export declare function apply(ctx: Context): void;

package/dist/index.js

@@ -0,0 +1,57 @@
+/**
+ * Host half of the dsh-analyze DSH plugin.
+ *
+ * Registers session-dataset analysis tools (`dataset_*`, `stats_describe`,
+ * `transform_agg`) on the global tool registry when the `dsh-analyze` CLI
+ * is discoverable. Fail-soft: a missing CLI logs a warning and registers
+ * nothing — the profile stays usable without analysis tools.
+ *
+ * Workspace: `DSH_ANALYZE_WORKSPACE` if set, else process cwd. Datasets live
+ * under `<workspace>/.dsh-analyze/{datasets,outputs,tmp}` and never leave it.
+ *
+ * CLI path: `DSH_ANALYZE_CLI_PATH` → legacy `INV_ANALYSIS_CLI_PATH` → PATH
+ * `dsh-analyze`.
+ * @module dsh-analyze
+ */
+import { probeAnalyzeCliSync, resolveAnalysisCliPath } from './cli.js';
+import { ANALYSIS_TOOL_NAMES } from './policy.js';
+import { createAnalysisToolDefinitions } from './tools.js';
+function getTools(ctx) {
+    try {
+        return ctx.root.get('tools');
+    }
+    catch {
+        return undefined;
+    }
+}
+function workspaceRoot() {
+    const env = process.env.DSH_ANALYZE_WORKSPACE;
+    if (env && env.trim())
+        return env.trim();
+    return process.cwd();
+}
+export function apply(ctx) {
+    const tools = getTools(ctx);
+    if (!tools || typeof tools.register !== 'function') {
+        console.warn('[dsh-analyze] tools runtime unavailable; analysis tools not registered');
+        return;
+    }
+    const cliPath = resolveAnalysisCliPath();
+    const ws = workspaceRoot();
+    const probe = probeAnalyzeCliSync({ workspaceRoot: ws, cliPath, timeoutMs: 10_000 });
+    if (!probe.ok) {
+        console.warn('[dsh-analyze] CLI not found or probe failed; tools not registered:', probe.error);
+        return;
+    }
+    const defs = createAnalysisToolDefinitions({ cliPath, workspaceRoot: ws });
+    const offs = ANALYSIS_TOOL_NAMES.map((name) => tools.register(defs[name]));
+    console.info(`[dsh-analyze] registered ${offs.length} tools (cli ${probe.version}) at ${ws}`);
+    ctx.effect(() => () => {
+        for (const off of offs) {
+            try {
+                off();
+            }
+            catch { /* already gone */ }
+        }
+    }, 'dsh-analyze-tools');
+}

package/dist/limits.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Shared limits for analysis tools / CLI bridge.
+ * @module @investigator/backend/analysis/limits
+ */
+export interface AnalysisLimits {
+    timeoutMs: number;
+    maxOutputBytes: number;
+    maxSampleRows: number;
+    maxHeadRows: number;
+    maxIngestBytes: number;
+    maxRows: number;
+    defaultRowLimit: number;
+    maxSpecBytes: number;
+    maxAggLimit: number;
+}
+export declare const DEFAULT_ANALYSIS_LIMITS: AnalysisLimits;
+export declare function clampHeadN(n: unknown, limits: AnalysisLimits): number;

package/dist/limits.js

@@ -0,0 +1,19 @@
+/**
+ * Shared limits for analysis tools / CLI bridge.
+ * @module @investigator/backend/analysis/limits
+ */
+export const DEFAULT_ANALYSIS_LIMITS = {
+    timeoutMs: 60_000,
+    maxOutputBytes: 262_144,
+    maxSampleRows: 8,
+    maxHeadRows: 20,
+    maxIngestBytes: 268_435_456,
+    maxRows: 5_000_000,
+    defaultRowLimit: 1000,
+    maxSpecBytes: 32_768,
+    maxAggLimit: 5000,
+};
+export function clampHeadN(n, limits) {
+    const raw = typeof n === 'number' && Number.isFinite(n) ? Math.floor(n) : 5;
+    return Math.min(Math.max(raw, 1), limits.maxHeadRows);
+}

package/dist/paths.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Workspace path confinement for analysis datasets.
+ * @module @investigator/backend/analysis/paths
+ */
+export declare class AnalysisPathError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare function newDatasetId(): string;
+export declare function analysisRoot(workspaceRoot: string): string;
+export declare function datasetsDir(workspaceRoot: string): string;
+export declare function outputsDir(workspaceRoot: string): string;
+export declare function tmpDir(workspaceRoot: string): string;
+/**
+ * Per-session analysis workspace under a profile dir.
+ * Never the profile root itself — sessions cannot read each other's data
+ * or profile credentials. Creates the directory once.
+ */
+export declare function ensureSessionWorkspaceRoot(profileDir: string, sessionId: string): string;
+/** Resolve user path and require it stays under workspaceRoot. */
+export declare function resolveInWorkspace(workspaceRoot: string, userPath: string): string;
+export declare function validateDatasetId(id: string): void;

package/dist/paths.js

@@ -0,0 +1,60 @@
+/**
+ * Workspace path confinement for analysis datasets.
+ * @module @investigator/backend/analysis/paths
+ */
+import { randomBytes } from 'node:crypto';
+import { existsSync, mkdirSync } from 'node:fs';
+import { isAbsolute, join, normalize, resolve, sep } from 'node:path';
+export class AnalysisPathError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'AnalysisPathError';
+        this.code = code;
+    }
+}
+export function newDatasetId() {
+    return `ds_${randomBytes(6).toString('hex')}`;
+}
+export function analysisRoot(workspaceRoot) {
+    return join(workspaceRoot, '.dsh-analyze');
+}
+export function datasetsDir(workspaceRoot) {
+    return join(analysisRoot(workspaceRoot), 'datasets');
+}
+export function outputsDir(workspaceRoot) {
+    return join(analysisRoot(workspaceRoot), 'outputs');
+}
+export function tmpDir(workspaceRoot) {
+    return join(analysisRoot(workspaceRoot), 'tmp');
+}
+/**
+ * Per-session analysis workspace under a profile dir.
+ * Never the profile root itself — sessions cannot read each other's data
+ * or profile credentials. Creates the directory once.
+ */
+export function ensureSessionWorkspaceRoot(profileDir, sessionId) {
+    const sid = sessionId.replace(/[^A-Za-z0-9_-]/g, '_').slice(0, 128) || 'anon';
+    const root = join(profileDir, 'inv-analysis', 'sessions', sid);
+    if (!existsSync(root)) {
+        mkdirSync(root, { recursive: true });
+    }
+    return root;
+}
+/** Resolve user path and require it stays under workspaceRoot. */
+export function resolveInWorkspace(workspaceRoot, userPath) {
+    if (!userPath || typeof userPath !== 'string') {
+        throw new AnalysisPathError('analysis/invalid-path', 'path is required');
+    }
+    const ws = resolve(workspaceRoot);
+    const abs = isAbsolute(userPath) ? normalize(userPath) : resolve(ws, userPath);
+    if (abs !== ws && !abs.startsWith(ws + sep)) {
+        throw new AnalysisPathError('analysis/invalid-path', 'path escapes workspace');
+    }
+    return abs;
+}
+export function validateDatasetId(id) {
+    if (!/^ds_[a-f0-9]{8,32}$/.test(id)) {
+        throw new AnalysisPathError('analysis/invalid-args', 'bad datasetId');
+    }
+}

package/dist/policy.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Expert allowlist helpers for analysis tools.
+ * @module @investigator/backend/analysis/policy
+ */
+export declare const ANALYSIS_TOOL_NAMES: readonly ["dataset_ingest", "dataset_head", "dataset_schema", "dataset_list", "dataset_export", "dataset_rm", "stats_describe", "transform_agg"];
+export type AnalysisToolName = (typeof ANALYSIS_TOOL_NAMES)[number];
+export declare function isAnalysisToolName(name: string): name is AnalysisToolName;
+/**
+ * Analysis tools to register on an agent scope for one expert.
+ * - deny-all → none
+ * - explicit `analysisTools` wins (any mode except deny-all)
+ * - allowlist → intersection with toolAllowlist
+ * - unconfigured without analysisTools → none (safe default)
+ */
+export declare function analysisToolsForExpert(input: {
+    mode: 'unconfigured' | 'deny-all' | 'allowlist';
+    toolAllowlist: readonly string[];
+    analysisTools?: readonly string[];
+}): AnalysisToolName[];

package/dist/policy.js

@@ -0,0 +1,36 @@
+/**
+ * Expert allowlist helpers for analysis tools.
+ * @module @investigator/backend/analysis/policy
+ */
+export const ANALYSIS_TOOL_NAMES = [
+    'dataset_ingest',
+    'dataset_head',
+    'dataset_schema',
+    'dataset_list',
+    'dataset_export',
+    'dataset_rm',
+    'stats_describe',
+    'transform_agg',
+];
+export function isAnalysisToolName(name) {
+    return ANALYSIS_TOOL_NAMES.includes(name);
+}
+/**
+ * Analysis tools to register on an agent scope for one expert.
+ * - deny-all → none
+ * - explicit `analysisTools` wins (any mode except deny-all)
+ * - allowlist → intersection with toolAllowlist
+ * - unconfigured without analysisTools → none (safe default)
+ */
+export function analysisToolsForExpert(input) {
+    if (input.mode === 'deny-all')
+        return [];
+    if (input.analysisTools && input.analysisTools.length > 0) {
+        const set = new Set(input.analysisTools);
+        return ANALYSIS_TOOL_NAMES.filter(n => set.has(n));
+    }
+    if (input.mode !== 'allowlist')
+        return [];
+    const allow = new Set(input.toolAllowlist);
+    return ANALYSIS_TOOL_NAMES.filter(n => allow.has(n));
+}