release: ship capability-gated install for embedders

Phase 1 of the lean-embed cycle: introduce a capability-gated install
API so hosts opt into exactly the surface they need without changing
what a mino_install_core-equipped runtime exposes to user Clojure.

New surface:

- mino_install_minimal: floor (reader, evaluator, GC, persistent
  collections, numeric ops, basic seq, foundational macros). No
  core.clj eval.
- mino_install_regex / _bignum / _multimethods / _protocols /
  _transducers: each flips its capability bit and (for the C-backed
  ones) registers prims into clojure.core.
- mino_install_clojure_core: evaluates core.clj against whatever
  capability bits the host has flipped. Optional sections are wrapped
  in (when (mino-installed? :cap) ...) and skip cleanly when off.
- mino_install_core: back-compat alias that pre-sets the canonical
  Clojure-core caps (regex + bignum + multimethods + protocols +
  transducers) then calls mino_install_clojure_core. Existing
  embedders see no behaviour change.

mino_state_t carries a new caps_installed bitmask; MINO_CAP_*
constants plus mino_capability_installed / mino_capabilities let
host code query what is on. A static capability registry powers
mino_capability_for_symbol(name), used by eval_symbol to raise an
enriched diagnostic when user code calls a name from a capability
the host disabled.

New diagnostic code MNS002 (capability-disabled), distinct from
MNS001 (unbound symbol). The :mino/data payload carries
{:capability :symbol :reason :enable-via} so user-side error
handlers can pattern-match on the disabled capability.

REPL UX: :capabilities (alias :caps) prints a two-column
installed-vs-not table; the banner shows "embedded, N of M
capabilities installed" plus a one-liner pointing to :capabilities
when the runtime is in a partial-install state.

Capability-install ordering rule: a capability that gates a
core.clj section must have its bit set before
mino_install_clojure_core runs. The back-compat mino_install_core
wrapper handles this for the canonical caps; mino_install_all does
the same for the I/O / fs / proc / stm / agent / async / host tier.

Critical bug found and fixed during integration: each
mino_install_<cap> originally installed its prims into the
caller-supplied env (a user env from mino_env_new), not the
clojure.core ns env. core.clj eval (which runs with current_ns =
clojure.core) then could not resolve the capability's prims, raising
MNS002 even on a fully-installed runtime. Each install_<cap> now
ns_env_ensures clojure.core and installs into that env.

tests/embed_caps_test.c exercises three paths: minimal floor,
minimal + selective caps (multimethods only) with MNS002
verification on the off caps, and install_all coverage. Standalone
test suite (1616 tests, 7527 assertions) green; embed_multi_state
green; embed_stm_test pre-existing latent bug unrelated to this
change.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: leifericf

.gitignore

@@ -60,6 +60,9 @@ embed_multi_state
 embed_multi_state_asan
 embed_multi_state_tsan
 embed_stm_test
+embed_caps_test
+embed_caps_test_asan
+embed_caps_test_tsan
 tests/transient_test
 tests/transient_test_asan
 tests/transient_test_ubsan

CHANGELOG.md

@@ -1,5 +1,79 @@
 # Changelog
 
+## v0.146.0 — Capability-Gated Install: Lean Embedded Footprint, Same Standalone Surface
+
+Embedded mino's `mino_install_core` was monolithic — every fresh runtime
+parsed and evaluated all ~117 KB of `core.clj` and registered every C
+primitive whether the host needed it or not. Hosts that wanted just a
+calculator paid the full Clojure-stdlib bill. This release introduces a
+capability-gated install API so embedders opt into exactly the surface
+they need, without changing what a `mino_install_core`-equipped runtime
+exposes to user Clojure code.
+
+The new surface:
+
+- `mino_install_minimal(S, env)`  — reader, evaluator, GC, persistent
+  collections, numeric ops, basic seq, foundational macros. No
+  `core.clj` evaluation; sub-millisecond install cost.
+- `mino_install_regex(S, env)`, `mino_install_bignum`,
+  `mino_install_multimethods`, `mino_install_protocols`,
+  `mino_install_transducers` — each flips a capability bit and (for
+  the C-backed ones) registers its prims into `clojure.core`.
+- `mino_install_clojure_core(S, env)` — evaluates `core.clj` against
+  whatever capability bits the host has set. Optional sections (regex,
+  multimethods, protocols, transducers, bignum-aware `integer?`) are
+  wrapped in `(when (mino-installed? :cap) ...)` and skip cleanly when
+  their capability is off.
+- `mino_install_core(S, env)` is preserved as a back-compat alias that
+  pre-sets the canonical Clojure-core caps (regex + bignum +
+  multimethods + protocols + transducers) and then calls
+  `mino_install_clojure_core`. Existing embedders see no behaviour
+  change.
+
+`mino_state_t` carries a new `caps_installed` bitmask; `MINO_CAP_*`
+constants and `mino_capability_installed(S, bit)` / `mino_capabilities(S)`
+let host code query what is on. A static capability registry powers
+`mino_capability_for_symbol(name)`, used by the symbol-resolution path
+to raise an enriched diagnostic when user code calls a name from a
+capability the host disabled.
+
+New diagnostic code **MNS002** (capability-disabled), distinct from
+**MNS001** (unbound symbol). The `:mino/data` payload carries
+`{:capability :symbol :reason :enable-via}` so user-side error handlers
+can pattern-match on the disabled capability. Example:
+
+```
+error[MNS002]: slurp is not installed in this runtime
+               (capability 'io' disabled by host)
+note: the host can enable this capability by calling
+      mino_install_io from C before mino_install_core
+```
+
+REPL UX gains a `:capabilities` (alias `:caps`) command that prints a
+two-column installed-vs-not table, and the banner shows
+"embedded, N of M capabilities installed" plus a one-liner pointing
+to `:capabilities` when the runtime is in a partial-install state.
+
+Standalone `./mino`, `./mino -e ...`, `./mino script.clj`, REPL, all
+remain unchanged at the user-visible surface: same Clojure-core names,
+same diagnostics for non-capability errors, same 1616-test suite green.
+
+Embedded surface: a host that wants the full Clojure runtime still
+calls `mino_install_core` and gets bit-for-bit identical behaviour. A
+host that wants a lean numeric/collection-only mino calls
+`mino_install_minimal` and skips the `core.clj` eval entirely.
+
+The capability install ordering rule: a capability that gates a
+`core.clj` section must have its bit set **before**
+`mino_install_clojure_core` runs. The back-compat
+`mino_install_core` wrapper handles this for the canonical caps;
+`mino_install_all` does the same for the I/O / fs / proc / stm /
+agent / async / host tier.
+
+Subsequent phases of the lean-embed cycle (porting thin `core.clj`
+wrappers to C, pre-parsed AST, pre-compiled bytecode, image-based
+bootstrap) will compose on top of this surface without breaking it.
+
 ## v0.145.1 — Task Runner Fix: Pre-Resolve Tasks Outside The BC Doseq Body
 
 `mino task <name>` raised a confusing `subs: first argument must be

lib/mino/tasks/builtin.clj

@@ -336,12 +336,16 @@
      - embed_multi_state: 16 mino_state_t x 16 pthreads, asserts the
        embedding API is safe under the one-state-per-thread contract.
      - embed_stm_test: STM Layer 2a smoke test (mino_tx_run,
-       mino_tx_alter_c, mino_tx_commute_c, mino_tx_ensure, watches)."
+       mino_tx_alter_c, mino_tx_commute_c, mino_tx_ensure, watches).
+     - embed_caps_test: capability-gated install surface -- minimal /
+       selective caps / install_all paths and MNS002 diagnostics."
   []
   (compile-and-run-embed-test "tests/embed_multi_state.c"
                               "embed_multi_state")
   (compile-and-run-embed-test "tests/embed_stm_test.c"
-                              "embed_stm_test"))
+                              "embed_stm_test")
+  (compile-and-run-embed-test "tests/embed_caps_test.c"
+                              "embed_caps_test"))
 
 ;; ---- Architecture quality gates ----
 

main.c

@@ -376,14 +376,51 @@ static void print_repl_help(FILE *out)
 {
     fputs(
         "REPL meta-commands:\n"
-        "  :help      Show this help\n"
-        "  :quit      Exit the REPL (or press Ctrl-D)\n"
+        "  :help          Show this help\n"
+        "  :quit          Exit the REPL (or press Ctrl-D)\n"
+        "  :capabilities  Show installed vs. available capabilities (alias :caps)\n"
         "\n"
         "Type a form and press Enter to evaluate it. Multi-line forms are\n"
         "gathered until the parens balance.\n",
         out);
 }
 
+/* Two-column capability listing for the REPL `:capabilities` command.
+ * The full registry is enumerated; each entry is printed under
+ * INSTALLED or AVAILABLE depending on the runtime's bitmask. */
+static void print_repl_capabilities(FILE *out, mino_state_t *S)
+{
+    const mino_capability_info_t *p;
+    int total = 0, installed = 0, longest = 0;
+
+    for (p = mino_capability_list(); p->name != NULL; p++) {
+        int n = (int)strlen(p->name);
+        if (n > longest) longest = n;
+        total++;
+        if (mino_capability_installed(S, p->bit)) installed++;
+    }
+
+    fprintf(out, "Capabilities: %d of %d installed\n\n", installed, total);
+    fprintf(out, "  %-*s  %-24s  %s\n", longest, "name", "C entry point",
+            "description");
+    fprintf(out, "  %-*s  %-24s  %s\n", longest, "----",
+            "-------------",
+            "-----------");
+    for (p = mino_capability_list(); p->name != NULL; p++) {
+        const char *mark = mino_capability_installed(S, p->bit)
+                          ? "  [x]" : "  [ ]";
+        fprintf(out, "%s %-*s  %-24s  %s\n",
+                mark, longest, p->name,
+                p->install_fn != NULL ? p->install_fn : "",
+                p->summary != NULL ? p->summary : "");
+    }
+    fputc('\n', out);
+    fputs("  [x] installed   [ ] available -- call the C entry point\n",
+          out);
+    fputs("      from the embedder to enable. mino-installed? exposes\n", out);
+    fputs("      the same bits to running code.\n", out);
+}
+
 /* Exec a companion binary ("mino-nrepl" / "mino-lsp") from PATH, passing
  * remaining argv through. Replaces argv[first] with the binary name so the
  * companion observes its own argv[0]. Only returns on failure. */
@@ -948,8 +985,24 @@ int main(int argc, char **argv)
         return exit_code;
     }
 
-    fprintf(stderr, "mino %s\n", mino_version_string());
-    fputs("Type :help for help, :quit to exit\n", stderr);
+    {
+        const mino_capability_info_t *p;
+        int total = 0, installed = 0;
+        for (p = mino_capability_list(); p->name != NULL; p++) {
+            total++;
+            if (mino_capability_installed(S, p->bit)) installed++;
+        }
+        if (installed < total) {
+            fprintf(stderr,
+                "mino %s (embedded, %d of %d capabilities installed)\n",
+                mino_version_string(), installed, total);
+            fputs("Type :capabilities to see the full list, "
+                  ":help for help, :quit to exit\n", stderr);
+        } else {
+            fprintf(stderr, "mino %s\n", mino_version_string());
+            fputs("Type :help for help, :quit to exit\n", stderr);
+        }
+    }
     fputs("mino=> ", stderr);
     fflush(stderr);
 
@@ -1013,6 +1066,18 @@ int main(int argc, char **argv)
                     awaiting_continuation = 0;
                     continue;
                 }
+                if (strcmp(name, "capabilities") == 0
+                    || strcmp(name, "caps") == 0) {
+                    print_repl_capabilities(stderr, S);
+                    {
+                        size_t consumed  = (size_t)(end - buf);
+                        size_t remaining = len - consumed;
+                        memmove(buf, end, remaining + 1);
+                        len = remaining;
+                    }
+                    awaiting_continuation = 0;
+                    continue;
+                }
             }
             if (form == NULL) {
                 const char *err = mino_last_error(S);

src/core.clj

@@ -796,7 +796,9 @@
 
 (defn integer?
   "Returns true if x is an integer (long or bigint)."
-  [x] (or (int? x) (bigint? x)))
+  [x] (if (mino-installed? :bignum)
+        (or (int? x) (bigint? x))
+        (int? x)))
 ;; pos-int? / neg-int? / nat-int? specifically test the long-sized
 ;; int tier per Clojure's contract: `(neg-int? -1N)` returns false on
 ;; the JVM because clojure.core/neg-int? composes int? (Long-only),
@@ -1775,6 +1777,14 @@
   (prewalk (fn [x] (if (contains? smap x) (get smap x) x)) form))
 
 ;; --- Regex ---
+;;
+;; Gated on the :regex capability. When the host did not call
+;; mino_install_regex (or mino_install_clojure_core / mino_install_all),
+;; the entire section is skipped: re-pattern / re-find / re-matches are
+;; not bound, so any code calling them triggers a MNS002 "capability
+;; not installed" diagnostic instead of a bare unbound-symbol error.
+
+(when (mino-installed? :regex)
 
 ;; re-pattern is a C primitive that returns a MINO_REGEX from a
 ;; string source (and a no-op on an existing regex). Note that
@@ -1877,6 +1887,8 @@
                       {:matcher m})))
     last-match))
 
+) ;; end (when (mino-installed? :regex) ...)
+
 ;; --- Complex macros ---
 
 (defmacro condp
@@ -2110,6 +2122,10 @@
 
 ;; ---------------------------------------------------------------------------
 ;; Protocols: polymorphic dispatch on the type of the first argument.
+;; Gated on the :protocols capability -- defprotocol / extend-protocol /
+;; extend-type / satisfies? are absent when the host did not install
+;; protocols. The CollReduce / IKVReduce / Datafiable / Navigable
+;; extension points further down also live in this gate.
 ;;
 ;; (defprotocol Name
 ;;   (method1 [this])
@@ -2129,6 +2145,8 @@
 ;; (satisfies? Name x) returns true if x's type has implementations for Name.
 ;; ---------------------------------------------------------------------------
 
+(when (mino-installed? :protocols)
+
 (defn protocol-dispatch [dispatch-atom mname & args]
   (let [target (first args)
         t (type target)
@@ -2357,6 +2375,10 @@
         (impl m f init)
         (internal-reduce-kv f init m))))
 
+) ;; end (when (mino-installed? :protocols) ...)
+
+(when (mino-installed? :multimethods)
+
 ;; ---------------------------------------------------------------------------
 ;; Hierarchies: immutable parent/child/ancestor/descendant relationships.
 ;;
@@ -2645,6 +2667,8 @@
 
 (set-print-method! print-method)
 
+) ;; end (when (mino-installed? :multimethods) ...)
+
 (defmacro with-out-str
   "Evaluates body with *out* bound to a fresh string-collecting atom,
   and returns the accumulated string."
@@ -2692,14 +2716,20 @@
            (finally (close ~name)))))))
 
 ;; ---------------------------------------------------------------------------
-;; Transducers: composable algorithmic transformations.
+;; Transducers: composable algorithmic transformations. Gated on
+;; :transducers -- when off, the C-level `into` primitive handles
+;; (into to from) directly and transducer-aware shapes like
+;; (transduce xf f coll) raise a MNS002 "capability not installed"
+;; diagnostic. Depends on :protocols (reduce-kv lives there).
 ;;
 ;; A transducer is a function (rf -> rf) where rf is a reducing function
 ;; with three arities: ([] init), ([result] completion), ([result input] step).
 ;;
 ;; Use (transduce xf f coll) or (into to xf from) to apply.
 ;; ---------------------------------------------------------------------------
 
+(when (mino-installed? :transducers)
+
 (defn cat
   "A transducer that concatenates the contents of each input."
   [rf]
@@ -2842,6 +2872,8 @@
       (sequence (first xfs) coll)
       (sequence (apply comp xfs) coll))))
 
+) ;; end (when (mino-installed? :transducers) ...)
+
 ;; --- Array constructors ---
 ;;
 ;; object-array, int-array, long-array, etc. are now C primitives that

src/eval/special.c

@@ -11,6 +11,7 @@
 
 #include "eval/special_internal.h"
 #include "prim/internal.h"
+#include "mino.h"
 
 /* --- Evaluator helpers: one per value kind. --- */
 
@@ -168,6 +169,38 @@ static mino_val_t *eval_symbol(mino_state_t *S, mino_val_t *form, mino_env_t *en
         if (amb != NULL) v = mino_env_get_sym(amb, form);
     }
     if (v == NULL) {
+        const mino_capability_info_t *cap = mino_capability_for_symbol(data);
+        if (cap != NULL) {
+            char  msg[400];
+            char  note[200];
+            mino_val_t *keys[4];
+            mino_val_t *vals[4];
+            mino_val_t *data_map;
+
+            snprintf(msg, sizeof(msg),
+                "%s is not installed in this runtime "
+                "(capability '%s' disabled by host)",
+                data, cap->name);
+            snprintf(note, sizeof(note),
+                "the host can enable this capability by calling %s "
+                "from C before mino_install_core",
+                cap->install_fn);
+
+            keys[0] = mino_keyword(S, "capability");
+            vals[0] = mino_keyword(S, cap->name);
+            keys[1] = mino_keyword(S, "symbol");
+            vals[1] = mino_symbol(S, data);
+            keys[2] = mino_keyword(S, "reason");
+            vals[2] = mino_keyword(S, "not-installed");
+            keys[3] = mino_keyword(S, "enable-via");
+            vals[3] = mino_string(S, cap->install_fn);
+            data_map = mino_map(S, keys, vals, 4);
+
+            set_eval_diag_with_data(S,
+                mino_current_ctx(S)->eval_current_form,
+                "capability", "MNS002", msg, data_map, note);
+            return NULL;
+        }
         char msg[300];
         snprintf(msg, sizeof(msg), "unbound symbol: %s", data);
         set_eval_diag(S, mino_current_ctx(S)->eval_current_form, "name", "MNS001", msg);