The AI that stress-tests tomorrow.
Don't just make a plan. Break it before reality does.
FORKCAST is a local, deterministic counterfactual planning workstation for a simulated six-guest dinner. It builds a real task schedule, injects four controlled faults into isolated copies of the household world, calculates which constraints break, searches defined alternatives for a repair, verifies the repaired schedule with an independent scheduler pass, and requires explicit approval before writing anything to the local demo dataset.
It is not a chatbot and does not ask an LLM to invent times or decide whether a plan is feasible. The browser is a genuine MCP client; the Node backend is a genuine MCP server.
Status: version 0.1.0, public repository: https://github.com/purwar21darsh-code/FORKCAST. Local demonstration, not deployed, not affiliated with Amazon. FAULTLINE is published at https://github.com/purwar21darsh-code/faultline.
| Layer | Status |
|---|---|
| Household world | A fixed, local demonstration dataset. No live calendar or real household connection. |
| Schedule | Calculated by a deterministic dependency/resource scheduler. |
| Fault injection | Real state cloning and mutation through the FAULTLINE library. |
| Constraint result | Calculated from the resulting schedule, not hardcoded. |
| Repair | Searched over defined meals and task orders; accepted only after a second scheduler verification. |
| Commit | Writes inventory and execution state to data/demo-state.json only. |
| Purchases, messages, bookings, devices | Never performed. |
| LLM | Not used. The core works without any API key. |
The natural-language request is routed to the fixed six-guest demo seed. FORKCAST exposes that interpretation in every draft response. No language model is generating the plan.
- Household: six guests, arrival deadline 6:00 PM.
- Baseline meal: herb roast chicken with rice and seasonal vegetables.
- Chilled delivery: chicken and butter available at 3:30 PM.
- Baseline result: finishes 5:35 PM, with 25 minutes of slack.
- Alternate meal: paneer tomato curry, with a 4:30 PM service window start and pantry ingredients.
The four scenario branches are:
- Delivery delayed 30 minutes — chilled ingredients arrive at 4:00 PM. Baseline finish slips to 6:05 PM and the guest deadline is missed.
- Chicken unavailable — the chicken is removed from the isolated inventory copy. The roast path is unschedulable.
- Roast overruns 50% — 70 minutes becomes ceil(70 × 1.5) = 105 minutes. The plan finishes at 6:10 PM.
- Dishwasher unavailable — only the optional pre-rinse task is skipped. Mandatory dinner constraints still pass. This branch demonstrates a non-failure and a real "no repair needed" result.
For the three failures, the repair search selects the defined paneer curry and verifies completion at 5:32 PM. The repair never relaxes the arrival deadline or invents a new meal.
Browser (React + Vite, port 5173)
└─ official MCP TypeScript SDK
└─ Streamable HTTP client
└─ http://127.0.0.1:4179/mcp
└─ MCP server (McpServer + StreamableHTTPServerTransport)
├─ world model + seed
├─ deterministic scheduler
├─ FAULTLINE scenario matrix (published release artifact)
├─ bounded repair + independent verification
├─ approval tokens + commit service
└─ atomic local demo persistence
FORKCAST depends on FAULTLINE, a separate MIT-licensed repository, through its published v0.1.0 release tarball: "faultline-sim": "https://github.com/purwar21darsh-code/faultline/releases/download/v0.1.0/faultline-sim-0.1.0.tgz". FAULTLINE is the generic isolated-scenario engine; FORKCAST adds the household model, scheduler, comparisons, repair search, MCP tools and UI.
More detail: docs/ARCHITECTURE.md.
- Node.js 20.19 or newer (Vite 7 requirement). Tested with Node.js 24.22.0.
- npm 11. Tested with 11.19.1.
- Windows, macOS or Linux for the app.
- Playwright E2E uses an installed Chrome/Chromium; tested with Google Chrome on Windows.
If PowerShell blocks npm.ps1 with an execution-policy error, use npm.cmd in every command below. This was observed on the build machine.
FORKCAST installs its published FAULTLINE dependency from a versioned GitHub release tarball. A sibling clone is not required for normal installation.
git clone https://github.com/purwar21darsh-code/FORKCAST.git
cd FORKCAST
npm ci
npm test
npm run buildFAULTLINE can be developed or tested separately:
git clone https://github.com/purwar21darsh-code/faultline.git
cd faultline
npm ci
npm test
npm run build
npm run exampleOn Windows PowerShell where npm.ps1 is blocked, use npm.cmd.
The dependency is pinned to the published FAULTLINE v0.1.0 release tarball and package lockfile. To work on both projects simultaneously from source, replace the dependency with the local sibling path for that development session, then restore the pinned release artifact before committing.
Copy .env.example if you want to change defaults:
PORT=4179
MCP_HOST=127.0.0.1
FORKCAST_DATA_DIR=./data
VITE_MCP_URL=http://127.0.0.1:4179/mcpVite reads VITE_MCP_URL at build time. The browser has no server secrets.
Development:
npm run devThis starts:
- Frontend: http://127.0.0.1:5173
- MCP server: http://127.0.0.1:4179/mcp
- Health check: http://127.0.0.1:4179/health
Production build:
npm run build
npm start # MCP server on 4179
npm run start:web # static preview on 5173The backend binds to 127.0.0.1 by default. Do not expose it publicly: it has no authentication.
- Wait for the header to show MCP live and 9 MCP tools discovered.
- Click Run sample request. This sends
forkcast.draft_planthrough MCP. - Inspect the baseline timeline, dependency graph, constraint ledger and calculation evidence.
- Simulate a branch. Each click calls
forkcast.simulate_scenario; the server uses FAULTLINE on a fresh world clone. - Compare calculated baseline/faulted times, newly violated constraints and affected tasks.
- For a failed branch, click Find and verify a repair. The result is accepted only after a fresh independent re-schedule.
- Click Review exact local changes. This calls
forkcast.preview_commitand issues a single-use five-minute approval token. No demo data changes yet. - Optionally click Cancel — no write and verify the revision stays unchanged.
- Check the explicit approval box and click Approve and apply. This sends the token plus the exact phrase
APPROVE LOCAL DEMO COMMIT. - Reset the dedicated demo dataset with Reset demo data. The reset advances the revision to invalidate stale previews and preserves audit history.
The MCP endpoint is real Streamable HTTP, MCP spec 2025-11-25. The browser performs initialization and tools/list; it does not call hidden REST simulation endpoints.
| Tool | Purpose | Mutation |
|---|---|---|
forkcast.inspect_world |
World, revision, applied execution, audit history | Read-only |
forkcast.draft_plan |
Calculate baseline plan and schedule | In-memory proposal + audit |
forkcast.list_scenarios |
Four fault definitions | Read-only |
forkcast.simulate_scenario |
FAULTLINE simulation of one fault | Audit only; world untouched |
forkcast.compare_scenarios |
Run/compare the scenario matrix | Audit only; world untouched |
forkcast.repair_plan |
Bounded search + independent verification | In-memory proposal + audit |
forkcast.preview_commit |
Re-schedule, exact diff, approval token | In-memory token + audit |
forkcast.commit_approved_plan |
Write approved plan to local demo state | Demo data only |
forkcast.reset_demo |
Restore seed content, bump revision | Demo data only |
The server also exposes GET /health and GET / for operational checks. Those are not part of the MCP workflow.
npm test # 39 unit/integration/MCP tests
npm run typecheck
npm run build
npm run e2e # full Playwright acceptance against buildThe E2E script starts the real MCP server on 4179 and a Vite preview on 5173, uses a temporary data directory, and verifies:
- MCP initialization and 9-tool discovery in Chrome.
- Baseline 5:35 PM.
- Delivery-delay failure at 6:05 PM with the demo world unchanged.
- Verified repair at 5:32 PM.
- Cancel writes nothing.
- Explicit approval commits revision 2.
- Backend restart preserves revision 2 and the applied execution.
- Reset restores seed content and advances the revision.
- 390 px mobile and 820 px tablet layouts have no horizontal page overflow.
Artifacts are written to artifacts/. The E2E needs Chrome. Set PLAYWRIGHT_CHROMIUM_EXECUTABLE to a browser executable if Chrome is not on the standard channel.
- No credentials or API keys are used.
- Server binds to loopback by default.
- CORS allows only local frontend origins (5173) by default; additional origins must be explicitly configured.
- MCP POST requests must be
application/json; bodies are limited to 1 MB; sessions are capped. - Commit requires a per-plan, single-use approval token plus the exact approval phrase.
- Stale revisions, expired tokens, reused tokens, infeasible plans and repeat commits are rejected.
- Demo writes are atomic; malformed files are preserved before recovery.
npm auditreported 0 vulnerabilities in both repositories, including development dependencies, at final verification.- Reset affects only the dedicated demo data directory.
- FAULTLINE is a state-isolation coordinator, not a security sandbox. Do not run untrusted generated code as a simulation callback.
- The request-to-world mapping is a fixed demonstration route. It is not a general natural-language planner.
- The household model is small and hand-seeded.
- Scheduler is a greedy list scheduler; it is deterministic and bounded but not an optimal solver.
- Repair search considers defined meals and four task-order profiles. It does not invent ingredients, meals, resources or constraints.
- Single-user local demo. There is no authentication, multi-tenant isolation or hosted deployment.
- Plans/proposals live in server memory and do not survive a restart; committed demo state and audit events do.
- The browser bundle includes the official MCP SDK and is ~542 kB minified (161 kB gzip); no code splitting has been added yet.
- The live Official Rules page was blocked by Cloudflare during development. The deadline and rules were verified from an archived official-rules capture (1 October 2026). Re-check the live submission UI before entering. See docs/COMPETITION_REQUIREMENTS.md.
- Architecture
- Competition requirements
- Product description
- Three-minute demo script
- Product feedback
- Friction log
- Primary submission draft
- Open-source submission draft
- Changelog
MIT. See LICENSE.