feat(types): Dict + Set string-keyed containers (#54)

Types phase 4 — containers. A splice-on-demand open-addressing hash table
(runtime/native/dict.ludic, FNV-1a, linear probing, tombstones, grow at 0.7)
behind two namespaces:

- Dict.* — string -> int map: new/set/get/get_or/has/remove/size/clear/keys.
  Resource counts, id/name registries. O(1) average vs a linear list scan.
- Set.* — set of strings: new/add/has/remove/size/clear/members. Tags,
  unlocked achievements, visited tiles. Shares the same table.

Values are int (also an entity handle / small id); Value.* covers richer
maps. [T; N] inline fixed arrays remain future work — typed buffers and []T
slices already cover heap-backed arrays.

Wired: parser splice trigger (g_uses_dict), emit_call dispatch, reseeded seed,
a self-asserting example (examples/library/containers.ludic + feat_case), and
per-symbol docs + inventory. All suites green incl. golden renders byte-
identical and the bootstrap fixpoint.

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

changes/types-containers.md

@@ -0,0 +1,13 @@
+bump: minor
+type: feat
+**Containers — `Dict` + `Set` (#54, types phase 4).** Everyday string-keyed
+lookups backed by one open-addressing hash table (FNV-1a, linear probing,
+tombstone deletes, grows at load factor 0.7), spliced in on demand.
+`Dict.*` maps string keys to `int` values — `new`/`set`/`get`/`get_or`/`has`/
+`remove`/`size`/`clear`/`keys` — for resource counts and id/name registries.
+`Set.*` is a set of string members — `new`/`add`/`has`/`remove`/`size`/`clear`/
+`members` — for tags, unlocked achievements and visited tiles. O(1) average
+lookup instead of a linear list scan. Values are `int` (also holds an `entity`
+or any small id); the `Value.*` tree already covers richer/heterogeneous maps,
+and `[T; N]` inline fixed arrays remain future work (typed buffers `words` /
+`fixeds` / `pointers` and `[]T` slices cover heap-backed arrays today).

docs/language/dict/_section.md

@@ -0,0 +1,7 @@
+---
+id: dict
+title: Dict
+order: 12
+---
+
+A hash map from string keys to <code>int</code> values — the everyday lookup a game needs, like resource counts or an id registry by name. A <code>Dict</code> is backed by an open-addressing hash table (FNV-1a, linear probing, tombstone deletes, growing at load factor 0.7), so <code>get</code>/<code>set</code>/<code>has</code> are O(1) on average rather than the linear scan a list would give. Create one with <code>Dict.new</code>, then <code>set</code> / <code>get</code> / <code>get_or</code> / <code>has</code> / <code>remove</code> / <code>size</code> / <code>clear</code> / <code>keys</code>. Values are <code>int</code> (which also holds an <code>entity</code> or any small id); for richer values use the <code>Value.*</code> tree. Arguments are positional. The runtime is spliced in only when a program mentions <code>Dict.*</code> (or <code>Set.*</code>).

docs/language/dict/dict-clear.md

@@ -0,0 +1,22 @@
+---
+id: dict-clear
+name: Dict.clear
+category: dict
+kind: namespace-method
+tokens: Dict.clear
+sig: Dict.clear(d)
+tip: Remove every key.
+order: 7
+ns: Dict
+member: clear
+---
+
+Empties the map, removing every key while keeping its allocated capacity.
+
+```ludic
+program Demo {
+  handler Step phase Update {
+    Dict.clear(bank)
+  }
+}
+```

docs/language/dict/dict-get.md

@@ -0,0 +1,22 @@
+---
+id: dict-get
+name: Dict.get
+category: dict
+kind: namespace-method
+tokens: Dict.get
+sig: Dict.get(d, key) -> int
+tip: Look up a key (0 if absent).
+order: 2
+ns: Dict
+member: get
+---
+
+Returns the value stored for <code>key</code>, or <code>0</code> when the key is absent. Use <code>Dict.get_or</code> when <code>0</code> is a meaningful stored value.
+
+```ludic
+program Demo {
+  handler Step phase Update {
+    let gold = Dict.get(bank, "gold")
+  }
+}
+```

docs/language/dict/dict-get_or.md

@@ -0,0 +1,22 @@
+---
+id: dict-get_or
+name: Dict.get_or
+category: dict
+kind: namespace-method
+tokens: Dict.get_or
+sig: Dict.get_or(d, key, fallback) -> int
+tip: Look up a key with an explicit default.
+order: 3
+ns: Dict
+member: get_or
+---
+
+Returns the value for <code>key</code>, or <code>fallback</code> when the key is absent — the unambiguous lookup when <code>0</code> could be a real value.
+
+```ludic
+program Demo {
+  handler Step phase Update {
+    let n = Dict.get_or(bank, "stone", 0 - 1)
+  }
+}
+```

docs/language/dict/dict-has.md

@@ -0,0 +1,22 @@
+---
+id: dict-has
+name: Dict.has
+category: dict
+kind: namespace-method
+tokens: Dict.has
+sig: Dict.has(d, key) -> bool
+tip: Is a key present?
+order: 4
+ns: Dict
+member: has
+---
+
+Returns true when <code>key</code> is present in the map.
+
+```ludic
+program Demo {
+  handler Step phase Update {
+    if Dict.has(bank, "gold") { spend() }
+  }
+}
+```

docs/language/dict/dict-keys.md

@@ -0,0 +1,22 @@
+---
+id: dict-keys
+name: Dict.keys
+category: dict
+kind: namespace-method
+tokens: Dict.keys
+sig: Dict.keys(d) -> []pointer
+tip: Every key, as a slice of strings.
+order: 8
+ns: Dict
+member: keys
+---
+
+Returns every live key as a slice of strings, in unspecified order — iterate it with <code>len</code> and indexing to walk the whole map.
+
+```ludic
+program Demo {
+  handler Step phase Update {
+    let names = Dict.keys(bank)
+  }
+}
+```

docs/language/dict/dict-new.md

@@ -0,0 +1,22 @@
+---
+id: dict-new
+name: Dict.new
+category: dict
+kind: namespace-method
+tokens: Dict.new
+sig: Dict.new() -> Dict
+tip: Create an empty string-keyed map.
+order: 0
+ns: Dict
+member: new
+---
+
+Creates an empty <code>Dict</code> mapping string keys to <code>int</code> values. Fill it with <code>Dict.set</code> and read it back with <code>Dict.get</code>.
+
+```ludic
+program Demo {
+  handler Step phase Update {
+    let bank = Dict.new()
+  }
+}
+```

docs/language/dict/dict-remove.md

@@ -0,0 +1,22 @@
+---
+id: dict-remove
+name: Dict.remove
+category: dict
+kind: namespace-method
+tokens: Dict.remove
+sig: Dict.remove(d, key)
+tip: Delete a key.
+order: 5
+ns: Dict
+member: remove
+---
+
+Removes <code>key</code> from the map (a no-op if it is absent). Later lookups of other keys are unaffected.
+
+```ludic
+program Demo {
+  handler Step phase Update {
+    Dict.remove(bank, "wood")
+  }
+}
+```

docs/language/dict/dict-set.md

@@ -0,0 +1,22 @@
+---
+id: dict-set
+name: Dict.set
+category: dict
+kind: namespace-method
+tokens: Dict.set
+sig: Dict.set(d, key, value)
+tip: Insert or update a key.
+order: 1
+ns: Dict
+member: set
+---
+
+Associates <code>value</code> with <code>key</code>, inserting it or overwriting the previous value. The table grows automatically as it fills.
+
+```ludic
+program Demo {
+  handler Step phase Update {
+    Dict.set(bank, "gold", 100)
+  }
+}
+```

docs/language/dict/dict-size.md

@@ -0,0 +1,22 @@
+---
+id: dict-size
+name: Dict.size
+category: dict
+kind: namespace-method
+tokens: Dict.size
+sig: Dict.size(d) -> int
+tip: How many keys are stored.
+order: 6
+ns: Dict
+member: size
+---
+
+Returns the number of keys currently in the map.
+
+```ludic
+program Demo {
+  handler Step phase Update {
+    let kinds = Dict.size(bank)
+  }
+}
+```

docs/language/set/_section.md

@@ -0,0 +1,7 @@
+---
+id: set
+title: Set
+order: 13
+---
+
+A set of string members — membership tests for tags, unlocked achievements, or visited tiles. A <code>Set</code> shares the same open-addressing hash table as <code>Dict</code>, so <code>add</code> / <code>has</code> / <code>remove</code> are O(1) on average and duplicates are ignored. Create one with <code>Set.new</code>, then <code>add</code> / <code>has</code> / <code>remove</code> / <code>size</code> / <code>clear</code> / <code>members</code>. Arguments are positional. The runtime is spliced in only when a program mentions <code>Set.*</code> (or <code>Dict.*</code>).

docs/language/set/set-add.md

@@ -0,0 +1,22 @@
+---
+id: set-add
+name: Set.add
+category: set
+kind: namespace-method
+tokens: Set.add
+sig: Set.add(s, key)
+tip: Add a member (duplicates ignored).
+order: 1
+ns: Set
+member: add
+---
+
+Adds <code>key</code> to the set. Adding a member that is already present is a harmless no-op.
+
+```ludic
+program Demo {
+  handler Step phase Update {
+    Set.add(tags, "poison")
+  }
+}
+```

docs/language/set/set-clear.md

@@ -0,0 +1,22 @@
+---
+id: set-clear
+name: Set.clear
+category: set
+kind: namespace-method
+tokens: Set.clear
+sig: Set.clear(s)
+tip: Remove every member.
+order: 5
+ns: Set
+member: clear
+---
+
+Empties the set, removing every member while keeping its allocated capacity.
+
+```ludic
+program Demo {
+  handler Step phase Update {
+    Set.clear(tags)
+  }
+}
+```

docs/language/set/set-has.md

@@ -0,0 +1,22 @@
+---
+id: set-has
+name: Set.has
+category: set
+kind: namespace-method
+tokens: Set.has
+sig: Set.has(s, key) -> bool
+tip: Is a member present?
+order: 2
+ns: Set
+member: has
+---
+
+Returns true when <code>key</code> is a member of the set.
+
+```ludic
+program Demo {
+  handler Step phase Update {
+    if Set.has(tags, "poison") { tick() }
+  }
+}
+```

docs/language/set/set-members.md

@@ -0,0 +1,22 @@
+---
+id: set-members
+name: Set.members
+category: set
+kind: namespace-method
+tokens: Set.members
+sig: Set.members(s) -> []pointer
+tip: Every member, as a slice of strings.
+order: 6
+ns: Set
+member: members
+---
+
+Returns every member as a slice of strings, in unspecified order — iterate it with <code>len</code> and indexing.
+
+```ludic
+program Demo {
+  handler Step phase Update {
+    let all = Set.members(tags)
+  }
+}
+```

docs/language/set/set-new.md

@@ -0,0 +1,22 @@
+---
+id: set-new
+name: Set.new
+category: set
+kind: namespace-method
+tokens: Set.new
+sig: Set.new() -> Set
+tip: Create an empty string set.
+order: 0
+ns: Set
+member: new
+---
+
+Creates an empty <code>Set</code> of string members. Add to it with <code>Set.add</code> and test membership with <code>Set.has</code>.
+
+```ludic
+program Demo {
+  handler Step phase Update {
+    let tags = Set.new()
+  }
+}
+```

docs/language/set/set-remove.md

@@ -0,0 +1,22 @@
+---
+id: set-remove
+name: Set.remove
+category: set
+kind: namespace-method
+tokens: Set.remove
+sig: Set.remove(s, key)
+tip: Remove a member.
+order: 3
+ns: Set
+member: remove
+---
+
+Removes <code>key</code> from the set (a no-op if it is not a member).
+
+```ludic
+program Demo {
+  handler Step phase Update {
+    Set.remove(tags, "fire")
+  }
+}
+```

docs/language/set/set-size.md

@@ -0,0 +1,22 @@
+---
+id: set-size
+name: Set.size
+category: set
+kind: namespace-method
+tokens: Set.size
+sig: Set.size(s) -> int
+tip: How many members.
+order: 4
+ns: Set
+member: size
+---
+
+Returns the number of members in the set.
+
+```ludic
+program Demo {
+  handler Step phase Update {
+    let n = Set.size(tags)
+  }
+}
+```

examples/library/containers.ludic

@@ -0,0 +1,39 @@
+# containers.ludic — Dict.* (string-keyed hash map) and Set.* (string set).
+# Each assertion that holds prints its number, so a full run prints:
+#   1 2 3 4 5 6 7 8 9 10 11 12 13 14
+# One open-addressing hash table backs both (see runtime/native/dict.ludic).
+program Containers {
+  entry {
+    # --- Dict: name -> int (resource counts, id registries) ---
+    let bank = Dict.new()
+    Dict.set(bank, "gold", 100)
+    Dict.set(bank, "wood", 50)
+    Dict.set(bank, "gold", 150)          # update in place
+    if Dict.get(bank, "gold") == 150 { print(1) }
+    if Dict.get(bank, "wood") == 50 { print(2) }
+    if Dict.get(bank, "stone") == 0 { print(3) }         # absent -> 0
+    if Dict.get_or(bank, "stone", 0 - 1) == 0 - 1 { print(4) }
+    if Dict.has(bank, "wood") { print(5) }
+    if Dict.size(bank) == 2 { print(6) }
+    Dict.remove(bank, "wood")
+    if not Dict.has(bank, "wood") { print(7) }
+    if Dict.size(bank) == 1 { print(8) }
+
+    # grow past the initial capacity, then read back
+    var i = 0
+    while i < 100 { Dict.set(bank, "k" + string(i), i * 2);  i = i + 1 }
+    if Dict.get(bank, "k42") == 84 { print(9) }
+    if Dict.size(bank) == 101 { print(10) }               # gold + k0..k99
+    if len(Dict.keys(bank)) == 101 { print(11) }
+
+    # --- Set: membership by name (tags, unlocked, visited) ---
+    let tags = Set.new()
+    Set.add(tags, "poison")
+    Set.add(tags, "fire")
+    Set.add(tags, "poison")              # duplicate is ignored
+    if Set.has(tags, "fire") { print(12) }
+    if not Set.has(tags, "ice") { print(13) }
+    Set.remove(tags, "fire")
+    if Set.size(tags) == 1 { print(14) }
+  }
+}

runtime/native/dict.ludic

@@ -0,0 +1,162 @@
+# ============================================================================
+# dict.ludic — string-keyed containers: a hash map (`Dict.*`) from string keys
+# to int values, and a set (`Set.*`) of string members. Written in Ludic.
+#
+# The everyday lookups a game needs: counts and registries by name (Dict) and
+# membership by name — tags, visited tiles, unlocked achievements (Set). Both
+# are backed by one open-addressing hash table (FNV-1a hash, linear probing,
+# tombstone deletes, grow at load factor 0.7), so lookup and insert are O(1)
+# average, not the linear scan a plain list would give. Keys are compared by
+# content (the language's `==` on strings). Values are `int`, which also holds
+# an `entity` handle or any small id; for richer values, use the Value.* tree.
+#
+# ludicc splices this file into any program that mentions `Dict.*` or `Set.*`;
+# it is a self-contained fragment (only compiler intrinsics), so a plain tool
+# works as well as a game. The namespaces (emit_call.ludic) alias each method to
+# the matching `dict_*` / `set_*` function below. A Set is just a Dict whose
+# values are ignored, so `Set.*` delegates to the same table.
+# ============================================================================
+
+const DICT_EMPTY: int = 0    # slot never used
+const DICT_USED:  int = 1    # slot holds a live key
+const DICT_TOMB:  int = 2    # slot held a key that was removed
+
+# keys: one 8-byte pointer slot each (null when empty); vals/used: one word each.
+property Dict { keys: pointers, vals: words, used: words, cap: int = 0, count: int = 0 }
+
+# (re)allocate the three parallel arrays to `cap` slots, all cleared
+function dict_init(d: Dict, cap: int) -> void {
+  d.cap = cap;  d.count = 0
+  d.keys = bytes(cap * 8);  fill(d.keys, 0, cap * 8)   # null slots
+  d.vals = words(cap);      fill(d.vals, 0, cap * 4)
+  d.used = words(cap);      fill(d.used, 0, cap * 4)
+}
+
+function dict_new() -> Dict {
+  let d = new Dict
+  dict_init(d, 16)
+  return d
+}
+
+# FNV-1a over the key's bytes -> a non-negative slot index in [0, cap)
+function dict_slot(key: pointer, cap: int) -> int {
+  var h = 0 - 2128831035          # FNV-1a offset basis, as a signed i32
+  var i = 0
+  while key[i] != 0 { h = (h ^ key[i]) * 16777619;  i = i + 1 }
+  h = h & 2147483647              # clear the sign bit -> non-negative
+  return h - (h / cap) * cap      # h % cap
+}
+
+# slot index of `key`, or -1 if absent
+function dict_find(d: Dict, key: pointer) -> int {
+  if d.cap == 0 { return 0 - 1 }
+  var idx = dict_slot(key, d.cap)
+  var probes = 0
+  while probes < d.cap {
+    let u = d.used[idx]
+    if u == DICT_EMPTY { return 0 - 1 }
+    if u == DICT_USED and d.keys[idx] == key { return idx }
+    idx = idx + 1
+    if idx >= d.cap { idx = 0 }
+    probes = probes + 1
+  }
+  return 0 - 1
+}
+
+# grow to double capacity and reinsert every live key
+function dict_grow(d: Dict) -> void {
+  let oldcap = d.cap
+  let oldkeys = d.keys
+  let oldvals = d.vals
+  let oldused = d.used
+  var nc = oldcap * 2
+  if nc < 16 { nc = 16 }
+  dict_init(d, nc)
+  var i = 0
+  while i < oldcap {
+    if oldused[i] == DICT_USED { dict_set(d, oldkeys[i], oldvals[i]) }
+    i = i + 1
+  }
+}
+
+# insert or update key -> value
+function dict_set(d: Dict, key: pointer, value: int) -> void {
+  if d.cap == 0 { dict_init(d, 16) }
+  if (d.count + 1) * 10 >= d.cap * 7 { dict_grow(d) }      # load factor 0.7
+  var idx = dict_slot(key, d.cap)
+  var tomb = 0 - 1
+  var probes = 0
+  while probes < d.cap {
+    let u = d.used[idx]
+    if u == DICT_EMPTY {
+      var slot = idx
+      if tomb >= 0 { slot = tomb }
+      d.keys[slot] = key;  d.vals[slot] = value;  d.used[slot] = DICT_USED
+      d.count = d.count + 1
+      return
+    }
+    if u == DICT_TOMB { if tomb < 0 { tomb = idx } }
+    if u == DICT_USED and d.keys[idx] == key { d.vals[idx] = value;  return }
+    idx = idx + 1
+    if idx >= d.cap { idx = 0 }
+    probes = probes + 1
+  }
+  if tomb >= 0 {
+    d.keys[tomb] = key;  d.vals[tomb] = value;  d.used[tomb] = DICT_USED
+    d.count = d.count + 1
+  }
+}
+
+# the value for key, or 0 if absent (use dict_get_or to distinguish a stored 0)
+function dict_get(d: Dict, key: pointer) -> int {
+  let i = dict_find(d, key)
+  if i < 0 { return 0 }
+  return d.vals[i]
+}
+
+function dict_get_or(d: Dict, key: pointer, fallback: int) -> int {
+  let i = dict_find(d, key)
+  if i < 0 { return fallback }
+  return d.vals[i]
+}
+
+function dict_has(d: Dict, key: pointer) -> bool { return dict_find(d, key) >= 0 }
+
+# remove key (a no-op if absent); leaves a tombstone so probes still find later keys
+function dict_remove(d: Dict, key: pointer) -> void {
+  let i = dict_find(d, key)
+  if i < 0 { return }
+  d.used[i] = DICT_TOMB
+  d.keys[i] = null
+  d.count = d.count - 1
+}
+
+function dict_size(d: Dict) -> int { return d.count }
+
+function dict_clear(d: Dict) -> void {
+  if d.cap == 0 { return }
+  fill(d.keys, 0, d.cap * 8)
+  fill(d.used, 0, d.cap * 4)
+  d.count = 0
+}
+
+# every live key, in unspecified order
+function dict_keys(d: Dict) -> []pointer {
+  let out = new []pointer
+  var i = 0
+  while i < d.cap {
+    if d.used[i] == DICT_USED { push(out, d.keys[i]) }
+    i = i + 1
+  }
+  return out
+}
+
+# ---- Set: a Dict whose values are ignored ----------------------------------
+
+function set_new() -> Dict { return dict_new() }
+function set_add(s: Dict, key: pointer) -> void { dict_set(s, key, 1) }
+function set_has(s: Dict, key: pointer) -> bool { return dict_has(s, key) }
+function set_remove(s: Dict, key: pointer) -> void { dict_remove(s, key) }
+function set_size(s: Dict) -> int { return dict_size(s) }
+function set_clear(s: Dict) -> void { dict_clear(s) }
+function set_members(s: Dict) -> []pointer { return dict_keys(s) }

selfhost/backend/emit_call.ludic

@@ -365,6 +365,30 @@ function emit_ns_call(ns: pointer, meth: pointer, e: Node) -> Val {
     if (meth == "rescale") { bare = "decimal_rescale";  push(labels, "d"); push(labels, "places") }
     if (meth == "str")     { bare = "decimal_str";      push(labels, "d") }
   }
+  # Dict.* / Set.* -> the hash-table engine (runtime/native/dict.ludic, spliced
+  # on demand). Ordinary Ludic functions, so the generic call path resolves them
+  # to @fn_dict_* / @fn_set_* and keeps their return types (Dict / int / bool /
+  # []pointer).
+  if (ns == "Dict") {
+    if (meth == "new")     { bare = "dict_new" }
+    if (meth == "set")     { bare = "dict_set";    push(labels, "d"); push(labels, "key"); push(labels, "value") }
+    if (meth == "get")     { bare = "dict_get";    push(labels, "d"); push(labels, "key") }
+    if (meth == "get_or")  { bare = "dict_get_or"; push(labels, "d"); push(labels, "key"); push(labels, "fallback") }
+    if (meth == "has")     { bare = "dict_has";    push(labels, "d"); push(labels, "key") }
+    if (meth == "remove")  { bare = "dict_remove"; push(labels, "d"); push(labels, "key") }
+    if (meth == "size")    { bare = "dict_size";   push(labels, "d") }
+    if (meth == "clear")   { bare = "dict_clear";  push(labels, "d") }
+    if (meth == "keys")    { bare = "dict_keys";   push(labels, "d") }
+  }
+  if (ns == "Set") {
+    if (meth == "new")     { bare = "set_new" }
+    if (meth == "add")     { bare = "set_add";     push(labels, "s"); push(labels, "key") }
+    if (meth == "has")     { bare = "set_has";     push(labels, "s"); push(labels, "key") }
+    if (meth == "remove")  { bare = "set_remove";  push(labels, "s"); push(labels, "key") }
+    if (meth == "size")    { bare = "set_size";    push(labels, "s") }
+    if (meth == "clear")   { bare = "set_clear";   push(labels, "s") }
+    if (meth == "members") { bare = "set_members"; push(labels, "s") }
+  }
   if (ns == "Grid") {
     if (meth == "line")          { bare = "grid_line";          push(labels, "x0"); push(labels, "y0"); push(labels, "x1"); push(labels, "y1") }
     if (meth == "blocked")       { bare = "grid_blocked";       push(labels, "x"); push(labels, "y"); push(labels, "wall") }

selfhost/frontend/parse.ludic

@@ -176,6 +176,7 @@ function p_postfix() -> Node {
     if is_op(".") { pi = pi + 1; let m = node(E_MEMBER); m.a = e; m.s = eat_id(); e = m
       if e.a.kind == E_ID and e.a.s == "Regex" { g_uses_regex = true }   # splice the regex runtime on demand
       if e.a.kind == E_ID and (e.a.s == "BigInt" or e.a.s == "Decimal") { g_uses_bignum = true }   # splice the bignum runtime on demand
+      if e.a.kind == E_ID and (e.a.s == "Dict" or e.a.s == "Set") { g_uses_dict = true }   # splice the hash-table runtime on demand
       if e.a.kind == E_ID and e.a.s == "Query" { g_uses_query = true }   # splice the ECS spatial-query runtime on demand
       if e.a.kind == E_ID and e.a.s == "Reflect" { g_uses_reflect = true }   # force-emit the reflection ABI (Reflect.* reads the world schema)
       if e.a.kind == E_ID and e.a.s == "Light" { g_uses_light = true }   # splice the 2D light-accumulation pass on demand
@@ -423,6 +424,7 @@ var loaded_paths: []pointer
 var cur_dir: pointer
 var g_uses_regex: bool = false    # a program mentioned Regex.* -> splice the regex runtime
 var g_uses_bignum: bool = false   # a program mentioned BigInt.*/Decimal.* -> splice the bignum runtime
+var g_uses_dict: bool = false     # a program mentioned Dict.*/Set.* -> splice the hash-table runtime
 var g_uses_query: bool = false    # a program mentioned Query.* -> splice the query runtime + reflection ABI
 var g_uses_reflect: bool = false  # a program mentioned Reflect.* -> force-emit the reflection ABI
 var g_uses_light: bool = false    # a program mentioned Light.* -> splice the 2D light pass
@@ -608,6 +610,13 @@ function maybe_splice_runtime() -> void {
     do_import("runtime/native/bignum.ludic")
     cur_dir = saved
   }
+  # any program that uses Dict.*/Set.* gets the hash-table engine spliced in
+  # (self-contained — only compiler intrinsics — so a plain tool works too).
+  if g_uses_dict {
+    cur_dir = ""
+    do_import("runtime/native/dict.ludic")
+    cur_dir = saved
+  }
   # any program that uses Query.* gets the ECS spatial-query helpers spliced in;
   # they read entity state through the reflection ABI (emit_decl force-emits it
   # for a Query program even when it declares no events).
@@ -723,6 +732,7 @@ function parse_program() -> void {
   g_toggled_layers = new []pointer
   g_uses_regex = false
   g_uses_bignum = false
+  g_uses_dict = false
   g_uses_query = false
   g_uses_reflect = false
   g_uses_esys = false

tools/docgen/inventory.json

@@ -412,6 +412,26 @@
     "decimal-rescale",
     "decimal-str"
   ],
+  "dict": [
+    "dict-new",
+    "dict-set",
+    "dict-get",
+    "dict-get_or",
+    "dict-has",
+    "dict-remove",
+    "dict-size",
+    "dict-clear",
+    "dict-keys"
+  ],
+  "set": [
+    "set-new",
+    "set-add",
+    "set-has",
+    "set-remove",
+    "set-size",
+    "set-clear",
+    "set-members"
+  ],
   "duration": [
     "duration-seconds",
     "duration-minutes",

tools/x/test.ludic

@@ -194,6 +194,7 @@ function cmd_test() -> int {
   feat_case("library/uuid", "", "1 2 3 4 5 6 7 8 9 10", "uuid.ludic (Uuid v4/v7 format, version/variant, parse/equals)")
   feat_case("library/noise", "", "1 2 3 4 5 6 7 8 9 10 11", "noise.ludic (Noise value/perlin/simplex/fbm/cellular determinism + range)")
   feat_case("library/bignum", "", "1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16", "bignum.ludic (BigInt arbitrary-precision + Decimal exact base-10 money)")
+  feat_case("library/containers", "", "1 2 3 4 5 6 7 8 9 10 11 12 13 14", "containers.ludic (Dict string-keyed hash map + Set string set)")
   feat_case("library/regex", "", "1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18", "regex.ludic (Regex match/find/groups/classes/quantifiers/replace + linear-time safety)")
   feat_case("library/grid", "", "1 2 3 4 5 6 7 8 9 10 11 12 13", "grid.ludic (Grid line/flood/line_of_sight + A* pathfinding over the tilemap)")
   feat_case("library/anim", "", "1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34", "anim.ludic (Anim frame/once/pingpong/cell + Tween progress/loop/yoyo/ease/number/round/point/tint)")