# GENESIS Ω

A local, inspectable artificial civilization laboratory. Agents make inventory-driven choices in a finite landscape; harvesting, exchange, tools, migration, soil damage, and resource-funded reproduction connect individual actions to population and ecological change.

This is a computational model for investigating its own mechanisms. It is not empirical evidence about human civilizations. There is no language model, scripted historical narrative, remote API, account, or paid service in the application.

## Run locally

The delivered `dist/GENESIS.html` embeds the simulation, worker, styles, and recorded experiments. Open it directly in a modern browser for the offline edition. Its JavaScript and worker bundle have passed syntax checks; browser execution could not be verified in the provided sandbox.

For the source edition and reproduction tools, install **Node.js 22.8 or later** (tested with 24.19.0). No dependency installation is required for the application, engine tests, experiments, or benchmarks.

```sh
cd genesis
npm start
```

Open **http://127.0.0.1:5173**. Keep the terminal running. Use `PORT=8080 npm start` to choose another port. The server listens on loopback by default. A remote development environment may require its usual port forwarding to access this address from your computer. Opening the source `index.html` with `file://` is not supported; use the bundled `dist/GENESIS.html` for direct opening.

## First investigation

1. Generate the default seeded world. Step or play and inspect an agent on the map.
2. Switch map layers to compare food, wood, population, and soil. Examine the recorded decisions and events.
3. Open **Experiments**, capture a checkpoint, choose an intervention, and run an equal-horizon comparison.
4. Compare the two measured trajectories. Loading a branch changes the live world; merely running a comparison does not.
5. Export a save before closing if you need a portable, complete state. Browser storage is local to that browser and origin.

## Reproduce the evidence

```sh
npm test
npm run experiments
npm run verify:evidence
npm run benchmark
npm run build
```

The test command runs Node's test runner. Experiments and benchmarks regenerate numerical evidence in `results/`; `verify:evidence` reruns all experimental branches and compares their measurements and final-state hashes with the recorded results. The build copies the static application into `dist/` and creates a self-contained `dist/GENESIS.html`; it does not contact a hosting service. To serve the modular built copy, run `GENESIS_SERVE_DIR=dist npm start`.

Browser end-to-end verification uses Playwright and Chromium as optional test tools. They are not application dependencies. If Playwright is not installed in your environment, install it with `npm install --no-save playwright` and install its browser with `npx playwright install chromium`, then run:

```sh
npm run test:browser
```

Set `GENESIS_CHROMIUM` to a system Chromium executable if necessary. The browser test starts and stops its own loopback server.

**Verification limit:** the supplied environment denied loopback listening (`EPERM`) and Chromium socket initialization. Permission attempts were canceled. No browser pass or UI responsiveness measurement is claimed. The complete browser test is included for execution on a machine that allows those operations. Core simulation, worker calculation, build, experimental runs, and headless performance measurements did execute.

## Inspect the implementation

| Location | Purpose |
| --- | --- |
| `src/engine.js` | Deterministic state transitions, accounting, validation, metrics |
| `src/app.js`, `src/style.css`, `index.html` | Browser laboratory and visual inspection |
| `tests/` | Invariant, adversarial, and metamorphic regression tests |
| `experiments/config.json` | Reproducible experimental treatments and seeds |
| `scripts/experiments.mjs` | Runs paired controlled simulations |
| `scripts/benchmark.mjs` | Measures throughput, persistence, and long-run behavior |
| `results/` | Actual generated measurements and an example save |
| `docs/MODEL.md` | Implemented rules and numerical choices |
| `docs/EXPERIMENTS.md` | Research questions, results, limitations |
| `docs/VERIFICATION.md` | Test coverage and adversarial findings |
| `docs/PERFORMANCE.md` | Measured performance and limits |
| `docs/ENGINEERING_REPORT.md` | Delivery status and evidence boundaries |

Histories are bounded, so a save preserves the complete state needed to continue the simulation but only the retained observational history. Deterministic replay is promised within the tested JavaScript runtime for the same state and interventions; cross-engine bitwise equality is not claimed.