namespace WhiteMagic.Assembly;

/// <summary>
/// Abstraction over an x86/x64 assembler. The default <see cref="StubAssembler"/>
/// hand-emits calling-convention trampolines (no parsing, zero dep). An optional
/// <see cref="IcedAssembler"/> (Phase 8) handles arbitrary mnemonics via the Iced
/// library.
/// </summary>
/// <remarks>
/// This seam covers text assembly only (<see cref="Assemble"/>). Call-stub building
/// (<c>BuildCallStub</c>, <c>EmitU8</c>/<c>EmitU32</c>/<c>EmitU64</c>) is a
/// <see cref="StubAssembler"/> capability — not all backends need it.
/// </remarks>
public interface IAssembler
{
    /// <summary>
    /// Assembles text mnemonics into machine code.
    /// </summary>
    /// <param name="assemblyText">The assembly text (Intel syntax).</param>
    /// <param name="origin">The base address for relative encodings.</param>
    byte[] Assemble(string assemblyText, ulong origin = 0);
}