ludic.base, ludic.wildlife, ludic.npc: fact records reused, not made per fact

wl_fact made a new WildFact per fact, about one a frame, and Ludic never gives one back. ludic.base's q_unheld(q, pool, out) lists the records a queue no longer holds: neither waiting nor handed out by its last drain, which is good until the next drain. ludic.wildlife and ludic.npc now keep a pool, hand out a free record, and make a new one only when every record is held. Taking a record writes the state, so wl_fact / np_fact and the few callers holding their state read-only take it mut. Tests: q_unheld's rules (an empty drain holds on, the safe side); 3000 prints drained frame by frame use at most 4 records; 500 arrivals drained turn by turn use at most 4. base 37, wildlife 27, npc 17; all packages 420.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

packages/ludic.base/queue.ludic

@@ -56,6 +56,20 @@ export function q_clear<T>(q: Queue<T>) -> void {
   q.tag.pending = 0
 }
 
+# pool's records the queue no longer holds - neither waiting nor handed out by the last drain - put
+# into out (cleared first): what a package may fill again instead of making a new record per fact
+export function q_unheld<T>(q: Queue<T>, pool: []T, out: []T) -> int {
+  List.clear(out)
+  for i in 0 .. len(pool) {
+    let r = pool[i]
+    var held = false
+    for j in 0 .. len(q.items) { if q.items[j] == r { held = true } }
+    for j in 0 .. len(q.spare) { if q.spare[j] == r { held = true } }
+    if not held { push(out, r) }
+  }
+  return len(out)
+}
+
 # a queue's tag, for core_undrained: queues of different facts in one list
 export function q_tag<T>(q: Queue<T>) -> QueueTag { return q.tag }
 

packages/ludic.base/tests/queue_test.ludic

@@ -36,6 +36,32 @@ program QueueTest {
     expect(cs[0].weight == 1.5)
   }
 
+  # waiting and last handed out are held; what an earlier drain handed out is free again
+  function unheld_case() -> void {
+    let q: Queue<Caught> = queue_new("caught")
+    let a = caught(1, 1.0)
+    let b = caught(2, 2.0)
+    let c = caught(3, 3.0)
+    let pool = new []Caught
+    push(pool, a)
+    push(pool, b)
+    push(pool, c)
+    let free = new []Caught
+    q_push(q, a)
+    expect_eq(q_unheld(q, pool, free), 2)
+    q_drain(q)
+    q_push(q, b)
+    expect_eq(q_unheld(q, pool, free), 1)
+    expect(free[0] == c)
+    q_drain(q)
+    expect_eq(q_unheld(q, pool, free), 2)
+    q_drain(q)
+    expect_eq(q_unheld(q, pool, free), 2)   # an empty drain swaps nothing: b stays held, the safe side
+    q_push(q, a)
+    q_drain(q)
+    expect_eq(q_unheld(q, pool, free), 2)   # b is free at last, a is handed out
+  }
+
   function clear_case() -> void {
     let q: Queue<string> = queue_new("words")
     q_push(q, "a")
@@ -107,6 +133,7 @@ program QueueTest {
   test "an empty drain allocates nothing, and a drained list is the caller's" () { empty_case() }
   test "a queue holds records" () { record_case() }
   test "clear drops what is waiting" () { clear_case() }
+  test "a pool's records are free once no drain holds them" () { unheld_case() }
   test "a queue's element type is told by the queue alone" () { infer_case() }
   test "the undrained queues are named, and a drain clears the report" () { undrained_case() }
 }