FORKCAST

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.

What is real, and what is simulated

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.

Related MCP server: Sentinel MCP

The seeded demonstration

• 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:

1. Delivery delayed 30 minutes — chilled ingredients arrive at 4:00 PM. Baseline finish slips to 6:05 PM and the guest deadline is missed.

2. Chicken unavailable — the chicken is removed from the isolated inventory copy. The roast path is unschedulable.

3. Roast overruns 50% — 70 minutes becomes ceil(70 × 1.5) = 105 minutes. The plan finishes at 6:10 PM.

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

Architecture

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.

Requirements

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

Installation

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 build

FAULTLINE 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 example

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

Environment

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/mcp

Vite reads VITE_MCP_URL at build time. The browser has no server secrets.

Run

Development:

npm run dev

This 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 5173

The backend binds to 127.0.0.1 by default. Do not expose it publicly: it has no authentication.

Using the workstation

1. Wait for the header to show MCP live and 9 MCP tools discovered.

2. Click Run sample request. This sends forkcast.draft_plan through MCP.

3. Inspect the baseline timeline, dependency graph, constraint ledger and calculation evidence.

4. Simulate a branch. Each click calls forkcast.simulate_scenario; the server uses FAULTLINE on a fresh world clone.

5. Compare calculated baseline/faulted times, newly violated constraints and affected tasks.

6. For a failed branch, click Find and verify a repair. The result is accepted only after a fresh independent re-schedule.

7. Click Review exact local changes. This calls forkcast.preview_commit and issues a single-use five-minute approval token. No demo data changes yet.

8. Optionally click Cancel — no write and verify the revision stays unchanged.

9. Check the explicit approval box and click Approve and apply. This sends the token plus the exact phrase APPROVE LOCAL DEMO COMMIT.

10. Reset the dedicated demo dataset with Reset demo data. The reset advances the revision to invalidate stale previews and preserves audit history.

MCP tools

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.

The server also exposes GET /health and GET / for operational checks. Those are not part of the MCP workflow.

Testing

npm test             # 39 unit/integration/MCP tests
npm run typecheck
npm run build
npm run e2e          # full Playwright acceptance against build

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

Security and safety

• 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 audit reported 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.

Known limitations

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

Documentation

• Architecture

• Competition requirements

• Product description

• Three-minute demo script

• Product feedback

• Friction log

• Primary submission draft

• Open-source submission draft

• Changelog

License

MIT. See LICENSE.