# Phase 3: Server Documentation & Schemas - Discussion Log

> **Audit trail only.** Do not use as input to planning, research, or execution agents.
> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.

**Date:** 2026-05-03
**Phase:** 03-server-documentation-schemas
**Areas discussed:** Canonical-snapshot ADR (interactive). Schema representation, Persistence ADR depth, Parity checklist + admin scope (Claude's discretion under "modernize and streamline" steer).

---

## Gray-area selection

| Option | Description | Selected |
|--------|-------------|----------|
| Schema representation | 39dll opcode table + .bno/.bnb/.bnu schemas — output format and Phase-4 coupling | (delegated to Claude) |
| Canonical-snapshot ADR | Three drift'd snapshots — pick / merge / leave parallel; older .gmd extraction question | ✓ |
| Persistence ADR depth | Layer-choice only vs draft schema in-phase | (delegated to Claude) |
| Parity checklist + admin scope | Granularity + admin-anti-port + modernized command surface scope | (delegated to Claude) |

**User direction for delegated areas:** "modernize and streamline the server infrastructure"

---

## Canonical-snapshot ADR

### Q1: Purpose

| Option | Description | Selected |
|--------|-------------|----------|
| Prod seed for migration (Recommended) | Pick/merge a snapshot to seed accounts + characters + MB at launch. Returning players see last character. SRV-10 consumes. | ✓ |
| Historical preservation only | Document role; no merge. New server launches empty; users re-register. Loses returning-player continuity. | |
| GML drift reference only | Compare snapshots only for script differences vs Master 5-4. World state ignored. Doesn't satisfy SRV-10. | |

**User's choice:** Prod seed for migration

### Q2: Resolution across the three

| Option | Description | Selected |
|--------|-------------|----------|
| Per-record latest-mtime merge (Recommended) | Walk all three. Per record, pick latest mtime. Conflict log. | |
| Pick one snapshot whole | Declare ONE canonical (e.g., enlyzeam-current). Skip merge. | ✓ (with tie-break per Q4) |
| Union by username, prefer enlyzeam-current on conflict | Union of all usernames; conflict → enlyzeam-current. | |

**User's choice:** Pick one snapshot whole — "should be the one with the largest dataset/filesizes"

### Q3: Older Master .gmd / .gb1 extraction

| Option | Description | Selected |
|--------|-------------|----------|
| Skip — Master 5-4 is SoT (Recommended) | Per CLAUDE.md hard rule. Don't extend Phase 1 extractor. Faster phase, no GML-drift to reconcile. | ✓ |
| Extract older as cross-check | Run extractor against Master 4.gmd for opcode-table validation. De-risks SDOC-02 at extraction cost. | |
| Decide per-need during execution | Default skip; on-demand extract if a trace breaks. Pragmatic. | |

**User's choice:** Skip — Master 5-4 is SoT

### Q4: PII handling for the seed snapshot

| Option | Description | Selected |
|--------|-------------|----------|
| Import (legacy_hash, algo, force_reset) staging tuples (Recommended) | Phase 3 specs the staging table. Phase 4 SRV-10/11 owns rehash + force-reset. Plaintext NEVER lands in prod. | ✓ |
| Discard all legacy passwords; force re-register | Drop localList.txt. Cleanest security but no email-on-file → ~298 users lose account ownership. | |
| Defer PII strategy to Phase 4 SRV-10 | Phase 3 documents file format only. Keeps Phase 3 narrow. | |

**User's choice:** Import (legacy_hash, algo, force_reset) staging tuples

### Q5: Tie-break on "largest dataset"

Measured snapshots:
- `enlyzeam-current`: 34M total / 1.4M UserData / 973 .bnu / 597-acct localList / 39549 B MB_Log (newer mtime)
- `enlyzeam-archive`: 46M total / 1.4M UserData / 967 .bnu / 597-acct localList / 39549 B MB_Log (older mtime)
- `local-current`: 36M total / 311K UserData / 211 .bnu / 90-acct localList / 27606 B MB_Log

| Option | Description | Selected |
|--------|-------------|----------|
| World-state — enlyzeam-current (Recommended) | 6 more .bnu than archive, equal localList, newer MB_Log. Archive's 12M edge is .exe + .gb1 + dev cruft (already excluded per Q3). | ✓ |
| Total size — enlyzeam-archive | Strict literal of "largest filesize". 46M total. Mass is older Master .exe + .gb1 backups. | |

**User's choice:** World-state — enlyzeam-current

---

## Claude's Discretion (delegated areas)

Per user direction "modernize and streamline the server infrastructure", Claude exercised discretion on:

- **SDOC-02 schema representation** — three-artifact layered output (canonical JSON + TS types in `tools/protocol-doc/output/` + rendered MD with AUTOGEN). Per-opcode metadata: byte, direction, mvp tag, fields with `gml_type`/`ts_type`/`byte_size`, GML script:line citation, hex sample bytes. Methodology = PITFALLS A4 GML-grep, captures = post-hoc validation only.
- **SDOC-03 save-format schemas** — same three-artifact pattern. **Wiki/16 errata first**: extracted server uses `file_text_*` line-based, NOT `file_bin_*` as wiki currently asserts. Sectioned grammar (`@TOPIC`/`@REPLY` markers) modeled explicitly.
- **SDOC-04 persistence ADR depth** — lock SQLite + better-sqlite3 + Drizzle + Litestream-to-Tigris. Phase 3 also drafts the full table schema (accounts, legacy_credentials_staging, characters, inventory_items, message_board_topics/replies, audit_log seeded empty for Phase 7, sessions). No original-table-shape preservation; new normalized SQL designed for the new server (modernize bias).
- **SDOC-01 subsystem narrative** — 11 subsystem MDs locked (account-auth, world-simulation, room-management, chat, persistence, packet-protocol, admin-anti-port, client-server-bridge, message-board, unknown-actions-status, README). Functional-cluster depth + key-script call-out (Phase 2 D-10 pattern). mvp tagging per Phase 2 D-04.
- **SDOC-05 parity checklist** — per-feature granularity (NOT per-opcode, NOT per-script). Each row: feature / originating_gml / originating_opcodes / originating_save_fields / mvp / disposition (in-phase-6 | in-phase-7 | deferred-stage-8 | rejected-with-reason) / reason / modernized_replacement. Aggressive `rejected-with-reason` for B1-incompatible or Ctrl+E-RCE-dependent features.
- **D-20 modernized admin command surface** — every rejected admin command paired with concrete TS intent shape (kick / mute / ban / assign-role / view-audit-log / mb-moderate / account-recover), NOT just a placeholder name. Phase 7 PAR-07 ships UI on a defined contract.
- **D-21 tooling** — two new `tools/<name>/` standalone Node CLIs (`tools/protocol-doc`, `tools/save-format-doc`), parallel Phase 1 D-17 / Phase 2 D-15. No workspace conversion.
- **D-22 lint discipline** — three new lints (lint-protocol, lint-save-formats, lint-parity) enforce per-row citation completeness and disposition coverage.

---

## Deferred Ideas

- Per-record merge across snapshots (rejected per D-02).
- Older Master `.gmd`/`.gb1` extraction (rejected per D-03).
- Local-current and enlyzeam-archive as canonical seeds (rejected per D-02).
- apps/server, packages/protocol, packages/game-logic scaffolds (Phase 4).
- Modernized admin web UI implementation (Phase 7 PAR-07).
- Wireshark capture of original traffic (post-hoc validation only).
- Older-snapshot legacy-credential import (rejected per D-02).