/ijfw-compute

name: ijfw-compute
description: "Use when the user says: 'compute', 'crunch this', 'analyze logs', 'aggregate the data', 'run a script', 'dedupe', 'count by', 'top N', or any data-shaping ask. Replaces dumping raw data into context with sandboxed script execution."
context: fork
model: sonnet

Compute over read. When data is large or repetitive, run a sandboxed script and surface only the result. The four trees below decide which lever to pull.

Compute tree -- run a sandboxed script

Use when the input is bigger than the answer: log files, CSV/JSON dumps, file-tree walks, repeated string transforms, aggregate stats, deduping. Call `ijfw_run compute:python "<script>"` for pandas / numpy / stdlib parsing. Call `ijfw_run compute:js "<script>"` for JSON shape-checks, regex sweeps, quick numeric work. Sandbox is allowlist filesystem (cwd + project root) + best-effort OS-level network deny; opt-in with `IJFW_COMPUTE_NET=1` if the script needs egress. Default timeout 30s, hard cap 300s via `IJFW_COMPUTE_TIMEOUT_MS`. Output cap 100MB; overflow lands in the on-disk log.

Example: a 40MB nginx log. Instead of reading 200k lines into context, run `ijfw_run compute:python "import collections,sys;c=collections.Counter();[c.update([l.split()[8]]) for l in open('access.log')];print(c.most_common(10))"` and surface the top-10 status-code summary.

Read tree -- skip compute, just read

Use when the file is small (<2k lines), the task is a code edit or config tweak, or the agent needs to reason about structure rather than aggregate content. Direct Read is cheaper than spinning a subprocess; compute has fixed startup overhead.

Example: editing a single function in `mcp-server/src/server.js`. Read the file, edit it, move on. No compute call needed.

Index tree -- write findings to FTS5 for later search

Use after a compute or research step produces a finding worth recalling across sessions. Call `ijfw_run index:source <kind> <body>` to write into the per-project FTS5 db at `<project>/.ijfw/index/compute.db`. Schema is `raw` table (source_kind, source, session_id, project_root, body, ts). Per-write `PRAGMA quick_check` guards integrity.

Citation provenance (C9.6): pass `--source=<pointer>` before the body to attach an origin (file path / observation kind / skill name). Search hits surface this pointer + the session_id so users can trace where each row came from. Omitted -> source stays NULL.

Example: after analyzing the nginx log, index the verdict: `ijfw_run index:source compute_output --source=logs/access.log "Top error 502 from upstream X 2026-05-08; 4.1% of requests"`. Next session can search for it via the search tree below.

Search tree -- query the existing index

Use before computing again. If a previous session already answered a similar question, recall it instead of recomputing. Call `ijfw_memory_search compute:query "<query>"` for top-k FTS5 hits scoped to the current project. Each hit returns body + source_kind + source + session_id + ts; the agent decides whether the cached finding is still fresh and can cite the source pointer.

Stemmed BM25 (C9.4): the FTS5 tokenizer is `porter unicode61`. Morphological variants collapse: "authenticate" / "authenticating" / "authentication" share a stem; "configure" / "configured" / "configuring" share a stem.

Synonym expansion (C9.5): default-on. Bare tokens expand against ~80 coding- domain pairs (db <-> database, auth <-> authentication, perf <-> performance, etc.). The result envelope reports `synonym_matches: { token: [expansions] }` so callers see what fired. Disable per-process via `IJFW_SYNONYM_EXPAND=0`.

Session filter (C9.6): append `--session=<id>` to a query to scope hits to a single session. The envelope echoes the filter as `session_filter`.

Example: user asks "what was the top nginx error last week?" Run `ijfw_memory_search compute:query "nginx error rate"` first; if a recent indexed finding lands, surface it directly. If empty or stale, fall back to the compute tree on fresh log data.

Rules

• Default to compute when input >> output. Default to read when input <= output.
• Always index actionable findings; don't index raw dumps.
• Always search before computing on a recurring question.
• Subprocess runs are sandboxed -- treat untrusted script bodies as

untrusted; never disable the sandbox to make a script work.

• One compute-nudge per session via the PreToolUse hook; further nudges

are suppressed.