FaultForge

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

Comment

Inspiration

Embedded safety logic is often validated against happy paths or one isolated fault at a time. Real incidents are compound: the environment changes, a sensor lies, communication becomes unreliable, and a controller assumption turns those failures into an unsafe decision. We wanted a way to reproduce that chain before working with physical hardware.

What it does

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.

This VoltHacks release models one Smart Warehouse fire-safety system with temperature, smoke, and motion sensors; a battery-powered edge controller; alarm and ventilation actuators; and a Wi-Fi link.

The demonstration injects a compound incident:

  1. Environmental smoke and temperature rise into danger.
  2. The smoke sensor becomes stuck at zero.
  3. Wi-Fi packets intermittently disappear.
  4. The baseline controller trusts the smoke channel and network delivery too heavily.
  5. The baseline alarm remains inactive during a real simulated hazard.

FaultForge then correlates the timeline, detects the contradictory smoke measurement, ranks smoke-01 as the primary causal candidate, retains alternative candidates, and exposes violated invariants, dependencies, temporal evidence, confidence, and a causal path. It applies an inspectable controller-policy repair using sensor fusion, smoke-flatline detection, degraded temperature logic, and local alarm behavior independent of Wi-Fi. Finally, it replays the exact captured incident and shows the repaired controller activate the alarm.

How it works

A fixed one-second simulation uses a seeded local PRNG and records environmental ground truth, sensor noise, component faults, packet decisions, telemetry, battery state, controller decisions, actuator state, assertions, and ordered events.

The diagnostic engine evaluates expected-versus-observed behavior, safety invariants, contradictory measurements, temporal precedence, and component dependencies. It assigns deterministic evidence weights to causal candidates and generates the explanation from that structured result. No LLM or external AI service supplies the diagnostic truth.

The repair engine changes the actual inspectable controller configuration rather than a result label. Replay compares the same seed and policy-independent incident-input stream while allowing controller outputs to differ. The application visibly proves that the incident-input hash matches while the controller-policy hash and version change.

Validation is generated from both executions. In the official run, the baseline alarm remains inactive and the repaired alarm activates; false-negative ticks fall from 6 to 0 and violated assertions from 2 to 0. The displayed Scenario Safety Score changes from 5 to 100. That score is scoped only to the applicable checks in this deterministic incident; it is not a general reliability percentage, production claim, or safety certification.

Same incident. Same faults. Different safety policy.

How it was built

FaultForge is a frontend-only React application written in strict TypeScript and built with Vite. Framework-independent TypeScript modules implement simulation, diagnosis, repair, replay, and validation. Zustand manages the judge journey, Zod validates runtime data, React Flow renders the component topology, and Recharts renders execution telemetry. Vitest verifies the deterministic core, while Playwright verifies the central browser journey, responsive layouts, reset and transition behavior, downloads, and console health.

GitHub Pages serves the static build. The demo requires no backend, runtime secret, paid service, or AI API key; deterministic local explanations remain available at all times.

Codex collaborated on product design, implementation, testing, independent red-team audit, release packaging, documentation, and repeatable browser evidence. The engineering source of truth remains the deterministic TypeScript engines and their execution artifacts.

Technical challenges

  • Separating policy-independent replay inputs from policy-dependent controller outputs.
  • Diagnosing the failed sensor without checking a scenario name or winning seed.
  • Retaining alternative causal candidates and structured evidence while keeping the full journey understandable in about two minutes.
  • Defining an incident-scoped score without implying calibrated probability, fleet reliability, or certification.

Accomplishments

  • The baseline reproducibly misses the official compound incident.
  • Diagnosis ranks smoke-01 first with a deterministic confidence indicator of 0.85 and preserves structured supporting evidence and alternatives.
  • The repair changes the actual controller policy and resulting behavior.
  • Baseline and repaired runs share the complete incident-input fingerprint while policy hashes differ.
  • Six adversarial scenarios and five additional deterministic seeds pass the core audit.
  • Vitest passes 4/4 tests; the local Playwright suite passes 5/5 tests; live acceptance passes desktop, laptop, and mobile viewports without console, page, request, or horizontal-overflow errors.

What we learned

Determinism is most credible when it is visible as a data contract, not just a seed label. Separating captured incident inputs from controller outputs makes the replay comparison machine-verifiable. Diagnostic confidence and scenario scoring also need their scope presented beside the number.

What's next

The current release deliberately proves one complete simulated warehouse scenario. Future work could add independently validated scenarios, hardware-in-the-loop adapters, importable scenario schemas, repeated-trial analysis, and organization-specific safety invariants. None is claimed in this release.

Safety and scope

FaultForge is a hackathon engineering prototype operating on simulated data. No real hardware is connected. It is not production fire-safety software, fire-safety certification, a full electrical simulator, or a substitute for physical validation, regulatory review, and qualified engineering judgment.

The demo uses a neutral synthetic narrator. FaultForge’s diagnosis, repair, replay, and validation results are produced by deterministic TypeScript engines, not by the narration system.

Built With

Share this project:

Updates