---
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.