@spec all_ns(PtcRunner.Lisp.Prelude.t() | nil) :: {:ok, [String.t()]}

Sorted list of curated Lisp-facing namespace-name strings (plan §8), with the attached prelude's declared namespaces merged in. Never leaks BEAM internals, Java classes, or implementation-only namespaces.

@spec apropos(term(), map()) :: {:ok, [String.t()]} | {:programmer_fault, String.t()}

Returns rendered local apropos lines.

@spec apropos_matches(String.t(), map()) :: [map()]

Returns structured local apropos matches for unified MCP/local ordering.

@spec curated_namespaces() :: [String.t()]

Curated Lisp-facing namespace-name strings exposed by (all-ns) without an attached prelude.

@spec dir(term(), map()) ::
  {:ok, [String.t()]} | :unknown | {:programmer_fault, String.t()}

Lists members for a known local namespace or curated Java class.

@spec doc(term()) :: {:ok, String.t()} | :unknown | {:programmer_fault, String.t()}

Returns human-readable docs for a known local function or Java interop ref.

@spec meta(term()) :: {:ok, map()} | :unknown | {:programmer_fault, String.t()}

Returns compact metadata for a known local function or Java interop ref.

@spec ns_name(PtcRunner.Lisp.Prelude.t() | nil, term()) ::
  {:ok, String.t()} | :unknown | {:programmer_fault, String.t()}

Returns the namespace-name string for a known namespace ref (a curated Lisp-facing namespace or a prelude-declared namespace), or :unknown.

@spec ns_publics(term()) :: {:ok, map()} | :unknown | {:programmer_fault, String.t()}

Returns public vars for local Clojure/PTC namespaces only.

@spec prelude_apropos_matches(PtcRunner.Lisp.Prelude.t() | nil, String.t()) :: [map()]

Structured prelude apropos matches (@prelude_source_rank) for unified ordering. Scored over each public export's ref/symbol/doc/namespace.

@spec prelude_dir(PtcRunner.Lisp.Prelude.t() | nil, term(), map()) ::
  {:ok, [String.t()]} | :unknown | {:programmer_fault, String.t()}

dir-style member lines for a prelude namespace, or :unknown when ref is not a declared prelude namespace. Honors the same :limit/:offset pagination opts as the local/MCP dir paths.

@spec prelude_doc(PtcRunner.Lisp.Prelude.t() | nil, term()) ::
  {:ok, String.t()} | :unknown | {:programmer_fault, String.t()}

Human-readable docs for an exact prelude export ref (e.g. "crm/get-user"), or :unknown when there is no such public export.

@spec prelude_meta(PtcRunner.Lisp.Prelude.t() | nil, term()) ::
  {:ok, map()} | :unknown | {:programmer_fault, String.t()}

Compact metadata map for an exact prelude export ref, or :unknown.

@spec prelude_ns_publics(PtcRunner.Lisp.Prelude.t() | nil, term()) ::
  {:ok, map()} | :unknown | {:programmer_fault, String.t()}

Public exports of a prelude namespace as a {symbol-string => meta} map, or :unknown when ref is not a declared prelude namespace.

@spec prelude_source(PtcRunner.Lisp.Prelude.t() | nil, term()) ::
  {:ok, String.t()} | :unknown | {:programmer_fault, String.t()}

Rendered defining-form source for an exact prelude ref (e.g. "crm/get-user"), or :unknown when the ref is not in the prelude's source_index.

Resolves ONLY against the attached prelude — unlike prelude_doc/prelude_meta there is no local/MCP fallthrough (plan D2). The index covers public exports plus the private helpers transitively reachable from a public export, so a reachable defn- helper is source-visible even though it has no %Export{} (and so stays invisible to doc/meta/ns-publics/apropos).

@spec reserved_namespace_names() :: [String.t()]

Namespace-like names reserved by local discovery.

Prelude stores use this to reject candidate ids that would collide with built-in Clojure/JSON namespaces or curated Java interop aliases, including names that are intentionally omitted from (all-ns).

@spec score_tokens([String.t()], [String.t()], integer()) :: integer()

Shared lexical token scoring. Exact matches outrank prefixes; prefixes outrank substrings. No regex matching is used for search.

@spec sort_matches([map()]) :: [map()]

Sorts unified discovery matches.