Document instanced zones across all three audiences (#422)
Round 36 shipped instanced zones (#72) and Round 37 changed four things
about them; only the engine-developer page existed, and it predated the
Round 37 work.
Builder — new page, Building Instanced Zones:
- the `instanceable: true` opt-in and why it is opt-in (a mint runs the
zone's boot resets, so every copy is a generation faucet that also
routes around every in-world gate: a private copy has no doorman)
- the start_room requirement, enforced at mint, and both reasons for it
- mud.send_to_instance is self-only, and what "the invoking actor"
actually resolves to per attach point: a custom command or an ability
acts as the PLAYER, but on("enter")/on("greet") act as the room/mob,
so an entity trigger cannot send the entrant in. The dungeon-door
idiom is a verb the player types
- mud.zone() and why `ev.zone ~= "darkwood"` matches inside every copy
- the exhaustive does-not-work list with the why for each: persistent
resets (durable item dupe), timed repop (farmable), signal_region /
signal_world (the envelope drops source), reserved director schedule
events, nesting, the reload freeze
- the engine-owned player-facing lines, and the caps to design around
Sysadmin — a new section in Running at Scale plus the prune-guard
remedy in Content Pack Operations:
- the caps ARE PER PROCESS, so an account gets perAccount x shards; and
they are not config knobs today (compile-time defaults + a Go option,
no TELOS_INSTANCE_* env var wires them)
- shard-local and unleased: not in the placement pool, never
rebalanced, never a handoff destination, and they die with the shard
- metrics label by template because an instance id is unbounded,
player-driven cardinality; logs go the other way and keep the id.
Adds the missing telos.zone.instances gauge to the metrics table
- drain step 0 ejects occupants to their exit anchor
- the reload freeze and the pinned-instance advisory
- Round 37: a mint builds from the live content snapshot and refuses an
incomplete build (#418); the TTL'd dir:tmplinuse claim, so a content
pull can be REFUSED while parties are inside copies and clears ~45s
after the last one (#416); the concurrent bounded reaper sweep
(#419); and the up-to-3-minute rebalance deferral with its
"rebalance deferred" log lines (#421)
Mudlib — Instanced Zones:
- the routing-vs-isolation rule spelled out (the room map is the
isolation boundary; the zone-segment test is only a pre-filter), and
what the build-failing lint actually covers
- the "never mint on a zone goroutine" contract with the reason, the
three-hop entry, why the request carries the origin zone POINTER, and
why abandonInstance is a flag rather than a record deletion
- minting from the live snapshot, and the incomplete-build refusal
- the concurrent reaper: the detached per-teardown context, and why the
bound is a smoothing bound rather than a correctness one
- the dir:tmplinuse claim as the cheapest possible analogue of a lease,
its own goroutine, and the mint kick
- the anchor's invariant DECAYS, the pre-handoverZoneTo guard and why
the placement of that guard is the load-bearing property, why the
anchors are queried rather than maintained, and why it fails open