From b5998f4b4a9927e0b53a1872532c9afb8be91be1 Mon Sep 17 00:00:00 2001
From: Yogthos <yogthos@gmail.com>
Date: Wed, 1 Jul 2026 16:31:43 -0400
Subject: [PATCH] docs: register-class-supers! for library class hierarchies

Document the register-class-supers! seam next to the other host-class hooks:
when a library class belongs to a hierarchy (a custom exception caught as
IOException, a value matching instance? across its supertypes and dispatching a
protocol extended to any of them), declare its supers once and instance?/isa?/
supers/extend-protocol all derive.
---
 docs/host-interop.md | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/docs/host-interop.md b/docs/host-interop.md
index 880e5e4..fcd8088 100644
--- a/docs/host-interop.md
+++ b/docs/host-interop.md
@@ -240,6 +240,24 @@ register checks without clobbering each other. This is the mechanism jolt's
 HTTP client library uses to emulate `java.net.URL` and `HttpURLConnection` so
 `clj-http-lite` runs unchanged.
 
+`__register-instance-check!` answers one `(instance? Foo x)` question. When a
+class belongs to a *hierarchy* — a custom exception that should be caught as an
+`IOException`, or a value that should match `(instance? SomeInterface x)` across
+its whole supertype chain and dispatch a protocol extended to any of those
+supertypes — declare its direct supers once with `jolt.host/register-class-supers!`
+instead. `instance?`, `isa?`, `supers`/`ancestors`, and `extend-protocol`
+dispatch all derive from the one declaration (supers are given by canonical name;
+transitivity is computed):
+
+```clojure
+;; a library's exception type that catch/instance? should treat as an IOException
+(jolt.host/register-class-supers! "com.acme.RetryExhaustedException"
+                                  ["java.io.IOException"])
+
+(throw (jolt.host/throwable "com.acme.RetryExhaustedException" "gave up"))
+;; (catch java.io.IOException e …) now matches it; (instance? java.lang.Exception e) is true
+```
+
 Extending a *built-in* class instead (adding a method to core's `String` shim,
 say) means editing the relevant `host/chez/*.ss` file and running `make remint`
 — see [building-and-deps.md](building-and-deps.md).