完善客户端功能并加入40250一致性审计
This commit is contained in:
shen
@@ -0,0 +1,108 @@
|
||||
# Audit ledger schema
|
||||
|
||||
`audit/manifest.json` is machine-readable and version controlled. Keep one entry per externally meaningful behavior, not one entry per source file.
|
||||
|
||||
## Contract fields
|
||||
|
||||
Required fields:
|
||||
|
||||
- `id`: stable dotted ID such as `combat.local.normal_attack`.
|
||||
- `title`: concise behavior name.
|
||||
- `subsystem`: `network`, `lifecycle`, `movement`, `combat`, `skill`, `world`, `item`, `ui`, `resource`, `render`, `audio`, or another stable domain.
|
||||
- `priority`: `P0`, `P1`, `P2`, or `P3`.
|
||||
- `status`: one of the statuses below.
|
||||
- `reference.files`: paths relative to `manifest.reference_root`.
|
||||
- `reference.symbols`: relevant 40250 symbols.
|
||||
- `implementation.files`: paths relative to the repository root.
|
||||
- `implementation.symbols`: corresponding native or GDScript symbols.
|
||||
- `equivalence`: implementation-equivalence matrix described below.
|
||||
- `platform_adaptations`: documented engine/platform substitutions; use an empty array when none exist.
|
||||
- `evidence.contract`: detailed Markdown contract path relative to the repository root.
|
||||
- `evidence.tests`: test paths relative to the repository root.
|
||||
- `evidence.last_test_result`: `PASS`, `FAIL`, or `NOT_RUN`.
|
||||
- `remaining`: explicit unverified branches; use an empty array only when none remain.
|
||||
|
||||
Optional generated fields:
|
||||
|
||||
- `fingerprints.reference`: combined SHA-256 for the listed reference files.
|
||||
- `fingerprints.implementation`: combined SHA-256 for implementation files.
|
||||
- `fingerprints.tests`: combined SHA-256 for test files.
|
||||
- `stale_reasons`: generated reasons for invalidation.
|
||||
- `verified_commit`: Git commit at the last completed verification.
|
||||
- `notes`: concise information that does not belong in the detailed contract.
|
||||
|
||||
## Implementation-equivalence matrix
|
||||
|
||||
Every contract that reaches `STATIC_VERIFIED` or `TEST_VERIFIED` must contain all fields below with the value `VERIFIED`:
|
||||
|
||||
```json
|
||||
{
|
||||
"equivalence": {
|
||||
"preconditions": "VERIFIED",
|
||||
"branch_structure": "VERIFIED",
|
||||
"algorithms_formulas": "VERIFIED",
|
||||
"state_transition_order": "VERIFIED",
|
||||
"constants_units": "VERIFIED",
|
||||
"timing_event_sources": "VERIFIED",
|
||||
"resource_data_sources": "VERIFIED",
|
||||
"protocol_side_effects": "VERIFIED",
|
||||
"interruption_failure_cleanup": "VERIFIED"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`VERIFIED` means the detailed contract contains a branch-by-branch comparison and no material semantic difference. Matching a few outputs or passing only happy-path tests is not enough.
|
||||
|
||||
Language and engine boundary substitutions belong in `platform_adaptations`:
|
||||
|
||||
```json
|
||||
{
|
||||
"platform_adaptations": [
|
||||
{
|
||||
"reference": "D3DXMATRIX row-vector transform",
|
||||
"implementation": "Godot Transform3D column-vector transform",
|
||||
"invariant": "actor, offset, and bone composition produces the same world-space transform",
|
||||
"tests": ["project/example_transform_parity_test.gd"]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
An adaptation may change APIs or representation, never gameplay rules, branch outcomes, timing authority, or data authority. Missing equivalence proof keeps the contract at `MAPPED` or `PARTIAL`.
|
||||
|
||||
## Status meanings
|
||||
|
||||
- `UNMAPPED`: reference behavior has no located implementation.
|
||||
- `PARTIAL`: known material behavior or branches are missing.
|
||||
- `MAPPED`: both sides are located but not fully compared.
|
||||
- `STATIC_VERIFIED`: complete material call-chain and implementation-equivalence comparison is documented.
|
||||
- `TEST_VERIFIED`: static equivalence verification plus meaningful passing tests.
|
||||
- `IN_PROGRESS`: currently being audited; do not use as a long-term resting state.
|
||||
- `STALE`: reference, implementation, or test evidence changed after verification.
|
||||
- `REGRESSION`: a previously passing behavior test now fails.
|
||||
- `BLOCKED`: concrete missing input or dependency prevents progress.
|
||||
- `EXCLUDED`: not ported by design; requires `exclusion_reason` and replacement verification.
|
||||
|
||||
## Verification gates
|
||||
|
||||
`STATIC_VERIFIED` and `TEST_VERIFIED` both require:
|
||||
|
||||
1. Non-empty reference and implementation file lists.
|
||||
2. Existing detailed contract document.
|
||||
3. Every implementation-equivalence field set to `VERIFIED` with supporting detail in the contract.
|
||||
4. Every platform adaptation documented with its invariant and focused tests.
|
||||
5. No unresolved material branch in `remaining`.
|
||||
|
||||
`TEST_VERIFIED` additionally requires at least one existing automated test and `last_test_result` equal to `PASS`.
|
||||
|
||||
When a verified entry becomes stale, retain its previous evidence and history. Do not delete the entry or recreate it under a new ID.
|
||||
|
||||
## History events
|
||||
|
||||
Append one compact JSON object per meaningful state change to `audit/history.jsonl`:
|
||||
|
||||
```json
|
||||
{"time":"2026-09-19T00:00:00Z","event":"status_changed","id":"combat.local.normal_attack","from":"MAPPED","to":"TEST_VERIFIED","reason":"call chain audited and tests passed"}
|
||||
```
|
||||
|
||||
Never store credentials, packet payload secrets, binary captures, or generated screenshots in the ledger.
|
||||
@@ -0,0 +1,49 @@
|
||||
# Project map
|
||||
|
||||
## Reference client
|
||||
|
||||
- Root: `../40250/Server Client TMP4/ClientVS22/source`
|
||||
- High-level game and packet flow: `UserInterface`
|
||||
- actors, motion, maps, flying objects: `GameLib`
|
||||
- rendering, input, collision primitives: `EterLib`
|
||||
- effects: `EffectLib`
|
||||
- Granny integration: `EterGrnLib`
|
||||
- audio: `MilesLib`
|
||||
- terrain: `PRTerrainLib`
|
||||
|
||||
Use the Visual Studio project and active preprocessor flags to distinguish reachable product code from disabled, obsolete, and third-party code.
|
||||
|
||||
## Current client
|
||||
|
||||
- GDScript runtime and tests: `project/`
|
||||
- native extension: `extension/`
|
||||
- format readers: `formats/`
|
||||
- shared/native libraries: `libgr2/`
|
||||
- extracted assets and tables: `assets/`
|
||||
- numerical reference oracle: `oracle/`
|
||||
- host-side tools: `tools/`
|
||||
|
||||
## Existing evidence
|
||||
|
||||
- `docs/CLIENT-GAP.md`: historical broad gap analysis; migrate useful claims into contracts rather than trusting status text.
|
||||
- `docs/CLIENT-PARITY-AUDIT-AND-FIX-GUIDE.md`: existing methodology and high-risk domains.
|
||||
- `docs/CLIENT-40250-PORT.md`: porting context.
|
||||
- `docs/PARITY-GAP.md`: visual/rendering gap notes.
|
||||
- `oracle/run-diff-suite.sh`: Granny numerical comparison suite.
|
||||
- `project/test_*_parity.gd` and `project/*_test.gd`: existing tests; inspect assertions before treating them as evidence.
|
||||
|
||||
## Typical verification commands
|
||||
|
||||
Run a narrow Godot test with:
|
||||
|
||||
```bash
|
||||
godot --headless --path project --script project/test_name.gd
|
||||
```
|
||||
|
||||
Some scripts expect the path relative to `project/` instead:
|
||||
|
||||
```bash
|
||||
godot --headless --path project --script test_name.gd
|
||||
```
|
||||
|
||||
Follow the convention already used by the selected test. Always finish code changes with `git diff --check`.
|
||||
Reference in New Issue
Block a user