feat(all): add read model for the inventoryManager extended feed

[MahtraDR]

Problem

Lich can't answer whole-inventory questions — "find item X anywhere", "audit everything I carry", per-container weight budgeting. GameObj only holds containers the passive <container>/clearContainer stream has already streamed (hands, worn, a pack you just opened), and carries no weight, capacity, encumbrance, or closed/locked state. Unopened containers are simply absent from GameObj.@@contents.

The Saga "extended feed" inventoryManager stream (confirmed live on both GS and DR) returns the player's entire nested item tree in one response — every container's contents at once, with per-item weight, container load (in_encum), and closed/locked flags. Nothing consumes it today.

Fix

Add Lich::Common::Inventory — a standalone, read-only snapshot model that parses one <inventoryManager> response into an immutable, id-keyed tree. It is a passive tap on the game parser thread and is completely inert unless the extended feed appears, so non-Saga sessions are unaffected. It bridges to GameObj by exist id (borrowing type/sellable) rather than duplicating or rewriting it.

Safety properties, verified against a real 418-item DR capture:

• Crash-safe. observe never mutates the stream, never sends upstream, and never raises — the parser thread's only rescue does @socket.close and would drop the player's session. The new snapshot is built into a local and swapped in atomically last under a mutex.
• Fails closed. Ox.sax_parse doesn't raise on truncated input (it auto-closes), so damage is detected via a collecting error() callback and a structural-close check. Any parse error, missing close, continuation/paginated fragment, or a zero-item passive response over a non-empty snapshot is discarded and the prior snapshot kept.
• Locked ≠ empty. A locked container emits zero children by game design (treasure boxes populate on open; gem pouches aggregate) and is modeled as opaque (contents unknown), never empty; used_lbs/space_left are nil for it. A merely closed container still enumerates its contents.
• Correct classification. type/sellable derive from each item's own noun/name via a transient GameObj (GameObj[id] is nil for exactly the delta items — those in unopened containers).
• Bounded refresh. Runs on the caller thread with a per-id completion latch, a bounded timeout, and capped-exponential-backoff re-probing when the feed is absent — no permanent latch, no repeated stalls. Returns an immutable snapshot object (or nil), never blocks unbounded.

Wiring: required after gameobj in the load list; one guarded Inventory.observe(server_string) call on the parser thread beside process_downstream_hooks.

Every public class/method carries YARD (per docs/YARD-STYLE-GUIDE.md) with runnable @examples and documented nil/failure returns.

Tests

DAMP specs in spec/lib/common/inventory_spec.rb run against the real capture fixture (spec/fixtures/inventory/dr_full_inventory.xml) plus hand-built edge cases: truncation, continuation fragments, paginated responses, cyclic loc, self-closing/empty envelopes, empty-passive guard, feed-absent backoff, nil-capacity space_left, delta-item classification, and crash safety. Unshipped paths (continuation assembly, multi-line) are not faked.

• New: 49 examples, 0 failures
• Full suite: 6330 examples, 0 failures
• rubocop clean on all touched files

User- and developer-facing wiki guides (Inventory-Module-Guide, Inventory-Module-Developer-Guide) are drafted and will be published to the lich-5.wiki after review.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: 7cb17fdc-9eba-43df-b478-73159e4d95fe

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[mrhoribu]

This is going to populate a lot of new GameObjs the way it's written currently and not reuse existing GameObjs. Suggest swapping to:

@bridge_gameobj ||= GameObj.index_or_create(@id, @noun, @name, @before, @after)

https://github.com/elanthia-online/lich-5/blob/main/lib/common/gameobj.rb#L475

Also suggest have a way to have the LONG parsed to have the before/after (dropping the a/an/some) so the above can get the full name support on the GameObj

I'd also suggest using smart logic to know if something is in a container/ground/worn/etc to use the various GameObj.new_loot, GameObj.new_room_desc, or GameObj.new_inv. So that it has some nested functionality.

Basically, GameObj.new by itself should be avoided at all costs.

[MahtraDR]

Done in be0abd7:

#1 / #4 (avoid bare GameObj.new): the classification bridge now builds via GameObj.index_or_create (memoized per item), so it reuses an existing pooled instance for the same id|noun|name and joins the shared index + TTL instead of allocating an unpooled object each time. It's still deliberately not pushed into a registry, so GameObj[] won't start resolving delta items in unopened containers.

#2 (parse the LONG for before/after): it now feeds the full descriptive name — the item's long when present — with the leading a/an/some/the peeled into before_name, so GameObj#full_name reconstructs the whole phrase and classification matches on name/noun/full_name the way it does for a live GameObj. Added a spec that classifies via a full_name-only pattern to lock it in (it failed with the old short-name feed).

#3 (location-aware new_inv / new_loot / new_room_desc): I'd like to grab a few minutes with you to make sure I build exactly what you have in mind here. This one has Inventory populate the GameObj registries, which is a bigger step than the read-model separation the current design landed on, and I want to get the details right — e.g. @@contents for unopened containers (and how it interacts with commit_container when one is later opened), worn items vs @@inv/commit_inv, and how to route ground items (loc='room') between new_loot and new_room_desc when the wire doesn't distinguish them. Will ping you to talk it through.

[MahtraDR]

#3 is implemented (68ceaea). Live DR probing first turned up that the feed carries more relations than the design had assumed — so the mapping is richer than we'd discussed:

• righthand,player / lefthand,player — held items (confirmed both hands)
• atfeet,player — items at the player's own feet
• room — the shared room floor: two characters observing the same room get the same ground item by the same global exist id

Location → GameObj mirror, on each committed snapshot (parser thread), all via index_or_create/new_*, never bare new:

loc	GameObj home
in,{id} / on,{id}	new_inv(…, {id}) → GameObj.contents[{id}] — incl. unopened containers
worn,player	new_inv(…, nil) → GameObj.inv (deduped by exist id)
righthand/lefthand,player	new_right_hand / new_left_hand
atfeet,player / room	new_loot → GameObj.loot

The hand/loot constructors take only a name, so I backfill before_name/after_name afterward (nil-only, never clobbering the classic values) to keep full_name classification working. Classic stream stays live-authoritative — commit_inv/commit_container replace our writes for opened/worn slots, so those are transient; the durable win is @@contents for unopened containers. GameObj[id] now resolves delta items via @@contents, so the earlier "nil for delta items" concern is gone.

Also fixed two things the hand data exposed: worn? now keys on relation == 'worn' (was parent == 'player', which mis-bucketed held items as worn), and total_weight counts worn and held, excluding ground.

Full suite 6345 examples / 0 failures, rubocop clean, CI green. If any of the mapping choices (worn→inv dedupe, room+atfeet→loot, hand-slot writes) aren't what you had in mind, happy to adjust.

[MahtraDR]

Correction to the mapping above (f56a123): atfeet,player is on-character (at the player's own feet), so it does not go to @@loot — that registry is off-character room-floor loot (the classic room objs stream, cleared on nav). Only room (the shared room floor) maps to new_loot now; atfeet is pooled for identity/classification and surfaced via Inventory.at_feet only.

[mrhoribu]

this is still missing the after_name bit. Here's some sample data mappings. I think the a/an/some/the may very well go into the before_name but I'm also ok with that being nil instead for those. Since I know you also store some of the get cmd stuff in there on the DR side

<i id='165666521' loc='righthand,player' name="a gnarled,rowan,crook" long="a $_gnarled rowan crook$_ wound with knotted yarn" weight='2'/>
id: 165666521
noun: crook
name: gnarled rowan crook
before: nil
after: wound with knotted yarn

<i id='165666628' loc='worn,player' name="a tooled,leather coin,bag" long="a tooled leather drawstring coin bag" weight='1'/>
id: 165666628
noun: bag
name: tooled leather drawstring coin bag
before: nil
after: nil

<i id='145925572' loc='worn,player' name="a,linen,badge" long="a tin-bound linen badge" weight='1'/>
id: 145925572
noun: badge
name: tin-bound linen badge
before: nil
after: nil

<i id='165666522' loc='worn,player' name="a voluminous,mist tartan,cloak" long="a $_voluminous mist tartan cloak$_ lined in silver-tipped aquerne" weight='5' in_max='2500'/>
id: 165666522
noun: cloak
name: voluminous mist tartan cloak
before: nil
after: lined in silver-tipped aquerne

[MahtraDR]

Fixed in 4c277e1 — the $_ markers and after_name are now handled:

• Split the raw long on the $_..._$ markers: the text between them is name, the text after them becomes after_name.
• Dropped the leading article with before_name left nil (went with nil per your note, since DR already uses before_name for the get-command context).
• Also strips the $_ markers from Item#long so script authors get a clean description.

Verified against all four of your samples:

id	noun	name	before	after
165666521	crook	gnarled rowan crook	nil	wound with knotted yarn
165666628	bag	tooled leather drawstring coin bag	nil	nil
145925572	badge	tin-bound linen badge	nil	nil
165666522	cloak	voluminous mist tartan cloak	nil	lined in silver-tipped aquerne

Each is now a spec case. One thing your data surfaced that's worth a separate note: loc='righthand,player' — the feed does emit righthand/lefthand relations, which the earlier design notes had assumed it didn't. That's orthogonal to this thread (it's about top-level bucketing, not the bridge), so I'll fold it into the #3 conversation rather than change it here.

[MahtraDR]

@mrhoribu I've made some big changes to this for how it deals with pagination/continuation if you wouldn't mind looking again?