{
  "version" : "1.0",
  "compilerVersion" : "0.0.1-0",
  "tools" : [ {
    "type" : "function",
    "function" : {
      "name" : "ek9_version",
      "description" : "Returns the EK9 compiler toolchain version string, e.g. '0.0.1-0'.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : { },
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_help",
      "description" : "Returns the reference page for one keyword, built-in type or topic - hover summary, the full type API for a built-in type, usage examples - or the keyword index when no keyword is given.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "keyword" : {
            "description" : "The keyword, type name, operator symbol or topic (e.g. 'String', 'switch', '<=>', 'E05030'); case and near spellings are resolved. Omit for the index of every page.",
            "type" : "string"
          }
        },
        "required" : [ ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_explain_error",
      "description" : "Returns the curated rich explanation for one EK9 error code - [DIAGNOSIS], [EXAMPLES] (as ek9_ask 'Q<id>' routes), the first example's source inlined as [WORKED EXAMPLE Q<id>], [ACTION], [SEE ALSO] and, when tooling is mapped, [REMEDIATION].",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "errorCode" : {
            "description" : "The error code, E + 5 digits (e.g. 'E01010', 'E05030'); 'e5030' and '5030' are resolved to 'E05030'",
            "type" : "string"
          }
        },
        "required" : [ "errorCode" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_paradigm",
      "description" : "Returns the constant EK9 paradigm summary (syntax that is NOT C/Java/Python, first-attempt traps, concepts with no analogue elsewhere) and working rules - the smallest priming context for an AI about to write EK9 code - and with withExamples:true the compiled inline examples after it.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "withExamples" : {
            "description" : "Append forAI.json's compiled inlineExamples after the summary (default false; ~55K chars more)",
            "type" : "boolean"
          }
        },
        "required" : [ ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_ask",
      "description" : "Returns the best-matching curated Q&A entries: 'match: strong|weak|id' first, then per entry the id, question, category, Oracle tool, the answer and last the compiled EK9 example (capped by default).",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "includeMigration" : {
            "description" : "Append each entry's cross-language migration note where one exists (default false).",
            "type" : "boolean"
          },
          "maxResults" : {
            "description" : "Maximum entries returned (default 3)",
            "type" : "integer"
          },
          "mode" : {
            "description" : "Retained alias: 'summary' = verbosity:'summary', 'detailed' = verbosity:'full', 'migration' = includeMigration:true. Prefer the two parameters it expands to.",
            "enum" : [ "summary", "detailed", "migration" ],
            "type" : "string"
          },
          "query" : {
            "description" : "The question in natural language, or an entry id ('Q1043', '1043')",
            "type" : "string"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Response size: 'summary' (default for a search) = opening answer paragraph + first 15 example lines; 'full' (default for a Q<id> fetch) = whole answer, whole example, companion sources; 'none' = headline lines only.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ "query" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_query_tool_catalogue",
      "description" : "Returns the whole EK9 tool inventory grouped by category - toolCount and toolNames per category plus workflowNames by default; verbosity:'summary' adds each tool's description, rules and IDE precedent, 'full' the JSON schemas.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "category" : {
            "description" : "Only this category's section",
            "enum" : [ "enquiry", "editor", "execution" ],
            "type" : "string"
          },
          "includeSchemas" : {
            "description" : "Include the JSON Schema for every tool (lifts verbosity to 'full'). Default false.",
            "type" : "boolean"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Response size: 'none' (default) = names + counts (~4K); 'summary' = the slim catalogue with descriptions, rules and workflows; 'full' = with every tool's JSON schema.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_query_tool_detail",
      "description" : "Returns one tool's entry - status, match (exact|single|ambiguous|none), then whenToUse, whenNotToUse, description, examples and inputSchema - by name, intent phrase or the error code it remediates.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "errorCode" : {
            "description" : "An EK9 error code (E11066): answers with the tool mapped to remediate it, never a fuzzy guess",
            "type" : "string"
          },
          "tool" : {
            "description" : "Tool name ('ek9_query_construct', 'query construct') or an intent phrase ('find a class by name')",
            "type" : "string"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Response size: 'full' (default) = the JSON schema; 'summary' = parameters[] with name/type/required/enum; 'none' = name, whenToUse, description.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_query_workflow",
      "description" : "Returns one named multi-tool workflow's ordered steps (tool + one-line reason each), or with no name every workflow with workflowNames first.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "name" : {
            "description" : "Workflow name (e.g. 'release'); omit for every workflow",
            "type" : "string"
          }
        },
        "required" : [ ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_list_workflows",
      "description" : "Returns every named multi-tool workflow - workflowCount, workflowNames, then each workflow's summary and full step sequence.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : { },
        "required" : [ ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_query_metric_limits",
      "description" : "Returns EK9's ENFORCED quality-metric limits (coupling, cohesion, complexity, DI, size) - limitCount and limits[] with ruleCode, metricKey, limitKind, comparator, limit and usableMax - from the single source the checkers fire on.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : { },
        "required" : [ ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry",
      "idePrecedent" : "EK9 IDE — quality-gate settings panel (the enforced quality-metric limits)"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_read_construct",
      "description" : "Answers first: source.text with source.file/startLine/endLine from the compiled symbol-table boundaries (no line guessing), construct {name, fullyQualifiedName, kind}, members[{name, kind, signature, startLine, endLine, compilerMade?}] (a program has none) and source.contentHash.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "file" : {
            "description" : "IDE cursor form: the .ek9 file (workspace-relative or absolute inside the workspace). OPTIONAL - a symbol alone finds its file.",
            "type" : "string"
          },
          "includeBody" : {
            "default" : true,
            "description" : "When false, returns signatures only: each declaration's line and its '->' / '<-' lines (a typed return up to its initialiser), no bodies.",
            "type" : "boolean"
          },
          "line" : {
            "description" : "1-based line anywhere inside the target with file - OMIT it and pass symbol:'<name>' instead (a model counting lines miscounts).",
            "type" : "integer"
          },
          "lineNumbers" : {
            "default" : false,
            "description" : "When true, each line of source.text is prefixed 'N| ' (the ek9_read_file form). Default false - source.startLine/endLine already anchor the slice.",
            "type" : "boolean"
          },
          "memberName" : {
            "description" : "Narrows a bare construct symbol to ONE member (method / operator / constructor / field name; operators by symbol: ?, <=>, $). 'Shape.member' says the same in one key.",
            "type" : "string"
          },
          "module" : {
            "description" : "Exact module name that picks one declaration when symbol is a bare name declared in several modules; 'mod::Shape' says the same in one key.",
            "type" : "string"
          },
          "symbol" : {
            "description" : "The construct or member: 'Shape' | 'mod::Shape' (when the name is declared in several modules) | 'Shape.computeTotal' | 'Shape.?' (an operator by its EK9 symbol). No file or line needed. With file, the identifier to anchor on there.",
            "type" : "string"
          }
        },
        "required" : [ ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry",
      "idePrecedent" : "IntelliJ \"Show body of method\" / LSP textDocument/definition"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_read_file",
      "description" : "Answers first: content (numbered 'N| ' when lineNumbers:true), contentHash for expectedContentHash, and for .ek9 the structure outline {module, constructs[{kind,name,startLine,endLine,signature}]} - whole file up to 2,000 lines, truncated:true first when cut.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "endLine" : {
            "description" : "1-based last line of a slice (inclusive); clamped to the file's lineCount with a range-clamped warning.",
            "type" : "integer"
          },
          "includeStructure" : {
            "default" : true,
            "description" : "When true (default), .ek9 files include the structure outline {module, constructs[{kind,name,startLine,endLine,signature}]}. Ignored for non-EK9 files.",
            "type" : "boolean"
          },
          "lineNumbers" : {
            "default" : false,
            "description" : "When true, 'content' is returned with each line prefixed by its 1-based number ('15| sayHello() as pure'). Use it before ANY line-anchored call (edit_file line-replace, remove_statements, a 'line' argument) - counting lines in raw text miscounts. For the symbol tools prefer symbol:'<name>' and no line at all.",
            "type" : "boolean"
          },
          "path" : {
            "description" : "File path: workspace-relative (preferred) or absolute inside the workspace. Must exist and be a text file.",
            "type" : "string"
          },
          "range" : {
            "description" : "IDE alias for the flat startLine/endLine pair: {\"startLine\": 100, \"endLine\": 200}.",
            "properties" : {
              "endLine" : {
                "description" : "1-based end line (inclusive).",
                "type" : "integer"
              },
              "startLine" : {
                "description" : "1-based start line (inclusive).",
                "type" : "integer"
              }
            },
            "required" : [ "startLine", "endLine" ],
            "type" : "object"
          },
          "startLine" : {
            "description" : "1-based first line of a slice (inclusive). With endLine; omit both for the whole file (capped at 2,000 lines).",
            "type" : "integer"
          }
        },
        "required" : [ "path" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry",
      "idePrecedent" : "cat / Read tool (Claude Code) / fs.readFile"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_search_text",
      "description" : "Answers first: matchCount, files[], sites['file.ek9:LINE'] (truncated:true first when cut), then matches[{file,line,column,snippet}] - a literal or regex grep across the workspace with EK9-aware exclusions (build outputs, .ek9-cache/, dot-directories).",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "caseSensitive" : {
            "description" : "Omit it: an identifier with an uppercase letter (a symbol name) is searched case-sensitively, anything else case-insensitively. Set it to override.",
            "type" : "boolean"
          },
          "includeHidden" : {
            "default" : false,
            "description" : "When true, includes dot-files and otherwise-excluded build directories in the scan.",
            "type" : "boolean"
          },
          "isRegex" : {
            "default" : false,
            "description" : "When true, query is parsed as a java.util.regex.Pattern.",
            "type" : "boolean"
          },
          "maxResults" : {
            "default" : 100,
            "description" : "Cap on matches[] (default 100, max 1000). A cut result opens with truncated:true and matchTotal (the true count).",
            "type" : "integer"
          },
          "path" : {
            "description" : "Bounds the search: a workspace-relative directory, or ONE file to search just that file ('m04.ek9'). Defaults to the workspace root.",
            "type" : "string"
          },
          "pathPattern" : {
            "description" : "Optional glob restricting which files are searched, applied relative to path (e.g. \"**/*.ek9\", \"src/main/**\"). Intersects with default exclusions — cannot bring back excluded paths.",
            "type" : "string"
          },
          "query" : {
            "description" : "Literal text (default) or regex pattern (when isRegex:true). Literal mode matches special characters verbatim — no escaping needed for operators like <=> ? :=? * ( ) [ ] \\.",
            "type" : "string"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "full (default) returns matches[] records; summary keeps the headline only (files, sites, counts); none collapses the lists to counts.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ "query" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry",
      "idePrecedent" : "ripgrep / grep / Find in Files"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_list_files",
      "description" : "Answers first: entryCount and paths[] (workspace-relative, the value ek9_read_file takes), then entries[{path, name, kind, size, lastModified}] - never content; direct children unless pathPattern recurses.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "includeHidden" : {
            "default" : false,
            "description" : "When true, includes dot-files and otherwise-excluded build directories.",
            "type" : "boolean"
          },
          "maxResults" : {
            "default" : 500,
            "description" : "Cap on entries[] (default 500, max 5000). A cut listing opens with truncated:true and entryTotal.",
            "type" : "integer"
          },
          "path" : {
            "description" : "Directory path: workspace-relative (preferred) or absolute inside the workspace. Defaults to the workspace root.",
            "type" : "string"
          },
          "pathPattern" : {
            "description" : "Optional glob (e.g. \"**/*.ek9\", \"test/**/*Test.ek9\"), applied recursively from path; files only.",
            "type" : "string"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "full (default) returns entries[] records; summary keeps paths[] and the counts; none collapses the lists to counts.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry",
      "idePrecedent" : "ls / fs.readdir / Glob (Claude Code)"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_check_requirements",
      "description" : "Answers status (healthy | violations | dangling-anchors) and healthy first, then requirementCount, developedCount, outstandingCount, violations[] (the store is broken), danglingAnchors[] (a @Test names a requirement that does not exist), outstanding[] (the backlog) and unanchoredTests[] (the authoring work-list) - the whole graph, nothing to verify.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "includeDeveloped" : {
            "default" : false,
            "description" : "List every developed requirement with its anchoring tests, not just the counts. Verbose on a large graph.",
            "type" : "boolean"
          }
        },
        "required" : [ ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry",
      "idePrecedent" : "Requirement navigator → health view (planned)"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_query_requirement",
      "description" : "Answers status (ok | not-found) and requirementId first, then the node(s): each carries authored{title, body, retired, meta} and derived{developed, anchoringTests, parentChain, children} so a computed rollup is never mistaken for a person's assertion; list and outstanding return requirementCount + requirements[], footprint the anchoringTests and reachedSymbols.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "assignee" : {
            "description" : "For list: match nodes whose meta.assignee equals this.",
            "type" : "string"
          },
          "depth" : {
            "description" : "For hierarchy: how far down to walk. Omit for the whole subtree; 1 gives the node and its direct children.",
            "type" : "integer"
          },
          "developed" : {
            "description" : "For list: match only developed (true) or only outstanding (false). Omit to match either.",
            "type" : "boolean"
          },
          "mode" : {
            "description" : "Which read to perform.",
            "enum" : [ "detail", "hierarchy", "list", "outstanding", "footprint" ],
            "type" : "string"
          },
          "prefix" : {
            "description" : "For list: match one node kind.",
            "enum" : [ "REQ", "CTRL", "CAP", "CON" ],
            "type" : "string"
          },
          "requirementId" : {
            "description" : "Required for detail, hierarchy and footprint, e.g. REQ:fraud-screening.",
            "type" : "string"
          },
          "retired" : {
            "description" : "For list: match only retired (true) or only live (false). Omit to match either.",
            "type" : "boolean"
          },
          "titleLike" : {
            "description" : "For list: case-insensitive substring of the title or body.",
            "type" : "string"
          }
        },
        "required" : [ "mode" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry",
      "idePrecedent" : "Requirement navigator tree + detail pane (planned)"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_render_specification",
      "description" : "Answers status (ok | not-found), requirementId and markdown - the specification document generated from the requirement graph with every section marked authored or derived - plus anchorsResolved saying whether a compile backed the derived sections.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "depth" : {
            "description" : "How far down to disclose. Omit for the whole subtree; 1 gives the node and its direct children.",
            "type" : "integer"
          },
          "profile" : {
            "default" : "technical",
            "description" : "technical names the anchoring tests; summary gives intent and status only.",
            "enum" : [ "technical", "summary" ],
            "type" : "string"
          },
          "requirementId" : {
            "description" : "Where to cut the tree, e.g. CAP:payments. Render from a root for the whole picture.",
            "type" : "string"
          }
        },
        "required" : [ "requirementId" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry",
      "idePrecedent" : "Requirement navigator → Render Specification… preview (planned)"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_find_unused_code",
      "description" : "Answers first: deadNames and deadByOwner (owner -> its dead members), complete workspace-wide - then each finding classified.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "among" : {
            "description" : "Names to answer FOR: 'which of these ...' - the name lists shrink to these and amongUnmatched names the ones that are not in the answer. Bare names, 'mod::Type' or 'Type.member'; a MODULE name stands for every construct in it ('which in scale.m07 do not ...' = amongUnmatched).",
            "items" : {
              "type" : "string"
            },
            "type" : "array"
          },
          "excludePublic" : {
            "description" : "When true, excludes public-visibility findings (intentional library API). Default false. Useful when scanning a library.",
            "type" : "boolean"
          },
          "fileFilter" : {
            "description" : "Optional source-file substring to scope the scan. Omit to scan all source.",
            "type" : "string"
          },
          "kind" : {
            "description" : "Filter by what kind of unused code to find. Default 'all'. 'construct' = dead top-level functions; 'method' = dead members (methods/constructors); 'constant' = a 'defines constant' entry nothing references (each finding carries the ek9_safe_delete call). 'field'/'reference' are not yet covered (empty + note); 'parameter' is owned by the compiler (E08091/E11018).",
            "enum" : [ "all", "construct", "method", "constant", "field", "reference", "parameter" ],
            "type" : "string"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control — see EK9_TOOL_SPECIFICATIONS.md §1.6. full (default) returns the complete result; summary trims per-item detail (call_graph to its headline names and sites, effective-api to member names); none collapses lists to counts. A very large response auto-degrades with an explicit `truncated` marker.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry",
      "idePrecedent" : "Code → Inspect Code → Dead Code (IntelliJ)"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_find_inline_candidates",
      "description" : "Answers candidates[] (file, line, name, tier worth-inlining | safe, useCount) ranked slop-first, with counts{} - every local '<-' declaration in scope examined.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "fileFilter" : {
            "description" : "Optional case-insensitive substring on the source path to scope the scan (per-file or per-directory). Omit to scan all source.",
            "type" : "string"
          },
          "module" : {
            "description" : "Optional exact module name to scope the scan (per-module). Omit to scan all modules.",
            "type" : "string"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control — see EK9_TOOL_SPECIFICATIONS.md §1.6. full (default) returns the complete result; summary trims per-item detail (call_graph to its headline names and sites, effective-api to member names); none collapses lists to counts. A very large response auto-degrades with an explicit `truncated` marker.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry",
      "idePrecedent" : "Code → Inspect Code → 'Local variable is redundant' (IntelliJ)"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_query_translation_completeness",
      "description" : "Answers status, translationDebtCount and translationDebt[] (every {textType, locale, method} still needing translation) first, then the per-(text type, locale, method) status grid (translated | stubbed | missing-error) and summary totals - the whole module, nothing to verify.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "includeMethodBodies" : {
            "default" : false,
            "description" : "When true, each method entry includes its current body (truncated to 200 chars).",
            "type" : "boolean"
          },
          "localeFilter" : {
            "description" : "Limit results to specific locales. Default: all locales discovered in the module.",
            "items" : {
              "type" : "string"
            },
            "type" : "array"
          },
          "module" : {
            "description" : "The module to operate on. Default: the first module that defines any text type; supply it when several modules carry i18n.",
            "type" : "string"
          },
          "placeholderPattern" : {
            "description" : "Marker-detection regex applied to trimmed source lines. Default: literal match for `//AI: translate the message` (the marker emitted by LocalizedTextWriter).",
            "type" : "string"
          },
          "textTypeFilter" : {
            "description" : "Limit results to specific text type names. Default: all text types in the module.",
            "items" : {
              "type" : "string"
            },
            "type" : "array"
          }
        },
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry",
      "idePrecedent" : "NEW IDE surface — translation completeness panel (Surface 3 of ek9_edit_localized_text); read-only grid showing translated / stubbed / missing per (text type, locale, method)"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_git_status",
      "description" : "Answers first: summary, branch, ahead/behind, isClean, then stagedFiles / modifiedFiles / untrackedFiles / deletedFiles / conflictFiles names and changedFileCount, then the per-file records with change words.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "includeIgnored" : {
            "description" : "Include .gitignore-matched files. Default false.",
            "type" : "boolean"
          },
          "includeUntracked" : {
            "description" : "Include untracked files. Default true.",
            "type" : "boolean"
          },
          "path" : {
            "description" : "Workspace-relative file or directory to scope the status to. Default: the whole workspace.",
            "type" : "string"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control — see EK9_TOOL_SPECIFICATIONS.md §1.6. full (default) returns the complete result; summary trims per-item detail (call_graph to its headline names and sites, effective-api to member names); none collapses lists to counts. A very large response auto-degrades with an explicit `truncated` marker.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry",
      "idePrecedent" : "git status / Git Source Control panel"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_git_diff",
      "description" : "Answers first: summary, fileCount, additions/deletions and changedFiles names, then per-file hunks with fromLine/toLine and the unified-diff text (dropped at verbosity:'summary').",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "contextLines" : {
            "description" : "Unchanged lines around each hunk. Default 3.",
            "type" : "integer"
          },
          "from" : {
            "description" : "Start ref for scope:'range' (with to), or the commit for scope:'commit'.",
            "type" : "string"
          },
          "path" : {
            "description" : "Workspace-relative file or directory to narrow the diff to. Default: everything.",
            "type" : "string"
          },
          "ref" : {
            "description" : "One commit to show (sha, tag, HEAD~1) - shorthand for scope:'commit' with from.",
            "type" : "string"
          },
          "scope" : {
            "description" : "What to compare. Default working (working tree vs HEAD); staged (index vs HEAD); commit (one commit vs its parent, needs ref or from); range (from..to).",
            "enum" : [ "working", "staged", "range", "commit" ],
            "type" : "string"
          },
          "to" : {
            "description" : "End ref for scope:'range'.",
            "type" : "string"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control — see EK9_TOOL_SPECIFICATIONS.md §1.6. full (default) returns the complete result; summary trims per-item detail (call_graph to its headline names and sites, effective-api to member names); none collapses lists to counts. A very large response auto-degrades with an explicit `truncated` marker.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry",
      "idePrecedent" : "git diff / Diff view"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_git_log",
      "description" : "Answers first: commitCount and commitTotal with a truncation note, then commits (sha, author, date, subject, body, parents; files with includeFileList:true).",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "allBranches" : {
            "description" : "Log every ref in topological order (the full DAG) instead of one branch. Default false.",
            "type" : "boolean"
          },
          "author" : {
            "description" : "Author name or email substring.",
            "type" : "string"
          },
          "branch" : {
            "description" : "Branch or ref to log from. Default: the current HEAD.",
            "type" : "string"
          },
          "from" : {
            "description" : "Range start ref (pair with to).",
            "type" : "string"
          },
          "includeFileList" : {
            "description" : "Attach files[] to each commit. Default false.",
            "type" : "boolean"
          },
          "maxResults" : {
            "description" : "Most commits to return. Default 50, limit 1000.",
            "type" : "integer"
          },
          "path" : {
            "description" : "Workspace-relative file or directory - only commits touching it.",
            "type" : "string"
          },
          "since" : {
            "description" : "Commits on or after - a date (2026-09-01) or git's relative form ('2 weeks ago').",
            "type" : "string"
          },
          "to" : {
            "description" : "Range end ref (pair with from).",
            "type" : "string"
          },
          "until" : {
            "description" : "Commits on or before - a date (2026-09-01) or git's relative form ('yesterday').",
            "type" : "string"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control — see EK9_TOOL_SPECIFICATIONS.md §1.6. full (default) returns the complete result; summary trims per-item detail (call_graph to its headline names and sites, effective-api to member names); none collapses lists to counts. A very large response auto-degrades with an explicit `truncated` marker.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry",
      "idePrecedent" : "git log / Git History view"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_git_blame",
      "description" : "Answers first: lineCount and the range, then one record per line (line, sha, author, email, date, subject, text); verbosity:'summary' collapses them to same-commit runs.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "endLine" : {
            "description" : "1-based last line of the slice, inclusive (with startLine).",
            "type" : "integer"
          },
          "path" : {
            "description" : "Workspace-relative path of a tracked file.",
            "type" : "string"
          },
          "range" : {
            "additionalProperties" : false,
            "description" : "IDE alias: the same slice as one object {startLine, endLine}.",
            "properties" : {
              "endLine" : {
                "type" : "integer"
              },
              "startLine" : {
                "type" : "integer"
              }
            },
            "type" : "object"
          },
          "ref" : {
            "description" : "Commit, tag or branch to blame at. Default HEAD.",
            "type" : "string"
          },
          "startLine" : {
            "description" : "1-based first line of the slice to blame (with endLine). Default: the whole file.",
            "type" : "integer"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control — see EK9_TOOL_SPECIFICATIONS.md §1.6. full (default) returns the complete result; summary trims per-item detail (call_graph to its headline names and sites, effective-api to member names); none collapses lists to counts. A very large response auto-degrades with an explicit `truncated` marker.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ "path" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry",
      "idePrecedent" : "git blame / Annotate"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_git_branch",
      "description" : "Answers first: current, branchCount and branchNames, then per-branch records (name, current, upstream, ahead/behind, gone, sha).",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "includeRemote" : {
            "description" : "Also list remote-tracking branches (origin/...). Default false.",
            "type" : "boolean"
          },
          "pattern" : {
            "description" : "Glob (* and ?) matched against the short branch name, e.g. 'feature/*'. Default: every branch.",
            "type" : "string"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control — see EK9_TOOL_SPECIFICATIONS.md §1.6. full (default) returns the complete result; summary trims per-item detail (call_graph to its headline names and sites, effective-api to member names); none collapses lists to counts. A very large response auto-degrades with an explicit `truncated` marker.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry",
      "idePrecedent" : "git branch / Branches",
      "orchestrationRules" : [ "Orient before ek9_git_switch: 'current' says where HEAD is, and branchNames says whether a branch exists (switch to it) or not (create:true)." ]
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_check_package_dependency_cycles",
      "description" : "Answers with hasCycles, cycleCount and the cycles (closed package paths with their edges) across every package declared in the workspace, plus packagesAnalysed and sccCount.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : { },
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry",
      "idePrecedent" : "Package Dependency Cycle Detector"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_query_package_version",
      "description" : "Answers with version (the 'defines package' literal) and the line it is on for one .ek9 file; null with an error when the file declares no package.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "file" : {
            "description" : "The .ek9 file holding the 'defines package' block, workspace-relative (typically 'package.ek9'); an absolute path inside the workspace is accepted.",
            "type" : "string"
          }
        },
        "required" : [ "file" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry",
      "idePrecedent" : "mvn help:evaluate -Dexpression=project.version"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_query_package",
      "description" : "Answers first: status, packageCount, then packages[] {name, version, description, license, tags, publishable, deps, devDeps, excludeDeps, capabilities, sourceLocation} - declared, not resolved.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : { },
        "required" : [ ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry",
      "idePrecedent" : "View pom.xml / package.json (most IDEs)"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_query_name_clashes",
      "description" : "Answers first: status, name, fullyQualifiedName, clashFree, donorLocals, renames (one globally-safe fresh name per clashing local), callSiteCount, then callSites[] with per-site clashes and the summary line.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "callSiteColumn" : {
            "default" : 1,
            "description" : "single-call-site only — 1-based column on the call name (an IDE cursor); omit it and the first call on the line is taken.",
            "type" : "integer"
          },
          "callSiteFile" : {
            "description" : "single-call-site only — workspace-relative file of the target call.",
            "type" : "string"
          },
          "callSiteLine" : {
            "description" : "single-call-site only — line (1-based) of the target call.",
            "type" : "integer"
          },
          "file" : {
            "description" : "The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site.",
            "type" : "string"
          },
          "line" : {
            "description" : "1-based line of the declaration header - OMIT it and pass symbol:'Type.method' to let the tool find the line (a model counting lines miscounts).",
            "type" : "integer"
          },
          "scope" : {
            "description" : "Optional - inferred from the arguments: callSiteFile+callSiteLine present = single-call-site (just that call, no call graph needed), else all-call-sites (every call site via the Phase-5 call graph, across files).",
            "enum" : [ "all-call-sites", "single-call-site" ],
            "type" : "string"
          },
          "symbol" : {
            "description" : "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.",
            "type" : "string"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control — see EK9_TOOL_SPECIFICATIONS.md §1.6. full (default) returns the complete result; summary trims per-item detail (call_graph to its headline names and sites, effective-api to member names); none collapses lists to counts. A very large response auto-degrades with an explicit `truncated` marker.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry",
      "idePrecedent" : "Refactor → Inline (variable-capture pre-check)"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_inspect_symbol_at_cursor",
      "description" : "Answers first: name, fullyQualifiedName, kind, type, state, declaredAt, then the modifiers, flags, scope, purityContext and the type's operators - one symbol, cursor-precise.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "column" : {
            "description" : "0-based char offset of the target identifier on 'line' (an IDE cursor). OMIT it and pass symbol:'<name>' instead, or omit both and the first identifier on the line is taken (right for a declaration line). Reuse a column from ek9_inspect_symbol_at_cursor verbatim.",
            "type" : "integer"
          },
          "file" : {
            "description" : "The EK9 source file path",
            "type" : "string"
          },
          "line" : {
            "description" : "1-based line of the declaration or a reference - OMIT it and pass symbol:'<name>' to let the tool find the line (a model counting lines in a file miscounts); if you do count, use ek9_read_file(lineNumbers:true).",
            "type" : "integer"
          },
          "symbol" : {
            "description" : "The identifier you mean on 'line' (e.g. 'sayHello'); the tool finds its column. Prefer this to column - a column is a 0-based character offset an IDE supplies.",
            "type" : "string"
          }
        },
        "required" : [ "file" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry",
      "idePrecedent" : "Quick Documentation (IntelliJ) / Hover (VSCode)"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_list_visible_symbols",
      "description" : "Answers first: scopeChain[] innermost to outermost, each scope with its symbols (name, kind, type, state, roles), then activeGuards and purityConstraint.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "column" : {
            "description" : "0-based char offset of the target identifier on 'line' (an IDE cursor). OMIT it and pass symbol:'<name>' instead, or omit both and the first identifier on the line is taken (right for a declaration line). Reuse a column from ek9_inspect_symbol_at_cursor verbatim.",
            "type" : "integer"
          },
          "file" : {
            "description" : "The EK9 source file path",
            "type" : "string"
          },
          "line" : {
            "description" : "1-based line of the declaration or a reference - OMIT it and pass symbol:'<name>' to let the tool find the line (a model counting lines in a file miscounts); if you do count, use ek9_read_file(lineNumbers:true).",
            "type" : "integer"
          },
          "symbol" : {
            "description" : "The identifier you mean on 'line' (e.g. 'sayHello'); the tool finds its column. Prefer this to column - a column is a 0-based character offset an IDE supplies.",
            "type" : "string"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control — see EK9_TOOL_SPECIFICATIONS.md §1.6. full (default) returns the complete result; summary trims per-item detail (call_graph to its headline names and sites, effective-api to member names); none collapses lists to counts. A very large response auto-degrades with an explicit `truncated` marker.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ "file" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry",
      "idePrecedent" : "Variables Panel (debug) / Document Symbols (LSP)"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_query_complexity",
      "description" : "Answers first: in view 'totals' the workspace-wide methodCount, averages, maxima and methodsAboveCyclomaticThreshold / methodsAboveCognitiveThreshold; in 'hotspots' hotspotNames[] then hotspots[]; in 'inputVariety' per-callable floor/ceiling (display-only).",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "complexityThreshold" : {
            "default" : 10,
            "description" : "Hotspots view: methods with metric >= complexityThreshold. Default 10.",
            "type" : "integer"
          },
          "fileFilter" : {
            "description" : "Optional: keep only methods whose source path contains this text.",
            "type" : "string"
          },
          "metric" : {
            "default" : "cyclomatic",
            "description" : "Which metric to threshold on in the hotspots view.",
            "enum" : [ "cyclomatic", "cognitive" ],
            "type" : "string"
          },
          "view" : {
            "default" : "totals",
            "description" : "Which view: totals (aggregate stats), hotspots (above-threshold methods), or inputVariety (per-construct input-variation figures, display-only).",
            "enum" : [ "totals", "hotspots", "inputVariety" ],
            "type" : "string"
          }
        },
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry",
      "idePrecedent" : "Code Inspection / SonarQube Complexity"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_query_construct",
      "description" : "Answers first: fieldNames, methodNames, operatorNames, defaultedOperatorNames, superName, traitNames, then construct{name, fullyQualifiedName, module, genus, isOpen, extends, traits, modifiers} and the full fields/methods/operators/constructors/metrics.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "file" : {
            "description" : "The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site.",
            "type" : "string"
          },
          "line" : {
            "description" : "1-based line anywhere inside the target construct - OMIT it and pass symbol:'<name>' instead.",
            "type" : "integer"
          },
          "symbol" : {
            "description" : "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.",
            "type" : "string"
          }
        },
        "required" : [ ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry",
      "idePrecedent" : "Structure View (IntelliJ) / Outline (VSCode)"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_query_flow",
      "description" : "Answers first: status, branchCount, loopCount, guardCount, deadBranchCount, then method{name, fullyQualifiedName, signature, declaredAt}, isPure, metrics (cyclomatic/cognitive), flowNodes (the guard-tracked branch/loop tree) and deepAnalysis (provably dead branches, redundant tri-state checks).",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "file" : {
            "description" : "The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site.",
            "type" : "string"
          },
          "line" : {
            "description" : "1-based line anywhere inside the method/function or on its declaration - OMIT it and pass symbol:'Type.method' to let the tool find the line (a model counting lines miscounts).",
            "type" : "integer"
          },
          "symbol" : {
            "description" : "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.",
            "type" : "string"
          }
        },
        "required" : [ ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry",
      "idePrecedent" : "Code Inspection / Control Flow Analyzer (IntelliJ)"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_advise_loop",
      "description" : "Answers first: directions[] (each with summary such as 'candidate-stream-aggregation' or 'keep-as-loop', candidateShape, confidence), then the loop{} facts, outputs[], resources[] and unknowns[] - read-only.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "file" : {
            "description" : "The EK9 source file path",
            "type" : "string"
          },
          "line" : {
            "description" : "1-based line of the for/while loop header or any line inside the loop body - OMIT it and pass symbol:'<loop variable>' to let the tool find the line.",
            "type" : "integer"
          },
          "symbol" : {
            "description" : "A name on the loop header (the loop variable, e.g. 'i') - the tool finds its line, so you never count lines.",
            "type" : "string"
          }
        },
        "required" : [ "file" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry",
      "idePrecedent" : "IntelliJ 'Analyze Data Flow' + inspection hints (advisory, not an auto-fix)"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_verify_method",
      "description" : "Answers first: status, name, verified, then counterexampleCount, counterexamples[] {obligation, witness, suggestedTest, suggestedFix}, provedSafe, deadBranches and nextStep.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "file" : {
            "description" : "The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site.",
            "type" : "string"
          },
          "line" : {
            "description" : "1-based line inside the function's body or on its declaration - OMIT it and pass symbol:'name' to let the tool find the line (a model counting lines miscounts).",
            "type" : "integer"
          },
          "symbol" : {
            "description" : "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.",
            "type" : "string"
          }
        },
        "required" : [ ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry",
      "idePrecedent" : "Design-by-contract / bounded-model verifier (Dafny, Frama-C, CBMC)"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_query_module",
      "description" : "Answers first: status, module, constructCount, constructNames, then constructs[] with kind, member counts and quality metrics (complexity, coupling, cohesion).",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "file" : {
            "description" : "Any .ek9 file inside the module of interest (workspace-relative; absolute inside the workspace accepted)",
            "type" : "string"
          },
          "kinds" : {
            "description" : "Optional filter, e.g. ['constant'] or ['class','component']. Omit for everything. EK9 has no module-scoped variables — only constants are per-module values, everything else is a type — so 'constant' is just one kind here.",
            "items" : {
              "enum" : [ "application", "class", "component", "constant", "enumeration", "function", "program", "record", "service", "text", "trait", "type" ],
              "type" : "string"
            },
            "type" : "array"
          },
          "scope" : {
            "description" : "'file' (default) lists what THIS source file declares; 'module' lists what the whole module declares across ALL its files, adding a 'file' field per construct. A multi-file module has one scope per file, so the two differ: a constant declared in a sibling file is absent from the 'file' view.",
            "enum" : [ "file", "module" ],
            "type" : "string"
          }
        },
        "required" : [ "file" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_query_pipeline",
      "description" : "Answers first: status, stageCount, then stages[] in order {operator, kind, consumes, produces}, sourceType, resultType and summary.transformations.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "file" : {
            "description" : "The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site.",
            "type" : "string"
          },
          "line" : {
            "description" : "1-based line the pipeline spans - any line of the chain; OMIT it and pass symbol:'Type.method' for the first pipeline in that body, or use ek9_read_file(lineNumbers:true) rather than counting.",
            "type" : "integer"
          },
          "symbol" : {
            "description" : "The method or function whose body holds the pipeline - 'Type.method' or a function name - no file or line needed; the FIRST pipeline in that body is decomposed.",
            "type" : "string"
          }
        },
        "required" : [ ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_query_workspace",
      "description" : "Answers first: status, moduleCount, moduleNames, constructCount, then modules[] {name, constructCount, constructs[] {name, category, genus}}; verbosity:'none' lists modules only, 'full' adds per-construct detail.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "includeBuiltins" : {
            "description" : "Whether to include org.ek9.lang built-in modules (default false)",
            "type" : "boolean"
          },
          "moduleFilter" : {
            "description" : "Restrict to these modules - exact names; an entry ending in '*' is a prefix ('com.acme.*'). A single string is accepted. Omit for workspace-wide.",
            "items" : {
              "type" : "string"
            },
            "type" : "array"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "none = module names + sourceCount; summary (default) = each module's constructs as {name, category, genus}; full = adds line, memberCount and modifiers per construct.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_query_classes",
      "description" : "Answers first: classNames[], then classes[] (name, module, file, line, extends, traits, isOpen, isAbstract, keyMethods, methodCount) and summary counts - workspace-wide or the filtered subset.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "among" : {
            "description" : "Names to answer FOR: 'which of these ...' - the name lists shrink to these and amongUnmatched names the ones that are not in the answer. Bare names, 'mod::Type' or 'Type.member'; a MODULE name stands for every construct in it ('which in scale.m07 do not ...' = amongUnmatched).",
            "items" : {
              "type" : "string"
            },
            "type" : "array"
          },
          "extendsFilter" : {
            "description" : "Filter to classes whose extends-chain transitively includes this superclass name.",
            "type" : "string"
          },
          "includeAbstract" : {
            "description" : "Default true. When false, excludes classes marked 'as abstract'.",
            "type" : "boolean"
          },
          "includeMethodSummary" : {
            "description" : "Default true. When true each entry includes keyMethods[] (up to 5 public signatures). Set false for a lighter response.",
            "type" : "boolean"
          },
          "methodNameFilter" : {
            "description" : "Filter to classes declaring a method whose name matches (case-insensitive substring).",
            "type" : "string"
          },
          "moduleFilter" : {
            "description" : "Restrict to these exact module names. Default: workspace-wide.",
            "items" : {
              "type" : "string"
            },
            "type" : "array"
          },
          "nameFilter" : {
            "description" : "Case-insensitive substring match on class names.",
            "type" : "string"
          },
          "traitFilter" : {
            "description" : "Filter to classes carrying the listed traits (transitive) - any one of them, or every one with traitMatch:'all'. Exact names, bare or module::Name.",
            "items" : {
              "type" : "string"
            },
            "type" : "array"
          },
          "traitMatch" : {
            "description" : "How traitFilter combines: 'any' (default) - at least one; 'all' - every one.",
            "enum" : [ "any", "all" ],
            "type" : "string"
          }
        },
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry",
      "idePrecedent" : "Classes outline panel (reuse-discovery)"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_query_records",
      "description" : "Answers first: status, recordCount, recordNames - complete for the workspace or the filters given - then records[] {name, module, file, line, fields, extends, traits, isOpen}.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "fieldNameFilter" : {
            "description" : "Filter to records declaring a field whose name matches (case-insensitive substring).",
            "type" : "string"
          },
          "moduleFilter" : {
            "description" : "Restrict to specific modules (exact names). Default: workspace-wide.",
            "items" : {
              "type" : "string"
            },
            "type" : "array"
          },
          "nameFilter" : {
            "description" : "Case-insensitive substring match on record names.",
            "type" : "string"
          }
        },
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry",
      "idePrecedent" : "Records outline panel (reuse-discovery)"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_query_traits",
      "description" : "Answers first: status, implementedByAll (when asked), traitCount, traitNames - complete for the workspace or the filters given - then traits[] {name, module, file, line, traitOf, implementedBy, implementedByCount, methods, methodCount}.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "implementedByAll" : {
            "description" : "Trait names (exact, bare or module::Name). Answers implementedByAll: the constructs that carry EVERY one of them, transitively.",
            "items" : {
              "type" : "string"
            },
            "type" : "array"
          },
          "includeMethodSummary" : {
            "description" : "Default true. When true each entry includes methods[] (the contract signatures). Set false for a lighter response.",
            "type" : "boolean"
          },
          "methodNameFilter" : {
            "description" : "Filter to traits declaring a method whose name matches (case-insensitive substring).",
            "type" : "string"
          },
          "moduleFilter" : {
            "description" : "Restrict to specific modules (exact names). Default: workspace-wide.",
            "items" : {
              "type" : "string"
            },
            "type" : "array"
          },
          "nameFilter" : {
            "description" : "Case-insensitive substring match on trait names.",
            "type" : "string"
          }
        },
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry",
      "idePrecedent" : "Traits outline panel (reuse-discovery)"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_query_components",
      "description" : "Answers first: componentNames[], then components[] (name, module, file, line, extends, isOpen, isAbstract, keyMethods, methodCount) and summary counts - the DI-injectable constructs, workspace-wide or the filtered subset.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "extendsFilter" : {
            "description" : "Filter to components whose extends-chain transitively includes this super-component name.",
            "type" : "string"
          },
          "includeAbstract" : {
            "description" : "Default true. When false, excludes components marked 'as abstract'.",
            "type" : "boolean"
          },
          "includeMethodSummary" : {
            "description" : "Default true. When true each entry includes keyMethods[] (up to 5 public signatures). Set false for a lighter response.",
            "type" : "boolean"
          },
          "methodNameFilter" : {
            "description" : "Filter to components declaring a method whose name matches (case-insensitive substring).",
            "type" : "string"
          },
          "moduleFilter" : {
            "description" : "Restrict to these exact module names. Default: workspace-wide.",
            "items" : {
              "type" : "string"
            },
            "type" : "array"
          },
          "nameFilter" : {
            "description" : "Case-insensitive substring match on component names.",
            "type" : "string"
          }
        },
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry",
      "idePrecedent" : "Components outline panel (DI reuse-discovery)"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_query_constrained_types",
      "description" : "Answers first: constrainedTypeNames[], then constrainedTypes[] (name, module, file, line, constrains, constraint, admissibleWindow, suffix) and summary counts.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "baseTypeFilter" : {
            "description" : "Filter to constrained types whose base type matches (case-insensitive, e.g. 'String' finds EmailAddress, PostCode, ...).",
            "type" : "string"
          },
          "moduleFilter" : {
            "description" : "Restrict to these exact module names. Default: workspace-wide.",
            "items" : {
              "type" : "string"
            },
            "type" : "array"
          },
          "nameFilter" : {
            "description" : "Case-insensitive substring match on constrained-type names.",
            "type" : "string"
          }
        },
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry",
      "idePrecedent" : "Constrained-types outline panel (reuse-discovery)"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_query_functions",
      "description" : "Answers first: status, functionCount, functionNames - complete for the workspace or the filters given - then functions[] {name, module, file, line, signature, parameters, returnType, isPure, isAbstract}.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "includeAbstract" : {
            "description" : "Default false. When true, also includes abstract function-typedefs (higher-order parameter signatures).",
            "type" : "boolean"
          },
          "includePure" : {
            "description" : "Default true. When false, excludes functions marked 'as pure'.",
            "type" : "boolean"
          },
          "moduleFilter" : {
            "description" : "Restrict to specific modules (exact names). Default: workspace-wide.",
            "items" : {
              "type" : "string"
            },
            "type" : "array"
          },
          "nameFilter" : {
            "description" : "Case-insensitive substring match on function names.",
            "type" : "string"
          },
          "returnTypeFilter" : {
            "description" : "Filter to functions whose return type matches (case-insensitive substring, e.g. 'Boolean' finds predicates).",
            "type" : "string"
          }
        },
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry",
      "idePrecedent" : "Functions outline panel (reuse-discovery)"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_query_programs",
      "description" : "Answers first: status, programCount, programNames - complete for the workspace or the filters given - then programs[] {name, module, file, line, signature, parameters}.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "argTypeFilter" : {
            "description" : "Filter to programs whose argument list STARTS WITH these types, in order (case-insensitive, exact type-name match). Example: [\"Date\"] matches programs whose first argument is a Date.",
            "items" : {
              "type" : "string"
            },
            "type" : "array"
          },
          "moduleFilter" : {
            "description" : "Restrict to specific modules (exact names). Default: workspace-wide.",
            "items" : {
              "type" : "string"
            },
            "type" : "array"
          },
          "nameFilter" : {
            "description" : "Case-insensitive substring match on program names.",
            "type" : "string"
          }
        },
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry",
      "idePrecedent" : "Constructs navigator (by-genus) — Programs group"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_query_enumerations",
      "description" : "Answers first: enumerationNames[], then enumerations[] (name, module, file, line, values in declaration order, valueCount) and summary counts.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "moduleFilter" : {
            "description" : "Restrict to these exact module names. Default: workspace-wide.",
            "items" : {
              "type" : "string"
            },
            "type" : "array"
          },
          "nameFilter" : {
            "description" : "Case-insensitive substring match on enumeration names.",
            "type" : "string"
          },
          "valueFilter" : {
            "description" : "Filter to enumerations declaring a value whose name matches (case-insensitive substring). Example: \"PENDING\" finds every enum with a PENDING-like value — useful for catching duplicate value sets.",
            "type" : "string"
          }
        },
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry",
      "idePrecedent" : "Constructs navigator (by-genus) — Enumerations group"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_query_localisations",
      "description" : "Answers first: status, moduleCount, inconsistencyCount, workspaceLocales, then modules[] {name, locales, percentTranslated, methodCount} and inconsistencies[] {locale, supportedIn, missingIn}.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "excludeModules" : {
            "description" : "Modules to treat as intentionally non-i18n — removed from modules[] AND from inconsistencies[].missingIn. (Modules with zero text blocks are auto-excluded already.) Default: none.",
            "items" : {
              "type" : "string"
            },
            "type" : "array"
          },
          "includeFileDistribution" : {
            "default" : false,
            "description" : "Include i18nFiles[] (the .ek9 files holding each module's text blocks). Default off to keep responses compact; turn on when planning a ek9_organize_localized_text call.",
            "type" : "boolean"
          },
          "includeInconsistencies" : {
            "default" : true,
            "description" : "Include the inconsistencies[] array flagging cross-module locale support gaps. Set false to suppress.",
            "type" : "boolean"
          },
          "localeFilter" : {
            "description" : "Restrict per-module metrics + inconsistencies to specific locales (e.g. [\"fr_FR\", \"de\"]). workspaceLocales still lists the full discovered set. Default: all discovered locales.",
            "items" : {
              "type" : "string"
            },
            "type" : "array"
          },
          "moduleFilter" : {
            "description" : "Restrict the response to specific modules (exact names). Default: all i18n modules.",
            "items" : {
              "type" : "string"
            },
            "type" : "array"
          }
        },
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry",
      "idePrecedent" : "NEW IDE surface — Localisations Overview panel (locale × module completeness matrix + inconsistency flags)"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_query_env_vars",
      "description" : "Answers first: names[] (every env-var read), then envVars[] per call site (site, name, accessMethod, sanitization, inConstruct), dynamicAccesses[] and summary counts - type-resolved EnvVars calls, never text matches.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "accessMethodFilter" : {
            "description" : "Restrict to these access methods. Example: [\"unsanitizedGet\"] for a security audit. Default: all four.",
            "items" : {
              "enum" : [ "get", "unsanitizedGet", "sensitiveGet", "contains" ],
              "type" : "string"
            },
            "type" : "array"
          },
          "envVarNames" : {
            "description" : "Restrict to specific env-var names (case-sensitive EXACT match per name, e.g. [\"DATABASE_URL\", \"AUTH_SECRET\"]). Not a substring pattern — env-var names are a set of distinct identifiers. Default: all discovered.",
            "items" : {
              "type" : "string"
            },
            "type" : "array"
          },
          "includeDynamic" : {
            "default" : true,
            "description" : "Include the dynamicAccesses[] array flagging accesses where the env-var name is a runtime expression rather than a literal. Set false to suppress when only the statically-resolvable surface matters.",
            "type" : "boolean"
          },
          "moduleFilter" : {
            "description" : "Restrict to these exact module names. Default: workspace-wide.",
            "items" : {
              "type" : "string"
            },
            "type" : "array"
          }
        },
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry",
      "idePrecedent" : "NEW IDE surface — \"Environment Variables\" panel listing every env-var read across the workspace (name + file + line + access method + sanitization), row-click navigate, right-click find-usages-of-name"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_query_capability_usage",
      "description" : "Answers first: consistent, underDeclared, overDeclared, usedCapabilities, declaredCapabilities and findings, then actualUsage with every call site - the workspace-wide gated-type audit against the package block.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "capability" : {
            "description" : "Optional filter — restrict actualUsage to a single fully-qualified capability (e.g. \"org.ek9.lang::TCP\", \"org.ek9.lang::Stdout\"). An open string, NOT an enum — an unknown value simply matches nothing. Omit for all capabilities. Narrows the displayed call sites only; the audit remains workspace-wide.",
            "type" : "string"
          },
          "moduleFilter" : {
            "description" : "Optional: exact module names (an entry ending in * is a prefix) whose call sites to display; a bare string is accepted as a one-element list. Omit for workspace-wide. Narrows displayed call sites only; the audit remains workspace-wide.",
            "items" : {
              "type" : "string"
            },
            "type" : "array"
          }
        },
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry",
      "idePrecedent" : "EK9 IDE — \"Capabilities\" navigator (left dock): declared-vs-required gated-type audit; under-declared (compile-blocking) and over-declared (unnecessary attack surface) findings with Add/Remove capability quick-fixes; row-click navigate to each call site"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_query_sensitive_reveals",
      "description" : "Answers first: status, revealCount, violationCount, privilegedCount, violationSites as file.ek9:LINE, then reveals[] {file, line, column, module, inConstruct, inConstructFqn, privilege}.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "moduleFilter" : {
            "description" : "Restrict to these modules - exact names; an entry ending in '*' is a prefix ('com.acme.*'). A single string is accepted. Omit for workspace-wide.",
            "items" : {
              "type" : "string"
            },
            "type" : "array"
          }
        },
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry",
      "idePrecedent" : "EK9 IDE — \"Sensitive Reveals\" navigator (left dock): every Sensitive.reveal() call grouped by legality (⚠ unprivileged / in-function violations = E11090 first, then ✓ privileged), row-click navigate + Show call graph"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_query_service_routes",
      "description" : "Answers first: status, programState, routeCount, byService, then routes[] {verb, uri, fullPath, parameters with binding + sanitized, securityGate, cors, auditWarnings} and summary counts.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "audit" : {
            "description" : "Audit-level filter: all (default), unsanitized (routes with >=1 un-sanitized input parameter), unguarded (routes without a security gate).",
            "enum" : [ "all", "unsanitized", "unguarded" ],
            "type" : "string"
          },
          "service" : {
            "description" : "Optional service-name SUBSTRING filter ('Order' matches OrderService).",
            "type" : "string"
          },
          "uri" : {
            "description" : "Optional fullPath SUBSTRING filter ('/addresses' matches every route under it).",
            "type" : "string"
          },
          "verb" : {
            "description" : "Filter by HTTP verb (default all).",
            "enum" : [ "all", "GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS" ],
            "type" : "string"
          }
        },
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry",
      "idePrecedent" : "EK9 IDE — \"Service Routes\" diagram (bottom pane): services → routes → params with per-node click-to-source, security gate / CORS shown as cross-file jump targets, unsanitized-input and unguarded-route findings highlighted"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_query_diagnostics",
      "description" : "Answers first: diagnosticCount, errorCount, warningCount, errorCodes[] and sites[] ('file.ek9:LINE CODE message'), then diagnostics[] in full, byCode and byFile - the Problems View of the last compile.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "errorCode" : {
            "description" : "Optional specific error code filter (e.g., 'E05030')",
            "type" : "string"
          },
          "fileFilter" : {
            "description" : "Optional: keep only diagnostics whose file path contains this text",
            "type" : "string"
          },
          "includeFuzzySuggestions" : {
            "description" : "Include 'Did you mean?' fuzzy match suggestions per diagnostic. Default false.",
            "type" : "boolean"
          },
          "includeOffendingSymbol" : {
            "description" : "Include the likely-offending symbol name per diagnostic. Default: on while there are 20 diagnostics or fewer.",
            "type" : "boolean"
          },
          "includeQuickFixes" : {
            "description" : "Include actionable replacement suggestions extracted from parse errors and fuzzy matches. Default: on while there are 20 diagnostics or fewer.",
            "type" : "boolean"
          },
          "includeTokenSpan" : {
            "description" : "Include tokenLength for highlight rendering. Default false.",
            "type" : "boolean"
          },
          "severity" : {
            "description" : "Severity filter: 'all' (default), 'errors', or 'warnings'",
            "enum" : [ "all", "errors", "warnings" ],
            "type" : "string"
          }
        },
        "required" : [ ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry",
      "idePrecedent" : "Problems View (IntelliJ / VSCode)"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_query_effective_api",
      "description" : "Answers first: declaredMethodNames, inheritedMethodNames, overrides as 'method:Trait', operatorNames, traitNames - then every member in full with its source and file/line.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "column" : {
            "description" : "0-based char offset of the target identifier on 'line' (an IDE cursor). OMIT it and pass symbol:'<name>' instead, or omit both and the first identifier on the line is taken (right for a declaration line). Reuse a column from ek9_inspect_symbol_at_cursor verbatim.",
            "type" : "integer"
          },
          "file" : {
            "description" : "The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site.",
            "type" : "string"
          },
          "line" : {
            "description" : "1-based line of the declaration or a reference - OMIT it and pass symbol:'<name>' to let the tool find the line (a model counting lines in a file miscounts); if you do count, use ek9_read_file(lineNumbers:true).",
            "type" : "integer"
          },
          "symbol" : {
            "description" : "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.",
            "type" : "string"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control — see EK9_TOOL_SPECIFICATIONS.md §1.6. full (default) returns the complete result; summary trims per-item detail (call_graph to its headline names and sites, effective-api to member names); none collapses lists to counts. A very large response auto-degrades with an explicit `truncated` marker.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry",
      "idePrecedent" : "Show Members (IntelliJ) / Class View"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_query_type_hierarchy",
      "description" : "Answers first: subtypeNames (implementedBy on a trait), superNames, traitNames, allowedSubtypes for a sealed trait - complete workspace-wide - then the full graph.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "among" : {
            "description" : "Names to answer FOR: 'which of these ...' - the name lists shrink to these and amongUnmatched names the ones that are not in the answer. Bare names, 'mod::Type' or 'Type.member'; a MODULE name stands for every construct in it ('which in scale.m07 do not ...' = amongUnmatched).",
            "items" : {
              "type" : "string"
            },
            "type" : "array"
          },
          "column" : {
            "description" : "0-based char offset of the target identifier on 'line' (an IDE cursor). OMIT it and pass symbol:'<name>' instead, or omit both and the first identifier on the line is taken (right for a declaration line). Reuse a column from ek9_inspect_symbol_at_cursor verbatim.",
            "type" : "integer"
          },
          "file" : {
            "description" : "The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site.",
            "type" : "string"
          },
          "line" : {
            "description" : "1-based line of the declaration or a reference - OMIT it and pass symbol:'<name>' to let the tool find the line (a model counting lines in a file miscounts); if you do count, use ek9_read_file(lineNumbers:true).",
            "type" : "integer"
          },
          "symbol" : {
            "description" : "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.",
            "type" : "string"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control — see EK9_TOOL_SPECIFICATIONS.md §1.6. full (default) returns the complete result; summary trims per-item detail (call_graph to its headline names and sites, effective-api to member names); none collapses lists to counts. A very large response auto-degrades with an explicit `truncated` marker.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry",
      "idePrecedent" : "Type Hierarchy (IntelliJ)"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_query_references",
      "description" : "Answers first: useSiteCount, usedByConstructs, useSites as file.ek9:LINE - then each reference with its source line (omitted above 50 sites unless verbosity:'full').",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "among" : {
            "description" : "Names to answer FOR: 'which of these ...' - the name lists shrink to these and amongUnmatched names the ones that are not in the answer. Bare names, 'mod::Type' or 'Type.member'; a MODULE name stands for every construct in it ('which in scale.m07 do not ...' = amongUnmatched).",
            "items" : {
              "type" : "string"
            },
            "type" : "array"
          },
          "column" : {
            "description" : "0-based char offset of the target identifier on 'line' (an IDE cursor). OMIT it and pass symbol:'<name>' instead, or omit both and the first identifier on the line is taken (right for a declaration line). Reuse a column from ek9_inspect_symbol_at_cursor verbatim.",
            "type" : "integer"
          },
          "file" : {
            "description" : "The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site.",
            "type" : "string"
          },
          "include" : {
            "description" : "Which use sites: 'all' (default), 'explicit' (only sites whose text names the symbol) or 'inferred' (only names whose type was INFERRED as it, e.g. 'p <- find(id)' for Product - one per name). The headline counts both either way.",
            "enum" : [ "all", "explicit", "inferred" ],
            "type" : "string"
          },
          "line" : {
            "description" : "1-based line of the declaration or a reference - OMIT it and pass symbol:'<name>' to let the tool find the line (a model counting lines in a file miscounts); if you do count, use ek9_read_file(lineNumbers:true).",
            "type" : "integer"
          },
          "symbol" : {
            "description" : "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.",
            "type" : "string"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control — see EK9_TOOL_SPECIFICATIONS.md §1.6. full (default) returns the complete result; summary trims per-item detail (call_graph to its headline names and sites, effective-api to member names); none collapses lists to counts. A very large response auto-degrades with an explicit `truncated` marker.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry",
      "idePrecedent" : "Find Usages (IntelliJ) / Find All References (VSCode)"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_query_dispatchers",
      "description" : "Answers first: routing[] - per dispatcher method its dispatchOn type, typesWithOwnHandler, typesUsingInheritedHandler (served by a supertype's handler) and typesFallingBack (to the dispatchOn entry point's own body), with routingCovers when the lists are whole - then the full dispatcherMethods[] with resolutionTable; on a sealed type, allowedSubtypes[]. Do not read the class and simulate it.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "among" : {
            "description" : "Names to answer FOR: 'which of these ...' - the name lists shrink to these and amongUnmatched names the ones that are not in the answer. Bare names, 'mod::Type' or 'Type.member'; a MODULE name stands for every construct in it ('which in scale.m07 do not ...' = amongUnmatched).",
            "items" : {
              "type" : "string"
            },
            "type" : "array"
          },
          "column" : {
            "description" : "0-based char offset of the target identifier on 'line' (an IDE cursor). OMIT it and pass symbol:'<name>' instead, or omit both and the first identifier on the line is taken (right for a declaration line). Reuse a column from ek9_inspect_symbol_at_cursor verbatim.",
            "type" : "integer"
          },
          "file" : {
            "description" : "The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site.",
            "type" : "string"
          },
          "line" : {
            "description" : "1-based line of the declaration or a reference - OMIT it and pass symbol:'<name>' to let the tool find the line (a model counting lines in a file miscounts); if you do count, use ek9_read_file(lineNumbers:true).",
            "type" : "integer"
          },
          "symbol" : {
            "description" : "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.",
            "type" : "string"
          }
        },
        "required" : [ ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_query_build_status",
      "description" : "Answers first: programState, queriesReliable with its reason, buildOutcome, lastPhaseReached, then sourceCount/sourcesClean/sourcesWithErrors and sources[] with per-file error and warning counts.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "fileFilter" : {
            "description" : "Optional: keep only sources whose path contains this text",
            "type" : "string"
          }
        },
        "required" : [ ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_query_call_graph",
      "description" : "Answers first: callerNames / calleeNames and callerSites / calleeSites ('file.ek9:LINE') - then the chain to the requested depth.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "among" : {
            "description" : "Names to answer FOR: 'which of these ...' - the name lists shrink to these and amongUnmatched names the ones that are not in the answer. Bare names, 'mod::Type' or 'Type.member'; a MODULE name stands for every construct in it ('which in scale.m07 do not ...' = amongUnmatched).",
            "items" : {
              "type" : "string"
            },
            "type" : "array"
          },
          "depth" : {
            "description" : "Maximum traversal depth (0-5, default 1)",
            "type" : "integer"
          },
          "direction" : {
            "description" : "Direction: 'both' (default), 'outgoing', or 'incoming'",
            "enum" : [ "both", "outgoing", "incoming" ],
            "type" : "string"
          },
          "file" : {
            "description" : "The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site.",
            "type" : "string"
          },
          "line" : {
            "description" : "1-based line of the declaration or a reference - OMIT it and pass symbol:'<name>' to let the tool find the line (a model counting lines in a file miscounts); if you do count, use ek9_read_file(lineNumbers:true).",
            "type" : "integer"
          },
          "symbol" : {
            "description" : "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.",
            "type" : "string"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control — see EK9_TOOL_SPECIFICATIONS.md §1.6. full (default) returns the complete result; summary trims per-item detail (call_graph to its headline names and sites, effective-api to member names); none collapses lists to counts. A very large response auto-degrades with an explicit `truncated` marker.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry",
      "idePrecedent" : "Call Hierarchy (IntelliJ)"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_find_constructs_by_name",
      "description" : "Answers first: matchCount, then matches[] (name, fullyQualifiedName, module, genus, file, line, column) - workspace-wide; matches:[] when no top-level construct has that name.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "name" : {
            "description" : "Unqualified name to search for. Append `*` for case-insensitive prefix matching (e.g. \"Cust*\"). Without `*`, exact case-sensitive match.",
            "type" : "string"
          }
        },
        "required" : [ "name" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry",
      "idePrecedent" : "Search Everywhere (IntelliJ) / Go to Symbol in Workspace (VSCode)"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_find_symbols",
      "description" : "Answers first: symbolCount, symbolNames, withinNames (Type.method each belongs to), siteCount, byKind, byUse, sites as file.ek9:LINE - then each symbol (kind, within, declaredAt, renameable, counts) with its declared/read/written sites.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "caseSensitive" : {
            "description" : "Default true.",
            "type" : "boolean"
          },
          "file" : {
            "description" : "Scope: this one file. Omit file and module for the whole workspace.",
            "type" : "string"
          },
          "kinds" : {
            "description" : "Kinds to find: single kinds and/or the groups constructs, members, variables. Default all.",
            "items" : {
              "enum" : [ "class", "record", "trait", "component", "function", "abstract_function", "enumeration", "type", "text", "service", "program", "application", "property", "method", "operator", "constructor", "parameter", "return", "local", "loop_variable", "guard", "capture", "constant", "constructs", "members", "variables" ],
              "type" : "string"
            },
            "type" : "array"
          },
          "match" : {
            "description" : "exact (whole name, default), contains (anywhere in the name), or regex (Java, against the name).",
            "enum" : [ "exact", "contains", "regex" ],
            "type" : "string"
          },
          "maxSymbols" : {
            "description" : "Default 200, max 2000. The answer is the first maxSymbols symbols; a cut one says truncated:true and moreSymbols (how many more).",
            "type" : "integer"
          },
          "module" : {
            "description" : "Scope: every file of this module.",
            "type" : "string"
          },
          "name" : {
            "description" : "The name pattern - matched against symbol NAMES, never comments or Strings.",
            "type" : "string"
          },
          "renameTo" : {
            "description" : "Also return renameRequest - the ek9_rename_symbol arguments renaming every symbol found. Nothing is applied.",
            "type" : "string"
          },
          "sourceLines" : {
            "description" : "Give each site its source line (text). Default false.",
            "type" : "boolean"
          },
          "uses" : {
            "description" : "Which sites: declared, read, written. Default all three.",
            "items" : {
              "enum" : [ "declared", "read", "written" ],
              "type" : "string"
            },
            "type" : "array"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "full (default): each symbol with its sites; summary: each symbol without its sites; none: the headline alone.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ "name" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry",
      "idePrecedent" : "Find in Project, symbols mode (EK9 IDE) - no direct IntelliJ / VS Code equivalent: Find Usages starts from ONE symbol"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_query_dependency_injection",
      "description" : "Answers first: applicationCount and applications[] (registrations, injectionSites, boundPrograms, health incl. E11040 over-injection), programCount and programs[], then summary.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "applicationFilter" : {
            "description" : "Optional: keep only applications whose name contains this text",
            "type" : "string"
          }
        },
        "required" : [ ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry",
      "idePrecedent" : "Spring Bean Graph (IntelliJ Ultimate)"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_query_module_dependencies",
      "description" : "Answers first: status, moduleCount, edgeCount, hasCycles, then modules[] {name, files, constructCount}, dependencies[] {from, to, referenceCount, kinds} and metrics (fan-in/out, cycles).",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "includeBuiltins" : {
            "description" : "Whether to include org.ek9.lang built-in module dependencies (default false)",
            "type" : "boolean"
          }
        },
        "required" : [ ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry",
      "idePrecedent" : "Module Dependencies Analyzer (IntelliJ)"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_query_module_landscape",
      "description" : "Answers first: status, programState, moduleCount, moduleNames, then modules[] {name, band, types, metrics as headroom {rule, limit, value, band, enforced}, cycles} ranked worst-first and summary.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "band" : {
            "description" : "Restrict to modules whose overall health band is at/over this level. Default 'all'.",
            "enum" : [ "all", "ok", "approaching", "at-limit", "over" ],
            "type" : "string"
          },
          "metric" : {
            "description" : "Rank modules by this metric (worst first). Default 'efferent'.",
            "enum" : [ "efferent", "afferent" ],
            "type" : "string"
          },
          "moduleFilter" : {
            "description" : "Restrict to these modules - exact names; an entry ending in '*' is a prefix ('com.acme.*'). A single string is accepted. Omit for workspace-wide.",
            "items" : {
              "type" : "string"
            },
            "type" : "array"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control — see EK9_TOOL_SPECIFICATIONS.md §1.6. full (default) returns the complete result; summary trims per-item detail (call_graph to its headline names and sites, effective-api to member names); none collapses lists to counts. A very large response auto-degrades with an explicit `truncated` marker.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry",
      "idePrecedent" : "EK9 IDE — \"Module Landscape\" pane (health-coloured module map)"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_query_module_coupling",
      "description" : "Answers first: status, programState, edgeCount, then edges[] {from, to, types, weight, shape, sites, inCycle, proposals} ranked worst-first, audit (adHocCoupling, overDeclaredReferences candidates) and summary.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "direction" : {
            "description" : "With moduleFilter: 'outgoing' = edges out of those modules, 'incoming' = edges into them, 'both' (default) = either side.",
            "enum" : [ "both", "outgoing", "incoming" ],
            "type" : "string"
          },
          "minWeight" : {
            "description" : "Only edges with at least this weight (signature reference count). Default 1.",
            "type" : "integer"
          },
          "moduleFilter" : {
            "description" : "Restrict to these modules - exact names; an entry ending in '*' is a prefix ('com.acme.*'). A single string is accepted. Omit for workspace-wide.",
            "items" : {
              "type" : "string"
            },
            "type" : "array"
          },
          "targetAbstractness" : {
            "description" : "Only edges reaching this genus class (concrete = heaviest coupling risk).",
            "enum" : [ "value", "abstraction", "concrete" ],
            "type" : "string"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control — see EK9_TOOL_SPECIFICATIONS.md §1.6. full (default) returns the complete result; summary trims per-item detail (call_graph to its headline names and sites, effective-api to member names); none collapses lists to counts. A very large response auto-degrades with an explicit `truncated` marker.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry",
      "idePrecedent" : "EK9 IDE — module coupling diagram (directed typed edges, ranked worst-first)"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_query_module_cohesion",
      "description" : "Answers first: status, programState, moduleCount, then modules[] {name, moduleCohesion (E11017 disconnected groups), cohesionRatio, lcom4 (E11014 over-limit constructs)}; symbol:'Type' drills to one construct's LCOM4.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "moduleFilter" : {
            "description" : "Restrict to these modules - exact names; an entry ending in '*' is a prefix ('com.acme.*'). A single string is accepted. Omit for workspace-wide.",
            "items" : {
              "type" : "string"
            },
            "type" : "array"
          },
          "symbol" : {
            "description" : "A construct NAME ('OrderService' or 'com.acme.orders::OrderService') — drill straight to its LCOM4 (E11014) instead of the per-module view.",
            "type" : "string"
          }
        },
        "required" : [ ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry",
      "idePrecedent" : "EK9 IDE — module cohesion view (disconnected-group split signal + per-construct LCOM4)"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_query_construct_neighbourhood",
      "description" : "Answers first: nodeCount, nodes[] (name, fullyQualifiedName, module, genus, file, line, distance), edges[] (from, to, kind) and edgesByKind - the N-hop typed ego graph merging inheritance, calls, composition, references and DI.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "depth" : {
            "description" : "How many edges out from the target (default 1, max 5).",
            "type" : "integer"
          },
          "direction" : {
            "description" : "'outgoing' = what it depends on, 'incoming' = what depends on it (the blast radius), 'both' (default).",
            "enum" : [ "both", "incoming", "outgoing" ],
            "type" : "string"
          },
          "edgeKinds" : {
            "description" : "Restrict to these relationships. Omit for all.",
            "items" : {
              "enum" : [ "extends", "implements", "composes", "references", "calls", "injects", "dispatches" ],
              "type" : "string"
            },
            "type" : "array"
          },
          "file" : {
            "description" : "The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site.",
            "type" : "string"
          },
          "line" : {
            "description" : "1-based line of the declaration or a reference - OMIT it and pass symbol:'<name>' to let the tool find the line (a model counting lines in a file miscounts); if you do count, use ek9_read_file(lineNumbers:true).",
            "type" : "integer"
          },
          "symbol" : {
            "description" : "The construct: a bare name ('Order') or a qualified name ('com.acme.orders::Order') - no file needed, the tool finds it workspace-wide; 'Type.member' anchors on the member's construct.",
            "type" : "string"
          }
        },
        "required" : [ ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry",
      "idePrecedent" : "EK9 IDE — construct neighbourhood / blast-radius ego graph around the cursor"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_query_purity_impact",
      "description" : "Answers first: status, change, availableChanges, verdict (ready / would-fail / cascade-too-large / blocked-refuse-to-root), callerNames, calleeNames, then anchor, contract, afferent, efferent axes - the same closure ek9_fix_purity_contract applies.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "change" : {
            "description" : "'remove-pure' = which CALLERS break if this stops being pure; 'add-pure' = which CALLEES must become pure. Omit to take the natural direction for the diagnosed code (E08130 offers both - see availableChanges).",
            "enum" : [ "add-pure", "remove-pure" ],
            "type" : "string"
          },
          "file" : {
            "description" : "The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site.",
            "type" : "string"
          },
          "line" : {
            "description" : "1-based line where the purity error (E08130 / E05150 / E05160) fires - OMIT it and pass symbol:'Type.method' to let the tool find the flagged line.",
            "type" : "integer"
          },
          "symbol" : {
            "description" : "The flagged method or function - 'Type.method' or a function name - no file or line needed; the tool finds its first purity error.",
            "type" : "string"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control — see EK9_TOOL_SPECIFICATIONS.md §1.6. full (default) returns the complete result; summary trims per-item detail (call_graph to its headline names and sites, effective-api to member names); none collapses lists to counts. A very large response auto-degrades with an explicit `truncated` marker.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry",
      "idePrecedent" : "EK9 IDE — blast-radius impact pane (purity change preview)"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_query_data_touch",
      "description" : "Answers first: anchor and verdicts (parameter → untouched | mutates | escapes | ... ), then touches[] with the mutation and escape axes and every contributing site - read-only.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "column" : {
            "description" : "Optional 0-based IDE column. Advisory — the anchor is the enclosing callable, resolved by line, so this may be omitted.",
            "type" : "integer"
          },
          "file" : {
            "description" : "The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site.",
            "type" : "string"
          },
          "line" : {
            "description" : "1-based line inside the callable whose parameter you are tracking (the enclosing method or function is resolved from it) - OMIT it and pass symbol instead.",
            "type" : "integer"
          },
          "parameter" : {
            "description" : "The parameter name to track (the data structure). Omit to get a verdict for EVERY parameter of the callable.",
            "type" : "string"
          },
          "symbol" : {
            "description" : "The callable: 'Stash.keep' (Type.member) or a bare function name - no file needed, the tool finds it workspace-wide; or, with file (+ line), the name you mean there.",
            "type" : "string"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control — see EK9_TOOL_SPECIFICATIONS.md §1.6. full (default) returns the complete result; summary trims per-item detail (call_graph to its headline names and sites, effective-api to member names); none collapses lists to counts. A very large response auto-degrades with an explicit `truncated` marker.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry",
      "idePrecedent" : "EK9 IDE — construct-neighbourhood pane, data-touch lens (planned)"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_query_mutex_payload",
      "description" : "Answers first: status, summary {bodies, contained, mayEscape, unknown}, findingCount, then findings[] {file, line, inConstruct, payloadType, locks, escape, sites[] with via chain and origin}.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "includeUnknown" : {
            "default" : false,
            "description" : "Also report MutexKey bodies whose escape verdict is 'unknown' — an opaque callee, or the payload handed to a function value. Off by default so the list stays actionable.",
            "type" : "boolean"
          }
        },
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry",
      "idePrecedent" : "EK9 IDE — concurrency lens (planned); closest external analogue is an escape-analysis or thread-safety inspection"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_query_signature_impact",
      "description" : "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).",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "file" : {
            "description" : "The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site.",
            "type" : "string"
          },
          "line" : {
            "description" : "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).",
            "type" : "integer"
          },
          "mutations" : {
            "description" : "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.",
            "items" : {
              "anyOf" : [ {
                "properties" : {
                  "kind" : {
                    "const" : "add-parameter"
                  },
                  "parameter" : {
                    "properties" : {
                      "name" : {
                        "type" : "string"
                      },
                      "position" : {
                        "description" : "0-based position among the parameters; omitted = append",
                        "type" : "integer"
                      },
                      "type" : {
                        "type" : "string"
                      },
                      "valueForExistingCalls" : {
                        "description" : "The EK9 expression injected at EVERY existing call site (EK9 has no default parameter values) - required when the callable has call sites, e.g. '0.0' or 'CurrencyCode(\"USD\")'",
                        "type" : "string"
                      }
                    },
                    "required" : [ "name", "type" ],
                    "type" : "object"
                  }
                },
                "required" : [ "kind", "parameter" ],
                "type" : "object"
              }, {
                "properties" : {
                  "dropCallSiteArguments" : {
                    "description" : "true to drop the argument at every call site; without it live call sites block the removal",
                    "type" : "boolean"
                  },
                  "kind" : {
                    "const" : "remove-parameter"
                  },
                  "removeParameterName" : {
                    "type" : "string"
                  }
                },
                "required" : [ "kind", "removeParameterName" ],
                "type" : "object"
              }, {
                "properties" : {
                  "kind" : {
                    "const" : "reorder-parameters"
                  },
                  "newParameterOrder" : {
                    "items" : {
                      "type" : "string"
                    },
                    "type" : "array"
                  }
                },
                "required" : [ "kind", "newParameterOrder" ],
                "type" : "object"
              }, {
                "properties" : {
                  "kind" : {
                    "const" : "change-return-type"
                  },
                  "newReturnType" : {
                    "description" : "the new return type; null removes the return clause",
                    "type" : [ "string", "null" ]
                  }
                },
                "required" : [ "kind", "newReturnType" ],
                "type" : "object"
              }, {
                "properties" : {
                  "kind" : {
                    "const" : "change-purity"
                  },
                  "pure" : {
                    "description" : "true adds 'as pure', false removes it",
                    "type" : "boolean"
                  }
                },
                "required" : [ "kind", "pure" ],
                "type" : "object"
              } ]
            },
            "type" : "array"
          },
          "symbol" : {
            "description" : "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.",
            "type" : "string"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control — see EK9_TOOL_SPECIFICATIONS.md §1.6. full (default) returns the complete result; summary trims per-item detail (call_graph to its headline names and sites, effective-api to member names); none collapses lists to counts. A very large response auto-degrades with an explicit `truncated` marker.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ "mutations" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry",
      "idePrecedent" : "EK9 IDE — blast-radius impact (signature change preview, detached window)"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_check_module_cycles",
      "description" : "Answers first: hasCycles and cycleCount, then cycles[] (each a closed module path with edges[].via naming the source files) and moduleCount - the whole workspace module graph.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : { },
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry",
      "idePrecedent" : "Module Dependency Cycle Detector"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_query_dependency_tree",
      "description" : "Answers first: direction, rootPackage, rootVersion, then tree{} (dependsOn) or deduplicated[] with broughtInBy (broughtInBy), selections[] and summary - the transitive package dependency tree across the workspace.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "direction" : {
            "description" : "dependsOn (default): the downward tree from the root or the filtered module; broughtInBy: the flat list with, per module, the packages that pull it in.",
            "enum" : [ "dependsOn", "broughtInBy" ],
            "type" : "string"
          },
          "format" : {
            "description" : "Output shape: nested (hierarchical tree, = dependsOn) or flat (deduplicated list with broughtInBy, = broughtInBy). Optional when direction is given.",
            "enum" : [ "nested", "flat" ],
            "type" : "string"
          },
          "moduleFilter" : {
            "description" : "Optional: one exact module name, or a prefix with a trailing *. dependsOn: the subtree rooted at the first match; broughtInBy: the matching modules with their broughtInBy.",
            "type" : "string"
          }
        },
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry",
      "idePrecedent" : "mvn dependency:tree / npm ls"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_query_lock_analysis",
      "description" : "Answers first: status, then deadlockCount, lockIdentityCount, enterSiteCount, keyBodyCount, crossThreadEdgeCount and nextStep (the one drill-down worth calling); lockIdentityCount 0 = no MutexLock anywhere, deadlock structurally impossible.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : { },
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry",
      "idePrecedent" : "Lock Catalogue / Deadlock Detective"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_query_deadlock_chain",
      "description" : "Answers first: chains[] - per detected lock risk its errorCode, path, outerLock/innerLock and ordered steps[] with file/line/column - chains:[] when nothing is at risk.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : { },
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry",
      "idePrecedent" : "Lock Catalogue / Deadlock Detective"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_query_enter_sites",
      "description" : "Answers first: siteCount, then sites[] (stableId, kind, receiver, lockIdentityIds, location, enclosingFunction) - every lock acquisition, workspace-wide.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : { },
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry",
      "idePrecedent" : "Lock Catalogue / Deadlock Detective"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_query_lock_identity",
      "description" : "Answers first: status, identityCount, then identities[] {stableId, origin, displayName, originSymbol, originLocation, payload}; stableId joins ek9_query_enter_sites and ek9_query_deadlock_chain.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : { },
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "enquiry",
      "idePrecedent" : "Lock Catalogue / Deadlock Detective"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_write_file",
      "description" : "Answers first: status (applied | ready | would-fail | conflicts), written, edits[{file, type:create|overwrite, bytesWritten}] and contentHash; a .ek9 write carries wouldBeDiagnostics from the verifying compile, any other file is written as-is.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "content" : {
            "description" : "Content to write. For a .ek9 path on create, may be body-only — the writer prepends shebang + defines module and appends //EOF when missing.",
            "type" : "string"
          },
          "createIntermediateDirs" : {
            "default" : true,
            "description" : "When true (default), missing parent directories are created automatically.",
            "type" : "boolean"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "expectedContentHash" : {
            "description" : "The contentHash ek9_read_file (or a prior write) returned for the file's CURRENT content; the write is refused when the file changed since (lost-update protection).",
            "type" : "string"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "fileKind" : {
            "description" : "Inferred from the extension (.ek9 → ek9-source, else text); pass it only to override. ek9-source: boilerplate injection on create + compile verification; env: KEY=VALUE; config: reserved.",
            "enum" : [ "text", "ek9-source", "env", "config" ],
            "type" : "string"
          },
          "mode" : {
            "default" : "auto",
            "description" : "auto (default): create or overwrite; create-only: conflict if the file exists; overwrite-only: error if it doesn't.",
            "enum" : [ "auto", "create-only", "overwrite-only" ],
            "type" : "string"
          },
          "module" : {
            "description" : "Fully-qualified EK9 module name for a .ek9 create. Optional — defaults to the path-derived module under the workspace source root; an explicit value that differs emits a 'module-name-mismatches-path' warning.",
            "type" : "string"
          },
          "path" : {
            "description" : "File path: workspace-relative (preferred) or absolute inside the workspace. Created when absent (mode auto).",
            "type" : "string"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ "path", "content" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "fs.writeFile / Write tool (Claude Code) / IDE write-back"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_delete_file",
      "description" : "Answers first: status (applied | ready | conflicts | would-fail), written and, on a refusal, referenceCount + referencingFiles[] before the per-site conflicts[]; edits[{file, type:delete, disposition}].",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "force" : {
            "default" : false,
            "description" : "When false (default), the .ek9 reference check refuses deletion if workspace references point at constructs in the file. When true, the deletion proceeds REGARDLESS of references — the response includes warnings listing every reference that will fail to resolve. Also deletes while the workspace has compile errors (the reference check cannot be trusted), with a warning saying so.",
            "type" : "boolean"
          },
          "path" : {
            "description" : "File path: workspace-relative (preferred) or absolute inside the workspace. Must exist and be a file (directories: ek9_delete_directory). Give path or paths, not both.",
            "type" : "string"
          },
          "paths" : {
            "description" : "Several files to delete TOGETHER, instead of path - each a file path, workspace-relative (preferred) or absolute inside the workspace. References between files of the set do not count; the answer has files[], one entry per file.",
            "items" : {
              "type" : "string"
            },
            "type" : "array"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "useTrash" : {
            "default" : false,
            "description" : "When true AND the runtime supports trash semantics, the file is moved to the OS trash rather than permanently deleted. Falls back to permanent deletion with a warning otherwise.",
            "type" : "boolean"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "IntelliJ Safe Delete (file-level) / shell rm"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_delete_directory",
      "description" : "Answers first: status (applied | ready | conflicts), written and edits[{file, type:delete, kind:directory}] - removes an EMPTY workspace directory, never a populated tree.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "dryRun" : {
            "default" : false,
            "description" : "When true nothing is deleted; the response shows the would-be deletion or the not-empty conflict.",
            "type" : "boolean"
          },
          "expectedWorkspaceHash" : {
            "description" : "The workspaceHash a prior dry run returned; a mismatch adds a drift warning (the delete still proceeds).",
            "type" : "string"
          },
          "path" : {
            "description" : "Directory path: workspace-relative (preferred) or absolute inside the workspace. Must exist, be a directory, and not be the workspace root itself.",
            "type" : "string"
          },
          "terse" : {
            "default" : false,
            "description" : "Retained alias of verbosity:summary - prefer verbosity.",
            "type" : "boolean"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "full (default) returns the complete response; summary drops each edit's before/after bodies; none collapses edits[] to editCount.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ "path" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "IntelliJ \"Delete\" on an empty directory / shell rmdir"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_move_file",
      "description" : "Answers first: status (applied | ready | conflicts), written and edits[{file, newFile, type:move}] - a pure file-system relocation of any workspace file, contents untouched.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "createIntermediateDirs" : {
            "default" : true,
            "description" : "When true (default), missing parent directories at the destination are created (mkdir -p). When false, the tool errors if the destination's parent doesn't exist.",
            "type" : "boolean"
          },
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "newPath" : {
            "description" : "Destination: may be in a different directory; must not exist unless overwrite:true. Workspace-relative (preferred) or absolute inside the workspace.",
            "type" : "string"
          },
          "oldPath" : {
            "description" : "File path: workspace-relative (preferred) or absolute inside the workspace. The file as it is now; must exist.",
            "type" : "string"
          },
          "overwrite" : {
            "default" : false,
            "description" : "When false (default), the tool errors if a file already exists at newPath. When true, the existing file is replaced (its prior content is lost). Use cautiously.",
            "type" : "boolean"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ "oldPath", "newPath" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "IntelliJ \"Refactor → Move\" (file-level) / shell mv"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_rename_file",
      "description" : "Answers first: status (applied | ready | conflicts), written and edits[{file, newFile, type:move}] - a pure file-system rename of a .ek9 source, contents and module identity untouched.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "newPath" : {
            "description" : "Destination: must end in .ek9; may be in a different directory (the directory does NOT affect module membership). Workspace-relative (preferred) or absolute inside the workspace.",
            "type" : "string"
          },
          "oldPath" : {
            "description" : "File path: workspace-relative (preferred) or absolute inside the workspace. The .ek9 file as it is now; must exist.",
            "type" : "string"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ "oldPath", "newPath" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "IntelliJ \"Refactor → Rename File\""
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_edit_file",
      "description" : "Answers first: status (applied | ready | would-fail | conflicts), written, edits[{file, startLine, endLine, before, after}], wouldBeDiagnostics from the verifying compile and contentHash on an applied edit - an atomic batch of text edits to one file, or to several as one apply.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "edits" : {
            "description" : "Ordered edit operations, applied sequentially (edits[1] sees edits[0]'s output); one object per edit with mode + find/replace, or startLine/endLine + replace, or pattern + replace.",
            "items" : {
              "properties" : {
                "endLine" : {
                  "description" : "line-replace: 1-based last line of the range (inclusive).",
                  "type" : "integer"
                },
                "expectedOccurrences" : {
                  "description" : "find-replace / regex-replace: how many matches there must be - an integer (default 1) or 'all'; a mismatch is a conflict and nothing is applied."
                },
                "find" : {
                  "description" : "find-replace: the exact text (whitespace included); regex-replace: the Java regex (alias of pattern).",
                  "type" : "string"
                },
                "mode" : {
                  "description" : "find-replace: literal find → replace; line-replace: startLine..endLine → replace; regex-replace: Java pattern → replace with $1 backreferences.",
                  "enum" : [ "find-replace", "line-replace", "regex-replace" ],
                  "type" : "string"
                },
                "pattern" : {
                  "description" : "regex-replace: the Java regex (find is accepted too).",
                  "type" : "string"
                },
                "replace" : {
                  "description" : "The replacement text in every mode (empty deletes). A flush-left line-replace is re-indented to the replaced range; find-replace is NOT re-indented.",
                  "type" : "string"
                },
                "startLine" : {
                  "description" : "line-replace: 1-based first line of the range (inclusive) - read ek9_read_file with lineNumbers:true first.",
                  "type" : "integer"
                }
              },
              "required" : [ "mode" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "expectedContentHash" : {
            "description" : "The contentHash ek9_read_file returned for the file's CURRENT content; the call is refused when the on-disk content differs (lost-update protection, same semantics as ek9_write_file).",
            "type" : "string"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "files" : {
            "description" : "MULTI-FILE form: [{path, edits}] instead of path + edits - every file's edits are applied and the workspace compiled ONCE, so a change that only compiles when several files move together (a signature changed here, its callers there) lands as one atomic apply; any file failing rolls back all of them. Use it whenever a single-file edit would be rolled back for diagnostics in OTHER files.",
            "items" : {
              "properties" : {
                "edits" : {
                  "description" : "That file's edits, as the top-level edits.",
                  "type" : "array"
                },
                "path" : {
                  "description" : "File path: workspace-relative (preferred) or absolute inside the workspace. Must exist; an .ek9 source in the multi-file form.",
                  "type" : "string"
                }
              },
              "required" : [ "path", "edits" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "path" : {
            "description" : "File path: workspace-relative (preferred) or absolute inside the workspace. Must exist.",
            "type" : "string"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "Claude Code Edit tool / IntelliJ Find-and-Replace in File / sed -i"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_new_construct",
      "description" : "Scaffolds one top-level construct (class/record/trait/component/function/type/constant/service) into an EXISTING module file, or a new package.ek9 for mode:'package'; answers status, edits[] (one INSERT, or one CREATE for a package), stubs[] to fill with ek9_insert_statements, added[] and nextStep.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "allowOnly" : {
            "description" : "Sealed-hierarchy implementors (class + trait) — renders 'allow only A, B' after the header, restricting who may extend/implement.",
            "items" : {
              "type" : "string"
            },
            "type" : "array"
          },
          "applyStandardExcludes" : {
            "description" : "When true, EK9 standard excludes are merged with excludeFiles. Default false — must opt in. The directive is only emitted when this is explicitly true.",
            "type" : "boolean"
          },
          "applyStandardIncludes" : {
            "description" : "When true, EK9 standard includes (all .ek9 files in source tree) are merged with includeFiles. Default false — must opt in. The directive is only emitted when this is explicitly true.",
            "type" : "boolean"
          },
          "baseType" : {
            "description" : "type/constrained + type/alias: the underlying base type.",
            "type" : "string"
          },
          "body" : {
            "description" : "Raw EK9 source for the package-block body. When supplied, the structured fields below are ignored and the body is emitted verbatim inside the defines package wrapper. Indent each line with four spaces relative to column 0.",
            "type" : "string"
          },
          "capabilities" : {
            "description" : "Fully-qualified gated-type names (e.g. 'org.ek9.lang::Stdout', 'org.ek9.lang::TCP', 'org.ek9.lang::HTTPRequest'). Presence of this list — alongside publicAccess + version + license — turns on compile-time supply-chain capability enforcement for the package. EK9 forbids empty list literals; pass null/omit the parameter for a pure-computation library.",
            "items" : {
              "type" : "string"
            },
            "type" : "array"
          },
          "constraint" : {
            "description" : "type/constrained: the expression after 'constrain as' (e.g. '>= 16 and <= 100').",
            "type" : "string"
          },
          "constructors" : {
            "description" : "Constructors [{parameters:['price as Float', ...], pure?, default?, visibility?}] — one parameter per field, each assigned to the property (':=?' when pure). default:true renders a synthesised 'default Name()' (no body); visibility 'private'/'protected' prefixes the declaration.",
            "items" : {
              "properties" : {
                "default" : {
                  "type" : "boolean"
                },
                "parameters" : {
                  "items" : {
                    "anyOf" : [ {
                      "properties" : {
                        "name" : {
                          "description" : "The parameter's name.",
                          "type" : "string"
                        },
                        "type" : {
                          "description" : "Its type, e.g. 'Integer', 'List of String' - the TYPE only, no arrows.",
                          "type" : "string"
                        }
                      },
                      "required" : [ "name", "type" ],
                      "type" : "object"
                    }, {
                      "description" : "Also accepted: the EK9 text 'name as Type' - but send the object; the tool writes the '->' block, its indentation and its order.",
                      "type" : "string"
                    } ]
                  },
                  "type" : "array"
                },
                "params" : {
                  "description" : "Alias of 'parameters'.",
                  "items" : {
                    "anyOf" : [ {
                      "properties" : {
                        "name" : {
                          "description" : "The parameter's name.",
                          "type" : "string"
                        },
                        "type" : {
                          "description" : "Its type, e.g. 'Integer', 'List of String' - the TYPE only, no arrows.",
                          "type" : "string"
                        }
                      },
                      "required" : [ "name", "type" ],
                      "type" : "object"
                    }, {
                      "description" : "Also accepted: the EK9 text 'name as Type' - but send the object; the tool writes the '->' block, its indentation and its order.",
                      "type" : "string"
                    } ]
                  },
                  "type" : "array"
                },
                "pure" : {
                  "type" : "boolean"
                },
                "visibility" : {
                  "type" : "string"
                }
              },
              "type" : "object"
            },
            "type" : "array"
          },
          "constructs" : {
            "description" : "SEVERAL constructs in ONE call - each item has the same keys as this tool's top level (mode, name, fields, constructors, methods, operators, traits, parameters, returnType, statements, value, ...), mode:'program' with statements is allowed here, and an item may name its own targetFile (default: the call's) - a file that does not exist yet is created around the item's (or the call's) module. Rendered in order into their 'defines' blocks, every body pre-flighted, every touched file compiled ONCE: 'a trait, the classes over it and the program that drives them' is one call. What compiles is written; a construct that does not is named in refused[] with its diagnostics mapped to the statements[] entry (partial:true) - resend only that one.",
            "items" : {
              "properties" : {
                "mode" : {
                  "type" : "string"
                },
                "module" : {
                  "type" : "string"
                },
                "name" : {
                  "type" : "string"
                },
                "targetFile" : {
                  "type" : "string"
                }
              },
              "required" : [ "mode", "name" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "deps" : {
            "additionalProperties" : {
              "type" : "string"
            },
            "description" : "Runtime dependencies as module-name → version-string mapping. Becomes an EK9 Dict literal. Example: { 'ek9open.network.support.utils': '1.6.1-9' }.",
            "type" : "object"
          },
          "description" : {
            "description" : "Package description (becomes a quoted EK9 String literal).",
            "type" : "string"
          },
          "devDeps" : {
            "additionalProperties" : {
              "type" : "string"
            },
            "description" : "Development-only dependencies as module-name → version-string mapping. Same format as deps. Used for build/test dependencies that don't ship with the package.",
            "type" : "object"
          },
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "enumValues" : {
            "description" : "type/enumeration: the enum value names.",
            "items" : {
              "type" : "string"
            },
            "type" : "array"
          },
          "excludeDeps" : {
            "additionalProperties" : {
              "type" : "string"
            },
            "description" : "Transitive dependency exclusions: bad-module → context-module mapping. Example: { 'ek9open.some.bad.dependency.pack': 'ek9open.org.supertools.util' }.",
            "type" : "object"
          },
          "excludeFiles" : {
            "description" : "Glob patterns of files to exclude.",
            "items" : {
              "type" : "string"
            },
            "type" : "array"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "extends" : {
            "description" : "Parent type for class/record/trait/component, OR the abstract function a function extends (function inheritance: 'f() extends abstractFunction'). Pair with inheritanceKeyword for is-vs-extends. Closed-by-default: an unresolved or non-'as open' parent surfaces as a would-fail on dry-run.",
            "type" : "string"
          },
          "fields" : {
            "description" : "Field declarations as DATA: {name, type, defaultValue?, injected?} with BOTH name and type (the EK9 text 'name as Type' / 'name as Type: default' / 'name as Type!' / 'name <- default' is also accepted). A field without a type or default is rejected before anything is rendered. Not valid on traits. A typed field with no default is declared unset ('as Type?') and the compiler-required no-arg constructor is added for you (reported under 'added').",
            "items" : {
              "anyOf" : [ {
                "properties" : {
                  "defaultValue" : {
                    "description" : "Its initial value, e.g. '0.0', 'List() of String'; omitted renders the type's unset instance.",
                    "type" : "string"
                  },
                  "injected" : {
                    "description" : "true renders the DI form ('as Type!'); never with defaultValue.",
                    "type" : "boolean"
                  },
                  "name" : {
                    "description" : "The field's name.",
                    "type" : "string"
                  },
                  "type" : {
                    "description" : "Its type - the TYPE only, e.g. 'Float', 'List of String'.",
                    "type" : "string"
                  }
                },
                "required" : [ "name" ],
                "type" : "object"
              }, {
                "description" : "Also accepted: the EK9 text 'name as Type', 'name as Type: default', 'name as Type!' or 'name <- default' - but send the object; the tool writes the declaration and its indentation.",
                "type" : "string"
              } ]
            },
            "type" : "array"
          },
          "fileMode" : {
            "description" : "mode:package - auto (default; conflict 'file-exists' when the file exists), create-file (alias for auto), overwrite (replace the existing file).",
            "enum" : [ "auto", "create-file", "overwrite" ],
            "type" : "string"
          },
          "includeFiles" : {
            "description" : "Glob patterns of files to include in the package (e.g. '**.{cal}', 'License.txt'). Use alongside or instead of applyStandardIncludes.",
            "items" : {
              "type" : "string"
            },
            "type" : "array"
          },
          "inheritanceKeyword" : {
            "description" : "'extends' (default) or 'is' — synonyms; choice is stylistic (conventionally 'is' for components).",
            "enum" : [ "extends", "is" ],
            "type" : "string"
          },
          "license" : {
            "description" : "License identifier (e.g. 'MIT', 'Apache-2.0'). Becomes a quoted EK9 String literal. One of the four publishable conditions for capability enforcement.",
            "type" : "string"
          },
          "methods" : {
            "description" : "Methods [{name, parameters:[{name, type}, ...], returnType?, pure?, isAbstract?, override?, visibility?, dispatcher?, statements?}]. Each parameter is ONE item as DATA - {name:'code', type:'Integer'} - never a {name} and a {type} as two items, and never with '->' or '<-' in it: the tool writes the arrows and the layout. ('code as Integer' is also accepted.) Not valid on records (operators only). dispatcher:true renders 'as dispatcher' (double-dispatch root). Give the body as statements[] (each entry one statement or one block, assign 'rtn: <value>' on every path) and the member is complete in this call; without it the body is a stub listed under 'stubs' for ek9_insert_statements to fill.",
            "items" : {
              "properties" : {
                "dispatcher" : {
                  "type" : "boolean"
                },
                "isAbstract" : {
                  "type" : "boolean"
                },
                "name" : {
                  "type" : "string"
                },
                "override" : {
                  "type" : "boolean"
                },
                "parameters" : {
                  "items" : {
                    "anyOf" : [ {
                      "properties" : {
                        "name" : {
                          "description" : "The parameter's name.",
                          "type" : "string"
                        },
                        "type" : {
                          "description" : "Its type, e.g. 'Integer', 'List of String' - the TYPE only, no arrows.",
                          "type" : "string"
                        }
                      },
                      "required" : [ "name", "type" ],
                      "type" : "object"
                    }, {
                      "description" : "Also accepted: the EK9 text 'name as Type' - but send the object; the tool writes the '->' block, its indentation and its order.",
                      "type" : "string"
                    } ]
                  },
                  "type" : "array"
                },
                "pure" : {
                  "type" : "boolean"
                },
                "returnType" : {
                  "description" : "Return TYPE only - the tool writes '<- rtn as <Type>?'; the body assigns 'rtn: ...'.",
                  "type" : "string"
                },
                "statements" : {
                  "description" : "The body, one statement or one block per entry (assign 'rtn: <value>' on every path when there is a return); the member is complete in this call, no stub to fill.",
                  "items" : {
                    "type" : "string"
                  },
                  "type" : "array"
                },
                "visibility" : {
                  "type" : "string"
                }
              },
              "required" : [ "name" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "mode" : {
            "description" : "Construct kind. class/record/trait/component/function/type/constant/service/program append into an EXISTING .ek9 module file via the gated changeset path (omitted with parameters/returnType/statements and no fields = function); package creates a new file.",
            "enum" : [ "package", "class", "record", "trait", "component", "function", "type", "constant", "service", "program" ],
            "type" : "string"
          },
          "modifiers" : {
            "description" : "Trailing modifiers verbatim, e.g. ['as open'], ['as abstract']. All four aggregate genera (class/record/trait/component) accept open|abstract — closed by default.",
            "items" : {
              "type" : "string"
            },
            "type" : "array"
          },
          "module" : {
            "description" : "mode:package - the EK9 module name (FQ format like com.acme.orders); the same value as name, accepted in either. With constructs[] - the module a targetFile that does not exist yet is created around (an item's own 'module' wins).",
            "type" : "string"
          },
          "name" : {
            "description" : "Construct name - PascalCase for type-shaped genera, camelCase for a function or constant; for mode:package the MODULE name (com.acme.orders; 'module' is accepted).",
            "type" : "string"
          },
          "operations" : {
            "description" : "service mode (required, >=1): the web operations/routes. Each: {name | operator, verb?, uri, security?, params?, response?}. Use 'name' (+ optional 'verb' GET|POST|PUT|DELETE|PATCH|HEAD|OPTIONS, default GET) for a named route, or 'operator' (+= POST, -= DELETE, :^: PUT, :~: PATCH, ? HEAD) for the operator form. 'uri' is the operation path (e.g. '/{id}'). params: [{name, type, in: PATH|QUERY|HEADER|CONTENT|REQUEST|CONTEXT, source?, sanitized?}] — named extractions (PATH/QUERY/HEADER) are auto-captured + referenced so they compile. response: {status?, contentType?, contentLanguage?, cacheControl? | cache:{maxAge, visibility:public|private, mustRevalidate?, noStore?}} — only the fields you set are overridden; HTTPResponse defaults the rest.",
            "items" : {
              "type" : "object"
            },
            "type" : "array"
          },
          "operators" : {
            "description" : "Operators to declare. RULE OF THUMB: a string ('?', '$', 'all') means 'let the compiler synthesise it' (default operator); if the task describes what the operator RETURNS or DOES, you need the object form with custom:true, which renders a stub body for ek9_insert_statements(method:'<sym>') to fill. A plain string (or {symbol}) renders the terse 'default operator <sym>'; 'all' / '*' renders the bare 'default operator' (all defaultable). A CUSTOM operator object {symbol, custom:true, override?, pure?, parameters:[{name,type}], returnType?} renders a CONCRETE operator with a //AI-marked body — for operators the compiler cannot synthesise (a hand-rolled '$', an overriding '?', a mutating '+='). On a trait, default operators render as ABSTRACT contracts ('operator <sym> [as pure] as abstract' with resolved param/return) — Any-provided operators (?,==,$,$$,#?,<=>) are skipped + reported. Valid on class/record/trait/component. A fields-bearing aggregate auto-gets 'default operator ?' if one isn't requested (E07235).",
            "items" : {
              "anyOf" : [ {
                "description" : "The operator symbol ('?', '$', '==', '<=>' ...) or 'all' - rendered as 'default operator <sym>', synthesised by the compiler from the fields.",
                "type" : "string"
              }, {
                "properties" : {
                  "custom" : {
                    "description" : "true = render a CONCRETE operator with a stub body to fill; required whenever the operator's result is described by the task.",
                    "type" : "boolean"
                  },
                  "override" : {
                    "description" : "true for '?' on a class (every class inherits '?' from the root, E05120); false for '$', '+' etc. which have no parent version (E05110).",
                    "type" : "boolean"
                  },
                  "parameters" : {
                    "items" : {
                      "anyOf" : [ {
                        "properties" : {
                          "name" : {
                            "description" : "The parameter's name.",
                            "type" : "string"
                          },
                          "type" : {
                            "description" : "Its type, e.g. 'Integer', 'List of String' - the TYPE only, no arrows.",
                            "type" : "string"
                          }
                        },
                        "required" : [ "name", "type" ],
                        "type" : "object"
                      }, {
                        "description" : "Also accepted: the EK9 text 'name as Type' - but send the object; the tool writes the '->' block, its indentation and its order.",
                        "type" : "string"
                      } ]
                    },
                    "type" : "array"
                  },
                  "pure" : {
                    "type" : "boolean"
                  },
                  "returnType" : {
                    "type" : "string"
                  },
                  "statements" : {
                    "description" : "The body, one statement or one block per entry (assign 'rtn: <value>' on every path when there is a return); the member is complete in this call, no stub to fill.",
                    "items" : {
                      "type" : "string"
                    },
                    "type" : "array"
                  },
                  "symbol" : {
                    "type" : "string"
                  }
                },
                "required" : [ "symbol" ],
                "type" : "object"
              } ]
            },
            "type" : "array"
          },
          "parameters" : {
            "description" : "function mode: input parameters, each ONE item - 'code as Integer' or {name:'code', type:'Integer'}. 'params' is accepted as an alias.",
            "items" : {
              "anyOf" : [ {
                "properties" : {
                  "name" : {
                    "description" : "The parameter's name.",
                    "type" : "string"
                  },
                  "type" : {
                    "description" : "Its type, e.g. 'Integer', 'List of String' - the TYPE only, no arrows.",
                    "type" : "string"
                  }
                },
                "required" : [ "name", "type" ],
                "type" : "object"
              }, {
                "description" : "Also accepted: the EK9 text 'name as Type' - but send the object; the tool writes the '->' block, its indentation and its order.",
                "type" : "string"
              } ]
            },
            "type" : "array"
          },
          "publicAccess" : {
            "description" : "When true, the package can be deployed to the EK9 repository (or a private repository when false-and-published). One of the four publishable conditions. Default false.",
            "type" : "boolean"
          },
          "pure" : {
            "description" : "Pure-construction mode (class/record/component). Renders every field unset ('as Type?', any defaultValue relocated), forces every constructor 'as pure' (assigning via ':=?'), and — when no no-arg constructor was supplied and the construct has assignable fields — adds a public no-arg default-setter, so the construct is constructible in a pure context. Default false.",
            "type" : "boolean"
          },
          "returnType" : {
            "description" : "Return TYPE only, e.g. 'String', 'List of Integer' - never '<- rtn as String', never a name: the tool writes the '<- rtn as <Type>?' declaration and the body assigns 'rtn: <expr>'. Omitted means no return.",
            "type" : "string"
          },
          "security" : {
            "description" : "service mode: the security posture rendered after the base URI — 'open' or 'constrain by Gate [and Cors]'. Mandatory at service or operation level (E12050); defaults to 'open' when neither is given.",
            "type" : "string"
          },
          "serviceUri" : {
            "description" : "service mode (required): the base URI, e.g. '/addresses' — renders 'Name for :/addresses <posture>'. Base URIs cannot contain path variables (E07680).",
            "type" : "string"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "statements" : {
            "description" : "mode:function - the function's body, one statement or one block per entry (assign 'rtn: <value>' on every path when there is a return): the function is complete in this call, no stub to fill.",
            "items" : {
              "type" : "string"
            },
            "type" : "array"
          },
          "tags" : {
            "description" : "Tag list — used for repository search.",
            "items" : {
              "type" : "string"
            },
            "type" : "array"
          },
          "targetFile" : {
            "description" : "Destination: workspace-relative path of the .ek9 file - for package the NEW file to create (conflict 'file-exists' unless fileMode:'overwrite'); for every other mode the EXISTING module file the construct is appended to (its 'defines <genus>' block is created if absent). With constructs[] it is the default for items that name no targetFile of their own.",
            "type" : "string"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "traits" : {
            "description" : "'with trait of' composition (class/trait only). Each {trait, byField?}; byField delegates the trait to a field.",
            "items" : {
              "properties" : {
                "byField" : {
                  "type" : "string"
                },
                "trait" : {
                  "type" : "string"
                }
              },
              "type" : "object"
            },
            "type" : "array"
          },
          "typeForm" : {
            "description" : "type mode (required): 'enumeration' | 'constrained' | 'alias'.",
            "enum" : [ "enumeration", "constrained", "alias" ],
            "type" : "string"
          },
          "typeParameters" : {
            "description" : "Conceptual type parameters for a GENERIC class or function: [{name, constrainBy?}] → 'of type T' or 'of type (K, V)', each optionally 'constrain by <Type>'. Member signatures may reference the parameter names (T/K/V) as types. The parameterised header is grammar-incompatible with extends/with-trait-of/allow-only, so those are omitted when present.",
            "items" : {
              "properties" : {
                "constrainBy" : {
                  "type" : "string"
                },
                "name" : {
                  "type" : "string"
                }
              },
              "type" : "object"
            },
            "type" : "array"
          },
          "value" : {
            "description" : "constant mode: the literal verbatim (e.g. '\"localhost\"', '42', '3.14') — emitted as 'NAME <- value'.",
            "type" : "string"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          },
          "version" : {
            "description" : "Package version literal (Version type, not a String). Strict semver: MAJOR.MINOR.PATCH-BUILD or MAJOR.MINOR.PATCH-FEATURE-BUILD. Default '1.0.0-0'.",
            "type" : "string"
          }
        },
        "required" : [ "targetFile" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "File → New Package… / IntelliJ New… / Cargo new"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_remove_statements",
      "description" : "Deletes a contiguous statement range from one method/function/operator body; answers status and edits[] (one DELETE per line), or conflicts[] (range-straddles-method-boundary, range-not-on-statement-boundary, removed-statement-declares-used-local, removal-is-a-replacement, range-empties-body).",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "endLine" : {
            "description" : "Or the last line to remove (1-based, inclusive). Must be inside the SAME body as startLine, must align with a statement boundary, must be >= startLine.",
            "type" : "integer"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "file" : {
            "description" : "Workspace-relative path to the .ek9 source file containing the target body.",
            "type" : "string"
          },
          "fromText" : {
            "description" : "The block's FIRST line exactly as written (indentation ignored) - instead of counting startLine. Must name one line; add more of it when it occurs twice.",
            "type" : "string"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "startLine" : {
            "description" : "Or the first line to remove (1-based, inclusive) - an IDE selection. Must be inside a method/function/operator body and must align with a statement boundary.",
            "type" : "integer"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "toText" : {
            "description" : "The block's LAST line as written - the first line matching it at or after fromText. Omit it for a one-line block.",
            "type" : "string"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ "file" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "IntelliJ Cmd+Backspace delete-lines / LSP code action \"Remove statements\""
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_remove_comments",
      "description" : "Deletes one whole-line comment block (//, <!- -!>, <!-- --> or <?- -?>) in full; answers status and edits[] (one DELETE per line), or conflicts[] (kind 'comment-shares-line-with-code') when a boundary line also carries code.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "file" : {
            "description" : "Workspace-relative path to the .ek9 source file containing the comment.",
            "type" : "string"
          },
          "line" : {
            "description" : "Any 1-based line inside the comment - the tool expands to the full extent of the block via the ANTLR token stream. OMIT it and pass symbol:'<word>' to let the tool find the line.",
            "type" : "integer"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "symbol" : {
            "description" : "A word from the comment's text (e.g. 'AI' from '//AI: ...'); the first line carrying it as a whole word anchors the call. Pass line instead when the word also occurs in code.",
            "type" : "string"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ "file" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "IntelliJ Cmd+Shift+/ delete-block-comment / LSP code action \"Remove comment\""
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_insert_statements",
      "description" : "Splices EK9 statement(s) into a named method/function/operator body at anchor top, bottom, replace or a body line, re-indented by the tool; answers status, edits[] (one INSERT), insertedLineRange and resultingBodySnippet, or error.problems[] naming the entry that does not parse.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "anchor" : {
            "anyOf" : [ {
              "description" : "top: the first statement position (replaces a scaffold's placeholder; the tool resolves the rtn shape). bottom: after the last existing statement. replace: the WHOLE body is replaced by statements[] - the signature and any '<- rtn' declaration stay; use it to re-implement a member (a body 'rtn: <expr>' overrides an inline '<- rtn as T: value').",
              "enum" : [ "top", "bottom", "replace" ],
              "type" : "string"
            }, {
              "description" : "A 1-based line INSIDE the body: insert immediately AFTER it (the same as {afterLine:N}).",
              "type" : "integer"
            }, {
              "properties" : {
                "afterLine" : {
                  "description" : "Insert immediately after this 1-based line of the body.",
                  "type" : "integer"
                },
                "beforeLine" : {
                  "description" : "Insert immediately before this 1-based line of the body.",
                  "type" : "integer"
                },
                "position" : {
                  "enum" : [ "top", "bottom", "replace" ],
                  "type" : "string"
                }
              },
              "type" : "object"
            } ],
            "description" : "WHERE in the body: 'top' (first statement position; replaces a scaffold's placeholder), 'bottom' (after the last statement), 'replace' (the whole body - re-implement the member), a bare line number N (= {afterLine:N}), or {beforeLine:N} - a 1-based line INSIDE the body; with ek9_remove_statements(startLine, endLine) this replaces lines in the middle of a body."
          },
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "file" : {
            "description" : "Workspace-relative path to the .ek9 source file containing the target body (optional - found from symbol when omitted).",
            "type" : "string"
          },
          "includeBodySnippet" : {
            "default" : false,
            "description" : "When true, response.resultingBodySnippet carries the entire method/function body post-insert (delegated to ConstructSourceExtractor against the post-write program). Default false returns a ±2-line context window around the insert — usually enough to eyeball indent and position. Always check response.bodySnippetSource to confirm which path produced the snippet: \"extractor\" = full body delivered; \"contextWindowFallback\" = opt-in requested but the response carries the cheap window despite your request (typically because this call was dryRun:true — no file written, so no post-write extractor probe runs).",
            "type" : "boolean"
          },
          "memberName" : {
            "description" : "Method or operator name within symbol when symbol is the bare type ('Greeter' + memberName:'hello' is the same as symbol:'Greeter.hello'). OMIT for a program or a top-level function - do not send the string \"null\".",
            "type" : "string"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "statements" : {
            "description" : "Ordered list of EK9 statements to insert. Each entry is ONE top-level statement and MAY span several lines with '\\n' - a switch, an if, a for, a try - with its relative indentation preserved (two spaces per level); the tool owns the absolute indent. Write a block as ONE entry: \"switch code\\n  case 1\\n    rtn: \\\"active\\\"\\n  default\\n    rtn: \\\"unknown\\\"\" (one line per entry also works when the nested lines are indented deeper than the first entry). Every entry is parsed alone before anything is written; a syntax error is rejected as error.problems[{path:'statements[i]', line}] with nothing written. Spaces only - a tab is rejected.",
            "items" : {
              "type" : "string"
            },
            "type" : "array"
          },
          "symbol" : {
            "description" : "The body's owner: a program or top-level function by name ('Main', 'findLabel'), or a member as 'Type.member' ('Greeter.hello', an operator by its bare symbol: 'Order.$'). 'mod::Name' is understood.",
            "type" : "string"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ "symbol", "anchor", "statements" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "IntelliJ \"Generate\" menu / LSP code action \"Insert at cursor\""
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_create_dynamic_function",
      "description" : "Inserts `variableName <- (captures) is|extends Base as [pure] function` with its body (or an inline `(expr)`, or an //AI: stub) after the line; answers status, edits[] and summary, with a would-fail carrying the compiler's own diagnostics.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "baseType" : {
            "description" : "The abstract function being implemented: a user-defined function name in scope, or a parameterised built-in (e.g. `Function of (Integer, String)`, `Predicate of Integer`, `Consumer of String`).",
            "type" : "string"
          },
          "body" : {
            "description" : "Multi-line body. Mutually exclusive with bodyExpression. Refers to the base function's parameter names and its return-variable name. Omit BOTH body and bodyExpression to scaffold a `//AI: provide implementation` stub (block form + default-initialised inherited return) — supported only for a base that RETURNS a value; a no-return base (Consumer/BiConsumer/Acceptor/BiAcceptor) requires a body and a bodyless request is refused.",
            "type" : "string"
          },
          "bodyExpression" : {
            "description" : "Single-expression inline body (e.g. `rtn: number > threshold`). Mutually exclusive with body. For a NAMED base emitted inline as `(<expr>)`; for a PARAMETERISED base it is promoted to the block form (EK9's grammar makes the `function` keyword mandatory there).",
            "type" : "string"
          },
          "captures" : {
            "description" : "Capture list (may be empty). Each entry: {fieldName?, sourceExpression}. Captures are by-pointer-value — mutating the captured object inside the closure is visible to the caller (copy via :=: before capture for isolation).",
            "items" : {
              "additionalProperties" : false,
              "properties" : {
                "fieldName" : {
                  "description" : "Closure-field name (named capture). Omit for a simple identifier capture (field takes the same name). REQUIRED for literals/expressions, and all-or-none across the list.",
                  "type" : "string"
                },
                "sourceExpression" : {
                  "description" : "The value captured — a bare identifier, or any expression when fieldName is supplied.",
                  "type" : "string"
                }
              },
              "required" : [ "sourceExpression" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "file" : {
            "description" : "The .ek9 source file containing the host body (workspace-relative; an absolute path inside the workspace is accepted).",
            "type" : "string"
          },
          "inheritanceKeyword" : {
            "description" : "`is` and `extends` are synonyms. Default: `extends` for a parameterised (generic) base, `is` otherwise.",
            "enum" : [ "is", "extends" ],
            "type" : "string"
          },
          "line" : {
            "description" : "1-based line AFTER which the dynamic function is inserted (read it from ek9_read_file lineNumbers:true). Must be inside a function/program/method body and AFTER the captured variables are declared (a closure with captures cannot be hoisted above them).",
            "type" : "integer"
          },
          "pure" : {
            "description" : "Emit `as pure`. Default: auto — true for a pure built-in super (Predicate/Function/Consumer/...), false otherwise. Must match the base's purity or the scratch-compile reports a purity mismatch.",
            "type" : "boolean"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "variableName" : {
            "description" : "Local variable that receives the closure (e.g. gt, transformer, predicate1).",
            "type" : "string"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ "file", "line", "variableName", "baseType" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "IntelliJ \"Introduce Lambda\" / anonymous-class generate action"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_create_dynamic_class",
      "description" : "Inserts `variableName <- (captures) trait of T as class` (or the tuple / generic form) with its members after the line, auto-adding `default operator ?` for captures; answers status, edits[] and summary, with a would-fail carrying the compiler's own diagnostics (unimplemented abstract methods named).",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "baseType" : {
            "description" : "Generic-extension form: the parameterised base (e.g. `Iterator of Integer`, `Function of (String, Integer)`).",
            "type" : "string"
          },
          "captures" : {
            "description" : "Capture list (may be empty). Each entry: {fieldName?, sourceExpression}. Captures are by-pointer-value — mutating a captured object inside the class is visible to the caller (copy via :=: before capture for isolation). A non-empty list auto-adds `default operator ?`.",
            "items" : {
              "additionalProperties" : false,
              "properties" : {
                "fieldName" : {
                  "description" : "Closure-field name (named capture). Omit for a simple identifier capture (field takes the same name). REQUIRED for literals/expressions, and all-or-none across the list. Tuple captures are usually named (they double as the type's fields).",
                  "type" : "string"
                },
                "sourceExpression" : {
                  "description" : "The value captured — a bare identifier, or any expression when fieldName is supplied.",
                  "type" : "string"
                }
              },
              "required" : [ "sourceExpression" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "className" : {
            "description" : "The dynamic class's own name — the grammar identifier, a module-level TYPE, distinct from variableName. REQUIRED for the tuple form; optional (anonymous when omitted) for trait/generic forms.",
            "type" : "string"
          },
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "file" : {
            "description" : "The .ek9 source file containing the host body (workspace-relative; an absolute path inside the workspace is accepted).",
            "type" : "string"
          },
          "form" : {
            "description" : "Which grammar alternative to emit. Auto-detected when omitted: traits present → trait; baseType present → generic; otherwise tuple.",
            "enum" : [ "trait", "tuple", "generic" ],
            "type" : "string"
          },
          "inheritanceKeyword" : {
            "description" : "Generic-extension form only: `is` and `extends` are synonyms. Default: `is`.",
            "enum" : [ "is", "extends" ],
            "type" : "string"
          },
          "line" : {
            "description" : "1-based line AFTER which the dynamic class is inserted (read it from ek9_read_file lineNumbers:true). Must be inside a function/program/method body and AFTER the captured variables are declared (a class with captures cannot be hoisted above them).",
            "type" : "integer"
          },
          "members" : {
            "description" : "Multi-line aggregateParts body: fields, then methods, then operators, in grammar order (the caller owns ordering). Required for the tuple form UNLESS at least one capture is supplied (captures become the tuple's fields + an auto `default operator ?`). Omit for trait/generic to scaffold header-only (the dryRun would-fail then names the abstract methods to implement). If you author an `operator ?`, the auto `default operator ?` is suppressed.",
            "type" : "string"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "stubAbstractMethods" : {
            "default" : false,
            "description" : "When true, scaffold the OUTSTANDING abstract methods the base owes, each as a compiling `override … //AI: complete method` stub (require-guarded params, guard-first return). Generic form: the base type's abstract methods with conceptual type parameters substituted (`Iterator of Integer` -> `next() as Integer`). Trait form: the traits' unimplemented abstract methods. Tuple form has no abstract obligations (no-op). Deduped against methods you already supply in `members` — only the missing ones are added. The result is a SCAFFOLD: bodies are placeholders behind `//AI:` markers, and the fresh variable's E08090 (not-yet-referenced) is tolerated so the dryRun is `ready`. Leave false to instead have the would-fail simply NAME the methods to add.",
            "type" : "boolean"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "traits" : {
            "description" : "Trait form: the traits to implement or delegate. Each {name, by?}. Order preserved.",
            "items" : {
              "additionalProperties" : false,
              "properties" : {
                "by" : {
                  "description" : "Optional delegate: a captured field name. When given, emits `Name by field` — the whole trait is delegated to that captured field (no method stubs needed). Omit to implement the trait's abstract methods inline in `members`.",
                  "type" : "string"
                },
                "name" : {
                  "description" : "Trait name in scope (e.g. LenValidator).",
                  "type" : "string"
                }
              },
              "required" : [ "name" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "variableName" : {
            "description" : "Local variable that receives the instance (e.g. wrapper, iterator1). Emitted as `variableName <- …`.",
            "type" : "string"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ "file", "line", "variableName" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "IntelliJ \"Convert to anonymous class\" / anonymous-class generate action"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_add_field",
      "description" : "Inserts the field declaration at the construct's canonical field position; answers status, edits[] and summary, a clashing name as conflicts[] (name-collision).",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "defaultValue" : {
            "description" : "Default value expression for the field, e.g. '0', '\"\"', 'String()'. Required for records in the structured form.",
            "type" : "string"
          },
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "fieldName" : {
            "description" : "The new field's name (structured form) - with 'type' or 'defaultValue'; a name alone renders a typeless field (E07110).",
            "type" : "string"
          },
          "file" : {
            "description" : "The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site.",
            "type" : "string"
          },
          "mode" : {
            "description" : "Optional - inferred: rawDeclaration → raw, fieldName → structured.",
            "enum" : [ "structured", "raw" ],
            "type" : "string"
          },
          "rawDeclaration" : {
            "description" : "The whole declaration line as you would type it (raw form), e.g. 'name as String?' or 'logger as Logger!' (DI).",
            "type" : "string"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "symbol" : {
            "description" : "The class, record or component the field is added to - a bare name ('Order') finds its file workspace-wide; 'mod::Order' when the name is declared in two modules.",
            "type" : "string"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "type" : {
            "description" : "The field's type in the structured form, e.g. 'Float', 'List of String' - rendered 'name as Type: Type()' (present, unset until assigned) unless defaultValue is given.",
            "type" : "string"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          },
          "withConstructor" : {
            "description" : "Insert a NEW pure constructor taking this field, in the SAME change - the fields-mode rendering ek9_add_constructor mode:'fields' uses. Only applies when the field is left with no value ('name as Type?' / rawDeclaration ending '?', or the structured form with 'type' and no 'defaultValue') - that is the one shape a publicly-constructible class can leave uninitialised (E07170/E08070/E08060) until a second ek9_add_constructor call lands one; any other form already has what it needs and the option is a no-op. Default false.",
            "type" : "boolean"
          }
        },
        "required" : [ "symbol" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "Generate Field (IntelliJ) / Quick Fix - Add Field"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_rename_field",
      "description" : "Renames a private field and every use inside its owning construct body in one atomic edit; answers status and edits[] (one REPLACE per rewritten line).",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "file" : {
            "description" : "The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site.",
            "type" : "string"
          },
          "newName" : {
            "description" : "New field name. Must be a valid EK9 identifier and not collide with an existing field on the same construct.",
            "type" : "string"
          },
          "oldName" : {
            "description" : "Current field name. Must exist on the construct (omit when symbol is 'Type.field').",
            "type" : "string"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "symbol" : {
            "description" : "The construct that owns the field ('Greeter'), or the field itself as 'Greeter.farewell' (then oldName may be omitted) - found workspace-wide, no file needed.",
            "type" : "string"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ "symbol", "newName" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "Refactor → Rename (IntelliJ, field scope)"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_remove_field",
      "description" : "Deletes a field from a class/record/component; answers status and edits[] (one DELETE), or conflicts[] with every in-body reference classified by 'kind' and a suggestedRepair for the mechanical ones.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "file" : {
            "description" : "The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site.",
            "type" : "string"
          },
          "memberName" : {
            "description" : "Field to remove. Must exist on the construct (omit when symbol is 'Type.field').",
            "type" : "string"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "symbol" : {
            "description" : "The construct that owns the field ('Greeter'), or the field itself as 'Greeter.spare' (then memberName may be omitted) - found workspace-wide, no file needed.",
            "type" : "string"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ "symbol" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "Refactor → Safe Delete (IntelliJ, field scope)"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_introduce_field",
      "description" : "Lifts a local and its initialiser to a same-named field of the enclosing class/record/component and deletes the local (adding `default operator ?` when it is the first field); answers status, edits[] and conflicts[] (no-promotable-declaration, not-inside-fielded-aggregate, field-name-collision).",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "file" : {
            "description" : "Workspace-relative path to the .ek9 source file holding the local declaration.",
            "type" : "string"
          },
          "line" : {
            "description" : "1-based line of the declaration or a reference - OMIT it and pass symbol:'<name>' to let the tool find the line (a model counting lines in a file miscounts); if you do count, use ek9_read_file(lineNumbers:true).",
            "type" : "integer"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "symbol" : {
            "description" : "The identifier you mean (e.g. 'total'); the tool finds its declaration line in file. Pass line only to anchor one specific occurrence.",
            "type" : "string"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ "file" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "Refactor → Introduce Field (from local variable)"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_introduce_parameter",
      "description" : "Appends a new parameter to the enclosing method/function, replaces the selected in-body expression with it and passes the ORIGINAL expression at every call site (Fowler \"Introduce Parameter\"); answers status, edits[] and conflicts[] (value-expression-not-a-single-expression, type-not-inferable, ...).",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "endColumn" : {
            "description" : "1-based EXCLUSIVE column of the END of the span (an IDE selection). Omit it - pass the text instead.",
            "type" : "integer"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "expression" : {
            "description" : "The expression to turn into the parameter, exactly as written (e.g. '\"Hello \"' - quotes included for a string). Its first occurrence in file, or on 'line' when given.",
            "type" : "string"
          },
          "file" : {
            "description" : "Workspace-relative path to the .ek9 source file holding the expression (and its enclosing method/function).",
            "type" : "string"
          },
          "line" : {
            "description" : "Optional 1-based line holding the expression - when it occurs more than once.",
            "type" : "integer"
          },
          "name" : {
            "description" : "Identifier for the new parameter (camelCase by convention); kept verbatim. Rename later with ek9_rename_symbol.",
            "type" : "string"
          },
          "parameterType" : {
            "description" : "Optional explicit parameter type. Inferred from the expression when omitted; supply when inference yields type-not-inferable or you want a wider type than the expression's.",
            "type" : "string"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "startColumn" : {
            "description" : "1-based column of the START of the span on 'line' (an IDE selection). Omit it - pass the text instead.",
            "type" : "integer"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ "file", "name" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "Refactor → Introduce Parameter (IntelliJ)"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_safe_delete",
      "description" : "Deletes a top-level construct or a class/record/component member - or several as one change - after a workspace-wide reference check; answers status and edits[] (one DELETE per line), or conflicts[] with one 'construct-still-referenced' entry per citing site.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "column" : {
            "description" : "0-based char offset of the target identifier on 'line' (an IDE cursor). OMIT it and pass symbol:'<name>' instead, or omit both and the first identifier on the line is taken (right for a declaration line). Reuse a column from ek9_inspect_symbol_at_cursor verbatim.",
            "type" : "integer"
          },
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "file" : {
            "description" : "The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site.",
            "type" : "string"
          },
          "line" : {
            "description" : "1-based line of the declaration or a reference - OMIT it and pass symbol:'<name>' to let the tool find the line (a model counting lines in a file miscounts); if you do count, use ek9_read_file(lineNumbers:true).",
            "type" : "integer"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "symbol" : {
            "description" : "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.",
            "type" : "string"
          },
          "symbols" : {
            "description" : "Several to delete as ONE change - all or none (e.g. a dead method and its dead callers: ['reportTitles','Product.getTitle'], in any order). Instead of symbol.",
            "items" : {
              "type" : "string"
            },
            "type" : "array"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "Refactor → Safe Delete (IntelliJ)"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_extract_method",
      "description" : "Inserts the new method (parameters and return inferred from variable data-flow) and replaces the block with a call to it; answers status, edits[] and summary, an ambiguous or boundary-crossing block as conflicts[].",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "containerName" : {
            "description" : "Optional name for the synthesized container type (PascalCase). Defaults to <Name>Result.",
            "type" : "string"
          },
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "endLine" : {
            "description" : "Or the last line of the block (inclusive, 1-based). Same body as startLine.",
            "type" : "integer"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "file" : {
            "description" : "The .ek9 source file (workspace-relative; an absolute path inside the workspace is accepted).",
            "type" : "string"
          },
          "fromText" : {
            "description" : "The block's FIRST line exactly as written (indentation ignored) - instead of counting startLine. Must name one line; add more of it when it occurs twice.",
            "type" : "string"
          },
          "multiReturn" : {
            "description" : "When ≥2 values flow out of the block, the container shape that packages them into ONE return: 'formal-record' (top-level record, public fields, call site reads bundle.field), 'formal-class' (top-level class with accessor methods, bundle.field()), or 'dynamic-class' (inline captured class, no separate construct). Omit for a single value out; ≥2 out without it → return-type-ambiguous conflict listing these options. AI-directed: pick the shape from downstream intent (incidental bundle vs data carrier vs domain type).",
            "enum" : [ "formal-record", "formal-class", "dynamic-class" ],
            "type" : "string"
          },
          "name" : {
            "description" : "Name for the new method (camelCase).",
            "type" : "string"
          },
          "replaceDuplicates" : {
            "description" : "Default true: every other copy of the selected statements in the same body that is PROVEN the same computation (same shape, names mapped one-to-one, same types, only the same value flowing out) is replaced with the call too; near misses are listed in duplicates[] with the reason, never replaced.",
            "type" : "boolean"
          },
          "returnType" : {
            "description" : "Optional: the type the new member returns ('Integer'). A selection ending in the enclosing member's 'rtn: ...' line returns that member's whole result; when that is not the type asked for, the one other reading - those trailing return lines stay where they are - is taken if it returns the type asked for (said in corrected[]), else refused naming what each reading returns.",
            "type" : "string"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "startLine" : {
            "description" : "Or the first line of the block (inclusive, 1-based) - an IDE selection. Inside a method, function or program body.",
            "type" : "integer"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "toText" : {
            "description" : "The block's LAST line as written - the first line matching it at or after fromText. Omit it for a one-line block.",
            "type" : "string"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ "file", "name" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "Refactor → Extract → Method (IntelliJ) / LSP Extract Method"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_extract_variable",
      "description" : "Inserts `name <- expression` before the first occurrence and replaces every matching occurrence in the enclosing block with the name; answers status, edits[] and summary, a side-effecting multi-occurrence expression as conflicts[].",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "endColumn" : {
            "description" : "1-based EXCLUSIVE column of the END of the span (an IDE selection). Omit it - pass the text instead.",
            "type" : "integer"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "explicitType" : {
            "description" : "Optional. Emits `name as <Type>: expression` instead of the inferred `name <- expression` form.",
            "type" : "string"
          },
          "expression" : {
            "description" : "The expression exactly as written in the source ('base * base'); its first occurrence is the anchor.",
            "type" : "string"
          },
          "file" : {
            "description" : "The .ek9 source file (workspace-relative; an absolute path inside the workspace is accepted).",
            "type" : "string"
          },
          "line" : {
            "description" : "Optional 1-based line of the occurrence to anchor on. Omit it - the expression text is enough.",
            "type" : "integer"
          },
          "name" : {
            "description" : "Identifier for the new local. camelCase by EK9 convention; placeholder names (temp/data/value/…) are rejected.",
            "type" : "string"
          },
          "replaceAll" : {
            "default" : true,
            "description" : "When true (default) replaces EVERY matching occurrence in the enclosing block; when false replaces only the located occurrence.",
            "type" : "boolean"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "startColumn" : {
            "description" : "1-based column of the START of the span on 'line' (an IDE selection). Omit it - pass the text instead.",
            "type" : "integer"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ "file", "expression", "name" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "Refactor → Extract → Variable (IntelliJ) / LSP Extract Variable"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_extract_constant",
      "description" : "Appends `name <- literal` to the module's `defines constant` block (created if absent) and replaces every occurrence of the literal in the file with the name; answers status, edits[] and summary with the occurrence count, a clashing name as conflicts[] (constant-name-collision).",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "endColumn" : {
            "description" : "1-based EXCLUSIVE column of the END of the span (an IDE selection). Omit it - pass the text instead.",
            "type" : "integer"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "file" : {
            "description" : "The .ek9 source file holding the literal (workspace-relative; an absolute path inside the workspace is accepted).",
            "type" : "string"
          },
          "line" : {
            "description" : "Optional 1-based line of the occurrence to anchor on. Omit it - the literal text is enough.",
            "type" : "integer"
          },
          "literal" : {
            "description" : "The literal exactly as written in the source, quotes included for a string ('\"Hello\"', '42', '12.50#USD'); its first occurrence is extracted and every occurrence in the file replaced.",
            "type" : "string"
          },
          "name" : {
            "description" : "Identifier for the new constant. Must not clash with an existing constant; placeholder names (temp/data/value/…) are rejected.",
            "type" : "string"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "startColumn" : {
            "description" : "1-based column of the START of the span on 'line' (an IDE selection). Omit it - pass the text instead.",
            "type" : "integer"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ "file", "literal", "name" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "Refactor → Extract → Constant (IntelliJ) / LSP Extract Constant"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_promote_to_constant",
      "description" : "Moves a `name <- literal` declaration into the module's `defines constant` block (same name, original deleted); answers status, edits[] and conflicts[] (no-promotable-declaration, initialiser-not-a-literal, constant-name-collision).",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "file" : {
            "description" : "Workspace-relative path to the .ek9 source file holding the `name <- literal` declaration.",
            "type" : "string"
          },
          "line" : {
            "description" : "1-based line of the declaration or a reference - OMIT it and pass symbol:'<name>' to let the tool find the line (a model counting lines in a file miscounts); if you do count, use ek9_read_file(lineNumbers:true).",
            "type" : "integer"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "symbol" : {
            "description" : "The identifier you mean (e.g. 'total'); the tool finds its declaration line in file. Pass line only to anchor one specific occurrence.",
            "type" : "string"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ "file" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "Refactor → Introduce Constant (from field) — declaration-level"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_organize_constants",
      "description" : "Moves every `defines constant` declaration of one module into one block in one file (created when targetFile is new); answers status, edits[] (one INSERT + one DELETE per moved declaration) and conflicts[] (comments-in-block, module-ambiguous, target-file-ambiguous, pre-existing-duplicate-constant).",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "mode" : {
            "default" : "consolidate",
            "description" : "consolidate (default) gathers every constant into one block; hoist-comments lifts comments out of each block's declaration area up to its header — the one-time mechanical repair that unblocks consolidate.",
            "enum" : [ "consolidate", "hoist-comments" ],
            "type" : "string"
          },
          "module" : {
            "description" : "The exact module to organize. Default: the one module declaring constants; when several do, the call is conflicts[{kind:'module-ambiguous', modules:[...]}] until you name one.",
            "type" : "string"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "targetFile" : {
            "description" : "Workspace-relative path of the file that will hold the consolidated block. Three cases, all supported: (1) a source file of the resolved module that already has a `defines constant` block; (2) one with no such block yet — a block is created at the canonical position; (3) a path that DOES NOT EXIST — the file is created as a source file of this module (shebang + `defines module` + //EOF) with the consolidated block in it. Case (3) is the dedicated-constants-file outcome E11066's guidance recommends, so name e.g. 'myModuleConstants.ek9' and this one call does it; no separate ek9_write_file step is needed. Nothing is written on dryRun. Default: the file holding the block with the most declarations. Rejected for hoist-comments.",
            "type" : "string"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "NEW IDE surface — Refactor menu → \"Organize Constants…\". Nearest analogues are IntelliJ \"Move Members…\" (but constant-block-aware) and \"Optimize Imports\" (a whole-module tidy with no per-site decisions)."
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_create_requirement",
      "description" : "Writes the requirement nodes as flat markdown files under .ek9-ai/requirements/ (one atomic batch, each keyed by its frozen slug) and answers the editor envelope: status (applied | ready | conflicts), written, edits[] and summary naming the ids created.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "dryRun" : {
            "default" : false,
            "description" : "When true nothing is written; the response shows the would-be edits with status:'ready'.",
            "type" : "boolean"
          },
          "nodes" : {
            "description" : "The requirements to create, in intended order. A member's parentId may name an existing requirement OR another member of this same batch, which is what lets a whole subtree be created in one call.",
            "items" : {
              "additionalProperties" : false,
              "properties" : {
                "authorKind" : {
                  "description" : "Who is authoring - recorded in the changelog, the same attribution ek9_update_requirement records on every change. A child may omit authorKind and authorName to inherit its parent's; a root should state them.",
                  "enum" : [ "human", "persona" ],
                  "type" : "string"
                },
                "authorName" : {
                  "description" : "The authoring identity's name; paired with authorKind (both or neither).",
                  "type" : "string"
                },
                "body" : {
                  "description" : "Authored markdown — the WHY: intent, rationale, regulation, what success means. Not derivable from code.",
                  "type" : "string"
                },
                "meta" : {
                  "additionalProperties" : {
                    "type" : "string"
                  },
                  "description" : "Free attributes: priority, assignee, tags.",
                  "type" : "object"
                },
                "parentId" : {
                  "description" : "Parent's requirement id, e.g. REQ:payments. Omit for a root. May name another member of this batch.",
                  "type" : "string"
                },
                "prefix" : {
                  "default" : "REQ",
                  "description" : "Node kind. Closed registry. Immutable once set.",
                  "enum" : [ "REQ", "CTRL", "CAP", "CON" ],
                  "type" : "string"
                },
                "rankKey" : {
                  "description" : "Explicit sibling position (base-62 fractional index). Omit to append after existing siblings.",
                  "type" : "string"
                },
                "ruleAnchors" : {
                  "description" : "Named constraint rules for a structural requirement — one developed by a compiler rule rather than a @Test. Checked against a closed registry.",
                  "items" : {
                    "type" : "string"
                  },
                  "type" : "array"
                },
                "slug" : {
                  "description" : "Frozen at creation, [a-z0-9-]+. Combined with prefix to form the requirement id. Pick something distinctive: a collision is refused, never auto-suffixed.",
                  "type" : "string"
                },
                "title" : {
                  "description" : "Human label. Floats freely and is NOT the id.",
                  "type" : "string"
                }
              },
              "required" : [ "slug", "title", "body" ],
              "type" : "object"
            },
            "minItems" : 1,
            "type" : "array"
          },
          "terse" : {
            "default" : false,
            "description" : "Retained boolean alias for verbosity:'summary'.",
            "type" : "boolean"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Response size: full (default) carries each edit's full content; summary drops the edit bodies; none collapses edits[] to a count.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ "nodes" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "Requirement navigator → New Requirement… (planned)"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_update_requirement",
      "description" : "Rewrites one existing requirement node's markdown file (body, title, meta, position, retirement) or deletes it, and answers the editor envelope: status (applied | ready | conflicts), written, edits[] and summary naming the mode applied.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "authorKind" : {
            "description" : "Who is making the change - recorded in the changelog, the same attribution ek9_create_requirement records. Required here: an edit is never attributed by inheritance (only a created child inherits its parent's author).",
            "enum" : [ "human", "persona" ],
            "type" : "string"
          },
          "authorName" : {
            "description" : "The changing identity's name; paired with authorKind.",
            "type" : "string"
          },
          "dryRun" : {
            "default" : false,
            "description" : "When true nothing is written; the response shows the would-be edits with status:'ready'.",
            "type" : "boolean"
          },
          "meta" : {
            "additionalProperties" : {
              "type" : "string"
            },
            "description" : "For edit-meta: attributes to set. An empty value removes the key. Attributes not named are left alone.",
            "type" : "object"
          },
          "mode" : {
            "description" : "What to change.",
            "enum" : [ "edit-body-text", "edit-title", "edit-meta", "retire", "un-retire", "reparent", "confirm-intent", "delete" ],
            "type" : "string"
          },
          "parentId" : {
            "description" : "For reparent: the new parent's requirement id. Omit to promote the requirement to a root.",
            "type" : "string"
          },
          "rankKey" : {
            "description" : "For reparent: position among the new siblings.",
            "type" : "string"
          },
          "requirementId" : {
            "description" : "The requirement to change, e.g. REQ:fraud-screening.",
            "type" : "string"
          },
          "supersededBy" : {
            "description" : "For retire: the successor requirement that replaces this one. It must already exist.",
            "type" : "string"
          },
          "terse" : {
            "default" : false,
            "description" : "Retained boolean alias for verbosity:'summary'.",
            "type" : "boolean"
          },
          "text" : {
            "description" : "The new body (edit-body-text) or the new title (edit-title).",
            "type" : "string"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Response size: full (default) carries each edit's full content; summary drops the edit bodies; none collapses edits[] to a count.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ "mode", "requirementId", "authorKind", "authorName" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "Requirement navigator → right-click Edit / Retire / Reparent (planned)"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_inline_variable",
      "description" : "Deletes a single-assignment local's declaration and substitutes its initialiser at every use site (including `${...}` holes); answers status, edits[] and conflicts[] (variable-reassigned, impure-initialiser-multi-use, ...).",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "file" : {
            "description" : "Workspace-relative path to the .ek9 source file holding the local declaration.",
            "type" : "string"
          },
          "line" : {
            "description" : "1-based line of the declaration or a reference - OMIT it and pass symbol:'<name>' to let the tool find the line (a model counting lines in a file miscounts); if you do count, use ek9_read_file(lineNumbers:true).",
            "type" : "integer"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "symbol" : {
            "description" : "The identifier you mean (e.g. 'total'); the tool finds its declaration line in file. Pass line only to anchor one specific occurrence.",
            "type" : "string"
          },
          "symbols" : {
            "description" : "Several locals to inline as ONE change, in this order (e.g. ['prefix','message']) - all or none. Instead of symbol.",
            "items" : {
              "type" : "string"
            },
            "type" : "array"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ "file" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "Refactor → Inline Variable (IntelliJ) / LSP Inline Variable"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_inline_function",
      "description" : "Replaces every call to a FUNCTION or METHOD with its parameter-substituted body and deletes the declaration; answers status, edits[] (one REPLACE per call site + the DELETE) and conflicts[] (kind 'variable-clash' with {name, suggestedName}).",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "callSite" : {
            "description" : "single-call-site only: {file, line} of the ONE call to inline - the function's name on that line is found for you; column (0-based, an IDE cursor) is optional. The flat callSiteFile / callSiteLine / callSiteColumn (1-based) are the IDE form of the same thing.",
            "properties" : {
              "column" : {
                "type" : "integer"
              },
              "file" : {
                "type" : "string"
              },
              "line" : {
                "type" : "integer"
              }
            },
            "required" : [ "file", "line" ],
            "type" : "object"
          },
          "callSiteColumn" : {
            "default" : 1,
            "description" : "IDE form - column (1-based) on the call name; the name is found on the line when omitted.",
            "type" : "integer"
          },
          "callSiteFile" : {
            "description" : "IDE form of callSite.file - workspace-relative file of the target call.",
            "type" : "string"
          },
          "callSiteLine" : {
            "description" : "IDE form of callSite.line - line (1-based) of the target call.",
            "type" : "integer"
          },
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "file" : {
            "description" : "The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site.",
            "type" : "string"
          },
          "line" : {
            "description" : "1-based line of the declaration or a reference - OMIT it and pass symbol:'<name>' to let the tool find the line (a model counting lines in a file miscounts); if you do count, use ek9_read_file(lineNumbers:true).",
            "type" : "integer"
          },
          "scope" : {
            "default" : "all-call-sites",
            "description" : "all-call-sites (default): inline every call (via the Phase-5 call graph, across files) and remove the declaration. single-call-site: inline just the call at callSite:{file, line} and keep the declaration.",
            "enum" : [ "all-call-sites", "single-call-site" ],
            "type" : "string"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "symbol" : {
            "description" : "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.",
            "type" : "string"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "Refactor → Inline Function (IntelliJ) / LSP Inline Function"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_rename_symbol",
      "description" : "Renames a symbol and every workspace reference to it atomically across all files (references blocks and `${...}` holes included); answers status, edits[] per site and conflicts[] (name-collision-in-target-scope, convention-mismatch, symbol-not-renameable).",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "alsoRename" : {
            "description" : "OPTIONAL further symbols renamed in the same changeset, each {file, line, column, newName}: a place the symbol is written (its declaration or a reference; column 0-based) and its new name. Any conflict refuses them all.",
            "items" : {
              "type" : "object"
            },
            "type" : "array"
          },
          "column" : {
            "description" : "0-based char offset of the target identifier on 'line' (an IDE cursor). OMIT it and pass symbol:'<name>' instead, or omit both and the first identifier on the line is taken (right for a declaration line). Reuse a column from ek9_inspect_symbol_at_cursor verbatim.",
            "type" : "integer"
          },
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "file" : {
            "description" : "The .ek9 file containing the symbol's declaration (or a reference to it) - OPTIONAL when symbol is a construct name or 'Type.member'; required for a local or a parameter.",
            "type" : "string"
          },
          "line" : {
            "description" : "1-based line of the declaration or a reference - OMIT it and pass symbol:'<name>' to let the tool find the line (a model counting lines in a file miscounts); if you do count, use ek9_read_file(lineNumbers:true).",
            "type" : "integer"
          },
          "newName" : {
            "description" : "The new name. Must be a valid EK9 identifier honouring the symbol kind's casing convention (PascalCase for types, camelCase for members/locals) and not in EK9's banned non-descriptive set (temp/flag/data/value/...).",
            "type" : "string"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "symbol" : {
            "description" : "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.",
            "type" : "string"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ "symbol", "newName" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "Refactor → Rename (IntelliJ) / LSP Rename Symbol"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_change_signature",
      "description" : "Rewrites the declaration and EVERY call site atomically (add / remove / reorder parameters, change the return type, toggle 'as pure'); answers status, edits[] and summary with the call-site count, a blocking call site as conflicts[] (callsite-incompatible-with-new-signature).",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "column" : {
            "description" : "IDE cursor offset (0-based) on 'line'. Omit it - pass symbol instead.",
            "type" : "integer"
          },
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "file" : {
            "description" : "The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site.",
            "type" : "string"
          },
          "line" : {
            "description" : "1-based line of the declaration or a reference - OMIT it and pass symbol:'<name>' to let the tool find the line (a model counting lines in a file miscounts); if you do count, use ek9_read_file(lineNumbers:true).",
            "type" : "integer"
          },
          "mutations" : {
            "description" : "One or more mutations applied atomically, in order. Each: {kind: 'add-parameter' (+ parameter: {name, type, position?, valueForExistingCalls: the expression every existing call passes - REQUIRED whenever anything calls it, EK9 has no default parameter values}), 'remove-parameter' (+ removeParameterName, + optional dropCallSiteArguments: true to drop the argument expression at every call site — without it live call sites block the removal), 'reorder-parameters' (+ newParameterOrder: [names]), 'change-return-type' (+ newReturnType — null removes the return clause; OMIT the mutation to keep the return type), 'change-purity' (+ pure: true | false)}. position omitted = append.",
            "items" : {
              "anyOf" : [ {
                "properties" : {
                  "kind" : {
                    "const" : "add-parameter"
                  },
                  "parameter" : {
                    "properties" : {
                      "name" : {
                        "type" : "string"
                      },
                      "position" : {
                        "description" : "0-based position among the parameters; omitted = append",
                        "type" : "integer"
                      },
                      "type" : {
                        "type" : "string"
                      },
                      "valueForExistingCalls" : {
                        "description" : "The EK9 expression injected at EVERY existing call site (EK9 has no default parameter values) - required when the callable has call sites, e.g. '0.0' or 'CurrencyCode(\"USD\")'",
                        "type" : "string"
                      }
                    },
                    "required" : [ "name", "type" ],
                    "type" : "object"
                  }
                },
                "required" : [ "kind", "parameter" ],
                "type" : "object"
              }, {
                "properties" : {
                  "dropCallSiteArguments" : {
                    "description" : "true to drop the argument at every call site; without it live call sites block the removal",
                    "type" : "boolean"
                  },
                  "kind" : {
                    "const" : "remove-parameter"
                  },
                  "removeParameterName" : {
                    "type" : "string"
                  }
                },
                "required" : [ "kind", "removeParameterName" ],
                "type" : "object"
              }, {
                "properties" : {
                  "kind" : {
                    "const" : "reorder-parameters"
                  },
                  "newParameterOrder" : {
                    "items" : {
                      "type" : "string"
                    },
                    "type" : "array"
                  }
                },
                "required" : [ "kind", "newParameterOrder" ],
                "type" : "object"
              }, {
                "properties" : {
                  "kind" : {
                    "const" : "change-return-type"
                  },
                  "newReturnType" : {
                    "description" : "the new return type; null removes the return clause",
                    "type" : [ "string", "null" ]
                  }
                },
                "required" : [ "kind", "newReturnType" ],
                "type" : "object"
              }, {
                "properties" : {
                  "kind" : {
                    "const" : "change-purity"
                  },
                  "pure" : {
                    "description" : "true adds 'as pure', false removes it",
                    "type" : "boolean"
                  }
                },
                "required" : [ "kind", "pure" ],
                "type" : "object"
              } ]
            },
            "type" : "array"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "symbol" : {
            "description" : "The method or function - 'Order.total' or a bare function name finds its file and declaration workspace-wide; with file (+ line), the identifier you mean there.",
            "type" : "string"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ "symbol", "mutations" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "Refactor → Change Signature (IntelliJ)"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_fix_purity_contract",
      "description" : "Adds or removes 'as pure' on the callable the diagnostic names, with the override cascade applied; answers status, edits[] and summary, the horizontal cascade as advisories[] and a mode/diagnosis mismatch as conflicts[].",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "column" : {
            "description" : "IDE cursor offset (0-based) on 'line'. Omit it - pass symbol instead.",
            "type" : "integer"
          },
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "file" : {
            "description" : "The .ek9 source file with the purity diagnostic (workspace-relative; an absolute path inside the workspace is accepted). Optional when symbol names the callable.",
            "type" : "string"
          },
          "line" : {
            "description" : "1-based line the compiler flagged (the diagnostic's own line). Omit it and pass symbol for an override (E05150/E05160), whose declaration IS the flagged line.",
            "type" : "integer"
          },
          "mode" : {
            "description" : "The fix direction. Optional for E05150 (add-pure-to-override) and E05160 (remove-pure-from-override) - inferred from the diagnostic; required for E08130: make-callee-pure or remove-pure-from-caller.",
            "enum" : [ "make-callee-pure", "remove-pure-from-caller", "add-pure-to-override", "remove-pure-from-override" ],
            "type" : "string"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "symbol" : {
            "description" : "The flagged callable - 'Shape.area' or a bare function name finds its file and declaration workspace-wide; with file (+ line), the identifier you mean there.",
            "type" : "string"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "IDE quick-fix: reconcile purity contract (design-by-contract)"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_change_visibility",
      "description" : "Rewrites the method's declaration line with the new access modifier (public = none); answers status, edits[] and summary, an unchanged method as conflicts[] (already-<visibility>). Method-only: fields, operators and trait methods have fixed visibility.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "column" : {
            "description" : "IDE cursor offset (0-based) on 'line'. Omit it - pass symbol instead.",
            "type" : "integer"
          },
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "file" : {
            "description" : "The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site.",
            "type" : "string"
          },
          "line" : {
            "description" : "1-based line of the declaration or a reference - OMIT it and pass symbol:'<name>' to let the tool find the line (a model counting lines in a file miscounts); if you do count, use ek9_read_file(lineNumbers:true).",
            "type" : "integer"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "symbol" : {
            "description" : "The method - 'Order.total' finds its file and declaration workspace-wide; with file (+ line), the identifier you mean there.",
            "type" : "string"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          },
          "visibility" : {
            "description" : "The new access modifier.",
            "enum" : [ "public", "protected", "private" ],
            "type" : "string"
          }
        },
        "required" : [ "symbol", "visibility" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "Refactor → Change Signature (visibility) (IntelliJ) / Change Method Visibility (Eclipse)"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_make_open",
      "description" : "Appends 'as open' to the declaration so the construct can be extended; answers status and edits[] (one REPLACE on the declaration line), or conflicts[] when it is already open.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "file" : {
            "description" : "The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site.",
            "type" : "string"
          },
          "line" : {
            "description" : "1-based line of the declaration or a reference - OMIT it and pass symbol:'<name>' to let the tool find the line (a model counting lines in a file miscounts); if you do count, use ek9_read_file(lineNumbers:true).",
            "type" : "integer"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "symbol" : {
            "description" : "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.",
            "type" : "string"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "Refactor → Make Class Open"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_make_closed",
      "description" : "Strips 'as open' from the declaration so the construct can no longer be extended; answers status, edits[] and conflicts[] naming every subtype (kind 'subtype') that would break with E05030.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "file" : {
            "description" : "The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site.",
            "type" : "string"
          },
          "line" : {
            "description" : "1-based line of the declaration or a reference - OMIT it and pass symbol:'<name>' to let the tool find the line (a model counting lines in a file miscounts); if you do count, use ek9_read_file(lineNumbers:true).",
            "type" : "integer"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "symbol" : {
            "description" : "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.",
            "type" : "string"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "Refactor → Make Class Closed / Final"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_make_abstract",
      "description" : "Rewrites the declaration to 'as abstract' (replacing any 'as open') so the construct can no longer be instantiated; answers status, edits[] and wouldBeDiagnostics with every direct construction site (E10030).",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "file" : {
            "description" : "The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site.",
            "type" : "string"
          },
          "line" : {
            "description" : "1-based line of the declaration or a reference - OMIT it and pass symbol:'<name>' to let the tool find the line (a model counting lines in a file miscounts); if you do count, use ek9_read_file(lineNumbers:true).",
            "type" : "integer"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "symbol" : {
            "description" : "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.",
            "type" : "string"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "Refactor → Make Class Abstract"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_make_concrete",
      "description" : "Removes 'as abstract' from the declaration (keeping 'as open' unless keepOpen:false) so the construct can be instantiated; answers status, edits[] and conflicts[] listing every remaining abstract member (kind 'abstract-method').",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "file" : {
            "description" : "The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site.",
            "type" : "string"
          },
          "keepOpen" : {
            "default" : true,
            "description" : "Whether the resulting concrete class should be 'as open' (default true) or closed (false).",
            "type" : "boolean"
          },
          "line" : {
            "description" : "1-based line of the declaration or a reference - OMIT it and pass symbol:'<name>' to let the tool find the line (a model counting lines in a file miscounts); if you do count, use ek9_read_file(lineNumbers:true).",
            "type" : "integer"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "symbol" : {
            "description" : "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.",
            "type" : "string"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "Refactor → Make Class Concrete"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_seal_type",
      "description" : "Adds 'allow only A, B, C' to a class or trait declaration (plus 'as open' on a class that has no extensibility modifier); answers status, edits[] and conflicts[] naming any entry that does not extend the target or any existing subtype left off the list.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "allowOnly" : {
            "description" : "The 'allow only' list: every concrete class that may extend/implement the target, at any depth.",
            "items" : {
              "type" : "string"
            },
            "type" : "array"
          },
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "file" : {
            "description" : "The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site.",
            "type" : "string"
          },
          "line" : {
            "description" : "1-based line of the declaration or a reference - OMIT it and pass symbol:'<name>' to let the tool find the line (a model counting lines in a file miscounts); if you do count, use ek9_read_file(lineNumbers:true).",
            "type" : "integer"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "symbol" : {
            "description" : "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.",
            "type" : "string"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ "allowOnly" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "Kotlin \"Make sealed\" (loose analogue)",
      "orchestrationRules" : [ "allowOnly must name EVERY subtype in the target's hierarchy at ANY depth — a grandchild that extends a permitted subtype must still be listed, because EK9 rejects an unlisted concrete transitive descendant with E05240. Query the full subtype set first (e.g. ek9_query_type_hierarchy); any you omit come back as an 'existing-subtypes-not-in-allowlist' conflict." ]
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_unseal_type",
      "description" : "Removes the 'allow only A, B, C' clause from a sealed class or trait, keeping its 'as open' / 'as abstract'; answers status and edits[] (one REPLACE on the declaration line), or conflicts[] (kind 'already-unsealed') when there is no clause.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "file" : {
            "description" : "The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site.",
            "type" : "string"
          },
          "line" : {
            "description" : "1-based line of the declaration or a reference - OMIT it and pass symbol:'<name>' to let the tool find the line (a model counting lines in a file miscounts); if you do count, use ek9_read_file(lineNumbers:true).",
            "type" : "integer"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "symbol" : {
            "description" : "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.",
            "type" : "string"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "Remove sealed modifier (no direct IDE precedent)"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_add_to_sealed_allowlist",
      "description" : "Rewrites the sealed type's 'allow only' line with the new subtypes appended; answers status, edits[] and summary, each bad entry as conflicts[] (target-not-sealed, entry-does-not-extend-target, entry-already-in-allowlist).",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "allowOnly" : {
            "description" : "Concrete subtype names to add to the target's 'allow only' list, appended in the order given. Pass every unlisted subtype you intend to permit.",
            "items" : {
              "type" : "string"
            },
            "minItems" : 1,
            "type" : "array"
          },
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "file" : {
            "description" : "The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site.",
            "type" : "string"
          },
          "line" : {
            "description" : "1-based line of the declaration or a reference - OMIT it and pass symbol:'<name>' to let the tool find the line (a model counting lines in a file miscounts); if you do count, use ek9_read_file(lineNumbers:true).",
            "type" : "integer"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "symbol" : {
            "description" : "The sealed class or trait - a bare name ('Shape') finds its file and declaration workspace-wide; 'mod::Shape' when the name is declared in two modules.",
            "type" : "string"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ "symbol", "allowOnly" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "Kotlin sealed-hierarchy extension (loose analogue)",
      "orchestrationRules" : [ "Use only on an ALREADY-sealed target (has an 'allow only' clause) — for initial sealing use ek9_seal_type. The entry must already extend (class) / implement (trait) the target; a not-yet-extending entry returns 'entry-does-not-extend-target'. Adding a subtype to a type dispatched over (as dispatcher) may require a new handler (E05260) — surfaced as a would-fail; follow up with ek9_generate_dispatcher / ek9_add_method." ]
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_add_method",
      "description" : "Inserts the method (signature, a require-guarded stub body and the return) at the construct's canonical member position; answers status, edits[] and summary, a same-signature method as conflicts[] (signature-collision). Records reject named methods.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "emptyBody" : {
            "default" : false,
            "description" : "When true, generate ONLY the signature (declaration + parameters + return-with-default) with no placeholder body - no 'require param?' preconditions, no '//AI' lead, for a body you then supply with ek9_insert_statements. NOTE: EK9 flags unused parameters, so a shell WITH parameters will would-fail on apply until a body uses them; only the no-parameter-with-return shape compiles standalone.",
            "type" : "boolean"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "file" : {
            "description" : "The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site.",
            "type" : "string"
          },
          "isAbstract" : {
            "description" : "Add 'as abstract'. Only valid on traits and classes already marked 'as abstract'.",
            "type" : "boolean"
          },
          "name" : {
            "description" : "The new method's name (camelCase).",
            "type" : "string"
          },
          "override" : {
            "description" : "Add 'override' prefix when overriding a parent or trait method.",
            "type" : "boolean"
          },
          "parameters" : {
            "description" : "Parameter list, each ONE item as DATA - {name:'code', type:'Integer'} - never a {name} and a {type} as two items, and never with '->' or '<-' in it; the tool writes the arrows and the layout. ('code as Integer' is also accepted.) A malformed item is rejected before anything is rendered. Empty / omitted means a no-arg method.",
            "items" : {
              "anyOf" : [ {
                "properties" : {
                  "name" : {
                    "description" : "The parameter's name.",
                    "type" : "string"
                  },
                  "type" : {
                    "description" : "Its type, e.g. 'Integer', 'List of String' - the TYPE only, no arrows.",
                    "type" : "string"
                  }
                },
                "required" : [ "name", "type" ],
                "type" : "object"
              }, {
                "description" : "Also accepted: the EK9 text 'name as Type' - but send the object; the tool writes the '->' block, its indentation and its order.",
                "type" : "string"
              } ]
            },
            "type" : "array"
          },
          "pure" : {
            "description" : "Add 'as pure' modifier. Default false.",
            "type" : "boolean"
          },
          "returnType" : {
            "description" : "Return TYPE only, e.g. 'String', 'List of Integer' - never '<- rtn as String', never a name: the tool writes the '<- rtn as <Type>?' declaration, and the body assigns 'rtn: <expr>'. Omitted means no return.",
            "type" : "string"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "statements" : {
            "description" : "The body, one statement or one block per entry (assign 'rtn: <value>' on every path when there is a return): the method is complete in this call - no stub, no second ek9_insert_statements call. Parsed alone first; a problem names the entry and its fix.",
            "items" : {
              "type" : "string"
            },
            "type" : "array"
          },
          "symbol" : {
            "description" : "The class, trait, component or service the method is added to - a bare name ('Order') finds its file workspace-wide; 'mod::Order' when the name is declared in two modules.",
            "type" : "string"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          },
          "visibility" : {
            "description" : "The method's access. Default public.",
            "enum" : [ "public", "private", "protected" ],
            "type" : "string"
          }
        },
        "required" : [ "symbol", "name" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "Generate Method (IntelliJ) / Override/Implement Method"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_add_route",
      "description" : "Inserts the web operation (`byId() as GET for :/{id}` or `operator += for :/`) with a compiling stub body into the service; answers status, edits[] and summary, a duplicate route as conflicts[] (route-collision).",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "file" : {
            "description" : "The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site.",
            "type" : "string"
          },
          "name" : {
            "description" : "Named-route handler name (camelCase), e.g. 'byId'. Provide this OR 'operator'.",
            "type" : "string"
          },
          "operator" : {
            "description" : "Operator form of the route: += (POST), -= (DELETE), :^: (PUT), :~: (PATCH), ? (HEAD). Provide this OR 'name'.",
            "type" : "string"
          },
          "parameters" : {
            "description" : "Operation parameters: [{name, type, in:PATH|QUERY|HEADER|CONTENT|REQUEST|CONTEXT, source?, sanitized?}] - each ONE object (this list's items carry 'in', so the bare 'name as Type' form does not apply); 'type' defaults to String when omitted. PATH/QUERY/HEADER are auto-captured into the response and referenced in content() so they compile.",
            "items" : {
              "properties" : {
                "in" : {
                  "enum" : [ "PATH", "QUERY", "HEADER", "CONTENT", "REQUEST", "CONTEXT" ],
                  "type" : "string"
                },
                "name" : {
                  "type" : "string"
                },
                "sanitized" : {
                  "type" : "boolean"
                },
                "source" : {
                  "type" : "string"
                },
                "type" : {
                  "type" : "string"
                }
              },
              "required" : [ "name" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "response" : {
            "description" : "Response customisations: {status?, contentType?, contentLanguage?, cacheControl? | cache:{maxAge, visibility:public|private, mustRevalidate?, noStore?}}. Only set fields are overridden; HTTPResponse defaults the rest.",
            "type" : "object"
          },
          "security" : {
            "description" : "Per-operation security posture ('open' or 'constrain by <Gate>'). Omit to inherit the service posture.",
            "type" : "string"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "symbol" : {
            "description" : "The service the route is added to - a bare name ('OrdersService') finds its file workspace-wide; 'mod::OrdersService' when the name is declared in two modules.",
            "type" : "string"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "uri" : {
            "description" : "Operation path, e.g. '/{id}' or '/'. Path variables must be bound by a PATH param of the same name.",
            "type" : "string"
          },
          "verb" : {
            "description" : "HTTP verb for the named form. Default GET. Ignored for the operator form.",
            "enum" : [ "GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS" ],
            "type" : "string"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ "symbol" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "Add Endpoint / Generate REST Method"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_add_application",
      "description" : "Appends the application to the file's 'defines application' block (created if absent), one 'register Component() as Interface' line per registration; answers status, edits[] and summary, with a would-fail carrying the compiler's own diagnostics.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "file" : {
            "description" : "Workspace-relative path to the .ek9 module file the application is appended to (the 'defines application' block is created if absent).",
            "type" : "string"
          },
          "name" : {
            "description" : "Application name (PascalCase), e.g. 'DemoApp'.",
            "type" : "string"
          },
          "registrations" : {
            "description" : "DI registrations (>=1): [{component, as?, aspects?}]. Two forms: omit 'as' for a bare 'register Component()' (inject the concrete type), or supply 'as' for 'register Component() as Interface' (inject via the interface); 'aspects' (needs 'as') add 'with aspect of A()[, B()]' for AOP.",
            "items" : {
              "properties" : {
                "as" : {
                  "type" : "string"
                },
                "aspects" : {
                  "items" : {
                    "type" : "string"
                  },
                  "type" : "array"
                },
                "component" : {
                  "type" : "string"
                }
              },
              "type" : "object"
            },
            "type" : "array"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ "file", "name" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "New Application / DI Container"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_add_program",
      "description" : "Appends the program (or @Test program) to the file's 'defines program' block, created if absent, with a stub body that references every parameter and injection; answers status, edits[] and summary.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "application" : {
            "description" : "Application to bind for DI — renders 'with application of <App>'. The application must resolve (define it with ek9_add_application first).",
            "type" : "string"
          },
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "file" : {
            "description" : "Workspace-relative path to the .ek9 module file the program is appended to (the 'defines program' block is created if absent). For isTest:true this must be a dev source (dev/ subdirectory or QA####_dev_ file).",
            "type" : "string"
          },
          "injections" : {
            "description" : "Components pulled from the application by injection, each ONE item as DATA - {name:'code', type:'Integer'} - never a {name} and a {type} as two items, and never with '->' or '<-' in it; the tool writes the arrows and the layout. ('code as Integer' is also accepted.) A malformed item is rejected before anything is rendered. ('logger as Logger' or 'logger as Logger!' both render 'logger as Logger!'). Each is referenced in the stub (an unused injection is E11018).",
            "items" : {
              "anyOf" : [ {
                "properties" : {
                  "name" : {
                    "description" : "The parameter's name.",
                    "type" : "string"
                  },
                  "type" : {
                    "description" : "Its type, e.g. 'Integer', 'List of String' - the TYPE only, no arrows.",
                    "type" : "string"
                  }
                },
                "required" : [ "name", "type" ],
                "type" : "object"
              }, {
                "description" : "Also accepted: the EK9 text 'name as Type' - but send the object; the tool writes the '->' block, its indentation and its order.",
                "type" : "string"
              } ]
            },
            "type" : "array"
          },
          "isTest" : {
            "default" : false,
            "description" : "When true, prepend the @Test directive and emit an assert-based stub. Only legal in a dev source (E81015).",
            "type" : "boolean"
          },
          "name" : {
            "description" : "Program name (PascalCase), e.g. 'ShowInjection' or 'GreetingTest'.",
            "type" : "string"
          },
          "parameters" : {
            "description" : "Typed CLI argument parameters, each ONE item as DATA - {name:'code', type:'Integer'} - never a {name} and a {type} as two items, and never with '->' or '<-' in it; the tool writes the arrows and the layout. ('code as Integer' is also accepted.) A malformed item is rejected before anything is rendered. Each is referenced in the stub so it compiles (an unused arg is E08091).",
            "items" : {
              "anyOf" : [ {
                "properties" : {
                  "name" : {
                    "description" : "The parameter's name.",
                    "type" : "string"
                  },
                  "type" : {
                    "description" : "Its type, e.g. 'Integer', 'List of String' - the TYPE only, no arrows.",
                    "type" : "string"
                  }
                },
                "required" : [ "name", "type" ],
                "type" : "object"
              }, {
                "description" : "Also accepted: the EK9 text 'name as Type' - but send the object; the tool writes the '->' block, its indentation and its order.",
                "type" : "string"
              } ]
            },
            "type" : "array"
          },
          "requirementId" : {
            "description" : "Requirement id this test anchors, e.g. 'REQ:velocity-limit' - renders '@Test: \"REQ:velocity-limit\"'. Requires isTest:true; supplying it for a non-test program is rejected rather than ignored. The requirement need not exist yet (writing the test first is legitimate); ek9_check_requirements reports an id that names nothing as a dangling anchor.",
            "type" : "string"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "statements" : {
            "description" : "The program's body, one statement or one block per entry ('stdout <- Stdout()', 'stdout.println(...)'): the program is complete in this call - no stub, no ek9_insert_statements after it. Parsed alone first; a problem names the entry and its fix.",
            "items" : {
              "type" : "string"
            },
            "type" : "array"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ "file", "name" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "New Program / Main / Test"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_anchor_test",
      "description" : "Rewrites the @Test directive line above the program to '@Test: \"REQ:x\"' (the execution group kept); answers status, edits[] and summary, an unchanged directive as conflicts[] (already-anchored).",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "file" : {
            "description" : "The dev source holding the @Test program (workspace-relative; an absolute path inside the workspace is accepted).",
            "type" : "string"
          },
          "requirementId" : {
            "description" : "Requirement id to anchor to, e.g. 'REQ:velocity-limit'. Omit to CLEAR the anchor, leaving a plain @Test.",
            "type" : "string"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "symbol" : {
            "description" : "The @Test program's name, e.g. 'VelocityBreachesAboveFive' - a @Test program declared in this file.",
            "type" : "string"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ "file", "symbol" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "Anchor Test to Requirement"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_apply_symbolic_fix",
      "description" : "Inserts the 'require <divisor> <> 0' line guard-first (an inline-initialised return becomes '<- rtn as T?' + ':=?'), re-finding the counterexample server-side, and migrates a pinning @Test to assertPanic in the same changeset; answers status, edits[] and summary.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "file" : {
            "description" : "The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site.",
            "type" : "string"
          },
          "line" : {
            "description" : "1-based line of the declaration or a reference - OMIT it and pass symbol:'<name>' to let the tool find the line (a model counting lines in a file miscounts); if you do count, use ek9_read_file(lineNumbers:true).",
            "type" : "integer"
          },
          "obligation" : {
            "description" : "Optional counterexample selector when the function has several findings. V1 accepts only 'DIV_BY_ZERO'.",
            "type" : "string"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "symbol" : {
            "description" : "The function (or 'Type.method') to fix - a bare name finds its file workspace-wide; 'mod::name' when the name is declared in two modules.",
            "type" : "string"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          },
          "witness" : {
            "description" : "Optional counterexample selector ('<param>=<value>', e.g. 'quantity=0') when the function has several fixable divisions.",
            "type" : "string"
          }
        },
        "required" : [ "symbol" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "IDE quick-fix: add precondition (design-by-contract guard)"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_apply_guard_pattern",
      "description" : "Rewrites the construct's head to 'if x <- f()' (or ':=?', or ':=' with an explicit 'then x?', as the source assignment dictates) and deletes the standalone assignment and the redundant 'x?' check; answers status, edits[] and summary, an unsafe or unsupported shape as conflicts[].",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "file" : {
            "description" : "The EK9 source file (workspace-relative; an absolute path inside the workspace is accepted).",
            "type" : "string"
          },
          "line" : {
            "description" : "IDE refinement: the 1-based line of the control construct's opening line (if/while/do-while/for/switch/try). Omit it and pass symbol.",
            "type" : "integer"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "symbol" : {
            "description" : "The variable to lift into the guard ('customer'); the tool finds the control construct that tests it. Prefer this to line.",
            "type" : "string"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ "file" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "IDE quick-fix: convert check-then-use into a guard (design-by-contract null safety)"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_add_constructor",
      "description" : "Inserts one constructor at the construct's canonical member position; answers status, edits[] and summary, a same-shape constructor as conflicts[] (constructor-already-exists, with its line).",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "fields" : {
            "description" : "fields mode - names of the fields to take as constructor parameters, in order.",
            "items" : {
              "type" : "string"
            },
            "type" : "array"
          },
          "file" : {
            "description" : "The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site.",
            "type" : "string"
          },
          "mode" : {
            "description" : "no-arg: a bodyless 'default' constructor blocking default construction; all-fields: every field as a parameter; fields: the named subset (inferred when fields[] is given).",
            "enum" : [ "no-arg", "all-fields", "fields" ],
            "type" : "string"
          },
          "pure" : {
            "description" : "Add 'as pure'. Default false.",
            "type" : "boolean"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "symbol" : {
            "description" : "The class, record or component the constructor is added to - a bare name ('Order') finds its file workspace-wide; 'mod::Order' when the name is declared in two modules.",
            "type" : "string"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          },
          "visibility" : {
            "description" : "no-arg only - the constructor's access. Default 'private' (the typical force-a-factory use).",
            "enum" : [ "public", "private", "protected" ],
            "type" : "string"
          }
        },
        "required" : [ "symbol" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "Generate Constructor (IntelliJ)"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_convert_constructor",
      "description" : "Replaces the no-arg constructor with its other spelling - 'default Name()' ↔ an explicit 'this.field :=? Type()' default-setter body - purity and visibility preserved; answers status, edits[] and summary.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "file" : {
            "description" : "The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site.",
            "type" : "string"
          },
          "line" : {
            "description" : "IDE refinement: the 1-based line of the constructor declaration. Omit it - the no-arg constructor is found by symbol; needed only when two exist.",
            "type" : "integer"
          },
          "mode" : {
            "description" : "Optional - inferred from the constructor found: a 'default' constructor expands (→ explicit 'this.field :=? Type()' body), an explicit no-arg one collapses (→ 'default').",
            "enum" : [ "expand", "collapse" ],
            "type" : "string"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "symbol" : {
            "description" : "The class or record owning the no-arg constructor - a bare name ('Person') finds its file workspace-wide; 'mod::Person' when the name is declared in two modules.",
            "type" : "string"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ "symbol" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "Convert Constructor (collapse/expand)"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_add_operator",
      "description" : "Inserts the operator declaration (or the bare 'default operator' block) at the construct's canonical operator position; answers status, edits[] and summary - 'unchanged', naming where it is, for a default operator the construct already declares; statements[] for an operator already written by hand replace its body, and body:'explicit' over one names the insert route in conflicts[].",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "body" : {
            "description" : "default (the default): a 'default operator' declaration the compiler synthesises from the fields; explicit: a field-based stub for you to complete.",
            "enum" : [ "default", "explicit" ],
            "type" : "string"
          },
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "file" : {
            "description" : "The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site.",
            "type" : "string"
          },
          "operator" : {
            "description" : "The operator in EK9 source form: '==', '<=>', '<>', '?', '$', '#?', ':=:', '+', 'mod', … Omit it with body:'default' to default every defaultable operator at once.",
            "type" : "string"
          },
          "pure" : {
            "description" : "IGNORED for a known operator and not worth sending - purity is not a choice. The language fixes it: every non-mutating operator must be 'as pure' (E07500) and the ten mutators ':~: :^: :=: | += -= *= /= ++ --' must not be (E07510). It is derived and the response says so in 'corrected' when your value differed.",
            "type" : "boolean"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "statements" : {
            "description" : "The operator's body, one statement or one block per entry (assign 'rtn: <value>' on every path): the operator is complete in this call - override, pure and the language-fixed signature are filled in. Needs 'operator'; 'body' is then ignored. For an operator the construct already implements by hand, its body is REPLACED (the signature stays).",
            "items" : {
              "type" : "string"
            },
            "type" : "array"
          },
          "symbol" : {
            "description" : "The class, record, component, enumeration (or trait, for an explicit body) the operator is added to - a bare name ('Point') finds its file workspace-wide; 'mod::Point' when the name is declared in two modules.",
            "type" : "string"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ "symbol" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "Generate Operator (no direct equivalent — EK9-specific)"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_collapse_to_default_operator",
      "description" : "Replaces the operator's declaration and body with the one-line 'default operator <sym>' form (the inverse of ek9_expand_default_operator); answers status, edits[] and summary.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "file" : {
            "description" : "The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site.",
            "type" : "string"
          },
          "line" : {
            "description" : "IDE refinement: the 1-based line of the operator declaration. Omit it - the declaration is found by symbol + operator; needed only when two overloads declare the same operator.",
            "type" : "integer"
          },
          "operator" : {
            "description" : "The operator to collapse, in EK9 source form ('==', '<=>', '$'); must be in the defaultable set.",
            "type" : "string"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "symbol" : {
            "description" : "The class, record or component holding the operator - a bare name ('Order') finds its file workspace-wide; 'mod::Order' when the name is declared in two modules.",
            "type" : "string"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ "symbol", "operator" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "Code Cleanup → Use Default Implementation (no direct equivalent)"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_expand_default_operator",
      "description" : "Replaces the 'default operator' declaration with the explicit body the compiler would synthesise from the fields, ready to customise; answers status, edits[] and summary, a missing default line as conflicts[] (target-not-a-default-operator).",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "file" : {
            "description" : "The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site.",
            "type" : "string"
          },
          "line" : {
            "description" : "IDE refinement: the 1-based line of the 'default operator' declaration. Omit it - the declaration is found by symbol + operator.",
            "type" : "integer"
          },
          "mode" : {
            "description" : "Optional - inferred: operator given → one, none → all.",
            "enum" : [ "one", "all" ],
            "type" : "string"
          },
          "operator" : {
            "description" : "The one operator to expand, in EK9 source form ('==', '<=>', '$'). Omit it to expand the bare 'default operator' block into every defaultable operator.",
            "type" : "string"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "symbol" : {
            "description" : "The class, record or component holding the default operator - a bare name ('Order') finds its file workspace-wide; 'mod::Order' when the name is declared in two modules.",
            "type" : "string"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ "symbol" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "Generate Default Implementation (no direct equivalent)"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_adopt_trait",
      "description" : "Appends 'with trait of <Trait>' (or '… by <field>') to the construct's declaration and, when implementing, one override stub per abstract trait method; answers status, edits[] and summary, an already-adopted trait as conflicts[] (trait-already-adopted).",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "delegateFieldName" : {
            "description" : "To DELEGATE instead of implementing: the existing field on the construct to forward every trait method to (its type must satisfy the trait).",
            "type" : "string"
          },
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "file" : {
            "description" : "The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site.",
            "type" : "string"
          },
          "mode" : {
            "description" : "Optional - inferred: delegateFieldName present → delegate, else implement (override stubs).",
            "enum" : [ "implement", "delegate" ],
            "type" : "string"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "symbol" : {
            "description" : "The class or component that adopts the trait - a bare name ('Greeter') finds its file workspace-wide; 'mod::Greeter' when the name is declared in two modules.",
            "type" : "string"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "traitName" : {
            "description" : "The EXISTING trait to adopt (must resolve in the workspace); 'mod::Trait' when the name is declared in two modules.",
            "type" : "string"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ "symbol", "traitName" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "Implement Interface (IntelliJ — Cmd+I) / Generate Delegate"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_implement_methods",
      "description" : "Inserts an 'override' stub for every abstract trait method the class has not implemented; answers status and edits[] (one INSERT block), or an error carrying the resolutions[] a concrete-diamond collision needs.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "file" : {
            "description" : "The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site.",
            "type" : "string"
          },
          "line" : {
            "description" : "1-based line of the declaration or a reference - OMIT it and pass symbol:'<name>' to let the tool find the line (a model counting lines in a file miscounts); if you do count, use ek9_read_file(lineNumbers:true).",
            "type" : "integer"
          },
          "members" : {
            "description" : "Optional - only implement these methods (each must be an unimplemented trait method). A name gets a placeholder body; {name, statements:[...]} is written WITH that body, so one call implements the trait. Omit to implement all outstanding with placeholders.",
            "items" : {
              "anyOf" : [ {
                "type" : "string"
              }, {
                "additionalProperties" : false,
                "properties" : {
                  "name" : {
                    "type" : "string"
                  },
                  "statements" : {
                    "items" : {
                      "type" : "string"
                    },
                    "type" : "array"
                  }
                },
                "required" : [ "name" ],
                "type" : "object"
              } ]
            },
            "type" : "array"
          },
          "mode" : {
            "description" : "Optional: stubs (the default - placeholder bodies for every outstanding method) or conflict-resolution (inferred whenever resolutions[] is sent).",
            "enum" : [ "stubs", "conflict-resolution" ],
            "type" : "string"
          },
          "resolutions" : {
            "description" : "One {methodName, source} per conflicting method; source is 'trait:<TraitName>' or 'override'. Sending it selects conflict-resolution mode.",
            "items" : {
              "additionalProperties" : false,
              "properties" : {
                "methodName" : {
                  "type" : "string"
                },
                "source" : {
                  "type" : "string"
                }
              },
              "required" : [ "methodName", "source" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "symbol" : {
            "description" : "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.",
            "type" : "string"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "Implement Methods (IntelliJ)"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_generate_delegation",
      "description" : "Rewrites the class header's 'with trait of <Trait>' clause to '... by <field>' so the compiler forwards every trait method (no bodies generated); answers status, edits[] and summary.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "delegate" : {
            "description" : "The name of an existing field on the class to delegate to. Its declared type should implement the trait (the compile gate confirms).",
            "type" : "string"
          },
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "file" : {
            "description" : "The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site.",
            "type" : "string"
          },
          "line" : {
            "description" : "1-based line of the declaration or a reference - OMIT it and pass symbol:'<name>' to let the tool find the line (a model counting lines in a file miscounts); if you do count, use ek9_read_file(lineNumbers:true).",
            "type" : "integer"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "symbol" : {
            "description" : "The class that declares the trait - a bare name ('DelegatingProcessor') finds its file and declaration workspace-wide; 'mod::Name' when the name is declared in two modules.",
            "type" : "string"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "traitName" : {
            "description" : "The trait already declared on the class via 'with trait of'. Simple name (Processor) when unambiguous; fully-qualified (com.acme::Processor) when needed.",
            "type" : "string"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ "symbol", "traitName", "delegate" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "Generate Delegate (IntelliJ)"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_generate_dispatcher",
      "description" : "Inserts the '<name>() as dispatcher' entry with its fallback body plus one same-named handler overload per subtype of the base type; answers status, edits[] and summary naming any existing handlers kept.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "additionalParameters" : {
            "description" : "Optional extra parameters added to BOTH the entry and every handler, after the auto-added subtype parameter; each ONE item as DATA - {name:'code', type:'Integer'} - never a {name} and a {type} as two items, and never with '->' or '<-' in it; the tool writes the arrows and the layout. ('code as Integer' is also accepted.) A malformed item is rejected before anything is rendered.",
            "items" : {
              "anyOf" : [ {
                "properties" : {
                  "name" : {
                    "description" : "The parameter's name.",
                    "type" : "string"
                  },
                  "type" : {
                    "description" : "Its type, e.g. 'Integer', 'List of String' - the TYPE only, no arrows.",
                    "type" : "string"
                  }
                },
                "required" : [ "name", "type" ],
                "type" : "object"
              }, {
                "description" : "Also accepted: the EK9 text 'name as Type' - but send the object; the tool writes the '->' block, its indentation and its order.",
                "type" : "string"
              } ]
            },
            "type" : "array"
          },
          "baseType" : {
            "description" : "The type the dispatcher dispatches on. If SEALED, its 'allow only' subtypes drive handlers (exhaustive); if NON-SEALED, its known concrete subtypes do (entry fallback covers the rest). Fully-qualified (com.acme::Animal) when needed; simple name when unambiguous.",
            "type" : "string"
          },
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "file" : {
            "description" : "The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site.",
            "type" : "string"
          },
          "line" : {
            "description" : "1-based line of the declaration or a reference - OMIT it and pass symbol:'<name>' to let the tool find the line (a model counting lines in a file miscounts); if you do count, use ek9_read_file(lineNumbers:true).",
            "type" : "integer"
          },
          "name" : {
            "description" : "The dispatcher method name (e.g. describe, sound, route). ALL generated handlers share this exact name.",
            "type" : "string"
          },
          "returnType" : {
            "description" : "Optional shared return type for the entry + every handler. Omit for a void dispatcher.",
            "type" : "string"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "symbol" : {
            "description" : "The class the dispatcher is scaffolded on - a bare name ('ShapeProcessor') finds its file and declaration workspace-wide; 'mod::Name' when the name is declared in two modules.",
            "type" : "string"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          },
          "visibility" : {
            "description" : "The handlers' access (default 'private' - handlers are implementation details). The entry is always public.",
            "enum" : [ "private", "public", "protected" ],
            "type" : "string"
          }
        },
        "required" : [ "symbol", "name", "baseType" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "Generate (IntelliJ) — visitor/dispatch scaffolding"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_prune_empty_sources",
      "description" : "Deletes every .ek9 file that is a bare zero-construct module stub (shebang + 'defines module' + //EOF, line comments allowed); answers status, edits[] (one DELETE per file) and skipped[] with a reason per retained candidate.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "moduleFilter" : {
            "anyOf" : [ {
              "items" : {
                "type" : "string"
              },
              "maxItems" : 1,
              "type" : "array"
            }, {
              "type" : "string"
            } ],
            "description" : "Restrict candidates to files declaring this exact `defines module <name>` (an array of one name, or the bare name). When omitted, every module in the scanned roots is considered."
          },
          "roots" : {
            "description" : "Workspace-relative directories to scan. When omitted, defaults to the watched workspace roots.",
            "items" : {
              "type" : "string"
            },
            "type" : "array"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "NEW IDE surface — Build menu → \"Prune Empty Sources…\" wizard (root picker, module filter, preview pane with two columns: files to delete + retained candidates with reasons). Also wired as a receipts-pane follow-up action on every pure-relocation tool (ek9_organize_localized_text, ek9_extract_to_localized_text, ek9_move_construct)."
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_rewrite_string_concat",
      "description" : "Replaces a selected `\"a\" + var + \"b\"` concat with the equivalent backtick interpolation, escaping backtick and `$` in literal segments; answers status and edits[] (one REPLACE), conflicts[] (selection-not-a-string-expression, operand-has-no-string-operator with a suggestedRepair), or status:unchanged when the selection is already a backtick literal.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "file" : {
            "description" : "Workspace-relative path to the .ek9 source file containing the selection.",
            "type" : "string"
          },
          "selection" : {
            "description" : "The IDE selection covering exactly the concat expression (or one string literal): startLine/endLine and startColumn/endColumn, all 1-based, end INCLUSIVE - read them off ek9_read_file(lineNumbers:true). startCol/endCol are accepted.",
            "properties" : {
              "endColumn" : {
                "type" : "integer"
              },
              "endLine" : {
                "type" : "integer"
              },
              "startColumn" : {
                "type" : "integer"
              },
              "startLine" : {
                "type" : "integer"
              }
            },
            "required" : [ "startLine", "endLine" ],
            "type" : "object"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ "file", "selection" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "IntelliJ \"Convert to template string\" / VS Code \"Convert to template literal\""
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_insert_coalescing",
      "description" : "Splices `LEFT <op> RIGHT` in place of a selected single-line left operand using one of the EK9 coalescing / elvis operators; answers status, edits[] (one REPLACE) and conflicts[] (kind 'selection-not-an-expression'), with a type-incompatible pairing surfacing as would-fail.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "endColumn" : {
            "description" : "1-based EXCLUSIVE column of the END of the span (an IDE selection). Omit it - pass the text instead.",
            "type" : "integer"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "file" : {
            "description" : "Workspace-relative path to the .ek9 source file containing the expression.",
            "type" : "string"
          },
          "line" : {
            "description" : "Optional 1-based line of the operand. Needed only when the operand text is an operand on more than one line.",
            "type" : "integer"
          },
          "operand" : {
            "description" : "The LEFT operand exactly as written in the source ('name', 'a + b').",
            "type" : "string"
          },
          "operator" : {
            "description" : "The coalescing operator to insert: `?:` first SET - the one that defaults an unset value ('name ?: \"Anonymous\"'); `<?` min, `>?` max (the LEFT operand on a tie).",
            "enum" : [ "?:", "<?", ">?" ],
            "type" : "string"
          },
          "rightOperand" : {
            "description" : "The RIGHT operand expression as source text — e.g. a fallback literal (`\"Anonymous\"`), another variable (`y`), or a further chained expression (`b ?: c`). Spliced verbatim.",
            "type" : "string"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "startColumn" : {
            "description" : "1-based column of the START of the span on 'line' (an IDE selection). Omit it - pass the text instead.",
            "type" : "integer"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ "file", "operator", "rightOperand" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "no direct precedent — EK9-specific coalescing / elvis operators"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_surround_with",
      "description" : "Folds a contiguous line range under an if / if-else / try-catch / try-catch-finally / for-range / while / switch head, re-indenting the block per EK9's brace-free rules; answers status and edits[] (one REPLACE carrying the head + the re-indented lines, one DELETE per absorbed line).",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "caseValues" : {
            "description" : "switch: the text after 'case' for the selected code (e.g. '1, 2, 3, 4, 5', '< passMark'), emitted verbatim. Omitted: 'case 1 //AI: Replace with the case values'.",
            "type" : "string"
          },
          "condition" : {
            "description" : "if / if-else / while: the condition source text (e.g. 'count > 0', 'name?'), emitted verbatim; switch: the value switched on (e.g. 'day'). Omitted: an opaque placeholder with an //AI: marker to replace.",
            "type" : "string"
          },
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "endLine" : {
            "description" : "Or the last line of the selection (1-based, inclusive).",
            "type" : "integer"
          },
          "exceptionType" : {
            "description" : "try-catch / try-catch-finally: the caught type (default Exception).",
            "type" : "string"
          },
          "exceptionVariable" : {
            "description" : "try-catch / try-catch-finally: the handler's variable name (default ex).",
            "type" : "string"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "file" : {
            "description" : "Workspace-relative path to the .ek9 source file containing the lines to wrap.",
            "type" : "string"
          },
          "fromText" : {
            "description" : "The block's FIRST line exactly as written (indentation ignored) - instead of counting startLine. Must name one line; add more of it when it occurs twice.",
            "type" : "string"
          },
          "rangeExpression" : {
            "description" : "for-range: the text after 'for i in' (e.g. '1 ... 10', 'items'), or a whole 'item in items' clause. Omitted: 'for i in 1 ... 10 //AI: Replace range'.",
            "type" : "string"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "startLine" : {
            "description" : "Or the first line of the selection (1-based) - an IDE selection.",
            "type" : "integer"
          },
          "surroundType" : {
            "description" : "The wrapper: if, if-else, try-catch, try-catch-finally, for-range, while or switch (the selection becomes the first case, with a default).",
            "enum" : [ "if", "if-else", "try-catch", "try-catch-finally", "for-range", "while", "switch" ],
            "type" : "string"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "toText" : {
            "description" : "The block's LAST line as written - the first line matching it at or after fromText. Omit it for a one-line block.",
            "type" : "string"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ "file", "surroundType" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "Surround With… (IntelliJ — Cmd+Alt+T)"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_move_construct",
      "description" : "Relocates one top-level construct to another .ek9 file, rewriting every workspace 'references' entry when the move changes module; answers status, edits[] (source DELETE, target INSERT, one rewrite per referring file) and conflicts[].",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "file" : {
            "description" : "The .ek9 file currently containing the construct - OPTIONAL when symbol is a construct name (the tool finds it workspace-wide).",
            "type" : "string"
          },
          "line" : {
            "description" : "1-based line of the declaration or a reference - OMIT it and pass symbol:'<name>' to let the tool find the line (a model counting lines in a file miscounts); if you do count, use ek9_read_file(lineNumbers:true).",
            "type" : "integer"
          },
          "mode" : {
            "description" : "Optional - derived from the two files' 'defines module' lines: same-module (relocation) or cross-module (relocation + workspace-wide reference rewriting). A sent value that contradicts the files is rejected.",
            "enum" : [ "same-module", "cross-module" ],
            "type" : "string"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "sourceFile" : {
            "description" : "Alias of file (the file currently containing the construct).",
            "type" : "string"
          },
          "symbol" : {
            "description" : "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.",
            "type" : "string"
          },
          "targetFile" : {
            "description" : "Destination: workspace-relative path the construct should move to. Must already exist; its 'defines module' declaration determines the target module.",
            "type" : "string"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ "targetFile" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "Move Class (IntelliJ)"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_pull_up",
      "description" : "Moves the named methods/operators from a subclass into its superclass, dropping 'override' on the moved declarations; answers status and edits[] (one DELETE per member + one INSERT on the superclass).",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "file" : {
            "description" : "The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site.",
            "type" : "string"
          },
          "line" : {
            "description" : "1-based line of the declaration or a reference - OMIT it and pass symbol:'<name>' to let the tool find the line (a model counting lines in a file miscounts); if you do count, use ek9_read_file(lineNumbers:true).",
            "type" : "integer"
          },
          "members" : {
            "description" : "Names of methods/operators on the subclass to pull up. Operators use their symbol form (e.g. '==', '<=>').",
            "items" : {
              "type" : "string"
            },
            "type" : "array"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "superclass" : {
            "description" : "Optional — the superclass name. When omitted it is resolved from the subclass's 'extends' clause; when supplied it is validated against that superclass.",
            "type" : "string"
          },
          "symbol" : {
            "description" : "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.",
            "type" : "string"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ "members" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "Pull Members Up (IntelliJ)"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_push_down",
      "description" : "Removes the named methods/operators from a superclass and copies them into each named direct subclass; answers status, edits[] (one DELETE + one INSERT per subclass) and conflicts[] (subclass-not-direct, target-is-only-source-class).",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "file" : {
            "description" : "The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site.",
            "type" : "string"
          },
          "keepAsOverride" : {
            "default" : false,
            "description" : "Keep the 'override' modifier on the subclass copies (only for multi-level hierarchies where an ancestor above the superclass still declares the member).",
            "type" : "boolean"
          },
          "line" : {
            "description" : "1-based line of the declaration or a reference - OMIT it and pass symbol:'<name>' to let the tool find the line (a model counting lines in a file miscounts); if you do count, use ek9_read_file(lineNumbers:true).",
            "type" : "integer"
          },
          "members" : {
            "description" : "Names of methods/operators on the superclass to push down. Operators use their symbol form (e.g. '==', '<=>').",
            "items" : {
              "type" : "string"
            },
            "type" : "array"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "subclasses" : {
            "description" : "Names of DIRECT subclasses to receive the pushed-down members. Empty errors.",
            "items" : {
              "type" : "string"
            },
            "type" : "array"
          },
          "symbol" : {
            "description" : "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.",
            "type" : "string"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ "members", "subclasses" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "Push Members Down (IntelliJ)"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_extract_trait",
      "description" : "Appends a new 'defines trait' block declaring the chosen methods as abstract, adds 'with trait of <Name>' to the class header and 'override' to each method; answers status, edits[] and summary, a non-extractable member as conflicts[] (member-not-extractable-to-trait).",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "file" : {
            "description" : "The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site.",
            "type" : "string"
          },
          "line" : {
            "description" : "1-based line of the declaration or a reference - OMIT it and pass symbol:'<name>' to let the tool find the line (a model counting lines in a file miscounts); if you do count, use ek9_read_file(lineNumbers:true).",
            "type" : "integer"
          },
          "members" : {
            "description" : "Names of PUBLIC methods on the class to extract into the trait.",
            "items" : {
              "type" : "string"
            },
            "type" : "array"
          },
          "name" : {
            "description" : "The new trait's identifier (PascalCase by convention). Must not already exist in the file.",
            "type" : "string"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "symbol" : {
            "description" : "The class whose methods move to the trait - a bare name ('CustomerOrder') finds its file and declaration workspace-wide; 'mod::CustomerOrder' when the name is declared in two modules.",
            "type" : "string"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ "symbol", "members", "name" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "Extract Interface (IntelliJ / Eclipse)"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_toggle_block_comment",
      "description" : "Wraps a whole-line range in EK9 block-comment markers (<!- ... -!>) or removes them when the range already carries them, never nesting; answers status and edits[] (two INSERTs or two DELETEs).",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "endLine" : {
            "description" : "Last line of the range to toggle (1-based, inclusive). Must be >= startLine.",
            "type" : "integer"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "file" : {
            "description" : "Workspace-relative path to the .ek9 source file.",
            "type" : "string"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "startLine" : {
            "description" : "First line of the range to toggle (1-based, inclusive).",
            "type" : "integer"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ "file", "startLine", "endLine" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "Comment with Block Comment (IntelliJ)"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_format",
      "description" : "Rewrites the file in canonical EK9 style (indentation, spacing, blank-line and line-break conventions); answers status, edits[] (one per changed line) and summary, an unparseable file as conflicts[] (source-not-parseable).",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "file" : {
            "description" : "The .ek9 source file to format (workspace-relative; an absolute path inside the workspace is accepted).",
            "type" : "string"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ "file" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "Reformat Code (IntelliJ Ctrl+Alt+L)"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_edit_localized_text",
      "description" : "Rewrites the `defines text for \"<locale>\"` blocks of one text type in every locale that defines it (one atomic edit, so E07150 locale-completeness holds) and answers the editor envelope: status (applied | ready | would-fail | conflicts | error), written, edits[], summary, and translationDebt[] naming each {textType, locale, method} left placeholder-stubbed.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "includeTextTypes" : {
            "description" : "For add-locale: limit the clone to these text types; omit for every text type referenceLocale defines.",
            "items" : {
              "type" : "string"
            },
            "type" : "array"
          },
          "locale" : {
            "description" : "For remove-locale: the locale code to discontinue module-wide (e.g. fr, fr_FR, ja_JP) - every `defines text for \"<locale>\"` block matching it goes.",
            "type" : "string"
          },
          "methodBodies" : {
            "additionalProperties" : {
              "type" : "string"
            },
            "description" : "For add-text-method and update-text-method: locale -> body, e.g. {en_GB:'`Goodbye ${name}`', de:'`Auf Wiedersehen ${name}`'}; add-text-method stubs any locale left out, update-text-method leaves it alone.",
            "type" : "object"
          },
          "methodName" : {
            "description" : "For add-text-method: the new method's name; for update-text-method and remove-text-method: the existing method (supply parameters when the name is overloaded).",
            "type" : "string"
          },
          "methods" : {
            "description" : "For create-text-type: the text methods to author, each {name, parameters, body}.",
            "items" : {
              "properties" : {
                "body" : {
                  "description" : "The primary locale's body, e.g. '`Hello ${name}`'.",
                  "type" : "string"
                },
                "name" : {
                  "description" : "The text method's name.",
                  "type" : "string"
                },
                "parameters" : {
                  "description" : "Its parameters, 'name as Type' each; omit for none.",
                  "items" : {
                    "anyOf" : [ {
                      "properties" : {
                        "name" : {
                          "description" : "The parameter's name.",
                          "type" : "string"
                        },
                        "type" : {
                          "description" : "Its type, e.g. 'Integer', 'List of String' - the TYPE only, no arrows.",
                          "type" : "string"
                        }
                      },
                      "required" : [ "name", "type" ],
                      "type" : "object"
                    }, {
                      "description" : "Also accepted: the EK9 text 'name as Type' - but send the object; the tool writes the '->' block, its indentation and its order.",
                      "type" : "string"
                    } ]
                  },
                  "type" : "array"
                }
              },
              "required" : [ "name", "body" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "mode" : {
            "description" : "Which operation to perform.",
            "enum" : [ "create-text-type", "add-text-method", "add-locale", "update-text-method", "remove-text-method", "remove-locale" ],
            "type" : "string"
          },
          "module" : {
            "description" : "The module to operate on. Default: the first module that defines any text type; supply it when several modules carry i18n. Derived from targetFile when that is given.",
            "type" : "string"
          },
          "newLocale" : {
            "description" : "For add-locale: the locale to bring up (e.g. fr_FR) - every text type in referenceLocale gets a block, placeholder-stubbed.",
            "type" : "string"
          },
          "parameters" : {
            "description" : "For add-text-method: the new method's parameters, 'name as Type' each; for update/remove-text-method: the overload to pick when methodName is ambiguous.",
            "items" : {
              "anyOf" : [ {
                "properties" : {
                  "name" : {
                    "description" : "The parameter's name.",
                    "type" : "string"
                  },
                  "type" : {
                    "description" : "Its type, e.g. 'Integer', 'List of String' - the TYPE only, no arrows.",
                    "type" : "string"
                  }
                },
                "required" : [ "name", "type" ],
                "type" : "object"
              }, {
                "description" : "Also accepted: the EK9 text 'name as Type' - but send the object; the tool writes the '->' block, its indentation and its order.",
                "type" : "string"
              } ]
            },
            "type" : "array"
          },
          "primaryLocale" : {
            "description" : "For create-text-type: the locale whose bodies are authored (e.g. en_GB); every other supportedLocale gets a placeholder-stubbed body listed in translationDebt[].",
            "type" : "string"
          },
          "referenceLocale" : {
            "description" : "For add-locale: the existing locale whose text types and method signatures the new locale clones.",
            "type" : "string"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "supportedLocales" : {
            "description" : "For create-text-type: every locale to define the text type in, primaryLocale included (e.g. ['en_GB','de']).",
            "items" : {
              "type" : "string"
            },
            "type" : "array"
          },
          "targetFile" : {
            "description" : "Destination: the workspace-relative file the new text type lands in - required for create-text-type when no locale block exists yet. Optional for every other mode (they are workspace-wide and find the existing blocks through the module catalogue); supply it, or `module`, when the workspace has more than one module.",
            "type" : "string"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "textTypeName" : {
            "description" : "The text type (PascalCase) - the one to create for create-text-type, the existing one for add/update/remove-text-method; for add-locale and remove-locale see includeTextTypes / locale.",
            "type" : "string"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ "mode" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "NEW IDE surface — JavaFX dialog for create-text-type, right-click context menu inside `defines text for` blocks"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_extract_to_localized_text",
      "description" : "Replaces the selected string literal with `<localeAccessor>.<name>(args)` and adds the text method to every locale of the i18n file in one atomic changeset, answering the editor envelope: status (applied | ready | would-fail | conflicts | error), written, edits[], summary and translationDebt[] naming the locales left placeholder-stubbed.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "endColumn" : {
            "description" : "1-based column of the literal's closing quote or backtick, inclusive.",
            "type" : "integer"
          },
          "endLine" : {
            "description" : "1-based line the literal ends on (the same line for a one-line literal).",
            "type" : "integer"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "file" : {
            "description" : "The .ek9 source file holding the literal - workspace-relative (absolute inside the workspace accepted).",
            "type" : "string"
          },
          "i18nFile" : {
            "description" : "Destination: required when textTypeName does NOT yet exist in the module. Workspace-relative path where the new text type lands.",
            "type" : "string"
          },
          "localeAccessor" : {
            "description" : "Name of an existing variable in scope at the selection site whose type is the target text type. The rewritten call site becomes `<localeAccessor>.<name>(<args>)`.",
            "type" : "string"
          },
          "name" : {
            "description" : "Name for the new text method.",
            "type" : "string"
          },
          "parameters" : {
            "description" : "Optional override of the auto-inferred parameter signature. Supplied parameters must match the inferred count AND order; names can differ; types can widen.",
            "items" : {
              "anyOf" : [ {
                "properties" : {
                  "name" : {
                    "description" : "The parameter's name.",
                    "type" : "string"
                  },
                  "type" : {
                    "description" : "Its type, e.g. 'Integer', 'List of String' - the TYPE only, no arrows.",
                    "type" : "string"
                  }
                },
                "required" : [ "name", "type" ],
                "type" : "object"
              }, {
                "description" : "Also accepted: the EK9 text 'name as Type' - but send the object; the tool writes the '->' block, its indentation and its order.",
                "type" : "string"
              } ]
            },
            "type" : "array"
          },
          "primaryLocale" : {
            "description" : "Required when textTypeName does NOT yet exist. Strongly recommended whenever the text type already exists in multiple locales.",
            "type" : "string"
          },
          "selection" : {
            "description" : "IDE alias for the four flat keys: {startLine, startCol, endLine, endCol}, 1-based inclusive.",
            "properties" : {
              "endCol" : {
                "type" : "integer"
              },
              "endLine" : {
                "type" : "integer"
              },
              "startCol" : {
                "type" : "integer"
              },
              "startLine" : {
                "type" : "integer"
              }
            },
            "type" : "object"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "startColumn" : {
            "description" : "1-based column of the literal's opening quote or backtick, inclusive.",
            "type" : "integer"
          },
          "startLine" : {
            "description" : "1-based line the string literal starts on.",
            "type" : "integer"
          },
          "supportedLocales" : {
            "description" : "Optional for new text type creation.",
            "items" : {
              "type" : "string"
            },
            "type" : "array"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "textTypeName" : {
            "description" : "Target text type (PascalCase). If it exists in the module, the method is added via add-text-method semantics internally. If it does not exist, the tool creates it.",
            "type" : "string"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ "file", "textTypeName", "name", "localeAccessor" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "NEW IDE surface — Right-click on a selected string literal (double-quoted or backtick-interpolation) inside an EK9 source file → \"Extract to Localized Text…\""
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_organize_localized_text",
      "description" : "Moves the `defines text for \"<locale>\"` blocks between files to the chosen layout - block content preserved verbatim, donors kept as residual stubs, never deleted - and answers the editor envelope: status (applied | ready | conflicts | error), written, edits[] and summary; an already-canonical layout is applied with empty edits[].",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "mode" : {
            "description" : "Layout target. split-by-locale -> <locale>.ek9 per language; split-by-text-type -> <TextTypeName>.ek9 per text type; consolidate -> the single targetFile.",
            "enum" : [ "split-by-locale", "split-by-text-type", "consolidate" ],
            "type" : "string"
          },
          "module" : {
            "description" : "The module to operate on. Default: the first module that defines any text type; supply it when several modules carry i18n.",
            "type" : "string"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "targetFile" : {
            "description" : "Destination: the single output file (workspace-relative), required for consolidate; REJECTED for the split modes, whose outputs are deterministically named.",
            "type" : "string"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ "mode" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "NEW IDE surface — Build menu → \"Organize Localized Text…\" wizard (mode picker, preview pane, conflict resolver). Pairs with the Translation Completeness panel."
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_organize_references",
      "description" : "Deletes the unused entries of one file's 'references' block (usage judged by a scratch compile, so functions, types and name-collisions are all right) and answers the editor envelope: status (applied | ready | error), written, edits[] - one delete per unused line - and summary; an already-clean file is applied with empty edits[].",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "file" : {
            "description" : "The .ek9 source file whose references block to trim - workspace-relative (absolute inside the workspace accepted).",
            "type" : "string"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ "file" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "Optimize Imports (IntelliJ) / Remove Unused Imports"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_sync_references",
      "description" : "Rewrites one file's 'references' block - adding the module::Name entry for each cross-module symbol the file uses but has not declared (E50001/E50010) and deleting each entry nothing uses - and answers the editor envelope: status (applied | ready | conflicts | error), written, edits[] and summary ('Added N and removed M reference(s)').",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "addMissing" : {
            "default" : true,
            "description" : "Add references for cross-module symbols the file uses but doesn't declare. Default true.",
            "type" : "boolean"
          },
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "file" : {
            "description" : "The .ek9 source file whose references block to sync - workspace-relative (absolute inside the workspace accepted). The file must have compiled to FULL_RESOLUTION or beyond.",
            "type" : "string"
          },
          "removeUnused" : {
            "default" : true,
            "description" : "Remove references nothing in the file uses. Default true.",
            "type" : "boolean"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ "file" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "Optimize Imports (IntelliJ) / Organize Imports (VS Code)"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_add_dependency",
      "description" : "Answers with the edit that appends one runtime or dev dependency to the deps/devDeps Dict of a 'defines package' block - source only, nothing is fetched.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "bucket" : {
            "description" : "Which Dict to extend: 'deps' (runtime, deployed) or 'devDeps' (dev/test only, not deployed).",
            "enum" : [ "deps", "devDeps" ],
            "type" : "string"
          },
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "file" : {
            "description" : "The .ek9 file holding the 'defines package' block, workspace-relative (typically 'package.ek9'); an absolute path inside the workspace is accepted.",
            "type" : "string"
          },
          "module" : {
            "description" : "The dependency's module name, e.g. 'ek9open.network.support.utils' - the Dict key.",
            "type" : "string"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          },
          "version" : {
            "description" : "The version to pin, e.g. '1.6.1-9' (major.minor.patch-build; a feature-tagged major.minor.patch-feature-build is also accepted) - the Dict value.",
            "type" : "string"
          }
        },
        "required" : [ "file", "bucket", "module", "version" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "npm install / cargo add / mvn add-dependency"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_remove_dependency",
      "description" : "Answers with the edit that deletes one entry from the deps or devDeps Dict of a 'defines package' block (the whole Dict when it was the last entry).",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "bucket" : {
            "description" : "Which Dict to remove from: 'deps' (runtime, deployed) or 'devDeps' (dev/test only, not deployed).",
            "enum" : [ "deps", "devDeps" ],
            "type" : "string"
          },
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "file" : {
            "description" : "The .ek9 file holding the 'defines package' block, workspace-relative (typically 'package.ek9'); an absolute path inside the workspace is accepted.",
            "type" : "string"
          },
          "module" : {
            "description" : "The dependency's module name to remove, e.g. 'ek9open.network.support.utils' - matched against the Dict key.",
            "type" : "string"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ "file", "bucket", "module" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "npm uninstall / cargo remove / mvn dependency:remove"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_exclude_transitive_dependency",
      "description" : "Answers with the edit that adds an excludeDeps entry (module -> viaModule) to a 'defines package' block, blocking a transitive dependency a parent pulls in.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "file" : {
            "description" : "The .ek9 file holding the 'defines package' block, workspace-relative (typically 'package.ek9'); an absolute path inside the workspace is accepted.",
            "type" : "string"
          },
          "module" : {
            "description" : "The transitive module to block, e.g. 'ek9open.some.bad.dependency.pack' - the excludeDeps Dict key.",
            "type" : "string"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          },
          "viaModule" : {
            "description" : "The parent module whose dependency on 'module' is blocked, e.g. 'ek9open.org.supertools.util' - the excludeDeps Dict value (a module name, not a version).",
            "type" : "string"
          }
        },
        "required" : [ "file", "module", "viaModule" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "maven exclusions / npm overrides"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_remove_transitive_exclusion",
      "description" : "Answers with the edit that deletes one excludeDeps entry from a 'defines package' block, re-allowing a previously-blocked transitive dependency.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "file" : {
            "description" : "The .ek9 file holding the 'defines package' block, workspace-relative (typically 'package.ek9'); an absolute path inside the workspace is accepted.",
            "type" : "string"
          },
          "module" : {
            "description" : "The previously-excluded transitive module, e.g. 'ek9open.some.bad.dependency.pack' - matched against the excludeDeps Dict key.",
            "type" : "string"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ "file", "module" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "maven exclusion removal"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_add_capability",
      "description" : "Answers with the edit that declares one gated-type capability in the 'capabilities <- [...]' List of a 'defines package' block, plus the resolved capability name.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "capability" : {
            "description" : "The gated type to permit: a bare name such as 'TCP' or 'Stdout' (resolved to org.ek9.lang::<Name>) or the fully-qualified 'org.ek9.lang::TCP'. A primary capability covers its group (TCP covers TCPConnection/TCPHandler/NetworkProperties), so the related types need no entry of their own.",
            "type" : "string"
          },
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "file" : {
            "description" : "The .ek9 file holding the 'defines package' block, workspace-relative (typically 'package.ek9'); an absolute path inside the workspace is accepted.",
            "type" : "string"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ "file", "capability" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "EK9 IDE - package-block right-click \"Add Capability...\" + the E12010 quick-fix. Concept: Android manifest permissions / iOS entitlements."
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_remove_capability",
      "description" : "Answers with the edit that revokes one gated-type capability from the 'capabilities <- [...]' List of a 'defines package' block, plus the resolved capability name.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "capability" : {
            "description" : "The gated type to revoke: a bare name such as 'TCP' (resolved to org.ek9.lang::TCP) or the fully-qualified name - matched against the capabilities List entries.",
            "type" : "string"
          },
          "dirtyOverlay" : {
            "description" : "Universal — see §1.1. Override on-disk content for files with unsaved buffers. Entries are applied at read time; the apply path still writes the (post-edit) result to disk.",
            "items" : {
              "properties" : {
                "content" : {
                  "type" : "string"
                },
                "file" : {
                  "type" : "string"
                }
              },
              "required" : [ "file", "content" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "dryRun" : {
            "default" : false,
            "description" : "Universal — see EK9_TOOL_SPECIFICATIONS.md §1.1. When true, no disk mutation; response shows the would-be edit.",
            "type" : "boolean"
          },
          "expectedWorkspaceHash" : {
            "description" : "Universal — see §1.1. Drift-detection hash from a prior dry-run. Mismatch emits a WORKSPACE_DRIFTED warning.",
            "type" : "string"
          },
          "file" : {
            "description" : "The .ek9 file holding the 'defines package' block, workspace-relative (typically 'package.ek9'); an absolute path inside the workspace is accepted.",
            "type" : "string"
          },
          "removeListIfEmpty" : {
            "default" : false,
            "description" : "True allows removing the LAST entry, which drops the whole 'capabilities <- [...]' declaration (an empty List literal is a parse error) and switches capability enforcement off for the package. False (default) refuses that case with conflict 'would-empty-capabilities-list'.",
            "type" : "boolean"
          },
          "showExamples" : {
            "default" : false,
            "description" : "Universal — the inverse of terseErrors. When true each wouldBeDiagnostics entry is enriched with a 'richExplanation' field inlining that error code's rich explanation (diagnosis + correct-pattern action + 'ek9 -q N' worked-example pointers — the same text ek9_explain_error returns), so a would-fail dry-run carries the corrective pattern without a second call. terseErrors takes precedence if both set.",
            "type" : "boolean"
          },
          "terse" : {
            "default" : false,
            "description" : "Universal — token-saver. When true the response omits each edit's before/after bodies (keeping skeletal file/type/line range). Use on an apply after a dryRun already showed the full render — you keep WHAT changed WHERE without re-sending the content.",
            "type" : "boolean"
          },
          "terseErrors" : {
            "default" : false,
            "description" : "Universal — token-saver. When true each wouldBeDiagnostics entry collapses to its one-line message + errorCode/file/line (the multi-paragraph explanation is dropped). Recover full detail on demand with ek9_explain_error <errorCode>.",
            "type" : "boolean"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Universal response-size control (smaller / less detail / summary) — see §1.6. full (default) reproduces the complete response; summary drops each edit's before/after bodies (keeping file/type/line range); none collapses the edits array to a count. The `terse` boolean is the retained alias for summary.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ "file", "capability" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "editor",
      "idePrecedent" : "EK9 IDE - package-block right-click \"Remove Capability...\". Concept: Android manifest permission removal."
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_compile",
      "description" : "Compiles the workspace and answers status (ok | failed | found-no-sources | blocked), sourceCount, errorCount, warningCount and diagnostics[] - each with file, line, column, severity, errorCode and message, the ek9_query_diagnostics record - for every discovered .ek9 file.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "errorLevel" : {
            "default" : 3,
            "description" : "Error detail level: 0 minimal, 1 visual, 2 + fuzzy suggestions, 3 + rich explanations.",
            "maximum" : 3,
            "minimum" : 0,
            "type" : "integer"
          },
          "includeDev" : {
            "description" : "Include dev-only code (test sources, fixtures). Implies withDebug per the CLI -cd family bundling rule.",
            "type" : "boolean"
          },
          "mode" : {
            "default" : "full",
            "description" : "Cache strategy: incremental and full both compile the whole workspace today (incremental does not yet reuse earlier results), check-only (compile + analyse without emitting artefacts), clean (wipe artefacts + dependencies before compile).",
            "enum" : [ "incremental", "full", "check-only", "clean" ],
            "type" : "string"
          },
          "noLink" : {
            "description" : "Compile + analyse without producing an executable artefact. Equivalent to mode: check-only when paired with mode: incremental or full. Rejected with withProfiling.",
            "type" : "boolean"
          },
          "optimisation" : {
            "default" : "o2",
            "description" : "o0 (none - fastest compile, max debug fidelity), o2 (balanced), o3 (aggressive - inlining, DCE, loop opts; breaks debug attributes and profiling probes). Auto-set to o0 when withProfiling: true.",
            "enum" : [ "o0", "o2", "o3" ],
            "type" : "string"
          },
          "phaseUpTo" : {
            "default" : "PRE_IR_CHECKS",
            "description" : "Stop after the named compilation phase (e.g. FULL_RESOLUTION, IR_GENERATION) for pipeline-stage diagnostics.",
            "enum" : [ "READING", "PARSING", "SYMBOL_DEFINITION", "DUPLICATION_CHECK", "REFERENCE_CHECKS", "EXPLICIT_TYPE_SYMBOL_DEFINITION", "TYPE_HIERARCHY_CHECKS", "FULL_RESOLUTION", "POST_RESOLUTION_CHECKS", "PRE_IR_CHECKS", "PLUGIN_RESOLUTION", "SYMBOLIC_ANALYSIS", "IR_GENERATION", "IR_ANALYSIS", "IR_OPTIMISATION", "CODE_GENERATION_PREPARATION", "CODE_GENERATION_CONSTANTS", "CODE_GENERATION_APPLICATIONS", "CODE_GENERATION_AGGREGATES", "CODE_OPTIMISATION", "PLUGIN_LINKAGE", "APPLICATION_PACKAGING", "PACKAGING_POST_PROCESSING" ],
            "type" : "string"
          },
          "projectDir" : {
            "description" : "Project root to discover .ek9 files from - absolute, or relative to the workspace root; (re)initialises the workspace before compiling. Omit to reuse the initialised workspace. Shorthand for roots:[projectDir].",
            "type" : "string"
          },
          "repair" : {
            "default" : true,
            "description" : "Apply the fixes the language leaves no choice about, then compile again: a slip with one reading (e.g. '-> a as Integer, b as String', 'Type?: value', a stray ')'), and 'default operator ?' for a class, record or component with fields and no '?' (E07235) - each listed in corrected[] and edits[]. false compiles only, and changes nothing.",
            "type" : "boolean"
          },
          "roots" : {
            "description" : "Several project roots at once, each as projectDir. Omit for one root (use projectDir) or to reuse the initialised workspace.",
            "items" : {
              "type" : "string"
            },
            "type" : "array"
          },
          "traceCompiler" : {
            "default" : false,
            "description" : "Emit verbose compile-pipeline tracing to the build log.",
            "type" : "boolean"
          },
          "withDebug" : {
            "description" : "Emit debug info / SMAP for breakpoint + variable inspection. Compatible with optimisation o0 (max fidelity) or o2 (safe). Rejected with o3 (aggressive optimisation strips debug attributes).",
            "type" : "boolean"
          },
          "withProfiling" : {
            "description" : "Emit per-function profiling probes for hot-path / call-graph data. Forces optimisation: o0. Rejected with o2 / o3 (probes get inlined away). Rejected with noLink (no artefact to profile). Implies withDebug for source-line attribution.",
            "type" : "boolean"
          }
        },
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "execution",
      "idePrecedent" : "Build Project (IntelliJ)",
      "workflows" : [ "release", "feature_branch_start", "investigate_build_failure" ]
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_clean",
      "description" : "Wipes the on-disk .ek9/ artefacts the scope names and resets the server JVM's in-memory coverage/profiling runtimes; answers status:ok with cleanedSources[] listing what was wiped or reset, in order.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "file" : {
            "description" : "The entry-point .ek9 source file (absolute, or relative to projectDir). Omit to auto-detect the shallowest non-dev .ek9 file - enough to locate the .ek9/ directory.",
            "type" : "string"
          },
          "projectDir" : {
            "description" : "Project root holding the .ek9 sources - absolute, or relative to the workspace root. Omit to use the workspace root itself (the first root ek9_compile was given).",
            "type" : "string"
          },
          "scope" : {
            "default" : "full",
            "description" : "What to make pristine: coverage (generated/ + coverage runtime), profiling (coverage + profiling runtime), release and full (also lib/, the target executable and props).",
            "enum" : [ "coverage", "profiling", "release", "full" ],
            "type" : "string"
          }
        },
        "required" : [ ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "execution",
      "idePrecedent" : "Build → Clean (IntelliJ) / mvn clean / cargo clean",
      "workflows" : [ "release" ]
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_run_tests",
      "description" : "Compiles and runs the project's @Test programs (auto-forcing -Cd -O0 so coverage probes map to source) and answers status (ok | compile-failed | no-tests-found | tests-failed | coverage-low), tests:{passed, failed}, overallCoverage, results[] per test, plus the inputVariety and hex change-risk blocks.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "coverageDetail" : {
            "description" : "Retained boolean alias for verbosity:'full'.",
            "type" : "boolean"
          },
          "file" : {
            "description" : "The entry-point .ek9 source file (absolute, or relative to projectDir). Omit to auto-detect the shallowest non-dev .ek9 file.",
            "type" : "string"
          },
          "generateReport" : {
            "description" : "Default false. When true, additionally produces an HTML coverage report at .ek9/coverage/index.html.",
            "type" : "boolean"
          },
          "notes" : {
            "description" : "Default false. When true, include the full interpretation prose beside the metric blocks (how to read hex/hexMax/bands/cohorts, why Ca and purity sit outside the score, what asserted variety means). It is invariant text and ~1,300 tokens, so it is omitted by default and every block instead carries a one-line pointer. The same guidance is permanently available via ek9_help with keyword 'hex' - prefer that once, over paying for it on every run.",
            "type" : "boolean"
          },
          "projectDir" : {
            "description" : "Project root holding the .ek9 sources - absolute, or relative to the workspace root. Omit to use the workspace root itself (the first root ek9_compile was given).",
            "type" : "string"
          },
          "testGroupFilter" : {
            "description" : "Run only tests in the named group. Tests without the group are skipped.",
            "type" : "string"
          },
          "testNameFilter" : {
            "description" : "Run only this test: a fully qualified name (com.acme::SmokeTest) or a bare program name (SmokeTest) when it is unique across the workspace - an ambiguous bare name is refused naming the candidates.",
            "type" : "string"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Response size. summary (default): counts, per-test results, the hex and inputVariety headlines. full: also a 'coverage' block of every UNCOVERED method / branch / statement with file + line (the CLI -t4/-t5 data) and hex.constructs[], the full ranked per-construct list with raw signals. none: status and counts only.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "execution",
      "idePrecedent" : "Run All Tests (IntelliJ) / mvn test / cargo test",
      "workflows" : [ "release", "quality_check" ]
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_run_quality_checks",
      "description" : "Compiles, runs the tests and answers status (ok | compile-failed | no-tests-found | tests-failed | coverage-low) with tests:{passed, failed}, coverage (overall, methods, lines, branches, byModule), complexity.hotspots[], readability, injections, uncoveredMethods[] and the advisory lockPayloads - every quality metric in one call, extracted in-process.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "complexityThreshold" : {
            "default" : 10,
            "description" : "Methods with cyclomatic complexity >= this appear in complexity.hotspots.",
            "type" : "integer"
          },
          "file" : {
            "description" : "The entry-point .ek9 source file (absolute, or relative to projectDir). Omit to auto-detect the shallowest non-dev .ek9 file.",
            "type" : "string"
          },
          "projectDir" : {
            "description" : "Project root holding the .ek9 sources - absolute, or relative to the workspace root. Omit to use the workspace root itself (the first root ek9_compile was given).",
            "type" : "string"
          }
        },
        "required" : [ ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "execution",
      "idePrecedent" : "SonarQube dashboard / cargo-tarpaulin / istanbul coverage",
      "workflows" : [ "release", "quality_check" ]
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_generate_edge_case_tests",
      "description" : "Writes a compile-checked edge-case @Test program file for one .ek9 source and answers status (applied | ready | unchanged | blocked | error), written, testCount, the echoed seed and modifiedFiles[] - every harvested constructor, method, operator and function gets the tri-state UNSET value among its inputs.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "dryRun" : {
            "description" : "Default false. Preview only: harvest, generate, compile-filter and assemble exactly as a real run, but write NOTHING. Returns status 'ready' with testCount and the full fileContent that a committing call would write. Re-invoke without dryRun to commit. Use this to check testCount > 0 before writing.",
            "type" : "boolean"
          },
          "file" : {
            "description" : "The .ek9 source file to generate tests for - absolute, or relative to the first workspace root once one is initialised (ek9_compile); with no workspace, only an absolute path works. Refused when it resolves outside every workspace root. (The GENERATION itself runs against a fresh builtins-only program, not the workspace's compiled one.)",
            "type" : "string"
          },
          "includeGeneratedTests" : {
            "description" : "Default false. When true, include a compact [{name, description}] index of the surviving tests for inline curation (full bodies are written to outputFile).",
            "type" : "boolean"
          },
          "maxResults" : {
            "default" : 200,
            "description" : "Max candidate tests to generate before compile-filtering; testCount will be <= this.",
            "type" : "integer"
          },
          "mode" : {
            "description" : "Default 'edge' — spray type-aware edge values (fuzz). 'verify' — run bounded-model verification per function and synthesise a directed test for each counterexample (seed/count are ignored in this mode).",
            "enum" : [ "edge", "verify" ],
            "type" : "string"
          },
          "outputFile" : {
            "description" : "Destination: the generated test file - absolute, or relative to the workspace root exactly as 'file' is; refused when it resolves outside every workspace root. MUST be a dev source — under a 'dev/' subdirectory or a QA####_dev_ filename — because the generated @Test/assert constructs only compile there (E81015); a non-dev path is blocked. Also blocked if it already exists unless overwrite:true.",
            "type" : "string"
          },
          "overwrite" : {
            "description" : "Default false. Replace outputFile if it exists.",
            "type" : "boolean"
          },
          "seed" : {
            "description" : "Reproducibility seed. Default: random (always echoed in the response). Pass the echoed seed back to regenerate the exact same survivor set after a source edit.",
            "type" : "integer"
          },
          "targets" : {
            "description" : "Optional. Restrict generation to these construct names (types and/or functions, e.g. [\"Location\"]). Tests are generated ONLY for the named constructs, but nested arguments still use the full source for fidelity. Omit or empty = all testable constructs.",
            "items" : {
              "type" : "string"
            },
            "type" : "array"
          },
          "testModule" : {
            "description" : "Module to declare the generated @Test programs in. Omit to DETECT: whichever module already holds tests referencing the source's module wins, else a conventional '<sourceModule>.tests' if the project has one, else the source's own module. When it differs from the source's module the file gains an alphabetically-ordered references block (E11026) and its edge-value constants are de-duplicated against that module, not the source's. Validated when supplied: an illegal module name is rejected up front with status 'blocked' / reason 'invalid-test-module'. Note a segment may not be a reserved keyword EK9 excludes from moduleSegment — 'some.other.mod' is illegal ('mod' is an operator), 'some.other.place' is fine.",
            "type" : "string"
          },
          "verbose" : {
            "description" : "Default false. Verbose compiler reporting.",
            "type" : "boolean"
          }
        },
        "required" : [ "file", "outputFile" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "execution",
      "idePrecedent" : "Hypothesis (Python) / fast-check (JS) / QuickCheck (Haskell)",
      "orchestrationRules" : [ "Generated tests are liveness / edge-case SMOKE tests — they exercise edge + always-unset inputs and assert set-ness / no-crash, NOT business correctness. Read a green result as 'survives edge inputs', not 'behaviour verified'.", "Compile-surviving does NOT mean passing: some generated tests legitimately fail (e.g. asserting on an unset-input result). The flow is generate -> review / curate -> ek9_run_tests, not generate -> trust.", "The output is SCAFFOLDING. Every //AI: assertion is an expectation YOU must set from the REQUIREMENT the code is meant to satisfy — never from what the code currently returns. Do NOT run the tests and keep whichever assertion is green: that codes the test to the implementation and cements existing bugs as passing. A RED test is this tool working — decide whether the expectation or the code is wrong. Where the project tracks requirements, ek9_query_requirement / ek9_check_requirements is where the expectation should come from.", "Capture the echoed seed to regenerate the exact same survivor set after a source edit.", "If status is no-testable-symbols the source compiled but exposes nothing public to test — move on or widen the API surface." ]
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_git_init",
      "description" : "Reports branch and gitignoreCreated (a .gitignore for the generated .ek9/ directory is scaffolded when absent); refuses when already a repository.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "branch" : {
            "description" : "Initial branch name. Default main.",
            "type" : "string"
          }
        },
        "required" : [ ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "execution",
      "idePrecedent" : "git init / Enable Version Control Integration",
      "orchestrationRules" : [ "The only git tool valid OUTSIDE a repo. Refuses when already one. After init there are no commits yet - ek9_git_add all:true then ek9_git_commit." ]
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_git_add",
      "description" : "Reports stagedPaths and stagedPathCount (what this call staged), then indexAfter and indexAfterCount (everything now staged) and a summary line.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "all" : {
            "description" : "Stage every change including deletions (git add -A). Default false.",
            "type" : "boolean"
          },
          "paths" : {
            "description" : "Workspace-relative paths to stage.",
            "items" : {
              "type" : "string"
            },
            "type" : "array"
          }
        },
        "required" : [ ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "execution",
      "idePrecedent" : "git add / Stage Changes",
      "orchestrationRules" : [ "Stage before ek9_git_commit, or let ek9_git_commit paths:[...] do both. indexAfter is what the next commit will record." ]
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_git_commit",
      "description" : "Reports newSha and previousSha, branch, subject, changedFiles and changedFileCount; local history only, nothing is published until ek9_git_push.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "all" : {
            "description" : "Stage every tracked modification first (git commit -a); untracked files are not included. Default false.",
            "type" : "boolean"
          },
          "amend" : {
            "description" : "Rewrite the previous commit instead of creating a new one. Default false.",
            "type" : "boolean"
          },
          "message" : {
            "description" : "Commit message. Required unless amend:true, which then keeps the previous commit's message.",
            "type" : "string"
          },
          "paths" : {
            "description" : "Workspace-relative paths to stage before committing (stage + commit in one call).",
            "items" : {
              "type" : "string"
            },
            "type" : "array"
          }
        },
        "required" : [ ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "execution",
      "idePrecedent" : "git commit / Commit",
      "orchestrationRules" : [ "Stage first (ek9_git_add) or pass paths / all:true. Local history only - run ek9_git_push to publish. nothing-to-commit means the index is clean." ]
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_git_push",
      "description" : "Reports remote, branch, upstream, upToDate and a summary line, with git's own report under gitReport; outward-facing and not trivially reversible, so confirm intent first.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "branch" : {
            "description" : "Branch to push. Default: the current branch.",
            "type" : "string"
          },
          "force" : {
            "description" : "Replace the remote branch with --force-with-lease (refuses when the remote moved since the last fetch). Default false.",
            "type" : "boolean"
          },
          "remote" : {
            "description" : "Remote name. Default origin.",
            "type" : "string"
          },
          "setUpstream" : {
            "description" : "Set the upstream tracking ref (-u) - the first push of a new branch. Default false.",
            "type" : "boolean"
          }
        },
        "required" : [ ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "execution",
      "idePrecedent" : "git push / Push",
      "orchestrationRules" : [ "Push PUBLISHES and is not trivially reversible - confirm intent before calling. setUpstream:true on the first push of a new branch." ]
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_git_switch",
      "description" : "Reports status (switched or created), branch and previousBranch; a dirty tree that would be overwritten is refused with the route (commit, stash or restore first), never auto-stashed.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "branch" : {
            "description" : "Branch to switch to (or to create with create:true).",
            "type" : "string"
          },
          "create" : {
            "description" : "Create the branch first (git switch -c). Default false.",
            "type" : "boolean"
          },
          "ref" : {
            "description" : "Commit, tag or branch to create the new branch from (with create:true). Default: the current HEAD.",
            "type" : "string"
          }
        },
        "required" : [ "branch" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "execution",
      "idePrecedent" : "git switch / Checkout Branch",
      "orchestrationRules" : [ "Switch to an existing branch, or create:true to branch from HEAD (or ref) and switch. Branch BEFORE committing onto the default branch. A refusal names its route in nextStep - this tool never auto-stashes." ]
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_git_merge",
      "description" : "Reports status and outcome (already-up-to-date, fast-forward, clean-merge or conflict), newSha/previousSha, commitsMerged, changedFiles and conflictFiles; a conflicting merge aborts with the tree restored.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "branch" : {
            "description" : "The local branch to merge into the current branch.",
            "type" : "string"
          },
          "dryRun" : {
            "description" : "Predict the outcome, the changed and the conflicting files without merging. Default false.",
            "type" : "boolean"
          },
          "message" : {
            "description" : "Merge-commit message. Default: git's own.",
            "type" : "string"
          },
          "mode" : {
            "description" : "Default auto (fast-forward when possible, else a merge commit); merge-commit always records one (--no-ff); ff-only refuses when a merge commit would be needed.",
            "enum" : [ "auto", "merge-commit", "ff-only" ],
            "type" : "string"
          },
          "noFastForward" : {
            "description" : "IDE alias of mode:'merge-commit'.",
            "type" : "boolean"
          }
        },
        "required" : [ "branch" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "execution",
      "idePrecedent" : "git merge / Merge Branch",
      "orchestrationRules" : [ "Merges a LOCAL branch (the remote is ek9_git_pull mode:'merge'). Requires a clean tree; a conflicting merge auto-aborts and restores it, so run dryRun:true first and resolve conflicts on a branch." ]
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_git_restore",
      "description" : "Reports mode, paths and pathCount and a summary line; ref restores content from that commit instead of the index or HEAD.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "mode" : {
            "description" : "Default unstage (take out of the index, keep the working-tree edits); discard (overwrite the working-tree edits - DESTRUCTIVE); both.",
            "enum" : [ "unstage", "discard", "both" ],
            "type" : "string"
          },
          "paths" : {
            "description" : "Workspace-relative paths to restore.",
            "items" : {
              "type" : "string"
            },
            "type" : "array"
          },
          "ref" : {
            "description" : "Commit to restore content from. Default: the index for discard, HEAD for unstage.",
            "type" : "string"
          },
          "staged" : {
            "description" : "IDE alias: true means mode:'unstage'.",
            "type" : "boolean"
          },
          "worktree" : {
            "description" : "IDE alias: true means mode:'discard' (with staged:true, mode:'both').",
            "type" : "boolean"
          }
        },
        "required" : [ "paths" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "execution",
      "idePrecedent" : "git restore / Revert / Unstage",
      "orchestrationRules" : [ "Unstage with mode:'unstage' (safe - working tree untouched). Discard working-tree edits with mode:'discard' (DESTRUCTIVE, uncommitted changes are lost). The inverse of ek9_git_add." ]
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_git_revert",
      "description" : "Reports newSha, revertedSha, previousSha, branch, subject, changedFiles and changedFileCount; a conflicting revert aborts with the tree restored.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "mainline" : {
            "description" : "For a merge commit only: the parent number to keep (usually 1). Omit for an ordinary commit.",
            "type" : "integer"
          },
          "ref" : {
            "description" : "The commit to revert - a short or full sha, HEAD, a tag or any ref.",
            "type" : "string"
          }
        },
        "required" : [ "ref" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "execution",
      "idePrecedent" : "git revert / Revert Commit",
      "orchestrationRules" : [ "Revert is the push-safe undo: a NEW inverse commit, no history rewrite. On a conflict it auto-aborts and restores the tree - resolve by hand. To revert a merge commit pass mainline." ]
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_git_fetch",
      "description" : "Reports updated, upstream, behind and ahead, a summary line and a nextStep when behind; git's own report under gitReport.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "allRemotes" : {
            "description" : "Fetch every remote (--all) instead of one. Default false.",
            "type" : "boolean"
          },
          "prune" : {
            "description" : "Drop remote-tracking refs deleted on the remote (--prune). Default false.",
            "type" : "boolean"
          },
          "remote" : {
            "description" : "Remote name. Default origin.",
            "type" : "string"
          }
        },
        "required" : [ ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "execution",
      "idePrecedent" : "git fetch / Fetch",
      "orchestrationRules" : [ "Fetch never touches the working tree - it is the 'how far behind am I?' check. behind > 0 means ek9_git_pull has work to do." ]
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_git_pull",
      "description" : "Reports commitsPulled, newSha and previousSha, changedFiles and changedFileCount; a dirty tree is refused and a rebase/merge conflict is aborted with the tree restored.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "mode" : {
            "description" : "How to integrate. Default ff-only (advance the pointer only, never conflicts); rebase (linear, rewrites local shas); merge (records a merge commit).",
            "enum" : [ "ff-only", "rebase", "merge" ],
            "type" : "string"
          },
          "remote" : {
            "description" : "Remote name. Default origin.",
            "type" : "string"
          }
        },
        "required" : [ ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "execution",
      "idePrecedent" : "git pull / Update Project",
      "orchestrationRules" : [ "Default mode:'ff-only' cannot conflict; on divergence it is refused and you choose mode:'rebase' or mode:'merge'. Requires a clean tree; conflicts auto-abort and restore it." ]
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_git_stash",
      "description" : "Reports status (stashed, popped, applied, dropped or nothing-to-stash) and the stash ref; mode:'list' returns stashCount and stashes; a conflicting pop keeps the entry (stashPreserved:true).",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "includeUntracked" : {
            "description" : "Also stash untracked files (push only). Default false.",
            "type" : "boolean"
          },
          "index" : {
            "description" : "Entry for pop/apply/drop, as in stash@{N}. Default 0 (the most recent).",
            "type" : "integer"
          },
          "message" : {
            "description" : "Label for the entry (push only).",
            "type" : "string"
          },
          "mode" : {
            "description" : "push (park the changes), pop (restore and remove), apply (restore and keep), list, drop (delete an entry).",
            "enum" : [ "push", "pop", "apply", "list", "drop" ],
            "type" : "string"
          }
        },
        "required" : [ "mode" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "execution",
      "idePrecedent" : "git stash / Stash Changes",
      "orchestrationRules" : [ "Explicit stash only, never auto-stash. A conflicting pop/apply PRESERVES the entry (stashPreserved:true) - resolve by hand and retry." ]
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_package",
      "description" : "Answers with bundlePath and checksumPath after assembling the publishable SOURCE bundle (.ek9 files + manifest + capabilities, not bytecode) of one package.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "file" : {
            "description" : "The .ek9 file holding the 'defines package' block, workspace-relative (typically 'package.ek9'); an absolute path inside the workspace is accepted.",
            "type" : "string"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Response size. The default answers with status, summary, bundlePath and checksumPath; 'full' adds the CLI's stdout, argv, exitCode, elapsedMs and timedOut.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ "file" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "execution",
      "idePrecedent" : "mvn package / cargo build --release / npm pack",
      "workflows" : [ "release" ]
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_install_package",
      "description" : "Answers with installedTo (under ~/.ek9/lib) and bundlePath after packaging one package and installing its SOURCE bundle into the LOCAL library cache - not a remote registry push.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "file" : {
            "description" : "The .ek9 file holding the 'defines package' block, workspace-relative (typically 'package.ek9'); an absolute path inside the workspace is accepted.",
            "type" : "string"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Response size. The default answers with status, summary, bundlePath and installedTo; 'full' adds the CLI's stdout, argv, exitCode, elapsedMs and timedOut.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ "file" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "execution",
      "idePrecedent" : "mvn install / cargo install / npm install",
      "workflows" : [ "release" ]
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_deploy_package",
      "description" : "Answers with status and bundlePath after packaging one package's SOURCE bundle, generating missing signing keys, and signing it locally; there is no remote repository to push to yet, so nothing leaves this machine.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "confirm" : {
            "description" : "Must be true: acknowledges this is the release step. Kept as a guard because the push, once a secure repository exists to push to, will make the package visible to every consumer and hard to retract; today's run never leaves this machine.",
            "type" : "boolean"
          },
          "file" : {
            "description" : "The .ek9 file holding the 'defines package' block, workspace-relative (typically 'package.ek9'); an absolute path inside the workspace is accepted.",
            "type" : "string"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Response size. The default answers with status, summary and bundlePath; 'full' adds the CLI's stdout, argv, exitCode, elapsedMs and timedOut.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ "file", "confirm" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "execution",
      "idePrecedent" : "mvn deploy / cargo publish / npm publish",
      "workflows" : [ "release" ]
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_generate_signing_keys",
      "description" : "Answers with keysGenerated and publicKeyPath after ensuring the user-global signing keypair (~/.ek9/private.pem + public.pem) that ek9_deploy_package signs with exists; an existing pair is never overwritten.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "verbosity" : {
            "default" : "full",
            "description" : "Response size. The default answers with status, summary, keysGenerated and publicKeyPath; 'full' adds the CLI's stdout, argv, exitCode, elapsedMs and timedOut.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "execution",
      "idePrecedent" : "gpg --gen-key / ssh-keygen"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_set_version",
      "description" : "Answers with the new version and previousVersion after setting the 'defines package' version literal to an explicit MAJOR.MINOR.PATCH (build restarts at 0), plus written and line.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "file" : {
            "description" : "The .ek9 file holding the 'defines package' block, workspace-relative (typically 'package.ek9'); an absolute path inside the workspace is accepted.",
            "type" : "string"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Response size. The default answers with status, summary, version, previousVersion, written and line; 'full' adds the CLI's argv, exitCode, elapsedMs and timedOut.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          },
          "version" : {
            "description" : "The new MAJOR.MINOR.PATCH literal, e.g. '1.2.3' - no build suffix (the build restarts at 0).",
            "type" : "string"
          }
        },
        "required" : [ "file", "version" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "execution",
      "idePrecedent" : "mvn versions:set / npm version <new>"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_set_feature_version",
      "description" : "Answers with the new version and previousVersion after setting the 'defines package' version literal to MAJOR.MINOR.PATCH-feature (build restarts at 0), plus written and line.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "file" : {
            "description" : "The .ek9 file holding the 'defines package' block, workspace-relative (typically 'package.ek9'); an absolute path inside the workspace is accepted.",
            "type" : "string"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Response size. The default answers with status, summary, version, previousVersion, written and line; 'full' adds the CLI's argv, exitCode, elapsedMs and timedOut.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          },
          "version" : {
            "description" : "The MAJOR.MINOR.PATCH-FEATURE literal, e.g. '1.0.0-alpha' or '2.1.0-rc1'; a bare tag such as 'alpha' is prefixed with the file's current MAJOR.MINOR.PATCH. The tag is letters then letters/digits.",
            "type" : "string"
          }
        },
        "required" : [ "file", "version" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "execution",
      "idePrecedent" : "mvn versions:set with classifier"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_increment_version",
      "description" : "Answers with the new version and previousVersion after bumping one component of the 'defines package' version literal, plus written and line.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "component" : {
            "default" : "patch",
            "description" : "Which component to increment; the lower ones reset to 0.",
            "enum" : [ "major", "minor", "patch", "build" ],
            "type" : "string"
          },
          "file" : {
            "description" : "The .ek9 file holding the 'defines package' block, workspace-relative (typically 'package.ek9'); an absolute path inside the workspace is accepted.",
            "type" : "string"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Response size. The default answers with status, summary, version, previousVersion, written and line; 'full' adds the CLI's argv, exitCode, elapsedMs and timedOut.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ "file" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "execution",
      "idePrecedent" : "npm version patch / mvn versions:set",
      "workflows" : [ "release" ]
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_resolve_dependencies",
      "description" : "Answers with status after resolving one package's declared dependency tree (ek9 -Dp), which cleans all build artefacts and the project's dependency copy (.ek9/deps/) first, then rewrites ek9.lock.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "confirm" : {
            "description" : "Must be true: acknowledges that every build artefact and the project's dependency copy (.ek9/deps/) are deleted before re-resolving.",
            "type" : "boolean"
          },
          "file" : {
            "description" : "The .ek9 file holding the 'defines package' block, workspace-relative (typically 'package.ek9'); an absolute path inside the workspace is accepted.",
            "type" : "string"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Response size. The default answers with status and summary; 'full' adds the CLI's stdout, argv, exitCode, elapsedMs and timedOut.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          }
        },
        "required" : [ "file", "confirm" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "execution",
      "idePrecedent" : "mvn dependency:resolve / cargo fetch / npm install (resolve)",
      "workflows" : [ "release" ]
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_run_program",
      "description" : "Answers with programStdout, programStderr and programExitCode after compiling one .ek9 file and running the program it declares, with string args auto-parsed into the program's typed parameters; exitedBy says whether an exit code is the program's own or the EK9 CLI's.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "args" : {
            "description" : "Positional arguments passed to the running program, as strings; the runtime parses each into the declared parameter type.",
            "items" : {
              "type" : "string"
            },
            "type" : "array"
          },
          "env" : {
            "additionalProperties" : {
              "type" : [ "string", "null" ]
            },
            "description" : "Environment variables for the program's process (stage 2), merged onto the inherited shell environment; a null value unsets the variable. Pass resolved values - no ${VAR} expansion is done. Never applied to the compiler (stage 1).",
            "type" : "object"
          },
          "file" : {
            "description" : "The .ek9 file declaring the program, workspace-relative (an absolute path inside the workspace is accepted).",
            "type" : "string"
          },
          "programName" : {
            "description" : "Which program to run when the file declares several (the CLI's -r); a file with one program needs none.",
            "type" : "string"
          },
          "timeoutSeconds" : {
            "description" : "Wall-clock limit before the program is killed. Default 120.",
            "type" : "integer"
          },
          "verbosity" : {
            "default" : "full",
            "description" : "Response size. The default answers with status, summary, exitedBy, programStdout, programStderr and programExitCode (compileExitCode when the compile stage fails); 'full' adds the compile stage's stdout and both stages' argv, exit codes and elapsed times.",
            "enum" : [ "full", "summary", "none" ],
            "type" : "string"
          },
          "withDebug" : {
            "description" : "Default false. True runs the program with the JDWP debug agent attached (the CLI's -dr) so a debugger can connect.",
            "type" : "boolean"
          },
          "workingDir" : {
            "description" : "Working directory for the program's process (stage 2). Default: the server's own cwd.",
            "type" : "string"
          }
        },
        "required" : [ "file" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "execution",
      "idePrecedent" : "Run (IntelliJ) / cargo run / java -jar"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_debug_session",
      "description" : "Runs a program under the debugger - several inputs at once with a change journal (sweep), one run to its end, or step by step - and reports, waits on or ends THE debug session (one per server); answers status, runState, sequence, the stops, breakpoints and nextStep.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "action" : {
            "default" : "status",
            "description" : "launch a new session, report it, wait for it to change, or end it; sweep runs the program once per input set and compares the runs.",
            "enum" : [ "launch", "status", "wait", "terminate", "sweep" ],
            "type" : "string"
          },
          "args" : {
            "description" : "launch: the program's arguments, as strings, one per parameter; a count that does not fit is refused, naming the parameters.",
            "items" : {
              "type" : "string"
            },
            "type" : "array"
          },
          "breakpoints" : {
            "description" : "EK9 source lines, each {file:'main.ek9', line:12}; the file is its path from projectDir ('orders/main.ek9'), or just its name when only one source has it.",
            "items" : {
              "properties" : {
                "file" : {
                  "description" : "the .ek9 file: its path from projectDir, or its name when unique",
                  "type" : "string"
                },
                "line" : {
                  "description" : "the 1-based line",
                  "type" : "integer"
                }
              },
              "required" : [ "file", "line" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "env" : {
            "additionalProperties" : {
              "type" : "string"
            },
            "description" : "launch: environment variables for the debuggee only.",
            "type" : "object"
          },
          "failing" : {
            "description" : "sweep: what makes a run a failing one (default uncaught: an Exception or Panic the program did not catch; changeCheck: its journal.changeCheck broke) - as compare judges it.",
            "enum" : [ "uncaught", "anySymptom", "exitCode", "changeCheck" ],
            "type" : "string"
          },
          "inputs" : {
            "description" : "sweep: the input sets, each the program's arguments as strings, one per parameter - every set is checked against the program before any run starts.",
            "items" : {
              "items" : {
                "type" : "string"
              },
              "type" : "array"
            },
            "type" : "array"
          },
          "journal" : {
            "additionalProperties" : false,
            "description" : "launch, sweep: record every change to this property, on every instance, from the start of the run - before, after, the line and the EK9 stack that made it - into .ek9/debug-journal/<runId>.jsonl, never stopping the program. Caught at every line the compiler says can change it (ek9_query_references' writeSites); a store from any other line is recorded too, marked gap (gapNet). A line stops being journalled after siteCap hits (a capped row; capped in the answers), so a hot loop cannot use up the run's time. The answers carry journal:{file, changes, gaps, bySite, byRoute, missed}. Every row has a tick: cite the ticks of the rows that show each claim you make, and never infer a value from the code alone.",
            "properties" : {
              "calls" : {
                "description" : "functions or Type.methods whose EVERY call is logged: a call row when it starts (its arguments, who called it) and a return row naming that call's tick (what it returned); a call that throws has no return row. calls counts each, 0 if never run.",
                "items" : {
                  "type" : "string"
                },
                "type" : "array"
              },
              "changeCheck" : {
                "description" : "a condition that should hold after every change, as firstWhere takes it: 'total >= 0', 'total <= before.total + 100'. A change that breaks it is a symptom AT that change (cause changeCheck, atChange its tick), once per break for each object; changes while it stays broken are counted (stillBroken). Never a stop.",
                "type" : "string"
              },
              "gapNet" : {
                "default" : "on",
                "description" : "on: a store to the property from a line the analysis did not list is caught too, marked gap - a breakpoint on each such store, costing nothing until one runs. off: only the listed lines; every answer then says a store elsewhere is not seen.",
                "enum" : [ "on", "off" ],
                "type" : "string"
              },
              "hypothesis" : {
                "description" : "REQUIRED: what this run is to confirm or refute, in a sentence - it is written into the run row, so the evidence and the reason for gathering it stay together.",
                "type" : "string"
              },
              "properties" : {
                "description" : "several properties to journal in one run (at most 5), each Type.property; every change row names its property. Use it when the failure may come from how two values move together.",
                "items" : {
                  "type" : "string"
                },
                "maxItems" : 5,
                "type" : "array"
              },
              "property" : {
                "description" : "Type.property (or module::Type.property) to journal.",
                "type" : "string"
              },
              "siteCap" : {
                "description" : "how many times one line is journalled before it stops being (default 1000; 0 for no cap) - each hit costs about a millisecond, changed or not. Lower it for long runs and sweeps; raise it, or 0, to catch a change late in a long loop. A capped row and capped in the answers say where and when.",
                "minimum" : 0,
                "type" : "integer"
              },
              "stackArgs" : {
                "additionalProperties" : false,
                "description" : "argument values on each row's stack.",
                "properties" : {
                  "frames" : {
                    "description" : "how many of the top frames carry their argument values (default 3; 0 for callables and lines only).",
                    "type" : "integer"
                  }
                },
                "type" : "object"
              },
              "stackDepth" : {
                "description" : "how many of the innermost EK9 frames each row keeps (default 5): what got to the change, not the way in from the entry; a row cut short says outerFrames and its route starts '… ->'.",
                "type" : "integer"
              },
              "symptoms" : {
                "description" : "lines where the failure shows: reaching one writes a symptom row with the watched values its frame can see and the last change to each; never a stop. Every EK9 Exception and Panic is a symptom too.",
                "items" : {
                  "properties" : {
                    "file" : {
                      "type" : "string"
                    },
                    "line" : {
                      "type" : "integer"
                    }
                  },
                  "required" : [ "file", "line" ],
                  "type" : "object"
                },
                "type" : "array"
              }
            },
            "required" : [ "hypothesis" ],
            "type" : "object"
          },
          "maxThreads" : {
            "description" : "launch: the debug thread cap - at most this many task threads alive (default 64).",
            "type" : "integer"
          },
          "program" : {
            "description" : "launch: module::Program (or a bare name only one program has) when the project declares several; a program that is not there is refused, listing the programs.",
            "type" : "string"
          },
          "projectDir" : {
            "description" : "Project root holding the .ek9 sources - absolute, or relative to the workspace root. Omit to use the workspace root itself (the first root ek9_compile was given).",
            "type" : "string"
          },
          "run" : {
            "description" : "launch: 'toEnd' starts it and answers once - when the program has ended (with the journal's counts and, if something failed, its leadingTo account), when a breakpoint of yours stops it, or at timeoutMs. Exceptions do not stop it unless stopOnExceptions is given; a journal records them as symptoms.",
            "enum" : [ "toEnd" ],
            "type" : "string"
          },
          "seed" : {
            "description" : "launch, sweep: the random seed the program's SystemRandom and OS.random draw from, so a run can be repeated exactly (a sweep gives every set the same one). Left out, one is chosen; every answer says which (seed), and a journal records it as an input row. To check a cause, launch again with the same seed and the suspected input changed.",
            "type" : "integer"
          },
          "since" : {
            "description" : "wait: the sequence to wait past (default: the last one a debug tool answered, so a stop that landed before the wait arrived is answered at once).",
            "type" : "integer"
          },
          "stopOnExceptions" : {
            "default" : "uncaught",
            "description" : "launch: stop on an EK9 Exception or Panic where it is thrown - only when nothing in the program catches it, every one, or none.",
            "enum" : [ "none", "uncaught", "all" ],
            "type" : "string"
          },
          "timeoutMs" : {
            "description" : "wait: how long to wait (default 30000, at most 100000); launch with run: and sweep, for every run together (default and at most 100000). Counted from when the call reached the server.",
            "type" : "integer"
          },
          "until" : {
            "default" : "all",
            "description" : "sweep: run every set, or stop after the first failing run.",
            "enum" : [ "all", "firstFailure" ],
            "type" : "string"
          }
        },
        "required" : [ ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "execution",
      "idePrecedent" : "Debug (IntelliJ) / VS Code launch.json / gdb run",
      "workflows" : [ "investigate_runtime_defect" ]
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_debug_control",
      "description" : "Continues, pauses, steps or sets breakpoints in the current debug session; answers its new runState, sequence and stops.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "action" : {
            "description" : "what to do.",
            "enum" : [ "continue", "pause", "stepOver", "stepInto", "stepOut", "setBreakpoints", "setDataBreakpoint", "clearDataBreakpoint", "sendInput", "endInput", "runTo", "setExceptionBreakpoints" ],
            "type" : "string"
          },
          "breakpoints" : {
            "description" : "setBreakpoints: breakpoints that say when they stop, with lines: {line, condition?, hitCondition?: {op, count}, logMessage?}.",
            "items" : {
              "type" : "object"
            },
            "type" : "array"
          },
          "file" : {
            "description" : "setBreakpoints: the .ek9 file - its path from projectDir, or its name when unique.",
            "type" : "string"
          },
          "frameId" : {
            "description" : "setDataBreakpoint: the frame the path is read in (default: the top frame).",
            "type" : "integer"
          },
          "id" : {
            "description" : "clearDataBreakpoint: the data breakpoint's id.",
            "type" : "integer"
          },
          "line" : {
            "description" : "runTo: the line to run on to (with file).",
            "type" : "integer"
          },
          "lines" : {
            "description" : "setBreakpoints: every line to break on in that file (empty clears them).",
            "items" : {
              "type" : "integer"
            },
            "type" : "array"
          },
          "path" : {
            "description" : "setDataBreakpoint: the value to watch, read in the stopped frame: total, rex, names.",
            "type" : "string"
          },
          "stopOn" : {
            "description" : "setExceptionBreakpoints: stop on an EK9 Exception or Panic where it is thrown - only when nothing in the program catches it (the launch default), every one, or none.",
            "enum" : [ "none", "uncaught", "all" ],
            "type" : "string"
          },
          "text" : {
            "description" : "sendInput: what the program reads from stdin; a line ends with \\n, added when missing.",
            "type" : "string"
          },
          "threadId" : {
            "description" : "the stopped thread to act on (default: the most recent stop).",
            "type" : "integer"
          }
        },
        "required" : [ "action" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "execution",
      "idePrecedent" : "Resume / Pause / Step Over / Step Into / Step Out / Toggle Breakpoint (IntelliJ)"
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_debug_inspect",
      "description" : "Reads what runs recorded - a failure's account, where a value first went wrong, failing and passing runs compared, a report to share - and the current debug session by field (the recorded stop, a frame's locals, path values, the threads), never running the debuggee.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "action" : {
            "default" : "stop",
            "description" : "what to read; leadingTo, firstWhere, history, routes and slice reduce the run's change journal (history: every change to ONE object, named by its #N), compare (and routes with runs) several runs' journals; report writes those runs as a page to hand a person (index.html, and report.json with the same facts).",
            "enum" : [ "stop", "locals", "evaluate", "threads", "leadingTo", "firstWhere", "history", "routes", "slice", "compare", "report" ],
            "type" : "string"
          },
          "condition" : {
            "description" : "firstWhere: when the value is wrong, as a breakpoint condition: 'total < 0', 'not total?', 'total > 100 and before.total <= 100'; the property's name is its value after a change, before.<name> before it.",
            "type" : "string"
          },
          "failing" : {
            "description" : "compare, report: what makes a run a failing one (default uncaught: an Exception or Panic the program did not catch; changeCheck: its journal.changeCheck broke).",
            "enum" : [ "uncaught", "anySymptom", "exitCode", "changeCheck" ],
            "type" : "string"
          },
          "finding" : {
            "description" : "report: your conclusion - the cause and the fix - citing ticks (t5) and lines (Orders.ek9:36); shown as yours in the report's Finding, which the report never writes itself (default: none).",
            "type" : "string"
          },
          "frameId" : {
            "description" : "locals / evaluate: a frame id from a stop's frames; locals also takes a value's 'reference' and lists what it holds (a List's items, a Dict's values, an object's fields).",
            "type" : "integer"
          },
          "from" : {
            "description" : "history, slice: the first tick to include.",
            "type" : "integer"
          },
          "hypothesis" : {
            "description" : "leadingTo, firstWhere, history, routes, slice, compare: REQUIRED - what you expect the answer to confirm or refute, in a sentence; it is kept with the question.",
            "type" : "string"
          },
          "limit" : {
            "description" : "leadingTo, history (compare: how many differences; routes: how many routes; slice: how many rows, the first): how many change steps to show, the most recent (default 40); the rest are counted in envelope.",
            "type" : "integer"
          },
          "object" : {
            "description" : "history (required): whose changes to list - an object's identity #N as an earlier answer shows it, e.g. #4 from leadingTo's 't2 change #4.total 0 -> 100' (the owner) or a value's identity; the values one property took are its owner's changes to it.",
            "type" : "string"
          },
          "paths" : {
            "description" : "evaluate: paths such as 'total', 'rex.legs', 'names[0]', 'scores[\"bob\"]', 'total?'.",
            "items" : {
              "type" : "string"
            },
            "type" : "array"
          },
          "projectDir" : {
            "description" : "leadingTo, firstWhere, history, routes, slice, compare: the project whose journals to read (default: the session's) - absolute, or relative to the workspace root. With it they answer after terminate, and in a server that never ran the session.",
            "type" : "string"
          },
          "property" : {
            "description" : "routes: one of the watched properties, by field ('total') or 'Type.field' (default: every one, each route tagged with its own).",
            "type" : "string"
          },
          "runId" : {
            "description" : "leadingTo, firstWhere, history, routes, slice: another run's journal in the same project (default: the current session's run, or with projectDir and no session there, the most recent run).",
            "type" : "string"
          },
          "runs" : {
            "description" : "compare, report: the run ids (default: the most recent 20 runs in this project journalling the same property of the same program); routes: the runs to count each route across (default: the one run).",
            "items" : {
              "type" : "string"
            },
            "type" : "array"
          },
          "symptom" : {
            "description" : "leadingTo: the tick of the symptom to explain (default: the first uncaught exception, else the last symptom); the answer lists the others.",
            "type" : "integer"
          },
          "to" : {
            "description" : "history: the last tick to include; slice: the tick to stop BEFORE (required).",
            "type" : "integer"
          }
        },
        "required" : [ ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "execution",
      "idePrecedent" : "Variables / Watches / Frames / Threads panes (IntelliJ)",
      "workflows" : [ "investigate_runtime_defect" ]
    }
  }, {
    "type" : "function",
    "function" : {
      "name" : "ek9_debug_observe",
      "description" : "Runs the current debug session until a condition holds or the budget bites, reading the watched paths at every hit of the given lines; answers stoppedBecause, exact hits and the rows.",
      "parameters" : {
        "additionalProperties" : false,
        "properties" : {
          "budget" : {
            "description" : "required: {maxHits, maxWallClockMs} (maxWallClockMs at most 95000).",
            "properties" : {
              "maxHits" : {
                "type" : "integer"
              },
              "maxWallClockMs" : {
                "type" : "integer"
              }
            },
            "required" : [ "maxHits", "maxWallClockMs" ],
            "type" : "object"
          },
          "changesOf" : {
            "description" : "paths read where the program is stopped now ('total', 'counter'): every change to each is recorded - before, after, the line that made it, the thread - and never stops. With changesOf, points may be empty; the observation then ends with the budget or the program.",
            "items" : {
              "type" : "string"
            },
            "type" : "array"
          },
          "format" : {
            "default" : "compact",
            "description" : "compact: each row is {tick, values:[...]} in watch order, with what every row shares said once (a path unreadable at every hit is in 'unreadable' and 'absent' in the rows, one unreadable at some hits is {error}); records: each row is the full runtime-journal record (SPEC 3.2) with isSet and the object identity #N of every value, or {path, error} for a path it could not read.",
            "enum" : [ "compact", "records" ],
            "type" : "string"
          },
          "keep" : {
            "description" : "how many of the first and last hits keep their values (default {first:10, last:10}, each at most 100); hits stays exact whatever is kept.",
            "properties" : {
              "first" : {
                "type" : "integer"
              },
              "last" : {
                "type" : "integer"
              }
            },
            "type" : "object"
          },
          "points" : {
            "description" : "EK9 source lines, each {file:'main.ek9', line:12}; the file is its path from projectDir ('orders/main.ek9'), or just its name when only one source has it.",
            "items" : {
              "properties" : {
                "file" : {
                  "description" : "the .ek9 file: its path from projectDir, or its name when unique",
                  "type" : "string"
                },
                "line" : {
                  "description" : "the 1-based line",
                  "type" : "integer"
                }
              },
              "required" : [ "file", "line" ],
              "type" : "object"
            },
            "type" : "array"
          },
          "until" : {
            "description" : "optional - without it the observation runs until the budget bites or the program ends. {kind:'hits', count} or a condition: {kind:'comparison', path, op, literal} or {kind:'setCheck', path, negated}. literal is typed JSON: a number (100) for an Integer or Float, a string ('x') for a String or Character, true/false for a Boolean.",
            "type" : "object"
          },
          "watch" : {
            "description" : "paths to read at every hit: 'total', 'rex.legs', 'names[0]', 'scores[\"bob\"]', 'total?'.",
            "items" : {
              "type" : "string"
            },
            "type" : "array"
          }
        },
        "required" : [ "budget" ],
        "type" : "object"
      }
    },
    "x-ek9" : {
      "category" : "execution",
      "idePrecedent" : "Logpoints / tracepoints (IntelliJ, VS Code) with a stop condition"
    }
  } ],
  "workflows" : [ {
    "name" : "release",
    "summary" : "Bump version + run tests with coverage + build artefact + install locally + verify.",
    "sequence" : [ {
      "tool" : "ek9_increment_version",
      "reason" : "Bump the appropriate version part (typically patch after a fix)."
    }, {
      "tool" : "ek9_run_tests",
      "reason" : "Verify nothing regressed; produces the coverage report as a side effect."
    }, {
      "tool" : "ek9_run_quality_checks",
      "reason" : "Run full quality checks — coverage, complexity, readability, DI — to confirm nothing has degraded since the last release."
    }, {
      "tool" : "ek9_package",
      "reason" : "Build the deployable artefact at the new version."
    }, {
      "tool" : "ek9_install_package",
      "reason" : "Install into ~/.ek9/lib so sibling workspaces can pick it up."
    }, {
      "tool" : "ek9_query_package_version",
      "reason" : "Verify the installed version matches what was bumped."
    } ]
  }, {
    "name" : "feature_branch_start",
    "summary" : "Set feature-branch version + add new dependencies + resolve + verify.",
    "sequence" : [ {
      "tool" : "ek9_set_feature_version",
      "reason" : "Mark the package as on a feature branch (e.g. 2.1.0-PAYINTEG-0)."
    }, {
      "tool" : "ek9_add_dependency",
      "reason" : "Declare each new package dependency the feature requires."
    }, {
      "tool" : "ek9_resolve_dependencies",
      "reason" : "Pull the new dependencies into ~/.ek9/lib."
    }, {
      "tool" : "ek9_compile",
      "reason" : "Verify the package still compiles with the new deps."
    }, {
      "tool" : "ek9_run_tests",
      "reason" : "Verify existing tests still pass before any feature work begins."
    } ]
  }, {
    "name" : "investigate_build_failure",
    "summary" : "Diagnose dependency-resolution or compilation failure: diagnostics → tree → cycles → fix → re-resolve.",
    "sequence" : [ {
      "tool" : "ek9_query_diagnostics",
      "reason" : "Read the specific compiler/resolver error messages."
    }, {
      "tool" : "ek9_query_dependency_tree",
      "reason" : "See the resolved tree with version selections and any rejection reasons."
    }, {
      "tool" : "ek9_check_package_dependency_cycles",
      "reason" : "Rule out a transitive cycle in the published-package graph."
    }, {
      "tool" : "ek9_resolve_dependencies",
      "reason" : "Re-resolve after any fix to the package directive."
    }, {
      "tool" : "ek9_compile",
      "reason" : "Confirm the build now succeeds."
    } ]
  }, {
    "name" : "investigate_runtime_defect",
    "summary" : "A runtime failure whose cause is earlier: journal the value over failing AND passing runs -> compare -> leadingTo -> firstWhere -> confirm with one input changed -> report with a finding.",
    "sequence" : [ {
      "tool" : "ek9_debug_session",
      "reason" : "{action:'launch', run:'toEnd', args:<the failing input>}: reproduce the failure once - its message usually names the value that went wrong (a Panic on 'require total >= NOTHING' in Order.invoice -> watch Order.total)."
    }, {
      "tool" : "ek9_debug_session",
      "reason" : "{action:'sweep', inputs:[...], journal:{property:'Type.property', hypothesis}}: one run per input set, all with ONE seed. Include inputs you expect to PASS as well as the failing one - compare needs both; every change to the value, on every object, is recorded. Its answer already carries compare's top differences, and the investigation id."
    }, {
      "tool" : "ek9_debug_inspect",
      "reason" : "{action:'compare', runs, hypothesis}: what only the failing runs did - a step they took, a step they LEFT OUT (onlyInPassing), or none (then the values differ). A tie or thin evidence means more inputs, not a verdict. Cite each difference by its run and ticks."
    }, {
      "tool" : "ek9_debug_inspect",
      "reason" : "{action:'leadingTo', runId:<a failing run>, hypothesis}: the account - the changes that led to its failure, each with the line, the values and the calls that made it. Cite ticks for every claim."
    }, {
      "tool" : "ek9_debug_inspect",
      "reason" : "{action:'firstWhere', runId, condition:'total < 0', hypothesis}: the step where the value first went wrong - usually the line to fix."
    }, {
      "tool" : "ek9_debug_session",
      "reason" : "{action:'launch', run:'toEnd', seed:<the sweep's>, args:<one input changed>, journal}: confirm the suspect - the same run with only the suspect's input changed should pass. Without this, a difference is a suspect, not a cause."
    }, {
      "tool" : "ek9_debug_inspect",
      "reason" : "{action:'report', runs, hypothesis, finding:'cause and fix, citing t5 and Orders.ek9:36'}: write the investigation up for the person (index.html, report.json); the finding is shown as yours."
    } ]
  } ]
}