Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

F0 bridge and MCP test plan

Purpose

F0 is the first implementation milestone: a Lua bridge loaded into Cheat Engine 7.7 and a Rust MCP server over stdio. It is blocked until the implementation license is chosen. This page defines the acceptance tests now, so the spike does not invent its success criteria after the fact.

F0 exposes six tools:

  • ce_info
  • process_list
  • process_open
  • memory_read
  • scan_start
  • scan_results

Their input and output schemas are in spec/contracts/f0.yaml, with the conventions explained in F0 tool contracts. The tests below must validate results against those schemas.

Nothing on this page is implemented or tested.

Preconditions

ItemRequirement
LicenseAn explicit implementation license has been chosen
Cheat Engine7.7 from /Applications/CheatEngine77.app
HostmacOS 26 on arm64 for the primary run
TargetA disposable, self-signed test process with known values
SIPRecord the host state; do not disable it for the first run
PermissionsRecord whether the target is debuggable without elevation
RepositoryNo Cheat Engine assets, copied docs or target binaries committed

The test target should contain a known integer, float, string and a small allocated buffer. It must be safe to terminate and restart. Do not use a third-party game or a process whose state matters.

Bridge tests

Loading and discovery

  • Load bridge/ce_bridge.lua without modifying the application bundle.
  • Confirm the bridge version, Cheat Engine version and Lua version in ce_info.
  • Confirm ~/.ce-mcp/bridge.json is created.
  • Confirm the file mode is 0600; record the owner and directory mode.
  • Confirm the file contains a port, token and PID, and no secrets in logs.
  • Restart Cheat Engine and confirm the bridge can be loaded again without a stale port or token.

Protocol version compatibility

  • Modern stdio: call server/discover, then tools/list, then one read.
  • Legacy stdio: perform the 2025-11-25 initialize handshake, then tools/list and one read. Record whether the same tool schemas are returned.
  • Send an unsupported version and verify -32022 with the supported version list, not a silent downgrade.
  • If the SDK does not expose a working legacy path on stdio, record it and narrow the compatibility claim instead of advertising an untested path.

Network boundary

  • Confirm the listener is bound to 127.0.0.1, not 0.0.0.0 or ::.
  • Attempt a connection from another host or interface; it must fail.
  • Attempt a connection with a missing token, an empty token and a wrong token; each must be rejected before Lua evaluation.
  • Send a valid request after a rejected request; the bridge must remain usable.

Framing and limits

  • Send a valid length-prefixed JSON request and verify the response frame.
  • Send a length prefix larger than the configured maximum; the bridge must reject it without allocating an unbounded buffer.
  • Send a truncated frame, then close the socket; the bridge must recover.
  • Send invalid UTF-8 or invalid JSON; return a structured error.
  • Send an unknown method; return a structured error and keep the connection usable.
  • Send two requests in one read; both must be processed in order.
  • Send a partial frame across reads; it must be reassembled correctly.
  • Record the actual behavior of LuaPipe.Timeout and createServerSocket; the documentation describes timeouts in seconds, but the bridge must verify it.

Lifecycle and concurrency

  • Disconnect a client while the bridge is idle; no thread or socket leak.
  • Disconnect during a long scan; the scan must be cancellable or marked orphaned.
  • Connect a second client; the documented behavior is one active client, or a clean CE_BACKEND_BUSY, not interleaved evaluation.
  • Request shutdown; the bridge must close the listener and exit its thread.
  • Restart the bridge and verify old process/scan handles are not silently reused.

Tool tests

ToolTestPass condition
ce_infoCall with no argumentsReturns server, Cheat Engine, Lua, OS and architecture versions
ce_infoCall with no target openStill succeeds; no process-dependent fields are invented
process_listList all processesReturns bounded results with PID and name
process_listFilter by exact and partial nameFilter is case-insensitive where documented; no duplicate PIDs
process_listPaginateCursor is stable for an unchanged process list; invalid cursor is rejected
process_openOpen the test target by PIDReturns a process handle and correct PID
process_openOpen by name with one matchReturns the same target
process_openOpen an invalid PID or nameReturns CE_PROCESS_NOT_FOUND; no handle is leaked
process_openOpen a protected processReturns a structured permission error; does not bypass SIP
memory_readRead a known integer, float and stringBytes match the target before and after the call
memory_readRead an unmapped addressReturns CE_INVALID_ADDRESS; connection remains usable
memory_readRequest more than the size limitReturns CE_LIMIT_EXCEEDED; no partial silent truncation
memory_readRead after the target exitsReturns CE_PROCESS_CLOSED or the documented equivalent
scan_startScan for a known 4-byte integerReturns a scan handle and task state
scan_startScan for a known float and stringEach value type follows its documented comparison and alignment
scan_startScan with an invalid rangeReturns CE_INVALID_ARGUMENT
scan_startCancel a running scanReturns CE_SCAN_CANCELLED and releases the scan thread
scan_resultsRead results from a completed scanReturns bounded, paginated results with addresses and values
scan_resultsRead results from an unknown handleReturns CE_SCAN_NOT_FOUND
scan_resultsRead before the scan completesReturns CE_SCAN_BUSY or a progress object, not partial garbage
scan_resultsPaginate to the endLast page has no duplicate or skipped addresses

Handle tests

  • A process_handle from process_open is required by memory_read and scan_start.
  • A scan_handle from scan_start is required by scan_results.
  • Unknown, expired and cross-session handles return CE_HANDLE_EXPIRED.
  • Closing a process invalidates its scan handles.
  • Handle IDs are opaque and are not derived from target addresses.
  • A handle from one MCP connection is not accepted by another unless the protocol explicitly supports that sharing; F0 should not support it.

Error and security tests

  • Every tool error uses the structured error object from Errors.
  • Token and absolute user paths do not appear in error messages or logs.
  • The bridge does not evaluate Lua from unauthenticated clients.
  • The bridge does not expose an arbitrary shell, filesystem or network proxy.
  • The server does not install the bridge silently.
  • The token file is not committed, printed or included in diagnostics.
  • A malformed request cannot crash Cheat Engine; if it can, record it as a blocking defect.

Evidence to capture

For every run, record:

  1. the commit and bridge version;
  2. the macOS version, architecture and SIP state;
  3. the Cheat Engine version and binary SHA-256;
  4. the test target identity and how it was built;
  5. the exact request and response, with secrets redacted;
  6. pass, fail or blocked, with the observed error;
  7. timing for scan start, scan completion and a 1 MiB read;
  8. whether elevation was required.

Exit criteria

F0 is complete only when:

  • all six tools satisfy the table above on macOS arm64;
  • every successful result validates against its schema in spec/contracts/f0.yaml;
  • the modern and legacy stdio version paths behave as documented;
  • the bridge survives malformed input, reconnects and restart;
  • the localhost-only and token checks pass;
  • the handle lifecycle and error mappings are demonstrated;
  • no Cheat Engine binary, copied documentation or target binary is committed;
  • the evidence is recorded in the journal and the coverage page is updated.

Pointer scan, stack traces, debugger controls, UI form opening, snapshot restore and trainer generation are outside F0. Their dispositions are in Gap deferrals.

Open questions this plan must answer

  • Does createServerSocket(port, true) accept only loopback on macOS?
  • What is the real timeout unit for LuaPipe.Timeout?
  • Does openProcess(0) close the process, and is it safe to call twice?
  • Which arm64 scan value types and alignments match the Lua documentation?
  • Does loading from Lua/Autorun differ from loading through the Lua Engine?
  • Does the code signature or hardened runtime restrict either load path?