# ADR 0003: Use pinned HeavenClient only as an attributed client reference

Status: accepted

Date: 2026-08-19

## Context

The MapleWeb client was imported from the AGPL JourneyClient/LibreMaple lineage. The current AGPL HeavenClient repository continues the same native-client lineage and contains login views and several UI/domain implementations that are absent from the imported browser baseline. Its current client is still intended for v83 servers, but it is tested with much newer v229.2 game data and a native Windows runtime.

## Decision

Pin `ryantpayton/MapleStory-Client` commit `cbb0fe27cf9683a12eca0a569121d8033cdc2a4d` as a read-only, attributed client implementation reference.

Compatible AGPL code may be adapted when it materially closes a MapleWeb feature gap, provided that each adaptation:

- is reconciled field-by-field with the pinned Cosmic v83 protocol;
- is ported to the existing cross-platform/WASM abstractions instead of restoring native Windows dependencies;
- does not import v229.2 data, identifiers, binaries, hardware fingerprinting, or asset-version assumptions;
- preserves relevant copyright and AGPL notices; and
- receives the same fixture, live-server, and browser evidence required by the feature matrix.

HeavenClient does not replace Cosmic as the server/protocol authority and does not, by itself, prove feature completeness.

## Consequences

- Missing UI and state-machine work can reuse compatible code from the client’s own open-source lineage.
- Every imported feature still needs v83 protocol and post-Chaos UI compatibility review.
- Source/SBOM provenance must identify HeavenClient if deployed code is materially adapted from it.
