ek9_query_capability_usage

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.

Category: Enquiry · Compare: 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

When to use it

Which capabilities does the code actually need versus what the package block declares - one call, no arguments; underDeclared and overDeclared answer it. Capabilities are the gated types: network, filesystem, env-var, stdio, process, clock.

When not to use it

JUST the declared capabilities, not the actual-vs-declared comparison — use ek9_query_package.
Auditing secret-handling code (Sensitive.reveal callers), not capability usage — use ek9_query_sensitive_reveals. ('what env vars do I read?' is a CAPABILITY question, use THIS tool.)
You want the LIST of capability errors (use ek9_query_diagnostics) or one E12010 explained (use ek9_explain_error), not the full usage analysis.
You want method-level call relationships, not capability-level access — use ek9_query_call_graph.

Details

Capabilities are FQ gated-type names (org.ek9.lang::TCP / Stdout / File / EnvVars / OS / Clock …), NOT abstract kinds; the audit mirrors phase-5 CapabilityTypeReferenceOrError via the shared GatedTypeMapping, so underDeclared is EXACTLY the set that fires E12010 and overDeclared is declared-but-unused (leave-one-out, so alt-coverage like NetworkProperties covered by TCP/UDP is respected). The audit verdict applies ONLY when publishable:true (publicAccess + version + license + capabilities) — otherwise usage is informational, consistent is vacuously true and a note says so — and stays workspace-wide regardless of the filters, which narrow displayed call sites only. actualUsage is an OPEN map keyed by capability → {used, callSites[{site,file,line,column,type,module,inConstruct,inConstructFqn}]}; needs a compile reaching types_resolved (unresolved types are silently not counted); remediate via ek9_add_capability / ek9_remove_capability.

Arguments

Argument	Type	Required	What it is
`capability`	string		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.
`moduleFilter`	array of string		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.

Recorded calls

Real calls, recorded against small projects and checked on every build - a changed answer fails it. 3 of the 6 recorded are shown.

Capability filter no match

Request

{
  "capability" : "org.ek9.lang::TCP"
}

Response

{
  "actualUsage" : {
    "org.ek9.lang::TCP" : {
      "callSites" : [ ],
      "used" : false
    }
  },
  "consistent" : true,
  "declaredCapabilities" : [ "org.ek9.lang::Stdout" ],
  "findings" : [ ],
  "meta" : {
    "serverMs" : "<timing>"
  },
  "overDeclared" : [ ],
  "publishable" : true,
  "status" : "ok",
  "underDeclared" : [ ],
  "usedCapabilities" : [ ]
}

Consistent

Request

{ }

Response

{
  "actualUsage" : {
    "org.ek9.lang::Stdout" : {
      "callSites" : [ {
        "column" : 16,
        "file" : "package.ek9",
        "inConstruct" : "greet",
        "inConstructFqn" : "com.example.audit::greet",
        "line" : 13,
        "module" : "com.example.audit",
        "site" : "package.ek9:13",
        "type" : "Stdout"
      } ],
      "used" : true
    }
  },
  "consistent" : true,
  "declaredCapabilities" : [ "org.ek9.lang::Stdout" ],
  "findings" : [ ],
  "meta" : {
    "serverMs" : "<timing>"
  },
  "overDeclared" : [ ],
  "publishable" : true,
...

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

Capability filter

Request

{
  "capability" : "org.ek9.lang::Stderr"
}

Response

{
  "actualUsage" : {
    "org.ek9.lang::Stderr" : {
      "callSites" : [ ],
      "used" : false
    }
  },
  "consistent" : false,
  "declaredCapabilities" : [ "org.ek9.lang::Stderr", "org.ek9.lang::Stdout" ],
  "findings" : [ {
    "capability" : "org.ek9.lang::Stderr",
    "kind" : "overDeclared",
    "message" : "Capability 'org.ek9.lang::Stderr' is declared but no code uses a type that requires it. Unnecessary attack surface — candidate for removal via ek9_remove_capability."
  } ],
  "meta" : {
    "serverMs" : "<timing>"
  },
  "overDeclared" : [ "org.ek9.lang::Stderr" ],
  "publishable" : true,
  "status" : "ok",
  "underDeclared" : [ ],
  "usedCapabilities" : [ ]
}

When to use it

When not to use it

Details

Arguments

Recorded calls

Capability filter no match

Consistent

Capability filter

See also