FEA — Forward Engineer Anything

REA taught agents to read. FEA teaches them to rebuild — with proof.

FEA is an open-source MCP server + CLI that turns any software artifact into a verified working reimplementation:

ingest → capture → spec → synthesize → verify → export

• Ingest a target you are authorized to analyze (CLI binary, HTTP API in v0.1).

• Capture black-box behavior into I/O vectors.

• Extract a machine-checkable BehaviorSpec (Zod-validated, evidence-linked).

• Synthesize behind a clean-room firewall — the synthesis agent sees behavior only, never decompiled code, addresses, or symbols.

• Verify with a differential parity harness: original vs rebuild, same vectors, measured score.

• Export a reproducible evidence pack (spec + parity report + hash-chained provenance log).

Positioning: FEA does not replace REA — it consumes REA (or any analysis tool) as its reader. REA reads. FEA rebuilds.

Install (once published): npm i -g fea-agents — the fea binary. From source: pnpm install && pnpm build.

What v1.1 is

No more wrapper scripts. v1.1 makes the self-rebuilding loop one command:

• Agent presets (new @fea/agents package) — fea evolve --agent-preset codex (or claude-code) instead of --agent-cmd + a hand-written wrapper. The preset ships a prompt renderer (synthesis context + failing vectors → a clean-room prompt: behavior only, output code only) and a wrapper that invokes the model CLI (codex exec / claude -p), writes the code to <store>/evolve/, and prints {"rebuildPath"}. --agent-out-ext picks the file extension. Custom agents still work via --agent-cmd. Model CLIs must be installed and authenticated on the machine running evolve — FEA can't log you in.

• fea promote — bless a rebuild's new behavior as expected. After an intentional behavior change (new feature), the old vectors are stale: promote replays the vector set's inputs against the rebuild and stores a NEW vector set with its outputs. The new set is the rebuild's contract — verify passes against it. MCP tool: fea_promote (19 total), policy-gated as ask (it executes the rebuild).

Related MCP server: PEA MCP Server

What v1.0 is

The Twin Era. v1.0 turns FEA from a tool into a movement:

• Twin registry (new @fea/twins package) — fea twin publish mints a registry entry for a verified pack; fea twin search finds twins; fea twin get fetches a twin and re-verifies on arrival (pack-verify

  • manifest sha256 — trust, but verify). Publish is gated: the pack must pass pack-verify AND contain only manifest-listed files (nothing smuggled in — never the original binary). Policy-gated as ask by default. MCP tools: fea_twin_publish, fea_twin_search, fea_twin_get (18 total).

• Killer demo — examples/twin-demo/: a word-count utility twinned clean-room, parity 100, published as wc-twin@1.0.0, fetched back and re-verified. The whole Twin Era story in one directory.

The v1.0 index backend is a local JSON file (<store>/twins/index.json, overridable). It speaks the same TwinEntry shape as the planned GitHub-backed fea-twins index — swapping the backend later changes no entries.

What v0.9 was

The Self-Rebuilding Era begins. v0.9 closes the biggest open loop in FEA — until now the synthesis step belonged to the human:

• fea evolve — drives an external agent program until parity converges. The agent gets ONLY the firewalled synthesis context (behavior) plus the previous attempt's failing vectors — never the original binary's path (FEA fails closed if it ever leaks). The agent prints {"rebuildPath": "..."} on stdout; FEA scores each attempt with the parity oracle and stops at the target score or max attempts. FEA becomes the reward function; the agent does the writing.

• Agent protocol is just stdin/stdout JSON — wire anything: an LLM CLI wrapper, a synthesis script, a build hook. examples/evolve-agent/ shows the protocol with a scripted mock.

What v0.8 was

What changed. v0.8 answers the question every rebuild iteration asks:

• fea diff --a <set> --b <set> (MCP: fea_diff_vectorsets, 15th tool) — which vectors were added, removed, or changed between two captures. Vectors are matched by input identity (what was asked), so independently captured sets still line up; changed vectors list the exact field paths that differ (output.stdout, weight, …).

What v0.7 was

Continuous proof. v0.7 closes the iteration loop:

• fea watch — re-runs parity every time the rebuild changes (binary: mtime+size; API: content hash of the base URL). Prints each run's score and the delta vs the pinned baseline. Ctrl-C stops. Policy ask needs --yes (approvals don't work in a watch loop).

• fea pin — pins a parity report as the baseline for a (target, vector set) pair. Later fea verify runs report Δ vs baseline so regressions are visible at a glance.

• fea verify --junit <path> — JUnit XML for CI dashboards: one testcase per vector, failures carrying the expected/actual diff.

What v0.6 was

Proof of proof. v0.6 makes FEA's own guarantees verifiable:

• fea pack-verify <path> (MCP: fea_verify_pack, 14th tool) — checks an evidence pack end to end: manifest parses, every file present with matching sha256, spec re-validates against BehaviorSpec v1, report id matches, and the hash-chained provenance log verifies. A tampered pack fails with the exact broken check named.

• Chain pinpointing — verifyProvenanceChain reports the first broken entry (brokenAt + reason) instead of a bare boolean.

• Doctor+ — fea doctor now also validates the policy file and reports Android tool presence (adb/emulator) for the APK story.

• APK harness, honestly thin — AppHarness interface + ManualHarness (you launch the app, FEA takes its HTTP base URL) + probeAndroidTools. The emulator-backed harness waits for a machine with the Android SDK; until then the documented path is launch-it-yourself + --rebuild-url.

Dropped honestly: the proxy SSE transport from the old roadmap — it was a transport swap with no user-visible benefit over the working /call protocol, so it stays out rather than shipping theater.

APIs & onboarding. v0.5 adds:

• HTTP parity — the oracle now replays HTTP vectors against two base URLs: fea verify --target <id> --rebuild-url http://127.0.0.1:3001 --vectorset <id>. Same path+query on both sides; compares status, headers, and body after normalization. Mixed CLI+HTTP vector sets work (each kind needs its rebuild).

• fea init — scaffolds a project directory: fea.policy.json (recommended), capture-plans.json (examples), FEA.md (workflow cheat-sheet), .fea/ store. fea init my-api --kind http-api --target http://127.0.0.1:3000 ingests immediately.

• New normalizer packs — ansi (strip terminal color codes) and json (structural: parse, sort keys, re-stringify — auditable in the report).

Note: the proxy SSE transport from the v0.4 roadmap stays open — HTTP parity was the bigger real gap, so it went first.

What v0.5 was

What v0.4 was

Scale & ship. v0.4 adds:

• Persistent reader sessions — fea reader serve holds ONE REA session and shares it over loopback HTTP (127.0.0.1 + bearer token), so document-stateful workflows (open_binary → list_strings) work across separate fea read calls. Use --proxy-url / --proxy-token on fea read (or readerProxyUrl on the MCP tool).

• Normalizer packs — named, auditable noise filters: http (RFC1123 dates, ETags), log (timestamps, pids), path (temp/home dirs, ports), ids (UUIDs, hex tokens). fea verify --packs http,log — additive on the defaults, all listed in the parity report.

• apk target kind — APK files fingerprint like native binaries; the actual analysis goes through the REA reader (JADX/apktool on the reader's machine).

• npm-publish-ready — every package has publish metadata, the CLI publishes as fea-agents (name verified free; fea itself is taken), npm pack --dry-run verified. Steps in docs/PUBLISH.md — the publish itself needs your npm login, so it's yours to run.

Quick start

pnpm install
pnpm verify        # typecheck + lint + tests + build (must be green)

# toy demo: rebuild adder.js with 100 parity
node apps/cli/dist/index.js ingest ./examples/toy-cli/adder.js --kind cli --i-have-rights
node apps/cli/dist/index.js capture --target <tgt> --plans '[{"name":"add","argv":["2","3"]},{"name":"bad","argv":["x"]}]'
node apps/cli/dist/index.js spec --vectorset <vs>
node apps/cli/dist/index.js plan --spec <spec>            # human approves here
node apps/cli/dist/index.js synth-context --spec <spec> --token <token>
node apps/cli/dist/index.js verify --target <tgt> --rebuild <rebuild> --vectorset <vs>
node apps/cli/dist/index.js pack --spec <spec> --report <rep>

Or install the fea command globally from apps/cli, or register the MCP server with your agent:

node apps/cli/dist/index.js mcp     # stdio MCP server — 9 tools

See examples/toy-cli/README.md for the full demo script.

What v0.3 is

Trust & proof. v0.3 adds three things on top of v0.2:

• Policy engine (@fea/policy) — allow/ask/deny per tool. Anything that executes something (fea_capture_behavior, fea_verify_parity, fea_read) can be gated: allow runs, ask stages an approval the human completes (fea_approve / fea approve --token), deny refuses. Configure via FEA_POLICY env, --policy <file>, <store>/fea.policy.json, or ./fea.policy.json. A recommended profile ships in code (RECOMMENDED_POLICY).

• Vector fuzzing — fea fuzz --spec <id> --count 50 --seed s1 generates deterministic boundary vectors (empty args, NaN, Infinity, unicode, huge numbers…) stored as a new vector set, so parity is tested beyond the recorded examples.

• HTML parity reports — fea report --report <id> renders a self-contained page (score, failing-vector diffs, normalizers) with no external assets.

MCP surface is now 13 tools.

What v0.2 was

• ✅ Everything in v0.1, plus:

• ✅ Native binaries as a target kind (--kind native)

• ✅ REA reader adapter (fea read / fea_read): calls any REA MCP tool, stores findings as evidence — REA stays the reader, FEA stays the rebuilder

• ✅ CI mode: fea verify --fail-under 95 exits 1 below threshold

• ✅ Docker sandbox backend: FEA_SANDBOX=docker (image via FEA_DOCKER_IMAGE); fea doctor reports backend + docker + REA status

• ❌ Still no decompilers of its own · ❌ No license/DRM circumvention · ❌ Parity is behavioral, not a formal proof

What's next (v1.2)

The GitHub-backed fea-twins registry index (needs your go-ahead to create the repo), the actual npm publish run (docs/PUBLISH.md — needs your npm login), and the emulator-backed APK harness (honestly needs an Android SDK machine).

Docs

• docs/ARCHITECTURE.md — how the loop fits together

• docs/SECURITY.md — authorization, sandboxing, secret scrubbing

• docs/DISCLAIMER.md — read this before pointing FEA at anything

• ../your_files/fea-blueprint.md — full PRD + MVP + tech-stack blueprint (v1.0)

License

MIT — see LICENSE.