v0.1.0 to v0.1.0

---

name: lua-client-server-contract-audit

description: Use when normalized Lua client/server RPC contract copies or generated protocol tables disagree on opcode, request-response fields, types, ordering, or source authority.

version: 0.1.0

author: GameStudio-CodexKIT

license: MIT

compatibility:

engines: [engine-agnostic, unity]

versions: [lua-5.1+]

platforms: [windows, linux]

metadata:

studio:

type: diagnostic

lifecycle_stage: verify

risk_level: read-only

packs: [cpp-lua-mmorpg]

side_effects: none

artifact: lua-contract-audit.json

required_evidence: [client-contract, server-contract, mismatch-list]

owner: HoaTV Studio

reviewer: null

last_reviewed: 2026-08-07

provenance:

derived_from: none

patterns_from: [sanitized client-server synchronization map, source-to-generated ownership]

copied_text: none

---

# Lua Client Server Contract Audit

## Overview

Compare normalized client and server protocol contracts without editing either copy, then identify missing packets, opcode drift, field drift, and authority ambiguity.

## When to use

Use for Lua packet failures, RPC mismatch, silent request drops, wrong opcodes, missing response fields, duplicated protocol tables, or client/server copy drift.

## When NOT to use

Do not use for translation text authority, generic localization keys, or runtime network capture that requires service control or credentials.

## Required inputs and context discovery

Collect authoritative and copied protocol paths, generation pipeline, packet names, opcodes, field order/types, request/response direction, client/server versions, and no-touch generated paths.

## Safety and risk level

Read-only. Never edit generated protocol copies directly, send live exploit packets, start servers, or mutate network state during the audit.

## Workflow

1. Identify source-of-truth and generated/copied protocol files.

Completion criterion: every compared file is labeled source, generated, copy, or unknown.

2. Normalize packet names, opcodes, direction, and fields into deterministic maps.

Completion criterion: parsing ambiguity is reported rather than guessed.

3. Compare presence, opcode, field names/order/types, and request/response pairing.

Completion criterion: mismatches cite both client and server paths.

4. Trace the generation or synchronization path for each mismatch.

Completion criterion: the correct editable source is identified or BLOCKED.

5. Propose source-first fixes and regression fixtures without mutating live services.

Completion criterion: generated copies are never hand-edited.

## Evidence and output contract

Produce `lua-contract-audit.json` with source/copy classification, missing packets, opcode mismatches, field mismatches, authority, generation path, limitations, and recommended source fixes.

## Handoff contract

Record client/server paths, versions, source authority, mismatches, generated no-touch files, parsing limitations, and next source-first action.

## Pitfalls and anti-rationalization

- Same packet name does not prove same opcode or fields.

- Copy synchronization should not be fixed in every destination manually.

- Do not treat localized labels as protocol fields.

- Do not send packets to prove a static contract mismatch.

## Verification checklist

- [ ] Source and copies are classified.

- [ ] Packet presence, opcodes, and fields were compared.

- [ ] Mismatches cite both sides.

- [ ] Generated files remain untouched.

- [ ] Source-first regression plan exists.

## References and scripts

Use the bundled [scripts/lua_contract_audit.py](scripts/lua_contract_audit.py) on normalized JSON exports and project-local generation maps for authority.