initial: inventory-list v0.1.0 — list-container inventory over engine entity-tree

Provides add/remove/contents/contains/count over composition entities
acting as list containers. Items attach as synthetic children under
item.<n> slots; renderable tag toggled via composition.set_tag on
add/remove. Slot counter is reconstruction-safe (derived from
get_children scan, no persisted state). Depends on lib-core.composition
0.2.0 (get_container + set_tag).

init.lua

@@ -0,0 +1,172 @@
+-- =====================================================================
+-- lib-core.inventory-list v0.1.0 — List-Container Inventory
+--
+-- Manages a composition-entity acting as a list-container.
+-- Items are attached as synthetic engine.entity children under
+-- monotonically-increasing slot names (item.1, item.2, ...).
+--
+-- Surface:
+--   inventory.add(container, item)
+--   inventory.remove(container, item) -> item
+--   inventory.contents(container) -> {item, ...}
+--   inventory.contains(container, item) -> bool
+--   inventory.count(container) -> number
+--
+-- Deps:
+--   lib-core.composition (set_tag, get_container)
+--   engine.entity.* (attach, detach, get_children, get_parent)
+-- =====================================================================
+
+local composition = require("lib-core.composition")
+
+local M = {}
+
+-- ---------- internal helpers ----------
+
+-- Compute the next synthetic slot name for the given container.
+-- Scans existing children for slots matching "item.<n>" and returns
+-- "item.<max_n + 1>". This is fully derivable from the tree state,
+-- so no counter needs to be persisted — reconstruction-safe after load.
+local function next_slot(container)
+    local max_n = 0
+    for slot_name, _ in pairs(container:get_children()) do
+        local n = tonumber(slot_name:match("^item%.(%d+)$"))
+        if n and n > max_n then max_n = n end
+    end
+    return string.format("item.%d", max_n + 1)
+end
+
+-- Find the slot name under which `item` is attached to `container`.
+-- Returns the slot string or nil if not found.
+local function slot_of(container, item)
+    for slot_name, child in pairs(container:get_children()) do
+        if child == item then
+            return slot_name
+        end
+    end
+    return nil
+end
+
+-- Validate that container is a composition-entity with container-block
+-- kind="list" and no constraint fields. Errors loudly on violation.
+local function validate_container(container)
+    local block = composition.get_container(container)
+    if block == nil then
+        error("inventory.add: entity has no container block " ..
+              "(template must declare container={kind='list'})")
+    end
+    if block.kind ~= "list" then
+        error(string.format(
+            "inventory.add: container.kind must be 'list' (got '%s')",
+            tostring(block.kind)))
+    end
+    -- Double-belt: reject any declared constraint fields (composition v0.2
+    -- already rejects these at template-load, but we guard here too so the
+    -- lib is safe against containers created outside the composition gateway).
+    local constraint_fields = {
+        "weight_max", "volume_max", "grid",
+        "accepts_fluid", "accepts_gas", "restrictions",
+    }
+    for _, field in ipairs(constraint_fields) do
+        if block[field] ~= nil then
+            error(string.format(
+                "inventory.add: container declares '%s' which is a " ..
+                "Phase-F/G constraint not supported in v0.1",
+                field))
+        end
+    end
+end
+
+-- ---------- public API ----------
+
+-- add(container, item)
+-- Validates container (list, no constraints) and item (has stack_mode,
+-- stack_mode == "individual"). Detaches item from any current parent,
+-- attaches to container under a fresh synthetic slot, hides from
+-- renderable index.
+function M.add(container, item)
+    -- 1. Validate container.
+    validate_container(container)
+
+    -- 2. Validate item has stack_mode.
+    local sm = item:get_property("stack_mode")
+    if sm == nil or sm == "" then
+        error("inventory.add: entity is not an item (no 'stack_mode' property)")
+    end
+
+    -- 3. Validate stack_mode == "individual".
+    if sm ~= "individual" then
+        error(string.format(
+            "inventory.add: stack_mode='%s' is not supported in v0.1 " ..
+            "(only 'individual')",
+            tostring(sm)))
+    end
+
+    -- 4. Detach from current parent if any.
+    local old_parent = item:get_parent()
+    if old_parent ~= nil then
+        local old_slot = slot_of(old_parent, item)
+        if old_slot then
+            entity.detach(old_parent, old_slot)
+        end
+    end
+
+    -- 5. Determine new slot and attach.
+    local slot = next_slot(container)
+    entity.attach(container, slot, item)
+
+    -- 6. Remove from renderable index.
+    composition.set_tag(item, "renderable", false)
+end
+
+-- remove(container, item) -> item
+-- Detaches item from container, restores renderable tag, returns item.
+-- Loud-Error if item is not in container.
+function M.remove(container, item)
+    local slot = slot_of(container, item)
+    if slot == nil then
+        error("inventory.remove: item is not in this container")
+    end
+    entity.detach(container, slot)
+    composition.set_tag(item, "renderable", true)
+    return item
+end
+
+-- contents(container) -> {item, ...}
+-- Returns a stable-ordered list of all items in the container.
+-- Filters children by item-recognition rule (has stack_mode property).
+-- Sorted by the numeric suffix of the synthetic slot for stable ordering.
+function M.contents(container)
+    local children = container:get_children()
+    -- Collect slot/entity pairs whose slot matches item.<n>.
+    local entries = {}
+    for slot_name, child in pairs(children) do
+        local n = tonumber(slot_name:match("^item%.(%d+)$"))
+        if n ~= nil then
+            -- Item-recognition: entity must have stack_mode property.
+            local sm = child:get_property("stack_mode")
+            if sm ~= nil and sm ~= "" then
+                table.insert(entries, {n = n, entity = child})
+            end
+        end
+    end
+    -- Sort by n for stable ordering.
+    table.sort(entries, function(a, b) return a.n < b.n end)
+    local out = {}
+    for _, entry in ipairs(entries) do
+        table.insert(out, entry.entity)
+    end
+    return out
+end
+
+-- contains(container, item) -> bool
+function M.contains(container, item)
+    return slot_of(container, item) ~= nil
+end
+
+-- count(container) -> number
+function M.count(container)
+    return #M.contents(container)
+end
+
+return M