FaultForge

Break virtual hardware. Diagnose the failure. Repair it. Prove it works.

FaultForge is a deterministic digital-twin laboratory that breaks virtual IoT safety systems, diagnoses their failures, repairs controller policies, and proves the repair through identical replay.

Open the live demo · Watch the 2-minute demo · Devpost · GitHub · v1.0.0-volthacks release

Select Begin warehouse demo, optionally enable Guided Demo, then use the primary action to run the real simulation, diagnosis, repair, and replay.

The central demonstration

A virtual warehouse fire-safety system encounters rising smoke and heat while its smoke sensor sticks at zero and Wi-Fi packets disappear. The baseline controller trusts the smoke channel too heavily and misses the hazard. FaultForge then:

1. ranks the smoke sensor as the primary fault from structured evidence;
2. exposes the violated invariants, contradictions, dependencies, and causal path;
3. applies sensor fusion and degraded-mode logic to the inspectable controller policy;
4. replays the same seed, environment, sensor noise, packet decisions, and faults; and
5. shows the repaired controller activate the alarm.

The final report is generated from the two simulation executions. No final success state or metric is hard-coded in the interface.

Why it matters

IoT safety logic is often tested against one clean failure at a time. Real incidents combine environmental hazards, unreliable sensors, packet loss, and unsafe controller assumptions. FaultForge makes that compound behavior reproducible and inspectable before physical deployment.

Architecture

Scenario + seed + policy
          ↓
Deterministic simulator → telemetry + event history
          ↓
Structured diagnosis → ranked cause + evidence
          ↓
Inspectable policy repair
          ↓
Identical replay → execution-derived validation

The React interface calls framework-independent TypeScript engines through a small Zustand workflow store. React Flow renders topology, Recharts renders recorded telemetry, Zod validates configuration/report boundaries, and all truth-path behavior runs locally in the browser.

See Architecture, Simulation model, and Diagnostic engine.

Deterministic integrity

• fixed one-second timestep and seeded local PRNG;
• no Math.random, backend, or external AI in the truth path;
• baseline and repaired runs share the seed, scenario fingerprint, duration, initial battery, environmental progression, sensor noise, packet decisions, and fault schedule;
• controller-policy versions and hashes differ;
• replay and policy evidence are reproducibly generated by npm run audit:core.

The interface displays a shortened SHA-256 incident-input fingerprint and provides expandable full values. The machine-verifiable proof is documented here.

Run locally

Requirements: Node.js 22.12+ and npm 10+.

npm ci
npm run dev

Open the printed local URL and select Begin warehouse demo. Guided Demo is optional; manual controls execute the same engines.

Verify

npx tsc -b --pretty false
npm test
npm run audit:core
npm run report
npm run build
npm run test:e2e
npm audit --audit-level=low

The audited baseline and release-candidate results are recorded in RELEASE_CANDIDATE.md.

Demonstrate

Use DEMO_SCRIPT.md for the two-minute live flow or VOICEOVER_SCRIPT.md and VIDEO_SHOT_LIST.md for a recording. The published demo is Unlisted and includes synchronized English captions.

The demo narration uses a neutral synthetic voice for accessibility and presentation. FaultForge’s diagnostic and repair results are produced by deterministic TypeScript engines, not by the narration system.

Submission screenshots

• Normal laboratory
• Baseline failure
• Root-cause diagnosis
• Controller repair diff
• Final validation
• Mobile validation
• Project thumbnail

Every screenshot is captured by Playwright after operating the real journey.

Verified official result

For incident seed 26042026, generated execution data records:

Metric	Baseline	Repaired
Alarm activation	No	Yes
False-negative ticks	6	0
Violated assertions	2	0
Scenario Safety Score	5	100

Scenario Safety Score summarizes applicable checks in this deterministic warehouse incident. It is not production certification, fleet availability, or a general reliability percentage. See METRIC_DEFINITIONS.md.

Known limitations and safety

• This hackathon prototype validates one simulated Smart Warehouse scenario.
• No real hardware is connected.
• It is not production fire-safety certification, an electrical simulator, or a substitute for physical validation and independent engineering review.
• Automated browser coverage is Chromium-only.
• No scenario import, authentication, backend, or production telemetry exists.

VoltHacks new work

FaultForge was initialized as a fresh local repository for VoltHacks 2026. Project provenance, commits, verification evidence, libraries, assets, and optional-service disclosures are recorded in VOLTHACKS_NEW_WORK.md.