Proposal: ArchSim on Java 25, ported in stages
Status: approved by the owner on 2 Nov 2026, with the decisions below. Stage 0 (foundations) is built; its exit check is still open (see Stage 0). Stage 1 (the design model) is built and its exit check passes (see Stage 1). Stage 2 (the API on Spring Boot) is built and its exit check passes (see Stage 2). Stages 3 to 6 are built, and the port ends there; where the port ended sums it up. Stage 7, the benchmark harness and the repository's tooling, is built too (see Stage 7): no Python is left but the benchmarked stacks (their services and that service's own test) and three trial records.
Why: the owner works in Java and wants to maintain ArchSim. This is a port, not a redesign of what ArchSim does: the simulation model, the design format and the web app's behaviour stay the same. The structure and tooling become standard modern Java.
What moves and what stays#
| Part | Today | After the port |
|---|---|---|
| Simulation engine, analysis, sizing, cost, calibration, importers | Python, 28.8k lines (+9.6k tests) | two Java libraries, no framework: archsim-model and archsim-engine |
| HTTP API, sign-in, run queue, workers | Python FastAPI, 7.9k lines (+4.1k tests) | one Spring Boot 4 app, archsim-app |
| MCP server for AI agents | Python, 0.5k lines | Java (official MCP Java SDK) |
CLI and archsim check GitHub Action |
Python | Java (picocli) |
| Web app | TypeScript / Next.js, 39k lines | unchanged |
| Design document format (schema 1.7 JSON) | shared contract | unchanged |
| HTTP API contract (routes, JSON, cookies) | shared contract | unchanged |
| PostgreSQL data | Alembic migrations | same tables, Flyway from the current revision; no data migration |
| Benchmark harness (k6, Docker, statistics) | Python, 11.8k lines | stays Python during the port and calls the Java engine's CLI; ported to Java after stage 6 |
Principles#
- Strangler, not big bang. At every step main works and deploys. Python code is deleted only after its Java replacement has passed parity.
- Parity before replacement. Each stage has an exit check against the Python version.
- No model changes during the port. A port that also changes behaviour can't be verified. Accuracy improvements happen before or after, never in the same stage.
- Mainstream and documented. A Java developer should find the code where they expect it, built and checked the way they're used to.
Target architecture#
apps/web (Next.js, unchanged)
│ HTTP + JSON (same contract)
▼
archsim-app (Spring Boot 4: one image, started as api, worker or migrate)
one package per feature: io.archsim.app.projects · .runs · .auth · .tokens · .shared …
each holds its controller, service and repository (JdbcClient, PostgreSQL)
worker: a Spring profile without the web layer; claims runs from the queue (advisory lock)
archsim-cli (picocli) archsim-mcp (MCP Java SDK) benchmarks (Python → archsim-cli)
│ the app, CLI and MCP use both libraries below
▼
archsim-engine (plain Java library)
kernel (event-driven, single-threaded) · components · analysis · sizing · cost · pricing
calibration · importers · export
│ uses
▼
archsim-model (plain Java library, usable without the simulator)
design document records · upgrades from schema 1.0 to 1.7 · validation
The stack (each choice with a real alternative has an ADR; see Decisions):
- Java 25 (LTS): records, sealed interfaces for component types, pattern-matching
switch, virtual threads for request handling. - Gradle 9 with Kotlin DSL, a version catalog, and one Gradle module per box above, each added by the stage that first needs it.
- Spring Boot 4 (Spring Framework 7, Jackson 3), Spring Security's OAuth2 client for GitHub
and Google sign-in, CSRF protection and hashed API tokens, as today (ADR-0037 did sign-in in
plain Spring MVC instead, to keep the shared sessions and the HTTP contract, until ADR-0065
moved it to Spring Security after the port). One app,
archsim-app, organised by feature: one package per feature, holding that feature's controller, service and repository classes. It builds one image, started asapi,workerormigratelike today's Python image; the worker is a Spring profile without the web layer. - PostgreSQL through Spring's
JdbcClientwith explicit SQL. The run queue's claim (an advisory lock and arow_numberpick) and its leases read best as plain SQL. Flyway takes over from Alembic at the current schema revision. - Model and engine without Spring.
archsim-modelholds the design document's records, the upgrades from schema 1.0 to 1.7 and validation, so the app, CLI and MCP server can read and check a design without the simulator.archsim-engineholds the rest: the kernel, components, analysis, sizing, cost, pricing, calibration, importers and export. - Event-driven simulation kernel. It's a single-threaded priority queue of timed events, ordered like SimPy: time, then priority, then insertion order. Each component is a state machine whose steps are named after the Python blocks they replace; random streams are seeded per component, and component types sit behind a sealed interface. Why not virtual threads: ADR-0013.
- Quality gates in CI:
- formatting and style: Spring's formatter (spring-javaformat) and Checkstyle with clean-code rules (ADR-0030, Java conventions);
- null safety: Error Prone with NullAway and JSpecify annotations;
- layering: ArchUnit rules (controllers never use repositories directly; the model and the engine never import Spring or JDBC; the model never imports the engine);
- tests: JUnit and AssertJ, jqwik for engine invariants, and an embedded PostgreSQL for the database tests, with no Docker (ADR-0033). The build uses JUnit 6: the same Jupiter API as JUnit 5, and the version Spring Boot 4 manages;
- coverage: JaCoCo;
- the web contract: an OpenAPI document generated by springdoc, checked against the web
app's
api.ts.
- Packaging: one Docker image of
archsim-app, built with Jib.docker compose upworks as it does today.
Code layout#
One Gradle build at the repository root, with the standard multi-project layout: one top-level
folder per module. It sits beside the Python code, whose folders go stage by stage; apps/web
doesn't change.
| Path | What |
|---|---|
settings.gradle.kts, gradlew, gradle/wrapper/ |
the build and its wrapper (Gradle 9.8) |
gradle/libs.versions.toml |
every version, in one place |
gradle/gradle-daemon-jvm.properties |
Gradle runs on JDK 25 whatever JAVA_HOME says, and downloads one if none is installed |
build-logic/ |
the convention plugin every module applies: Java 25, spring-javaformat, Checkstyle, Error Prone with NullAway, JUnit, JaCoCo |
archsim-model/, archsim-engine/, archsim-app/, archsim-cli/, archsim-mcp/ |
one module per box above, each added by the stage that needs it. Maven's standard directories inside: src/main/java/io/archsim/<module>/ (in the app, io.archsim.app.<feature>), src/main/resources, src/test/java |
archsim-api-tests/ |
a test module: the black-box API tests (stage 0) |
parity/golden/ |
the frozen Python engine's golden files, the reference for stages 1 and 3 (parity/README.md) |
Stages#
Stage 0 · Foundations (3–5 days)#
- Build and CI: the Gradle build and a Java CI job.
- Golden files: a Python exporter records the inputs and outputs of every deterministic engine function across the 25 templates and their 124 scenarios.
- Black-box API tests: the 4.1k lines of API tests become HTTP tests that run against any base URL, so the same suite checks both the Python and the Java API.
- Exit: the Java CI is green, and the black-box suite passes against today's Python API.
- Built (2 Nov 2026):
- the Gradle build (see Code layout) and the CI job
java; - golden files in
parity/golden/, checked against the engine by the Python CI job; - the black-box suite in
archsim-api-tests/: 120 of the 162 Python API tests, with the other 42 listed there. It needs PostgreSQL and starts the Python API itself (-Parchsim.api.start=python).
- the Gradle build (see Code layout) and the CI job
- Still to run before the exit is met:
- the whole black-box suite against the Python API; Docker was stopped while it ran, so 36 of the tests have not run yet;
- the golden-file check on Linux (the files were written on Windows);
- the CI job on GitHub (a Linux container run of its steps passed).
Stage 1 · Design model and schema (3–5 days)#
- Model:
archsim-model: Java records for the design document, with upgrades from schema 1.0 to 1.7. - Validation: messages match Python's word for word, because the web app shows them.
- JSON Schema: generated from the records and compared with today's.
- Exit: all 25 examples and every test fixture read and write back identically, and every invalid fixture gives the same errors.
- Built (2 Nov 2026):
archsim-model/: the records, the upgrades, reading and writing, the JSON Schema and validation, with the component types' specifications and the price-snapshot lookup validation needs (ADR-0026). Every golden entry of the functions it ports passes: loading, upgrading, validating and normalizing every template, scenario and fixture, applying overrides, the JSON Schema, the distributions and the price snapshots. The exporter became a package,scripts/golden/. - Left for later stages: the component catalog the editor renders (stage 2); pinning prices and sizing "auto" parts when a scenario is resolved (stage 3).
Stage 2 · The API on Spring Boot, engine still Python (1–2 weeks)#
- Endpoints:
archsim-appserves all 69 of them. Same JSON, cookies, CSRF, rate limits and outbound block, and tokens keep working because the hash format is unchanged. - Simulation runs: they keep executing in Python workers through the shared PostgreSQL queue, which is already the seam between the API and the workers.
- Synchronous engine calls: validate, estimate, review, export, import, calibrate and pricing go to a small internal Python engine service inside compose until stage 3 replaces each one.
- Exit:
- the black-box suite and the Playwright end-to-end tests pass against the Java API;
- one database works with both APIs;
- compose switches to Java, and the FastAPI code is deleted.
- Built (3 Nov 2026):
archsim-app/, in six slices. The whole black-box suite (132 tests) and the Playwright end-to-end tests pass against it. Flyway'sV1builds Alembic's schema and takes over a database Alembic made (ADR-0032). Compose runs it from an image Jib builds, with the engine service (ADR-0036) and the Python workers. The FastAPI app is deleted;services/apikeeps the workers until stage 4. Its differences from the Python API, and the Python bugs it does not copy, are in its README.
Stage 3 · The engine's deterministic parts (1–2 weeks)#
- What it covers: in
archsim-engine, estimate, sizing, cost, pricing, design review and findings, confidence, explain, compare, exports, importers and calibration fits. - Parity bar: the golden files from stage 0. Text must match exactly, and numbers to a relative 1e-9.
- Exit: each part moves from the Python engine service to Java when it passes. When the last
one moves, the service keeps only the simulation a calibration replays, an interim
POST /simulatewithin the replay's limits, until stage 4's exit removes it and the service with it (ADR-0045). - Built (7 Nov 2026):
archsim-engine/, on the model's records (ADR-0038), in slices that each moved calls off the engine service.- All 117 functions the golden files record are ported to Java (archsim-model and archsim-engine), and their 6,018 entries match, with one listed departure: a YAML library's own words for text that is not YAML.
- The API answers from Java what the service answered: validating a scenario,
POST /analyze, preparing a run,GET /compare, seed-group summaries,POST /export,POST /importandPOST /calibrate, with the engine's versions inGET /meta. Departures from the Python engine are listed in the engine's README, and from the Python API in the app's. - Calibrations call Prometheus from the Java API, under its outbound policy, pinned to the address they check (ADR-0046).
- What stays: the engine service with
POST /simulatealone (ADR-0045). Compose, the black-box suite, CI and the end-to-end launcher still start it, for calibrations' replays. - The assumptions page and the
archsim checkgate are ported as libraries, for stage 5's commands.
Stage 4 · The simulation kernel and components (2–4 weeks, including parity runs)#
-
What it covers:
- the kernel and every component, including database locks and group commit, cache, Kafka fetch cycles, load balancer, Kubernetes, shared-host contention and external APIs;
- the run runtime, sweeps, sampled mode and multi-seed ranges.
-
Parity bar. A port can't reproduce Python's results bit for bit: tiny floating-point differences change the order of events, so result digests will differ. The bar is statistical:
- Every template scenario: with 20 seeds each, Java's median p50, p95, throughput and utilisation fall inside Python's seed range and within 2% of Python's median.
- Every kept benchmark calibration: the re-simulated knee is within 2% of Python's.
- Internal counters such as commits per flush and lock wait match per component on fixed inputs, so a semantic slip can't hide inside the tolerance.
- Replays, on top (decided during the stage): the Java simulator draws Python's random
numbers and keeps SimPy's order of events
(ADR-0047,
ADR-0048), so it replays the frozen engine's
runs number by number, counters included, and the statistical bar stays as above
(ADR-0049).
A Java report repeats itself on every platform; its digests keep their definitions and
name a result within one engine
(ADR-0050). The
harness runs the Java engine through
archsim run, the first command of stage 5's CLI (ADR-0051).
-
Speed: measure against
docs/performance.md. A Java kernel should be several times faster, but that's an estimate until it's measured. -
Exit:
- the parity report is published in
docs/validation/java-parity.md; - the Java engine ships as engine 1.0.0;
- /accuracy shows its in-sample results, labelled re-simulated;
- calibrations replay on the Java simulator, and
/simulateand the engine service are deleted (ADR-0045).
The harness's move to the Java CLI and the Python engine's deletion were in this exit until 8 Nov 2026; they are stage 5's now (below), because the MCP server and the
archsim checkaction import the Python engine until stage 5 ports them. - the parity report is published in
-
Built (10 Nov 2026):
archsim-engine/'s simulator, in slices that each replayed the frozen engine. Every item of the exit is met.- The parity report is published (java-parity.md): all 149 template cases meet the bar, every one of their 2,980 runs replays the frozen engine figure for figure with its digests, and all 65 kept calibrations' knees are the frozen engine's. The Java simulator runs the templates about 14 times faster (performance.md).
- The Java worker simulates every run
(ADR-0053): compose, the
black-box suite (132 tests) and the end-to-end tests run on it. A calibration's replay runs
on the Java simulator in the API's process, on platform threads of its own
(ADR-0054). The Python
worker,
/simulateand the engine service are deleted;services/apikeeps the Alembic migrations,migrateandseeduntil stage 6. - The Java engine is engine 1.0.0: new runs,
GET /meta, reports andarchsim --versionname it, and runs stored before keep 0.16.0.benchmarks/engines.jsonrecords it, not frozen yet: its source trees are pinned when it is frozen, before the next held-out campaign. - /accuracy and
docs/validation.mdsay in one sentence, labelled re-simulated and in-sample and never in the headline, that 1.0.0 re-simulates every kept calibration with exactly 0.16.0's knees (65 of 65), so the latest predictions they show are 0.16.0's, which 1.0.0 reproduces. Per-experiment figures would repeat 0.16.0's numbers beside themselves. - The harness simulates on the Java engine through
archsim runwhen asked (BENCH_ENGINE=java), and names its checks by the engine's version (ADR-0051).
Stage 5 · CLI, MCP server and GitHub Action (3–5 days)#
- What it covers:
archsimcommands with the same flags and output, and the MCP tools with the same names and schemas. - The
archsim-checkaction runs the CLI from a container image. A GraalVM native binary is optional, for faster start-up. - Exit (from stage 4's, 8 Nov 2026): the harness calls the Java CLI, and the Python engine is
deleted, with the scripts that recorded its oracles (their data stays). Before it goes, the
price snapshots move into
archsim-model's resources and the test fixtures out ofpackages/engine, and the harness takes the fits, the machine speed and the versions it imports from the Python engine from the Java CLI (ADR-0015). - Built (12 Nov 2026):
archsim-cli/andarchsim-mcp/, then the exit, in slices S5-1 to S5-10. Every item of the exit is met.- The CLI has every command of the Python CLI, with its flags, lines, exit codes and JSON
values, checked against 307 cases recorded from it
(ADR-0055,
ADR-0056); where Python
crashed, the Java answers in one line, as its README lists.
calibrate prometheus --urlcalls the app's Prometheus client, moved into the engine (ADR-0057), and the CLI and the MCP server read files as Python did (ADR-0059). - The MCP server serves the Python server's tools, resources and instructions word for word, on the official MCP Java SDK, checked against a recorded session of 55 requests (ADR-0058).
- The
archsim-checkaction runs the CLI in an image each job builds from the repository and never pushes; it needs a Linux runner with Docker (ADR-0060). No native binary was built. - The price snapshots are
archsim-model's resources, and the test fixtures are inparity/fixtures/. - The harness takes its fits, machine speeds, means and the report's version from one
long-lived Java process,
archsim functions(ADR-0061; stage 7 removed it with the Python harness, ADR-0073), and simulates on the Java engine only (ADR-0062). - What else needed the Python engine moved to Java: the sizing audit and the checks against
queueing theory (M/M/c, Little's law, the starter's reference ranges, the estimate against
the simulation) are tests of
archsim-engine,archsim-app'sseedrole seeds the examples, and./gradlew :archsim-engine:generatewrites the web app's engine fixtures anddocs/assumptions.md, which a test holds to the Java engine's output. - The Python engine (
packages/engine) and the Python MCP server (packages/mcp) are deleted, with the scripts that recorded the engine's oracles and the scripts only it ran; the tagengine-0.16.0keeps the engine as it was frozen, and git history the scripts. What they recorded stays as the Java tests' data and is not recorded again: the golden files, the simulation baselines and the recorded cases, beside the fixtures they were made from (parity/README.md).
- The CLI has every command of the Python CLI, with its flags, lines, exit codes and JSON
values, checked against 307 cases recorded from it
(ADR-0055,
ADR-0056); where Python
crashed, the Java answers in one line, as its README lists.
Stage 6 · Clean-up (2–3 days)#
- Remove Python: everything except the benchmark harness.
- Docs: CONTRIBUTING, the README and
IMPLEMENTATION_STATUS.mdrewritten for the Java build. - Sign-in: weigh moving it to Spring Security, now that the API contract can change. Stage 2 signed people in with plain Spring MVC to keep FastAPI's contract (ADR-0037); ADR-0065 moved it after the port.
- Built (12 Nov 2026): in slices S6-1 to S6-8. Every item is met.
- Python removed from what ArchSim ships and needs to run.
services/api, the Alembic migrations Flyway took over from, is deleted withscripts/schema_snapshot.py; a database below Alembic's revision 0008 is brought there from the tagalembic-0008first (ADR-0063), and the schema snapshot is data recorded once. The end-to-end launcher makes its database with the PostgreSQL driver in the API's jar, and the action posts its comment withgithub-script. Python stays for the benchmark harness and the repository's scripts until stage 7 (ADR-0064): uv's project keeps no dependency but the development tools. - Docs: the README, CONTRIBUTING (its "Changing simulation semantics" included),
IMPLEMENTATION_STATUS.md,docs/extending-components.mdand the docs that described the Python engine as the product describe the Java build. - Sign-in: ADR-0065 moves it to Spring Security after the port, keeping its HTTP contract but for the changes it records, in six test-first slices, all built (12 Nov 2026).
- Also:
NOTICElists the third-party software the images and the CLI bundle, none of it incompatible with the AGPL-3.0 ArchSim is licensed under (ADR-0067), and the web image leaves out sharp and its libvips (ADR-0066); stage 5's follow-ups are closed; and two gaps in the contract found in review are closed. The API ignores a request body's unknown keys, as FastAPI's request models did, and a number's text of any length is read as Python'sfloat()and pydantic read it, where a few thousand digits or groups of them had overflowed the stack.
- Python removed from what ArchSim ships and needs to run.
Stage 7 · The benchmark harness (after the port)#
- What it covers:
benchmarks/run.py,report.pyand their tests, rewritten in Java once stages 0–6 are done. - Parity bar: the committed results under
benchmarks/resultsreduce to the same numbers (medians, knees, spreads, digests of the reduced summaries), because past and future runs must stay comparable. - Exit: the harness runs from Gradle, and the last Python code is deleted.
- Also: the repository's tooling in
scripts/moves to Java or goes (ADR-0064). - Decisions (13 Nov 2026, all accepted): the harness is a module,
archsim-benchmarks, calling the engine in process, with its data left inbenchmarks/(ADR-0068); it runs as./gradlew :archsim-benchmarks:run --args="<command>", withrun.py's command names (ADR-0069); it writes every file as the Python harness did, byte for byte, charts included (ADR-0070), with Python's statistics ported exactly (ADR-0071); the tooling moves to a modulearchsim-tools, and the recorders of CPython's behaviour retire (ADR-0072). - Slices, each test first (its tests ported from the Python ones), each commit that touches
Java, the build or CI reviewed before it lands:
- S7-1 · The module and the reduction of a run:
archsim-benchmarks, the experiments, Python's arithmetic on the results' JSON values and their median, the results' files, andcompare. Parity: every kept run'scomparison.jsonrecomputed byte for byte. - S7-2 · The reports:
report [--json] [--dev]: the validation page's blocks, the charts, bothaccuracy.json,dev-checks.mdandknee-range.md. Parity: all regenerated from the committed results, byte for byte but for the command names (ADR-0070). - S7-3 · The Java engine's parity page:
java-parity [--check], fromscripts/java_parity_report.py; CI's check becomes the module's test. - S7-4 · Model inputs, designs and simulation in process: the calibration's inputs, the
design, the knee search,
resimulateandresources. Parity: re-simulating every kept calibration gives the Java engine's recorded checks (results/dev/0.16.0-java/). - S7-5 · The knee's range: the sensitivity, the variation fit and
range-fit. Parity:benchmarks/knee-range.jsonreproduced from the same checks. - S7-6 · Docker, k6 and a campaign: stacks, cpusets, cgroup readings, k6, the calibration
staircase, measurement, the held-out seals and
smoke; the seal fix below. Proof: one smoke run and one experiment on Docker. - S7-7 · The machine checks:
envcheckandcontention(host counters, probes). - S7-8 · The tooling:
archsim-tools(commit messages, CI's changes, the price refresh); the hook and CI on Java; the CPython recorders retire. - S7-9 · Python removed:
benchmarks/*.pyand their tests,scripts/,pyproject.toml,uv.lock,.python-version, CI's Python job, the Makefile's and the workflows' uv steps,archsim functionsin the CLI; the docs.
- S7-1 · The module and the reduction of a run:
- The prediction seal: a run's
predictionsSha256sealspredictions.jsonbefore the first measured step. Of the 53 sealed runs, 27 match their file and 24 were edited by the 2 Nov 2026 history rewrite (commit IDs and the harness's hash), their originals matching. The other two, cache-aside's runs 4 and 5, show a harness bug: a ladder that still met the objective at its top was extended, and each extension step was saved into the sealed file after the seal, so the file no longer matches it. S7-6 fixes it in the Java harness, test first. - Built (14 Nov 2026): in slices S7-1 to S7-9. The exit is met: the harness runs from Gradle,
and no Python is left but the benchmarked stacks (their services and that service's own test)
and the three trial records.
- The harness is
archsim-benchmarks, with every commandrun.pyhad. Its tests regenerate every kept run's comparison, the validation page, its charts, bothaccuracy.jsonand the Java parity page from the committed results, byte for byte, and refit the knee's range; its parity task (./gradlew :archsim-benchmarks:parity) checks every kept run again on the engine, the 65 development checks and W27's checks on a host machine all as recorded (117 tests, 18 minutes). A smoke run on Docker passes all nine experiments (238 s on 14 Nov 2026). - The tooling is
archsim-tools: the commit messages' check, which the hook and CI'scommitsjob run from its source, CI's changed parts and the price refresh. The recorders of CPython's behaviour retired; the tagcpython-recorderskeeps them, with the Python harness and the scripts. - Python removed:
benchmarks/*.pyand their tests, ported to Java first;scripts/,pyproject.toml,uv.lockand.python-version; CI's Python job and the Makefile's and the workflows' uv steps.archsim functions, which only the Python harness called, left the CLI (ADR-0073). - Open: CI's Java steps for the commits, the changed parts, the benchmarks and the prices
have not run on GitHub while Actions cannot start jobs. The price refresh matched
aws.pyon live offer files on 14 Nov 2026, byte for byte (ADR-0072's note).
- The harness is
Where the port ended#
- In Java: the design model, the engine (1.0.0), the API with its worker, seed and migrate
roles, the CLI, the MCP server and the
archsim-checkaction's CLI; since stage 7, the benchmark harness and the repository's tooling too. The web app stays Next.js and talks to the Java API unchanged. - Kept: the design format (schema 1.7), the HTTP API's contract
(ADR-0034), the CLI's output
(ADR-0055) and the MCP tools. The Java
engine's tests replay the runs the frozen Python engine 0.16.0 recorded, figure for figure,
and match its golden files (
parity/README.md). - Departures, each listed: the API's in
archsim-app's README, the
CLI's in archsim-cli's README, and the Unicode version (Java
25's 16.0 against Python 3.12's 15.0) in
IMPLEMENTATION_STATUS.md's known limitations. - Still Python: none of ArchSim or its tooling since stage 7.
benchmarks/service-pythonis one of the stacks the harness measures, not part of ArchSim: its service and that service's own test, run by hand. Three trial records underbenchmarks/results/trials/keep the scripts the W23 and W26 trials ran, as recorded. - Tags:
engine-0.16.0keeps the frozen engine, its MCP server and the Python API's tests;alembic-0008keeps the Alembic migrations,archsim-api migrateand the schema-snapshot script;cpython-recorderskeeps the Python harness, the repository's scripts and the recorders of CPython's own answers. - Not done: stage 0's exit was never run in full against the Python API, which is gone; the black-box suite passes in full against the Java API (137 tests). CI has not run on GitHub since Actions stopped starting jobs on 5 Nov 2026; every CI command runs locally.
- Decided by the owner on 12 Nov 2026, before anything is published: ADR-0065's slices are
built first, and
ARCHSIM_DATABASE_URLtakes a plainpostgresql://URL, the form the documentation now shows, besides SQLAlchemy's and JDBC's (ADR-0035's note of that day).
Accuracy work during the port#
Decided order: the Python engine is frozen at 0.16.0, and the held-out campaign runs on it before stage 4 starts. Accuracy and model work stop until the port is complete.
- Why first: the held-out results then describe the engine customers use today. The Java engine is checked against the same measurements afterwards. Because the port changes no behaviour, that check is fair, but it's labelled re-simulated, never prospective.
- What waits: stages 0–3 don't touch the simulation, so they can run alongside the accuracy work.
Risks#
- Hidden simulation differences. A statistical bar can hide a small semantic slip. The per-component counter checks and invariant tests are there for that.
- Two stacks for a while. Python and Java side by side add complexity, so each stage should be short, and Python goes as soon as a stage passes.
- Sessions. Signed-in users may have to sign in once more after stage 2. API tokens keep working.
- No SQLite mode. Local development uses PostgreSQL in Docker, and the tests an embedded PostgreSQL (ADR-0033).
- Effort. The durations are rough estimates at this project's pace (169 commits in nine days). Parity runs need the laptop overnight, like the benchmark campaigns.
Decisions#
The owner decided these on 2 Nov 2026. Each has an Architecture Decision Record in
docs/adr/, which gives its reasons, the options weighed and what follows;
the port itself is ADR-0005.
| # | Decision | ADR |
|---|---|---|
| 1 | Build with Gradle, the Kotlin DSL and a version catalog | 0006 |
| 2 | Spring Boot 4 for the application | 0007 |
| 3 | PostgreSQL through JdbcClient with explicit SQL; Flyway migrations |
0008 |
| 4 | Base package io.archsim |
0009 |
| 5 | The benchmark harness stays Python during the port, then moves to Java (stage 7) | 0015 |
| 6 | No SQLite development mode: PostgreSQL only | 0016 |
| 7 | The Python engine is frozen at 0.16.0; the held-out campaign runs before stage 4 | 0017 |
| 8 | One Gradle build at the repository root, one folder per module | 0010 |
| 9 | The app's code is organised by feature | 0011 |
| 10 | The design model (archsim-model) is a module apart from the engine |
0012 |
| 11 | An event-driven, single-threaded simulation kernel | 0013 |
| 12 | One deployable, archsim-app, started as api, worker or migrate |
0014 |
Stage 0 proposes three more, for the owner to accept:
| Decision | ADR |
|---|---|
| Black-box API tests in Java, run against any base URL | 0019 |
| The frozen engine's deterministic functions recorded as golden files | 0020 |
| The Java build's conventions: one convention plugin, warnings as errors, JUnit 6 | 0021 |
Stage 1 proposes eight more:
| Decision | ADR |
|---|---|
| Records and a pydantic-compatible codec over Jackson trees | 0022 |
| Upgrades as a chain of steps on the JSON; only the current schema is modelled | 0023 |
| Issues with stable codes and the Python engine's words | 0024 |
| The JSON Schema generated from the records, as pydantic writes it | 0025 |
| Component specifications and the price-snapshot lookup belong to the model | 0026 |
| Python's text conventions for numbers and values in one package | 0027 |
| The golden-file reader shared as Gradle test fixtures | 0028 |
| The model's packages in layers, checked by ArchUnit | 0029 |
The Java conventions and stage 2 added eight:
| Decision | ADR |
|---|---|
| Java in Spring Framework's style, with clean-code rules the build enforces | 0030 |
| The component catalog built from the specifications, its presentation as data | 0031 |
| Flyway takes over from Alembic at revision 0008 | 0032 |
| The database tests on an embedded PostgreSQL, without Docker | 0033 |
| The FastAPI API's HTTP contract kept in Spring MVC | 0034 |
The Python API's ARCHSIM_* settings read unchanged |
0035 |
| The engine's synchronous calls in a small internal Python service | 0036 |
| Sign-in with plain Spring MVC, not Spring Security | 0037, superseded by 0065 |
Stage 3 added nine:
| Decision | ADR |
|---|---|
| The engine computes on the model's records and typed configs, not on JSON trees | 0038 |
| A run's report read as records of the parts the engine reads | 0039 |
| A comparison copies the report parts it shows and diffs the inputs as stored | 0040 |
| The application's clock never tells the same microsecond twice | 0041 |
| Exports read settings leniently and write their own YAML | 0042 |
| Imported YAML read with SnakeYAML, resolved as PyYAML resolves it | 0043 |
Terraform JSON read with Jackson, as Python's json reads it |
0044 |
Calibrations replayed through an interim /simulate on the engine service |
0045 |
| Prometheus called with Apache HttpClient 5, pinned to the address it checks | 0046 |
Rough total: 6–10 weeks of sessions for stages 0–6, plus overnight parity runs, then the harness port.