# Pinned Cosmic v83 baseline

MapleWeb consumes Cosmic as an unmodified server dependency. The client repository does not vendor Cosmic source or change its protocol, schema, scripts, or gameplay behavior.

## Reproducible source and build

The locked source is `P0nk/Cosmic` at commit `fec53bc7714dc0f1ae3f50b2986cdf2727e0912a`. Its repository, commit, Java runtime, Apache Maven distribution, download URLs, and publisher archive checksums live in `toolchains.lock.json`. The bootstrap scripts verify Temurin with SHA-256 and Maven with Apache's SHA-512 before extraction; builds invoke that repo-local Maven directly rather than allowing the wrapper to download an unchecked distribution.

Windows:

```powershell
./scripts/bootstrap_toolchain.ps1
./scripts/bootstrap_cosmic.ps1
./scripts/build_cosmic.ps1 -SkipBootstrap
```

Linux x86_64:

```bash
./scripts/bootstrap_toolchain.sh
./scripts/bootstrap_cosmic.sh
./scripts/build_cosmic.sh --skip-bootstrap
```

The scripts place source below `.cache/references/Cosmic`, Maven settings/cache state below `.cache/maven`, and the verified artifact plus attestation below `.cache/build/cosmic`. Maven's user home and local repository are explicitly redirected there, and host-provided Maven/Java option variables are cleared for the build. The scripts reject symlink/reparse-point output trees, refuse a changed source checkout both before and after Maven runs, and never write Cosmic files tracked by Git. Maven's ignored `target/` directory is the only source-checkout build output.

The attestation records the exact commit, verified clean state, actual Java runtime, Maven version, publisher archive hashes, lock digest, test totals, artifact digest, and aggregate Liquibase migration-tree digest. Treat `Cosmic.jar` as publishable only when its sibling `build-attestation.json` exists and its recorded size/hash match; a failed build deliberately removes the prior attestation before doing work.

## Database initialization and migration

Cosmic owns the gameplay schema. At the locked commit it runs Liquibase during server startup from `src/main/resources/db/changelog-root.xml`; startup fails if migration cannot complete. MapleWeb must not maintain a competing schema or replay individual SQL files out of order.

The clean environment procedure is:

1. Create an empty MySQL 8 schema dedicated to the environment.
2. Create a Cosmic runtime user for that schema. During initialization it needs the DDL and DML privileges required by the locked Liquibase change sets.
3. Create a deployment-only copy of Cosmic's `config.yaml` outside the public document root. Set `DB_HOST`, `DB_USER`, `DB_PASS`, and `DB_URL_FORMAT` there; never commit the password.
4. Start the exact attested `Cosmic.jar` from the directory containing that private configuration. Wait for Liquibase and server readiness to complete.
5. Record the resulting Liquibase state and application smoke evidence. Do not edit generated tables manually.
6. After the registration adapter is verified, set Cosmic's existing `AUTOMATIC_REGISTER` option to `false`. Keep `BCRYPT_MIGRATION` enabled. The public deployment intentionally sets `ENABLE_PIN: false`; PIC remains enabled and separate.

Disposable integration databases use the same procedure and are destroyed only by the test harness that created them. Production backup, restore, privilege reduction, and rollback rehearsal remain Stage 8 gates.

## Separation of database identities

Cosmic and the registration adapter must use different database users. The registration user receives only the account-table operations proven necessary by the Stage 3 adapter; it receives no character, inventory, gameplay, DDL, file, process, grant, or administrative privileges. Credentials are supplied through root-readable service configuration at deployment and are never exposed to the browser bundle.
