deep-clone-runtime

---
name: deep-clone-runtime
description: "Recover functions, types, ABI, and object semantics from vendor binary evidence, then build and integrate Runtime substitution / Hybrid version. Use for real function recovery and integration, reusing the recovered source to form Cloned software."
---

# Function recovery and Runtime substitution

## Recover functions and types under their original ownership

Write the evidenced original implementation into source. Connect function identity, local comparisons, actual hooks, and test decks.

Before writing implementation files, [analyze the likely original source language(s)](../deep-clone-scope/SKILL.md#identify-the-original-source-languages) of the code being recovered. Recover in those languages and choose file extensions accordingly. Do not substitute generated `.s` / `.S` for source-language recovery merely to reproduce instruction bytes. Assembly may be used as an intermediate aid or for parts evidenced as originally assembly; keep that role explicit.

### Required source organization and naming

Source organization and naming are mandatory. They constrain AI from leaving the original binary behind and writing a new implementation of its visible features. Probe first, then create files from those findings. Do not invent business directories and filenames and fit functions into them afterward.

```text
src/
  abi/
    <actual-original-binary-filename>/
      <probed-namespace>/
        <probed-class>/
          <probed-function-name>.<language-extension>
      <probed-procedural-function-name>.<language-extension>
  runtime_substitution/           Launch, process integration, hooks, exports, ABI bridges
  application/                    Explicit non-algorithmic application wrappers
```

- **Organize by original binary.** Every recovered function belongs under its original binary's actual filename. Do not merge implementations from different binaries under agent-invented feature categories.
- **Implementation filenames must come from probed function names. Do not make up source filenames.** Namespaces, classes, and function declarations also follow probe evidence. Omit namespace or class levels absent from the original function.
- **If the original name is unknown, keep investigating.** If a tool provides only an address-based identifier, retain that identifier and mark the original name unknown. Do not name it after a guessed business purpose.
- **Only mechanical filesystem adaptations are allowed.** Reversibly escape characters forbidden in filenames. Distinguish overloads by the probed full signature, not invented abbreviations or business names. Name shared type declarations after the probed class or type.
- **Separate support code from recovered implementations.** Exports, ABI bridges, loaders, hook support, and application wrappers may be named by responsibility. Do not put original business implementation there to evade these rules.

Correct filenames alone are insufficient. Recover objects, calculations, state transfer, and call dependencies from original evidence inside the functions; do not put a mathematically equivalent rewrite behind original names.

Keep all runtime integration code in `src/runtime_substitution/`: launching, process integration, hook installation and counts, export aliases, `.def`, C entry points, and ABI bridges. Do not create a second `runtime_substitution/` at the project root. This support code does not replace original types and methods. Maintain shared types under their original owner and reference them explicitly from other build targets; do not duplicate different layouts in consumers.

`src/application` handles only explicit non-algorithmic wrapping, such as command-line handling, file selection, and lifecycle adaptation. The core of Cloned software continues to use recovered source, not a new mathematically equivalent calculator.

### Questions every recovered function must answer

| Area | Recovery content |
| --- | --- |
| Original identity | Module, full symbol and aliases, address, namespace, class, or procedural owner. |
| ABI | Arguments and hidden arguments, value/reference passing, returns, calling convention, stack and registers, cross-language descriptors and hidden parameters. |
| Types and objects | Size, alignment, fields, inheritance or vtables, array shape and indexing, ownership, aliases, construction, and destruction. |
| Function semantics | Branches, calculations and writes, return relationships, errors, state changes, and call dependencies. |
| Numerical behavior | Conversions, operation order, rounding, FMA, vectorization, CPU dispatch, and actual selected paths. |
| Support boundary | Observed and tested inputs, unknown branches, temporary vendor dependencies, and further evidence needed. |

Check decompiler arguments such as `arg1`, inferred types, and temporary variables. Preserve unknowns rather than guessing classes or ownership. Feed layouts established by constructors, methods, or call sites back into shared types, avoiding inconsistent raw offsets between functions.

Algorithms and data structures both belong to recovery. Input parsing, object management, data preparation, processing, state updates, post-processing, and output all need recovery when in scope. Do not recover only a numerical kernel and fill the rest with newly written workflows.

Update known semantics and unknown branches each time. Prioritize real gaps on the current feature's call path. Counts of functions with no observed hits or of helper functions do not establish added coverage. On completing a function's recovery and verification, [clear its intermediate evidence](../deep-clone/references/workflow.md#evidence-lifecycle).

## Build and runtime substitution

### Build and third-party dependencies

Bind builds to source revision, reproducible uncommitted changes, compile/link commands, configuration, toolchain, dependencies, and artifact hashes. Check the artifact actually used at runtime. Toolchain, ABI, and floating-point options affect instructions, stack, operation order, vectorization, and CPU paths; compiler compatibility does not establish equivalence.

Separate product dependencies from verification tools. For example, ARPACK is an eigensolver dependency and follows the project's third-party import, build, link, and install conventions. If h5py only reads results for comparison, install it on the verification machine. Classify other software by its actual use.

Bring required third-party dependencies into the independent build, preserving compatible versions and build settings. Prefer Conan to manage product dependencies. Check whether Conan is available: if it is not, discuss adopting it with the user before installing it; if it is, configure it together with the user.

### Common runtime substitution structure

Connect original process and module identity → original symbol or relative location → recovered artifact and entry point → ABI connection → mode and runtime evidence.

Use the [substitution configuration template](assets/substitution.example.json) and the [integration steps](#integrate-runtime-substitution). Its initial mode is `off`; it provides no evidence that hooks have been installed.

Keep build and integration boundaries aligned with original modules. A native shared-library target can use one recovery library per original module, coexisting with the vendor; other platforms use their corresponding loading mechanism. Preserve [original source ownership](#recover-functions-and-types-under-their-original-ownership).

Provide explicit off, observe-only, and substitution modes. Keep an unsubstituted Vendor version as the baseline. Confirm loaded module versions and entry points; record installation errors, hits, call scope, and delegation. A failed hook must not silently fall back to vendor and report recovery success.

Record dependencies still executed by vendor. A function declared recovered must execute its recovered body, without hidden delegation to the original. That declaration does not establish recovery of its whole call chain.

Handle code and object lifetimes, failures, and cleanup after stopping. Hook APIs may vary; check capabilities through the [binary tools skill](../deep-clone-binary/SKILL.md#minimum-binary-probing-capabilities).

Library and build-target names, OS, compiler, configuration filenames, and export forms are project choices. Original functions, source, ABI, integration configuration, and actual execution must still correspond.

### Compare at function boundaries

From identical initial conditions, compare control inputs, returns, object writes, memory that should remain unchanged, and necessary side effects. Then check calls and results in the natural workflow. State the scopes of component replay and real-workflow verification separately.

Do not run the second implementation on an object already mutated by the first and assume identical input. Declare truncation caused by call-sampling limits. Failing to observe a call does not prove it is absent.

## Integrate runtime substitution

Names and paths in the template are placeholders; its initial mode is `off`. It is not an executable universal hook. Adapt to the actual platform, processes, and ABI:

1. **Find the process executing the function.** Derive `process_selector` from the actual launch chain and record where and when the module loads. Attaching a script to the launcher alone is insufficient.
2. **Bind the original module.** Store its actual name, path, architecture, and hash in Module. `Function.module_id` and `Substitution.module_id` identify the same version and agree on symbol or module-relative location.
3. **Organize source and artifacts.** Follow the [source naming rules](#required-source-organization-and-naming). Build and Artifact identify the actual recovery library and hash.
4. **Specify the recovered entry point.** `recovered_entry` names an actual entry in the artifact. `abi_contract_ref` points to recovered declarations or working ABI analysis for arguments, returns, convention, object layout, and ownership; it need not point to retained intermediate evidence. Explain the relationship among source function, export bridge, and original symbol.
5. **Test integration.** Use actual tools to load, resolve, install, return, and unload. Save `hook_install`, `call`, or `memory` Observations in the natural workflow and link them to this Run. Distinguish no hits, wrong module versions, and installation failure.
6. **Declare recovery scope afterward.** Infrastructure probes may explicitly delegate to the original function, but do not count as business recovery. Compare all results and declared behavior after substitution. A `substitute` configuration does not prove installation, hits, or verification.

Keep each original module aligned with its recovery build target and ensure both can coexist in the real loading environment. Actual libraries, processes, tools, and compilers depend on the target. See [build and runtime substitution](#build-and-runtime-substitution) and the [common structure](#common-runtime-substitution-structure) for requirements.

• SKILL.md 11 KB
• assets/substitution.example.json 1 KB