# 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 file paths relative to the repository root (paths only; missing files fail `refresh`).
- `evidence.commands` (optional): command lines and live/manual evidence descriptions.
- `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.

A contract's `evidence.tests` and `implementation.files` must be reachable from the runtime
(loaded by `AppFlow`/`GameScene`/the native extension in a normal session). A file used only by its
own test is not an implementation and its test is not evidence.

## Port-map entries

One JSON file per 40250 source unit at `audit/port-map/<Lib>/<File>.json`:

```json
{
  "reference": "UserInterface/InstanceBaseMovement.cpp",
  "reference_sha256": "<sha256 of the reference file>",
  "priority": "P0",
  "contracts": ["movement.keyboard.motion", "movement.remote_sync_state"],
  "functions": {
    "CInstanceBase::SetMoveSpeed": {
      "status": "PORTED",
      "impl": ["project/player_controller.gd:set_server_speed", "extension/src/net/entity_store.cpp:motion_move_speed"],
      "note": ""
    },
    "CInstanceBase::__EnableSkipCollision": {"status": "TODO"}
  }
}
```

- Function keys are the reference's qualified names (`Class::Method`, or the free-function name).
- `status` is one of `TODO`, `PORTED`, `RUN_AS_IS`, `ADAPTED`, `N_A`, `DIVERGENT`, `NEEDS_LIVE`
  (meanings in `SKILL.md`).
- `RUN_AS_IS` is valid only for a Python script unit whose exact reference bytes are shipped and
  loaded unchanged by embedded CPython. It requires `impl` (the packaged script path) and a
  non-empty `evidence` list naming target-platform import/runtime evidence. The unit's
  `reference_sha256` plus the committed resource manifest bind the evidence to exact source bytes.
- `impl` is required for `PORTED`/`RUN_AS_IS`/`ADAPTED`/`NEEDS_LIVE`; `note` is required for `ADAPTED`, `N_A`,
  `DIVERGENT` and `NEEDS_LIVE`. `ADAPTED` also needs a `test` path.
- When `reference_sha256` no longer matches the file, every non-`TODO` function in the unit must be
  rechecked before the hash is updated.

## History events

Append one compact JSON line per round to `audit/history.jsonl`:

```json
{"time":"2026-09-22T00:00:00Z","event":"port_round","unit":"UserInterface/InstanceBaseMovement.cpp","ported":["CInstanceBase::SetMoveSpeed"],"deleted":["player_controller.gd clampf(0.25,3.0)"],"divergent":[],"needs_live":[],"tests":["project/keyboard_motion_timeline_test.gd PASS"],"commit":"c5c183da"}
```

Contract status changes still use `{"event":"status_changed","id":...,"from":...,"to":...,"reason":...}`.

Never store credentials, packet payload secrets, binary captures, or generated screenshots in the ledger.