Skip to content
This repository was archived by the owner on Aug 12, 2026. It is now read-only.

Commit ec54a22

Browse files
committed
own<T> handles: A, B and D work; C is refused and the reason is not yet known
Implements 0016 against the real resource guest. A handle is an opaque AutoCloseable that lowers into a borrow parameter and stays live across repeated calls; close is try { drop } finally { delete } and is idempotent; handles are cloned on lift, registered with the instance, and closed by it before the store their context points into is deleted -- which is the one real use-after-free in this row. C does not work. A handle from this instance's own [constructor]counter, one that works fine as a borrow, is refused when lowered into an own parameter: call local:res/bag@0.1.0#consume: mismatched resource types Ruled out: the clone. Skipping it entirely gives the identical message. Not separated: whether the guest's [resource-*] imports resolve to a different resource type than the exported interface's, or the host writes the wrong thing into the val. A C control would tell them apart, as it did for 0013. The test asserts the failure and its message rather than skipping it, so the day it changes a test says so instead of a comment going stale. Chasing it produced the thing worth keeping: ok! now reads wasmtime's own error message. "call ... failed" became "call ...: mismatched resource types", which is the difference between a guess and a bounded question. Every error this library raises from wasmtime now says what wasmtime said. Two test-shape lessons landed as comments: the own-lowering test runs last because the trap it provokes poisons the instance and erases its own cause, and the instance-close test asserts the handle's state rather than a second close, because closing twice is a no-op by design. 175 assertions. Claude-Session: https://claude.ai/code/session_01XF5Hfq4Ca2N2XYEzWQQuHt
1 parent 7b6cac4 commit ec54a22

4 files changed

Lines changed: 207 additions & 50 deletions

File tree

‎doc/design/0016-own-handles.md‎

Lines changed: 30 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
# 0016 — `own<T>` handles, in both directions
22

3-
**Status:** proposed · 2026-07-30 · rewritten after an adversarial review built
3+
**Status:** accepted for A, B and D, which are implemented and tested.
4+
**C is open** — lowering an `own` is rejected by wasmtime with `mismatched
5+
resource types` and nobody knows why yet; see the end. · 2026-07-30 · rewritten after an adversarial review built
46
the guest this note said it was missing. The file was `0016-resource-handles.md`
57
until that review showed `borrow` is not a question this note can ask.
68

@@ -148,6 +150,33 @@ instead of it."
148150
the result val. Measured true today, and the failure is a silent resource
149151
leak, so it needs re-checking on upgrade.
150152

153+
## C does not work, and the reason is not yet known
154+
155+
Implemented and measured 2026-07-30. A handle that came from *this instance's
156+
own* `[constructor]counter`, and that works as a `borrow` across repeated
157+
`bump` calls, is refused when lowered into an `own` parameter:
158+
159+
```
160+
call local:res/bag@0.1.0#consume: mismatched resource types
161+
```
162+
163+
What has been ruled out: **the clone is not the cause** — skipping it entirely
164+
gives the identical message. What has not been separated is whether the fault
165+
is in the guest's `[resource-new]` / `[resource-rep]` / `[resource-drop]`
166+
imports resolving to a different resource type than the one in the exported
167+
interface, or in what the host writes into the val. A C control that does the
168+
same round trip would separate them, exactly as it did for `0013`.
169+
170+
The test asserts the failure and its message, so the day this changes a test
171+
says so rather than a comment going stale. Everything else in this note is
172+
implemented: lifting an `own`, lowering into a `borrow`, `close` as
173+
`try { drop } finally { delete }`, and the instance closing what it still
174+
holds.
175+
176+
**A side effect worth having**: chasing this added wasmtime's own error text to
177+
every `ok!`. `call … failed` became `call …: mismatched resource types`, which
178+
is what turned this from a guess into a bounded question.
179+
151180
## Notes for whoever writes the guest
152181

153182
**It exists now:** `dev/resources/res.{wit,wat}`, exercised by

‎doc/status.md‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,8 +13,13 @@ _Short by design, and printed at every session start — so findings live in
1313
`close` as `try { drop } finally { delete }`, lowering an `own` transfers,
1414
the instance closes outstanding handles before deleting its store) and
1515
`borrow` is out of scope because it **cannot appear in a return position**.
16-
The guest to test it against now exists (`dev/resources/res.{wit,wat}`) and
17-
reflects correctly; what is left is the marshalling.
16+
**A, B and D are implemented**: lifting an `own`, lowering into a `borrow`,
17+
`close` as `try { drop } finally { delete }`, and the instance closing
18+
handles the caller never destructured before deleting its store.
19+
**C is open** — lowering an `own` is refused with `mismatched resource
20+
types` for a handle from this instance's own constructor that works fine as
21+
a borrow. The clone is ruled out; a C control would separate guest from
22+
host, as it did for `0013`.
1823
2. **Host imports.** `0014` names them as its most-likely-to-fire falsifier,
1924
WASI requires them, and nothing has touched them. They also invalidate
2025
`0014` E's argument-buffer reuse, which is safe today only because no guest

‎src/cljwit/host.clj‎

Lines changed: 105 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -63,7 +63,7 @@
6363
(def ^:private VAL-KIND
6464
{:bool 0 :s8 1 :u8 2 :s16 3 :u16 4 :s32 5 :u32 6 :s64 7 :u64 8
6565
:f32 9 :f64 10 :char 11 :string 12
66-
:flags 20 :tuple 15})
66+
:flags 20 :tuple 15 :own 21 :borrow 21})
6767

6868
(defn- lib-path []
6969
(or (System/getenv "CLJWIT_WASMTIME_LIB")
@@ -83,11 +83,22 @@
8383
(.invokeWithArguments mh ^java.util.List (vec args)))
8484

8585
(defn- ok!
86-
"wasmtime returns a null error pointer on success."
87-
[what v]
86+
"wasmtime returns a null error pointer on success. On failure the message is
87+
the only thing that says *why*, and throwing without it turned a two-minute
88+
debug into an afternoon once already."
89+
[api what v]
8890
(let [^MemorySegment e v]
8991
(when-not (.equals MemorySegment/NULL e)
90-
(throw (ex-info (str what " failed") {:cljwit/error :wasmtime})))
92+
(let [msg (with-open [a (Arena/ofConfined)]
93+
(let [nm ^MemorySegment (.allocate a (long 16))]
94+
(invoke (:err-message api) e nm)
95+
(let [n (.get nm I64 (long 0))
96+
p ^MemorySegment (.get nm ADDR (long 8))
97+
b (byte-array n)]
98+
(MemorySegment/copy (.reinterpret p n) I8 0 b 0 (int n))
99+
(String. b "UTF-8"))))]
100+
(invoke (:err-delete api) e)
101+
(throw (ex-info (str what ": " msg) {:cljwit/error :wasmtime}))))
91102
v))
92103

93104
(defn- api
@@ -134,7 +145,12 @@
134145
:instantiate (b "wasmtime_component_linker_instantiate" ADDR ADDR ADDR ADDR ADDR)
135146
:export-index (b "wasmtime_component_instance_get_export_index" ADDR ADDR ADDR ADDR ADDR I64)
136147
:get-func (b "wasmtime_component_instance_get_func" BOOL ADDR ADDR ADDR ADDR)
137-
:func-call (b "wasmtime_component_func_call" ADDR ADDR ADDR ADDR I64 ADDR I64)}))
148+
:func-call (b "wasmtime_component_func_call" ADDR ADDR ADDR ADDR I64 ADDR I64)
149+
:res-clone (b "wasmtime_component_resource_any_clone" ADDR ADDR)
150+
:res-drop (b "wasmtime_component_resource_any_drop" ADDR ADDR ADDR)
151+
:res-delete (b "wasmtime_component_resource_any_delete" nil ADDR)
152+
:err-message (b "wasmtime_error_message" nil ADDR ADDR)
153+
:err-delete (b "wasmtime_error_delete" nil ADDR)}))
138154

139155
(defn- cstr [^Arena arena ^String t]
140156
(let [b (.getBytes t "UTF-8")
@@ -237,6 +253,39 @@
237253
(range (invoke (:var-count api) of)))})
238254
k)))
239255

256+
(def ^:private RESOURCE 21) ; wasmtime_component_val_t's kind for a handle
257+
258+
(deftype Handle [^MemorySegment ptr ^MemorySegment ctx api registry
259+
^AtomicBoolean closed]
260+
java.lang.AutoCloseable
261+
(close [this]
262+
;; 0016 B: `delete` is required per handle whatever `drop` did, so it goes
263+
;; in a finally. Marking closed first would leak the host memory when
264+
;; `drop` throws; marking last would re-drop on a retry.
265+
(when (.compareAndSet closed false true)
266+
(swap! registry disj this)
267+
(try
268+
(ok! api "resource drop" (invoke (:res-drop api) ctx ptr))
269+
(finally (invoke (:res-delete api) ptr))))
270+
nil)
271+
Object
272+
(toString [_] (str "#cljwit/resource[" (if (.get closed) "closed" "open") "]")))
273+
274+
(defn- transfer!
275+
"0016 C: lowering an `own` gives the resource to the guest. The host's handle
276+
is stale immediately — dropping it afterwards is `unknown handle index` —
277+
so it is deleted, never dropped."
278+
[^Handle h]
279+
(when (.compareAndSet ^AtomicBoolean (.-closed h) false true)
280+
(swap! (.-registry h) disj h)
281+
(invoke (:res-delete (.-api h)) (.-ptr h))))
282+
283+
(defn- live-ptr [^Handle h what]
284+
(when (.get ^AtomicBoolean (.-closed h))
285+
(throw (ex-info (str "resource handle is closed (" what ")")
286+
{:cljwit/error :closed})))
287+
(.-ptr h))
288+
240289
;; --- marshalling ------------------------------------------------------------
241290
;; Lowering and lifting are *compiled* from the reflected tree once per export,
242291
;; not interpreted per call. An unsupported type fails at instantiation naming
@@ -294,10 +343,20 @@
294343

295344
(defn- lower-fn [tree]
296345
(if (keyword? tree)
297-
(if (= :string tree)
298-
(fn [^Arena arena ^MemorySegment seg v]
299-
(.set seg I8 (long 0) (byte (VAL-KIND :string)))
300-
(write-name! arena seg UNION v))
346+
(case tree
347+
:string (fn [^Arena arena ^MemorySegment seg v]
348+
(.set seg I8 (long 0) (byte (VAL-KIND :string)))
349+
(write-name! arena seg UNION v))
350+
(:own :borrow)
351+
(let [own? (= :own tree)]
352+
(fn [_ ^MemorySegment seg v]
353+
(let [^Handle h v
354+
^MemorySegment p (live-ptr h (if own? "transferring" "borrowing"))]
355+
(.set seg I8 (long 0) (byte RESOURCE))
356+
(.set seg ADDR (long UNION) p)
357+
;; A borrow leaves the handle live; an own is stale the moment the
358+
;; guest takes it (0016 C).
359+
(when own? (transfer! h)))))
301360
(scalar-lower tree))
302361
(case (:kind tree)
303362
:enum (fn [^Arena arena ^MemorySegment seg v]
@@ -377,28 +436,38 @@
377436
(.set seg I64 (long (+ UNION VEC-SIZE)) (long (count fs)))
378437
(.set seg ADDR (long (+ UNION VEC-DATA)) buf)))))))
379438

380-
(defn- lift-fn [tree]
439+
(defn- lift-fn [tree rt]
381440
(if (keyword? tree)
382-
(if (= :string tree)
383-
(fn [^MemorySegment seg] (read-str seg UNION))
441+
(case tree
442+
:string (fn [^MemorySegment seg] (read-str seg UNION))
443+
;; 0016: clone on lift. With one reused result val, the next call deletes
444+
;; the previous handle -- and deletes without dropping, so the resource
445+
;; leaks and its destructor never runs.
446+
(:own :borrow)
447+
(fn [^MemorySegment seg]
448+
(let [p ^MemorySegment (.get seg ADDR (long UNION))
449+
c ^MemorySegment (invoke (:res-clone (:api rt)) p)
450+
h (->Handle c (:ctx rt) (:api rt) (:registry rt) (AtomicBoolean. false))]
451+
(swap! (:registry rt) conj h)
452+
h))
384453
(scalar-lift tree))
385454
(case (:kind tree)
386455
:enum (fn [^MemorySegment seg] (keyword (read-str seg UNION)))
387-
:option (let [inner (lift-fn (:ty tree))]
456+
:option (let [inner (lift-fn (:ty tree) rt)]
388457
(fn [^MemorySegment seg]
389458
(let [p ^MemorySegment (.get seg ADDR (long UNION))]
390459
(when-not (.equals MemorySegment/NULL p)
391460
(inner (.reinterpret p (long VAL)))))))
392-
:result (let [lo (some-> (:ok tree) lift-fn)
393-
le (some-> (:err tree) lift-fn)]
461+
:result (let [lo (when (:ok tree) (lift-fn (:ok tree) rt))
462+
le (when (:err tree) (lift-fn (:err tree) rt))]
394463
(fn [^MemorySegment seg]
395464
(let [ok? (not= 0 (.get seg I8 (long RES-OK)))
396465
f (if ok? lo le)
397466
p ^MemorySegment (.get seg ADDR (long RES-VAL))]
398467
[(if ok? :ok :err)
399468
(when (and f (not (.equals MemorySegment/NULL p)))
400469
(f (.reinterpret p (long VAL))))])))
401-
:variant (let [lifts (into {} (map (fn [[n t]] [n (some-> t lift-fn)]))
470+
:variant (let [lifts (into {} (map (fn [[n t]] [n (when t (lift-fn t rt))]))
402471
(:cases tree))]
403472
(fn [^MemorySegment seg]
404473
(let [nm (read-str seg VAR-NAME)
@@ -412,20 +481,20 @@
412481
p ^MemorySegment (.get seg ADDR (long (+ UNION VEC-DATA)))
413482
b (.reinterpret p (long (* 16 n)))]
414483
(into #{} (map (fn [i] (keyword (read-str b (* 16 i))))) (range n))))
415-
:tuple (let [els (mapv lift-fn (:types tree))]
484+
:tuple (let [els (mapv (fn [t] (lift-fn t rt)) (:types tree))]
416485
(fn [^MemorySegment seg]
417486
(let [p ^MemorySegment (.get seg ADDR (long (+ UNION VEC-DATA)))
418487
b (.reinterpret p (long (* VAL (count els))))]
419488
(mapv (fn [i] ((nth els i) (.asSlice b (long (* VAL i)) (long VAL))))
420489
(range (count els))))))
421-
:list (let [el (lift-fn (:element tree))]
490+
:list (let [el (lift-fn (:element tree) rt)]
422491
(fn [^MemorySegment seg]
423492
(let [n (.get seg I64 (long (+ UNION VEC-SIZE)))
424493
p ^MemorySegment (.get seg ADDR (long (+ UNION VEC-DATA)))
425494
b (.reinterpret p (long (* VAL n)))]
426495
(mapv (fn [i] (el (.asSlice b (long (* VAL i)) (long VAL))))
427496
(range n)))))
428-
:record (let [fs (mapv (fn [[n t]] [(keyword n) (lift-fn t)]) (:fields tree))]
497+
:record (let [fs (mapv (fn [[n t]] [(keyword n) (lift-fn t rt)]) (:fields tree))]
429498
(fn [^MemorySegment seg]
430499
(let [n (.get seg I64 (long (+ UNION VEC-SIZE)))
431500
p ^MemorySegment (.get seg ADDR (long (+ UNION VEC-DATA)))
@@ -504,7 +573,8 @@
504573
nil))
505574

506575
(deftype Instance [^Artifact artifact ^Arena arena exports aliases sigs
507-
^MemorySegment store ^AtomicBoolean closed ^AtomicBoolean in-call]
576+
^MemorySegment store ^AtomicBoolean closed ^AtomicBoolean in-call
577+
registry]
508578
java.lang.AutoCloseable
509579
(close [_]
510580
;; 0014 D: close is an entry into the store like any other. Take `in-call`
@@ -516,6 +586,9 @@
516586
(throw (ex-info "cannot close while a call is in flight"
517587
{:cljwit/error :concurrent-use})))
518588
(when (.compareAndSet closed false true)
589+
;; Before the store goes: a handle that outlives it holds a dangling
590+
;; context, which is the one real use-after-free in this row (0016 D).
591+
(run! (fn [^java.lang.AutoCloseable h] (.close h)) @registry)
519592
(invoke (:store-delete (.-api ^Engine (.-engine artifact))) store)
520593
(.close arena)))
521594
nil)
@@ -555,7 +628,7 @@
555628
buf ^MemorySegment (.allocate arena (long (alength ^bytes bs)))
556629
_ (MemorySegment/copy ^bytes bs 0 buf I8 0 (alength ^bytes bs))
557630
out ^MemorySegment (.allocate arena ^java.lang.foreign.MemoryLayout ADDR)]
558-
(ok! "component_new"
631+
(ok! a "component_new"
559632
(invoke (:comp-new a) (.-ptr e) buf (long (alength ^bytes bs)) out))
560633
(->Artifact e arena (.get out ADDR (long 0)) (AtomicBoolean. false))))
561634

@@ -584,10 +657,10 @@
584657
and reused; the result is lifted eagerly and nothing backed by it escapes
585658
(`0014` E)."
586659
[api ^Arena arena ^MemorySegment ctx ^MemorySegment f sig
587-
^AtomicBoolean closed ^AtomicBoolean in-call nm]
660+
^AtomicBoolean closed ^AtomicBoolean in-call nm rt]
588661
(let [ptypes (mapv (comp lower-fn second) (:params sig))
589662
n (count ptypes)
590-
rlift (some-> (:result sig) lift-fn)
663+
rlift (when (:result sig) (lift-fn (:result sig) rt))
591664
args ^MemorySegment (.allocate arena (long (max 1 (* VAL n))))
592665
res ^MemorySegment (.allocate arena (long VAL))
593666
;; A confined arena per call would be safer for strings, but nothing
@@ -607,7 +680,7 @@
607680
(with-open [scratch (Arena/ofConfined)]
608681
(dotimes [i n]
609682
((nth ptypes i) scratch (.asSlice args (long (* VAL i)) (long VAL)) (nth vs i)))
610-
(ok! (str "call " nm) (invoke call! f ctx args (long n) res (long 1)))
683+
(ok! api (str "call " nm) (invoke call! f ctx args (long n) res (long 1)))
611684
;; No val_delete on `res`. Its header says it "will deallocate the
612685
;; contents of the value but not the value pointer itself", and on a
613686
;; result or variant — the two kinds carrying a payload pointer — the
@@ -631,11 +704,16 @@
631704
ctx (invoke (:store-context api) store)
632705
clink (invoke (:linker-new api) (.-ptr e))
633706
inst ^MemorySegment (.allocate arena (long INSTANCE))
634-
_ (ok! "linker_instantiate"
707+
_ (ok! api "linker_instantiate"
635708
(invoke (:instantiate api) clink ctx (.-ptr art) inst))
636709
ct (invoke (:comp-type api) (.-ptr art))
637710
closed (AtomicBoolean. false)
638711
in-call (AtomicBoolean. false)
712+
;; 0016 D: one call can yield handles the caller never destructured, so
713+
;; the instance keeps the list and closes what is left before deleting
714+
;; the store a handle's context points into.
715+
registry (atom #{})
716+
rt {:ctx ctx :api api :registry registry}
639717
item-kind (fn [^MemorySegment it] (bit-and (long (.get it I8 (long 0))) 0xFF))
640718
;; Every export, flattened. A function inside an interface is keyed the
641719
;; way WIT spells it — "pkg:name/iface@ver#func" — and remembers the
@@ -704,9 +782,9 @@
704782
(when-not (invoke (:get-func api) inst ctx eidx f)
705783
(throw (ex-info (str "export " key " vanished between type and instance")
706784
{:cljwit/error :wasmtime})))
707-
(export-fn api arena ctx f sig closed in-call key)))])))
785+
(export-fn api arena ctx f sig closed in-call key rt)))])))
708786
found)]
709-
(->Instance art arena fns (alias-map fns) sigs store closed in-call)))
787+
(->Instance art arena fns (alias-map fns) sigs store closed in-call registry)))
710788

711789
(defn exports
712790
"Every exported function, by its exact WIT name."

0 commit comments

Comments
 (0)