The Archaeologist’s Copilot

The Hallucination of Competence

The AI acted like a well mannered, eager-to-please tour information. It scanned the
README.txt, ignored the many years of mud, and confidently generated a
fashionable “Starter Equipment.” It gave me a pristine construct.gradle file and a
clear HelloBlobStore.java. It instructed me precisely how to hook up with the
database. On the floor, it seemed like a miracle.

The AI-generated construct.gradle

plugins {
   id 'java'
}

group = 'com.legacycorp.blobstore'
model = '1.1'

sourceCompatibility = '1.8'
targetCompatibility = '1.8'

repositories {
   mavenCentral()
}

dependencies {
   implementation 'org.apache.commons:commons-pool2:2.11.1'
   implementation 'log4j:log4j:1.2.17'
   testImplementation 'junit:junit:4.13.2'
}

check {
   useJUnit()
}

The consequence was a lie — and a structural lie at that. By producing a
fashionable construct file, the AI merely painted a recent coat of paint over a
crumbling structural wall.

First, it hallucinated dependencies by suggesting commons-pool2
(v2.x) when the legacy code truly relied on org.apache.commons.pool
(v1.x). As a result of these libraries have utterly totally different APIs, blindly
working the AI’s code would have crashed the construct with “Class Not Discovered”
errors, sending me down a irritating rabbit gap of debugging “fashionable”
code that was by no means meant to be fashionable.

Subsequent got here the structural gaslighting. The AI confidently assumed a
normal Maven format src/important/java, utterly ignoring the fact
of a non-standard Ant construction java/com/legacycorp.... It was describing
the fact it needed to see, not the one that truly existed.

Lastly, it hid the underlying rot. Its pristine “Good day World” instance
featured PooledBlobStoreImpl, omitting the truth that the core
implementation SimpleBlobStoreImpl wasn’t even thread-safe, the
error-handling code routinely swallowed exceptions, and the so-called
“Unit Checks” have been truly integration assessments that required a dwell MySQL
database to run.

The Lesson

AI defaults to optimism. Once I ask “How do I run this?”, it assumes I
can run it. In a restoration mission, optimism is deadly.

If I had
adopted the Vacationer path, I might have began refactoring
instantly—altering Listing to ArrayList<> or including Generics—doubtless
breaking hidden behaviors I did not absolutely perceive. I might have been
making blind adjustments to a fragile system with out establishing its present
state.

To actually restore a brownfield undertaking, I have to cease appearing like
Vacationers and begin appearing like Archaeologists.

The Archaeologist Immediate

I crafted a immediate designed to strip away the optimism. I assigned the
AI a particular persona: Senior Legacy Programs Architect. I explicitly
forbade it from summarizing the README (which is commonly a lie in legacy
tasks) and ordered a “Forensic Code Audit”.

I'm conducting a technical due diligence evaluation on this legacy Java
repository: https://github.com/nikmalykhin/java-blobstore.

Act as a Senior Legacy Programs Architect. Your purpose is to not inform me what the
code "does," however to judge its structural well being and "age."

Don't summarize the README. As a substitute, carry out a "Forensic Code Audit" focusing
on these 4 pillars:

1.  **Carbon Courting (The Period):**
    * Based mostly on syntax (e.g., uncooked sorts vs. generics, annotations), imports, and
    construct instruments (Ant vs. Maven), estimate the particular Java model (e.g., 1.4,
    1.5, 6) and the yr this code was doubtless written.
    * Cite particular traces of code as "forensic proof."

2.  **Architectural Integrity (The Construction):**
    * Does it comply with normal separation of considerations (Transport vs. Protocol vs.
    Logic), or is it a "Huge Ball of Mud"?
    * Establish any "God Courses" which are doing an excessive amount of.

3.  **Knowledge Circulation & Typing (The "Stringly" Entice):**
    * Analyze how knowledge is handed. Is it utilizing correct Area Objects, or is it
    counting on "Stringly-typed" Maps and uncooked arrays?
    * Search for "Leaky Abstractions" the place protocol particulars leak into enterprise logic.

4.  **The "Security" Verify (Error Dealing with & Threading):**
    * Search for anti-patterns in error dealing with (swallowed exceptions, returning null).
    * Analyze the threading mannequin. Is `SimpleBlobStoreImpl` thread-safe?

Output your findings as a structured "Threat Evaluation Report" for a stakeholder
deciding whether or not to refactor or rewrite.

The AI dropped the well mannered facade instantly. As a substitute of a “Starter
Equipment,” it handed me a Threat Evaluation Report with a brutal verdict:
“essential rewrite really helpful“.

Discovering 1: Carbon Courting the Artifact

The AI analyzed the syntax like an archaeologist uncovering historic
strata, citing proof reasonably than guessing. Wanting first on the
historic document, it discovered a construct.xml file with none signal
of a pom.xml, inserting the undertaking squarely within the pre-2010
“Ant Period.” Subsequent, it flagged key syntax markers, recognizing the legacy use of
org.apache.commons.pool.ObjectPool (Model 1.x) alongside
uncooked sorts like Map as an alternative of Map. This led to an unmistakable verdict: this was Java 1.5
code written throughout the transition period of 2005–2008, utterly predating
fashionable generics, try-with-resources, and normal listing layouts.

Discovering 2: The “Transliteration” Entice

Probably the most damning perception was that this was truly Perl code
masquerading as Java; the unique creator had merely taken a procedural
Perl script and compelled it into Java syntax. This procedural mindset
manifested instantly in SimpleBlobStoreImpl, a large monolithic god
class that attempted to deal with all the pieces from low-level socket connections
and protocol parsing to core enterprise logic. Moreover, the codebase was
aggressively “stringly-typed”. As a substitute of using correct area
objects like Gadget or File, the code continually handed round uncooked
Map objects and manually constructed uncooked protocol
strings simply to open a file. This launched an immense operational threat:
a single typo in a string key, reminiscent of get(“fiel_id”), would set off a
catastrophic runtime crash as an alternative of being caught safely at compile
time.

Discovering 3: Mendacity Checks

The Archaeologist revealed that the perceived check protection was nothing
greater than a harmful phantasm. The complete check suite relied closely on
LocalFileBlobStoreImpl, a whole re-implementation of the storage
system that wrote on to the native disk as an alternative of traversing the
community. Whereas these assessments efficiently proved that this native mock labored
flawlessly in isolation, that superficial success masked an alarming
actuality: the precise networking code, the thread-unsafe pooling, and the
fragile protocol parser—absolutely the most risky components of the
system—have been being utterly bypassed.

The Choice: Containment over Restore

The report saved me from catastrophe. Had I adopted the optimistic
“Vacationer” recommendation to refactor SimpleBlobStoreImpl instantly, I might have
blindly launched generics and damaged the delicate parsing logic. The
assessments would have nonetheless handed—because of that misleading native mock —however the
precise manufacturing code would have been utterly non-functional.

Realizing the code was an absolute legal responsibility, too fragile to the touch and
too opaque to belief. I made the strategic resolution to halt all lively
adjustments. I refused to repair the bugs, replace the dependencies, and even
reformat the whitespace. As a substitute, I transitioned instantly right into a section of
full containment, wrapping the legacy code inside an remoted,
standardized Docker setting earlier than attempting to research it any
additional.

The Mission: Brownfield Restoration

For this section of brownfield restoration, the core mission was to
set up a standardized setting. To information the AI and actively forestall
insidious “modernization creep”, I established a strict set of prime
directives. First, we needed to protect the period, which means completely no
updates to the legacy construct instruments or the Java model—we have been strictly
mimicking the yr 2008. Second, I prioritized containment over
modernization, retaining the unique Ant construct.xml file and working the
complete course of inside an remoted Docker container to keep away from polluting my
host machine. Lastly, there have been to be completely no code adjustments; I
refused to slap public modifiers onto courses simply to repair visibility bugs.
If it labored in 2008, it needed to work now inside the appropriate container.

But, regardless of these strict guidelines, my first intuition was nonetheless secretly
tainted by the vacationer mindset—a traditional case of modernizer’s hubris. I
caught myself considering, “Okay, I am unable to change the Java code, however certainly I
can swap out this historical Ant construct for Gradle 8, proper?” Appearing on that
impulse, I requested the AI to carry out a swift “carry and shift,” grabbing the
uncooked Java 1.5 supply information and dropping them instantly into a contemporary Gradle
8 container.

The consequence was a spectacular crash. The construct failed not as a result of the
legacy code itself was buggy, however as a result of the foundational guidelines of the
software program setting had radically shifted over twenty years. The legacy
code routinely relied on accessing package-private courses from fully
separate packages (reminiscent of TestBackend reaching into
Backend). Again in 2008, Ant and Eclipse have been extremely
permissive about these structural violations; by 2026, Gradle 8 and
fashionable JDKs had turn out to be strict, unyielding enforcers of
encapsulation.

The Construct Failure Log

/src/check/java/com/legacycorp/blobstore/check/TestBackend.java:12:
error: Backend is just not public in com.legacycorp.blobstore; can't be accessed from outdoors package deal
        Backend backend = new Backend(trackers, true);
        ^

Confronted with this roadblock, the AI’s speedy suggestion was
predictable: “Simply add public to the category.” However I refused. Doing so
would instantly violate one among my prime directive of constructing zero code
adjustments. Modifying manufacturing supply code solely to appease a contemporary construct
instrument is a slippery slope, and I wasn’t going to step onto it.

The Pivot: The “Time Capsule” technique

Realizing that I could not stabilize the artifact in a contemporary
setting, I pivoted to a “Time Capsule” technique. If I needed to
seize this technique, I needed to construct a containment zone that strictly
mirrored the requirements of 2008. I turned to Docker to recreate the precise
setting the code was born in, looking for an previous picture that bundled
Java 6 and Ant 1.5 collectively.

However I hit an instantaneous {hardware} actuality test. The one accessible Java
6 Docker photographs have been compiled for x86 (linux/amd64), whereas I used to be
making an attempt to run the construct on a contemporary Apple Silicon (ARM64) laptop computer.
Whereas emulation layers like Rosetta or QEMU are theoretically doable,
they introduce a harmful, unpredictable variable into an already fragile
course of. If the construct fails, how have you learnt whether or not it is an inherent code
defect or simply the emulation layer choking on twenty-year-old
binaries?

To eradicate that variable fully, I modified my setting. I
deserted the laptop computer and switched to a local Intel machine powered by a
fashionable i9 processor. The lesson right here was clear: generally software program
archaeology requires the appropriate shovel. I solely made progress after I stopped
preventing the host structure and moved instantly onto the native floor
of the artifact.

The “Moist” Take a look at: Bending Actuality

As soon as I had the compiler engaged on Intel—finishing the “dry” capsule—I
confronted the ultimate structural problem: a cussed integration check named
TestBlobStore.java. This “moist” check was a pure artifact of its time,
suffering from hardcoded assumptions tied on to the unique
developer’s native machine. Particularly, it seemed for a magic host,
attempting to hook up with qbert.legacycorp.com:7001, and relied on a magic file
path positioned at ~/Tasks/blobstore/…. In a normal
fashionable refactor, I might have merely deleted these traces. However as a result of I
was strictly in containment mode, touching the check file was off the
desk. As a substitute of adjusting the code to suit fashionable actuality, I needed to change
actuality to suit the code.

The answer lay in setting emulation through Docker Compose. I
prompted the AI to behave as a community engineer to assist me pull off some
infrastructure illusions. First, we executed some community trickery: I spun
up a contemporary BlobStore container and used a Docker community alias to trick
the check runner into believing this container was truly the long-lost
qbert.legacycorp.com. Subsequent got here the filesystem trickery, the place I configured
Docker volumes to mount our dwell, native supply code listing contained in the
container on the actual, similar path engineer had used again in 2005.

This setting trick materialized in my docker-compose.yml
file:

The community configuration.

  providers:
    blobstore:
      picture: hrchu/blobstore-all-in-one:newest
      networks:
        default:
          aliases:
            - qbert.legacycorp.com  
  
    builder:
      picture: blobstore-legacy-builder
      volumes:
        - .:~/Tasks/blobstore/java/com/legacycorp/blobstore/
      command: ant check

This orchestrated phantasm led to full stabilization. Once I
executed docker-compose up, the legacy check suite fired up and ran
flawlessly. It seemed up qbert.legacycorp.com and seamlessly routed straight
to my native Docker container; it reached out for engineer’s previous hardcoded path
and located our dwell quantity mount as an alternative.

The construct succeeded. With out altering a single byte of historic
supply code, I had efficiently restored full performance to a
twenty-year-old software. The setting was steady, the code was
lastly verifiable, and I might in the end take into consideration shifting it into
the long run.

The {Hardware} Rationale

The selection of Java 8 was not aesthetic; it was a practical necessity
pushed by my {hardware} constraints. I wanted to run the undertaking natively on
Apple Silicon (ARM64), however that purpose crashed right into a double-ended technical
wall. On one facet of the timeline, fashionable JDKs (Java 17+) have dropped
help for compiling legacy Java 1.5 supply code fully, rejecting the
previous -source 1.5 flag. On the opposite facet, historical JDKs like Java 6 refuse
to run natively on ARM64 structure, trapping you in buggy emulation
layers.

So I turned to Java 8, the one, particular model able to
satisfying each ends of the timeline. As a result of it stands as absolutely the
final model to help the compilation of Java 1.5 targets and one of many
earliest variations that may be put in natively on fashionable Mac {hardware},
it turned our excellent architectural entry level.

The “Java 17 Entice”

I hit the primary laborious technical wall when selecting the instrument model. My
intuition was to make use of the most recent launch, Gradle 8.5, however this alternative
instantly crashed right into a wall: Gradle 8 requires Java 17 simply to run its
inner daemon, and as we already famous, Java 17 is incapable of
compiling legacy Java 1.5 supply code.

To resolve this bottleneck, I settled on a pivot to Gradle 7.6. This
stands as absolutely the final modern-ish Gradle model that may nonetheless
execute on a Java 8 JVM, permitting me to determine an ideal chain of
environmental compatibility:

Apple Silicon -> Java 8 JVM -> Gradle 7.6 -> Java 1.5 Supply

The Execution: Mapping the Legacy Construction

I did not simply wrap the previous construct.xml. Realizing the Ant script was
actively obscuring the underlying logic, I configured Gradle to map
on to the legacy listing construction. To realize native compilation,
I overrode the trendy defaults and explicitly instructed Gradle to look
for the supply code in srcDirs = ['java'] as an alternative of anticipating the
normal src/important/java format.

Subsequent, I needed to deal with the legacy check runner. As a result of the historic
assessments have been structured as old-school important() strategies reasonably than a contemporary
JUnit suite, the usual out-of-the-box gradle check command could not
discover them. To bypass this limitation, I wired up a customized JavaExec activity
named runLegacyTest to execute these check entry factors manually.

Mapping Gradle to the Legacy Format

  java {
      sourceCompatibility = JavaVersion.VERSION_1_5
      targetCompatibility = JavaVersion.VERSION_1_5
  }
  
  sourceSets {
      important {
          java {
              srcDirs = ['java'] 
          }
      }
  }
  
  duties.register('runLegacyTest', JavaExec) {
      mainClass.set(undertaking.findProperty('mainClass'))
      classpath = sourceSets.important.runtimeClasspath
  }

The “Mendacity Checks” Discovery

With the construct modernized to Gradle, the runLegacyTest activity executed
efficiently. However the assessments ran suspiciously quick. Once I audited the
supply of TestBlobStore.java to search out out why, I found a traditional
legacy anti-pattern: the silent swallow. The code was actively capturing
failures and smothering them earlier than they may bubble as much as the runtime
setting:

Legacy Code Sample

  public static void important(String[] args) {
      attempt {
          BlobStore bs = new PooledBlobStoreImpl(...);
          bs.storeFile("test_file", ...);
          System.out.println("Success!");
      } catch (Exception e) {
          System.out.println("Failed: " + e.getMessage());
          e.printStackTrace();
      }
  }

Whereas a human studying the console outputs would simply acknowledge this
as a blatant failure, an automatic construct instrument sees it very in a different way.
As a result of the exception is caught and dealt with internally with out throwing it
additional or exiting this system, the method finishes with an ideal exit
code 0. These assessments have been utterly deceptive; the backend connection
might fail fully, but our fashionable pipeline would nonetheless confidently
report a inexperienced go.

Hardening the Baseline

To strip away this false safety, I initiated a means of deliberate
hardening. I instructed the AI to refactor the previous check harness in order that it
would explicitly throw exceptions all the way in which up the execution stack. This
marked my very first structural change to the legacy codebase, and it was
achieved with a singular objective: to drive my verifiable baseline to turn out to be
utterly trustworthy. As a substitute of wrapping the operations in an
error-smothering blanket, I stripped out the try-catch block fully and
compelled the applying to crash naturally if one thing went improper:

Hardened Sample

  public static void important(String[] args) throws Exception { 
      BlobStore bs = new PooledBlobStoreImpl(...);
      bs.storeFile("test_file", ...); 
  }

Immediately, the construct turned vivid purple. Removed from a defeat, this was a
huge narrative victory—a purple construct meant I used to be lastly trying on the
unvarnished actuality of the system. I spent the following hour tracing down and
repairing the damaged connection configurations till the construct pipeline
lastly flipped again to inexperienced. However this time, it was an trustworthy inexperienced.

The AI-Compiler Suggestions Loop

As soon as the assessments have been “trustworthy” and the construct turned Inexperienced, I used to be confronted
with a mountain of technical debt. The construct was profitable, however the
compiler was screaming:

Observe: Some enter information use or override a deprecated API.
Observe: Recompile with -Xlint:deprecation for particulars.
Observe: Some enter information use unchecked or unsafe operations.
Observe: Recompile with -Xlint:unchecked for particulars.

To systematically clear this up, I moved away from basic refactoring
and established a good, iterative AI-compiler suggestions loop. I did not
simply ask the AI to vaguely “repair the codebase”; as an alternative, I used the
compiler itself as the last word driver.

First, I explicitly enabled the -Xlint:unchecked flag contained in the
Gradle construct configuration to drive the compiler to disclose the precise
supply traces triggering the violations. At any time when the construct ran and
captured a particular warning block—reminiscent of an unsafe name to a uncooked sort
checklist—I fed these actual error logs on to the AI with a extremely
focused immediate, instructing it to refactor solely these particular traces to
resolve the warnings utilizing fashionable Java generics.

This extremely localized technique was extremely efficient at neutralizing
historic runtime dangers. For instance, the unique codebase used
primitive, Java 1.5-style uncooked collections the place the compiler had no thought
what objects truly lived inside them, forcing me to depend on blind,
harmful sort casting:

BEFORE: The “Uncooked Kind” Threat (Java 1.4 Model)

  public class Backend {
      non-public Listing hosts;
      non-public Map deadHosts;
  
      public void reload(Listing trackers, boolean connectNow) {
          this.hosts = trackers;
          this.deadHosts = new HashMap();
      }
      
      InetSocketAddress host = (InetSocketAddress) hosts.get(index); 
  }

By passing this actual snippet and its accompanying warning log to the
AI, it swiftly up to date the structure to the right Java 8 type-safe
normal, transferring the burden of validation from runtime guesswork to
compile-time enforcement:

AFTER: The “Kind Protected” Customary (Java 8 Model)

  public class Backend {
      non-public Listing hosts;
      non-public Map deadHosts;
  
      public void reload(Listing trackers, boolean connectNow) {
          this.hosts = trackers;
          this.deadHosts = new HashMap<>();
      }
      
      InetSocketAddress host = hosts.get(index);
  }

By sustaining this disciplined, repetitive cycle throughout each file, I
ultimately crossed the end line with a profitable construct and completely
zero warnings. The historic artifact wasn’t simply practical; it was
formally standardized.

Mastering the Craft

Earlier than attacking the manufacturing code, I needed to repair the workbench. I
began with a much-needed section of sanitization, shifting the supply information
out of their archaic java/ root folder and into the industry-standard
src/important/java format. Making this shift allowed me to delete my earlier
customized Gradle listing workarounds fully; by lastly bowing to
normal conventions, the construct instrument merely labored out of the field.

With the undertaking’s skeleton straightened out, I tackled a complete
JUnit 5 migration to transform the primitive legacy important() scripts—reminiscent of
TestBackend and TestBlobStore—into real unit assessments. All through the
implementation, I systematically swapped out the previous, crude
System.out.println(“Error”) traps for correct Assertions.assertEquals()
statements. This instantly paid off with a deeply satisfying consequence: I
gained granular, automated check reporting, completely liberating me from
having to manually audit limitless textual content logs simply to test if a check had
handed in favor of receiving a normal, unambiguous inexperienced checkmark.

The TestContainers Entice

I bought bold and regarded changing the handbook docker-compose
setup with TestContainers to make the assessments actually self-contained, however the
try shortly collapsed. The migration quickly degenerated right into a messy
“Huge Bang” refactor—I discovered myself attempting to overtake the check runner, the
community topology, and the startup logic suddenly, whereas concurrently
wrestling with complicated Docker-in-Docker networking points on ARM
structure.

This friction taught me a significant engineering lesson: momentum is
oxygen. The second I spotted I used to be spending all my vitality preventing the
tooling reasonably than recovering the precise code, I made the acutely aware
resolution to abort the experiment. I gladly accepted the “Exterior Sidecar”
sample—working docker-compose up manually—as a result of it was dependable and
it labored, intentionally selecting ground-level pragmatism over
over-engineered perfection.

Scrubbing the Setting

To make sure the following developer would not need to repeat my tedious
archaeological dig, I switched my AI persona one final time to behave as a
lead repository maintainer. With this ultimate goal in thoughts, I
recognized and systematically purged each historic artifact that
belonged firmly to the previous. First went construct.xml, the legacy Ant script
that had dictated the repository’s guidelines for many years. Subsequent, I emptied out
the previous lib/ folder—completely discarding a free bag of unversioned,
hardcoded JARs—and swept away .classpath and .undertaking, which have been
nothing greater than deserted artifacts from long-forgotten IDE setups.
Operating rm construct.xml stood as the ultimate, cathartic act of modernization;
it formally severed our fragile hyperlink to the traditional Ant period and
completely compelled the repository to depend on my fashionable Gradle engine.

The Undertaking Roadmap: README.md

I did not simply go away behind a clear repository; I left a map. Working
with the AI, I generated a complete README.md file that completely
displays this new, standardized actuality. As a substitute of an undocumented
labyrinth, the file outlines a totally frictionless path to
productiveness, specifying fundamental stipulations like Docker and Java 8+, and
providing a dead-simple fast begin that builds the undertaking with a single
./gradlew construct. Testing all the infrastructure is now simply as
simple, requiring a fast docker-compose up -d to spin up the
backend dependencies adopted by a normal ./gradlew check. This single
doc utterly transforms the undertaking from an intimidating thriller
field right into a predictable, normal Java library, completely shifting the
expertise for the following engineer from a grueling forensic investigation to
a routine, normal onboarding.

The Transformation: Earlier than vs. After

Closing Thought: The Augmented Archaeologist

A very powerful lesson from this experiment was basically about
human company. Once I initially leaned on the helpless “Vacationer
Immediate”—vaguely asking the machine to “repair this for me”—all the try
collapsed as a result of the AI lacked a foundational understanding of the
setting and the inflexible constraints of the previous. Success solely arrived
after I fluidly shifted mindsets to direct the execution: appearing first as
an archaeologist to establish the true architectural decay, then as a
DevOps engineer to design the containerized time capsule, and at last as
an architect to outline a strict refactoring coverage.

The AI did not magically restore this historic system by itself;
reasonably, I restored it by wielding the expertise as a robust drive
multiplier. It took care of the tedious, repetitive translation
layers—churning by the conversion from Ant to Gradle, drafting the
Dockerfiles, and systematically squashing fifty distinct compiler
warnings—whereas I targeted fully on high-level technique. Due to
this lively partnership, the codebase is not an intimidating,
tangled black field. It has turn out to be fully runnable, testable, and
predictable—absolutely outfitted to endure the following ten years and completely
positioned for no matter future refactoring awaits it.