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:

{
  "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:

{
  "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:

Non-empty reference and implementation file lists.
Existing detailed contract document.
Every implementation-equivalence field set to VERIFIED with supporting detail in the contract.
Every platform adaptation documented with its invariant and focused tests.
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:

{
  "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:

{"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.

6.9 KiB Raw Blame History