Crusader_Decomp/docs/ghidra-mcp-class-lifting-endpoint-spec.md

GhidraMCP Class-Lifting Endpoint Spec

Purpose

This note drafts the endpoint surface needed to support the Remorse class-lifting workflow described in docs/remorse-cpp-decompilation-plan.md and grounded by docs/remorse-class-candidate-inventory.md.

This is not an implementation batch. It is a local design spec so that when MCP work resumes later, the endpoint set can be built in a way that matches the actual reverse-engineering workflow instead of a generic symbol-edit API.

Design Goals

The new endpoints should make these workflows cheap and repeatable:

1. create class and namespace containers in Ghidra without touching the GUI
2. move already-renamed flat functions under explicit class ownership
3. build typed instance structs and typed vtables from verified evidence
4. attach this-pointer semantics and method signatures to recovered methods
5. preserve ambiguity when evidence is partial instead of forcing speculative class conversions
6. support dry-run review before any bulk symbol or datatype mutation

Non-Goals

• automatic recovery of class hierarchies from raw heuristics alone
• one-shot convert whole binary to C++ classes
• speculative inheritance inference without vtable or field evidence
• silent symbol moves that hide rename collisions or ownership conflicts

Existing MCP Behavior To Reuse

The local fork already has patterns worth reusing:

• explicit target selectors: project_dir, project_name, folder_path, program_name
• dry-run oriented edit-plan behavior
• machine-friendly outputs rather than prose-heavy summaries
• backward-compatible aliases when route names change

Every new class-lifting endpoint should follow the same conventions.

Core Object Model Assumptions

The class-lifting workflow needs to manipulate four kinds of things explicitly:

1. namespace/class containers in the symbol tree
2. function ownership and method naming
3. datatypes for instance structs and vtables
4. binding metadata between methods, vtable slots, and instance layouts

That means symbol-only endpoints are not enough. Datatype endpoints and method-binding endpoints are part of the minimum viable feature set.

Proposed Endpoints

1. create_namespace

Create a namespace or class container.

Parameters:

• name: string
• parent_path: string, optional
• kind: enum namespace|class, default namespace
• explicit target selectors, optional

Response:

• status
• created: bool
• kind
• path
• symbol_id or equivalent stable identifier if available
• collision: existing path info when create is skipped or merged

Why it matters:

• lets the workflow create Entity, SpriteNode, EntityVmRuntime, or similar owners before moving methods

2. list_namespace_members

Return members of a namespace or class container in a machine-friendly form.

Parameters:

• path: string
• include_child_namespaces: bool, default false
• include_functions: bool, default true
• include_data: bool, default true
• explicit target selectors, optional

Response:

• status
• path
• members: array of { kind, name, address?, datatype?, child_count? }

Why it matters:

• needed for inventory verification and idempotent batch moves

3. move_symbol_to_namespace

Move a function or data symbol under a namespace/class.

Parameters:

• symbol_address: string, optional
• symbol_name: string, optional
• one of the above required
• namespace_path: string
• new_name: string, optional
• conflict_policy: enum fail|keep_existing|rename_incoming, default fail
• dry_run: bool, default false
• explicit target selectors, optional

Response:

• status
• moved: bool
• old_path
• new_path
• collision: optional structured collision detail

Why it matters:

• this is the basic operation needed to turn flat functions into methods after evidence is verified

4. set_function_class

High-level helper to move a function into a class and apply method-oriented naming/signature metadata in one call.

Parameters:

• function_address: string
• class_path: string
• method_name: string
• this_param_name: string, optional, default this
• calling_convention: string, optional
• dry_run: bool, default false
• explicit target selectors, optional

Response:

• status
• function_address
• old_path
• new_path
• signature_before
• signature_after

Why it matters:

• reduces the number of separate write operations for the common move + rename + set this semantics workflow

5. create_or_update_struct

Create or update a structure datatype.

Parameters:

• name: string
• category_path: string, optional
• size: integer, optional
• packing: integer, optional
• fields: array of field specs

Each field spec:

• offset: integer

• name: string

• datatype: string

• comment: string, optional

• confidence: enum high|medium|low, optional

• dry_run: bool, default false

• explicit target selectors, optional

Response:

• status
• datatype_path
• created_or_updated
• size
• field_count
• conflicts: array, optional

Why it matters:

• class lifting without struct authoring is not enough for readable or recompilable source

6. create_or_update_vtable

Create a vtable datatype as a structure of function pointers.

Parameters:

• name: string
• category_path: string, optional
• slots: array of slot specs
• dry_run: bool, default false
• explicit target selectors, optional

Each slot spec:

• offset: integer
• name: string
• function_address: string, optional
• prototype: string, optional
• comment: string, optional

Response:

• status
• datatype_path
• slot_count
• bound_functions: array of { offset, function_address, name }

Why it matters:

• this is the missing datatype-side half of stable virtual dispatch recovery

7. set_function_this_type

Apply or update this-pointer typing on a function.

Parameters:

• function_address: string
• this_type: string
• this_param_name: string, optional, default this
• this_storage: enum stack|register|farptr, optional
• calling_convention: string, optional
• dry_run: bool, default false
• explicit target selectors, optional

Response:

• status
• function_address
• signature_before
• signature_after

Why it matters:

• many decompiler improvements only show up after the instance type is attached to the first argument correctly

8. analyze_vtable

Read-side helper that inspects a suspected vtable region and emits slot candidates.

Parameters:

• address: string
• slot_count: integer, optional
• stop_on_invalid_pointer: bool, default true
• explicit target selectors, optional

Response:

• status
• address
• slots: array of { offset, target_address, target_name, is_function, current_owner?, comment? }
• warnings: array, optional

Why it matters:

• this is the minimum analysis helper needed before class authorship is applied at scale

9. apply_class_layout

Bind a class namespace, instance struct, optional vtable struct, and a set of methods in one dry-runnable transaction.

Parameters:

• class_path: string
• instance_struct: string
• vtable_struct: string, optional
• vtable_address: string, optional
• methods: array of method specs
• dry_run: bool, default false
• explicit target selectors, optional

Each method spec:

• function_address: string
• method_name: string
• slot_offset: integer, optional
• is_virtual: bool, default false
• this_type: string, optional
• comment: string, optional

Response:

• status
• class_path
• applied_methods
• applied_structs
• warnings

Why it matters:

• supports one-shot promotion of a verified family from notes into Ghidra with explicit review first

10. export_class_candidate

Read-side export helper for documentation and source-generation prep.

Parameters:

• class_path: string
• include_struct_fields: bool, default true
• include_vtable: bool, default true
• include_method_signatures: bool, default true
• explicit target selectors, optional

Response:

• machine-friendly JSON-like object containing class metadata, methods, field layouts, and slot maps

Why it matters:

• the local docs and future C++ skeleton emission need a clean export surface, not just screen scraping

Field Schemas

Struct field schema

Recommended stable shape:

{
  "offset": 0,
  "name": "vtable",
  "datatype": "EntityVTable *",
  "comment": "Primary vtable pointer",
  "confidence": "high"
}

Method schema

{
  "function_address": "0008:ba00",
  "method_name": "Init",
  "slot_offset": null,
  "is_virtual": false,
  "this_type": "EntityDispatchEntry *",
  "comment": "Base constructor-style init"
}

Vtable slot schema

{
  "offset": 20,
  "name": "OnEventType2",
  "function_address": "000b:3ab2",
  "prototype": "void (__far *OnEventType2)(SpriteNode *, Event *)"
}

Transaction And Safety Rules

All write-capable class-lifting endpoints should support:

• dry_run
• explicit target selectors
• structured conflict reporting
• idempotent repeat calls where practical
• no silent overwrite of unrelated symbols or datatype fields

Recommended conflict output shape:

• type: symbol_collision|datatype_collision|slot_conflict|owner_conflict|signature_conflict
• path or address
• existing
• requested
• resolution_options

Backward Compatibility And Aliases

Where practical, add aliases instead of replacing older names.

Recommended aliases:

• create_class -> create_namespace(kind=class)
• move_function_to_class -> set_function_class
• set_this_type -> set_function_this_type
• build_vtable -> create_or_update_vtable

This follows the local fork’s existing pattern of keeping compatibility wrappers when route names evolve.

Suggested Implementation Order

If implementation resumes later, the smallest useful sequence is:

1. create_namespace
2. move_symbol_to_namespace
3. set_function_this_type
4. create_or_update_struct
5. analyze_vtable
6. create_or_update_vtable
7. apply_class_layout
8. export_class_candidate

That order enables immediate manual class work after only the first three or four endpoints, while leaving the richer transactional workflows for later.

First Real Workflow To Target

The first workflow this API should make easy is the pilot family from the current inventory:

EntityDispatchEntryBase promotion workflow

1. create class namespace Remorse::EntityDispatchEntry
2. create instance struct EntityDispatchEntry
3. move 0008:ba00, 0008:bca8, 0008:bd53, 0008:bf8e, 0008:c01d, 0008:dbec, and constructor variants under that class as methods
4. attach this typing
5. analyze or define vtables 0x3b06, 0x2d10, 0x3afe, 0x3ad2, 0x3aa6
6. export the class candidate for repo-side documentation and C++ skeleton generation

If the endpoint surface handles that family cleanly, it is probably sufficient for the rest of the early C++ lifting work.

Open Questions To Resolve Later

• whether Ghidra class namespaces or plain namespaces produce better decompiler output in this 16-bit NE environment
• how best to encode far-pointer aware this conventions in method signatures
• whether vtable datatypes should be attached to concrete memory addresses automatically or only on explicit request
• whether confidence annotations should live in datatype comments, decompiler comments, or external export metadata

Summary

The endpoint surface needed here is not large, but it does need to span both symbol ownership and datatype authorship. If later MCP work only adds move function into class, it will still leave the hardest part of the C++ lift undone.

The minimum viable class-lifting feature set is therefore:

• namespace/class creation
• symbol-to-class moves
• this typing
• struct authoring
• vtable analysis/authoring
• one transactional apply_class_layout path