Graveyard Shift — Floppy Recovery Lab

Break a floppy image, trace the damage, and bring its files back—with evidence at every step.

Comment

Inspiration

A file can survive even when the route to it is broken. That distinction is easy to miss when a filesystem is presented only as a diagram or a finished recovery result.

Graveyard Shift gives computer science students and curious digital archivists an experiment they can control. They can create a disk, damage one part of it, follow the consequences, and check the recovered file against an independent checkpoint. The old floppy becomes a small, inspectable system for learning a modern engineering habit: connect a result to the evidence that supports it.

What it does

The lab creates a real FAT12 disk from the included fictional field log or the user's own text. Each experiment works on a separate copy, preserving the original image.

  • Sever a link: break the primary allocation chain, then follow the surviving mirror to the file's bytes.
  • Create a loop: introduce a circular reference and watch the bounded reader identify it.
  • Split the evidence: construct two complete but conflicting paths and inspect why the disk cannot choose an authoritative original automatically.

Both allocation-table paths are visible beside a selectable cluster map. Selecting a cluster reveals its actual bytes. When the evidence supports extraction, the lab recovers the file and compares it byte for byte against a checkpoint kept outside the recovery engine. The working disk, extracted file and JSON evidence report can all be downloaded.

Imported FAT12 images use the same inspection and extraction flow. Their output is labeled Content unverified because an uploaded image does not supply an independent record of its original content.

Turn a recovery experiment into a challenge someone else can solve. Export the damaged disk and its target file as a challenge, import it in a fresh browser, and recover from that same damaged image. An optional supplied answer digest is compared with the extracted file only afterward. The challenge transports the experiment without packaging a separate pristine file or saved recovery output. Its description is labeled Supplied metadata.

How it was built

The current application uses TypeScript and Vite, with no runtime package dependencies. Image parsing, controlled mutations, path tracing, extraction and SHA-256 calculation run in the browser. Original CSS and SVG graphics make the disk, damaged path and recovered text part of one coherent archive-lab interface.

The recovery engine receives only the supplied image and file selection. The checkpoint lives in a separate UI layer and is consulted after extraction. This separation makes the comparison meaningful: recovery cannot obtain its answer by copying the pristine file.

Independent fixtures and counterexamples shaped the implementation. A separately generated 720 KiB image exercises fragmented chains and a different cluster size. Tests cover malformed geometry, truncated images, cycles, bad or reserved clusters, conflicting chains, root-file cross-links, source immutability and the absence of an oracle input. Near-limit allocation tests also verify that a conflict experiment cannot allocate a reserved cluster number.

Kiro built the shareable challenge workflow. Using the authenticated Kiro CLI 2.37.0, the build moved through requirements, design, independent specification review, implementation and a focused repair pass. Kiro produced the challenge module, UI integration and 27 tests while preserving the original Codex-assisted recovery engine during that feature phase. A later, separately recorded Kiro repair phase corrected the existing engine’s aggregate ownership work, conflict allocator and asynchronous UI behavior; it does not change the original engine’s authorship. Manager-prepared custom agents scoped the specification phase separately from implementation. The root .kiro retains the actual specifications and clearly attributed prompts/configuration. See the Kiro usage write-up.

Engineering challenges resolved

The most important distinction is between a structurally complete path and verified original content. Two valid paths can disagree, and intact metadata can point to overwritten data. The lab therefore keeps path validity, extraction and independent comparison as separate outcomes.

Independent review also exposed concrete boundary problems: directory entries could conceal shared clusters, reserved cluster identifiers needed stricter handling, and an evidence report could follow the next selected fault instead of the fault actually applied. Those cases were corrected and retained as regression evidence. The supported format stays explicit, so each experiment has a clear interpretation.

The new challenge workflow added a second demanding boundary: imported data must be validated without changing an existing experiment prematurely. An independent adversarial test exposed quadratic padding validation; Kiro replaced both scans and the unchanged regression then passed. Kiro also labeled supplied metadata and captured report state before asynchronous hashing. Expanded stress testing then exposed repeated long-chain scans, conflict allocation into a cluster referenced by a broken file, stale raw imports, stranded image hashes and a form draft lost during background rendering. Kiro repaired these in three focused runs. Independent browser checks verified the resulting import order, report/hash lifecycle and draft preservation; the two new independent engine regressions were retained unchanged by Kiro.

Accomplishments

  • Recovered all 1,496 bytes of the included file after a real allocation-table fault, with an exact checkpoint match and an unchanged original-image hash.
  • Recovered a 2,203-byte fragmented file from an independently generated 720 KiB FAT12 image through chain 2 → 5 → 3.
  • Recovered 1,100 bytes of custom UTF-8 text, including Chinese and HTML-like text, while keeping the preview literal and inert.
  • Demonstrated two complete conflicting paths and blocked automatic extraction instead of inventing certainty.
  • Verified actual downloaded file and disk hashes against the exported report.
  • Exported byte-identical challenge files and replayed one in a fresh browser, recovering the same 1,496 bytes and comparing its SHA-256 with the supplied answer.
  • Imported a non-first target, SECOND.TXT, and recovered 1,100 bytes matching the independent fixture oracle.
  • Kept conflicting valid paths ambiguous even when a supplied answer digest matched one route; absent or incorrect answers did not change extracted bytes.
  • Passed 59 automated tests and the production build through actual Kiro tool execution: 20 original tests, 27 Kiro-authored tests, 10 independent challenge tests and 2 independent stress regressions.
  • Passed an independent 9,476-case deterministic corpus and 3 additional allocator work-budget cases, with the two ordinary stress regressions already included in the 59-test suite.
  • Passed an expanded 21-group browser stress review: 12 ordinary/boundary groups and 9 explicitly delayed async diagnostics, with 85 actual downloads checked and zero page/console errors or external requests in that run.

The judge guide walks through these reproducible local results.

What the project demonstrates

Redundancy helps when one route is damaged; it does not remove the need to interpret conflicting evidence. A file hash identifies bytes, while an independently known checkpoint makes a comparison meaningful. A useful recovery interface should let a learner see both distinctions directly.

The product's contribution is the complete create → damage → trace → recover or decline → compare → share learning loop. Existing disk viewers already provide format inspection and extraction; Graveyard Shift uses those filesystem concepts to make a repeatable, reversible experiment that another learner can replay.

What's next

The working challenge workflow provides a foundation for teaching exercises with different faults and file layouts. A next step is to observe learners using those exercises and use that feedback to improve explanations and navigation.

Platform and scope

Desktop web browser. Supports raw FAT12 images up to 4 MiB, two allocation tables and root-directory 8.3 files. Subdirectory-bearing images are rejected; deleted files and long-name reconstruction are outside this version. Custom lab text supports up to 65,536 UTF-8 bytes. The conflicting-copy experiment requires a file spanning more than one cluster and enough usable free clusters.

Authorship, license and assets

This is a solo entrant's project supported by AI development tools; the agents are not human team members. Original application code is MIT licensed. Interface graphics and the fictional sample text were created for this project. System fonts are used, and the application contains no externally hosted music, images or fonts. Development dependencies and provenance are documented in the third-party notices.

Built With

Share this project:

Updates

Submission history