ek9_query_signature_impact

Answers first: status, direction (the mutation kind), verdict (ready / would-fail), callerSites, then anchor, contract (root + overrides the change cascades to) and afferent (the call sites ek9_change_signature would rewrite, each fixable or breaks).

Category: Enquiry · Compare: EK9 IDE — blast-radius impact (signature change preview, detached window)

When to use it

'What breaks if I add, remove or reorder a parameter, or change the return type' is one call with symbol:'Type.method' plus the mutations - no file needed.

When not to use it

applying the change, not previewing it (use ek9_change_signature with the same mutations)
previewing a PURITY change derived from an existing diagnostic, not a signature edit (use ek9_query_purity_impact)
raw caller/callee chains without the per-site update verdict (use ek9_query_call_graph)
EVERY reference to a symbol (any kind), not the call sites a specific mutation would rewrite (use ek9_query_references)

Details

Overall verdict is would-fail if ANY afferent site is breaks, else ready. Axes: 'contract' (⬆ override group — root has verdict 'root', overrides 'fixable'); 'afferent' (▲ one-hop call sites — each fqn a call-site file:line:col; 'fixable' rewritten mechanically, 'breaks' for an added param with no valueForExistingCalls and no unset instance, or a removed param without dropCallSiteArguments, 'consistent' when the argument list is unchanged (a return-type or purity change rewrites no site)); 'efferent' (▼ always empty — a signature change does not alter what the anchor calls). direction/availableDirections carry the mutation kind verbatim (add-parameter / remove-parameter / reorder-parameters / change-return-type / change-purity), not an axis; needs a FULL_RESOLUTION workspace (default ek9_compile suffices).

Arguments

Argument	Type	Required	What it is
`file`	string		The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site.
`line`	integer		1-based line of the method or function declaration - OMIT it and pass symbol:'Type.method' to let the tool find the line (a model counting lines miscounts).
`mutations`	array of any	yes	The proposed signature change (same shape as `ek9_change_signature`): one or more {kind: 'add-parameter' (+ parameter:{name,type,position?,valueForExistingCalls?}), 'remove-parameter' (+ removeParameterName, + optional dropCallSiteArguments:true), 'reorder-parameters' (+ newParameterOrder:[names]), 'change-return-type' (+ newReturnType), 'change-purity' (+ purityChange)}. Drives the direction and the per-site verdict.
`symbol`	string		A construct NAME alone ('Shape', 'sample.deps.core::Validator') - no file needed, the tool finds it workspace-wide; or, with file (+ line), the identifier you mean there.

It also takes the arguments every tool takes.

Recorded calls

Real calls, recorded against small projects and checked on every build - a changed answer fails it.

Add parameter

Request

{
  "file" : "r.ek9",
  "line" : 6,
  "mutations" : [ {
    "kind" : "add-parameter",
    "parameter" : {
      "name" : "scale",
      "type" : "Integer",
      "valueForExistingCalls" : "1"
    }
  } ]
}

Response

{
  "afferent" : [ {
    "detail" : "argument list rewritten mechanically",
    "file" : "r.ek9",
    "fullyQualifiedName" : "<workspace-root>/r.ek9:20:26",
    "label" : "r.ek9:20",
    "line" : 20,
    "verdict" : "fixable"
  }, {
    "detail" : "argument list rewritten mechanically",
    "file" : "r.ek9",
    "fullyQualifiedName" : "<workspace-root>/r.ek9:21:26",
    "label" : "r.ek9:21",
    "line" : 21,
    "verdict" : "fixable"
  } ],
  "anchor" : {
    "detail" : "add scale as Integer",
    "file" : "r.ek9",
    "fullyQualifiedName" : "sig.probe::Renderer.render(org.ek9.lang::Integer)",
    "label" : "Renderer.render()",
    "line" : 6,
    "verdict" : "root"
  },
...

Cut short here: 32 more lines. The whole recorded call.

Remove parameter