modules/uo/SCHEMA.md

@@ -245,29 +245,49 @@ marketplace listing — but with no table to resolve it against, the character s
 | Table | Shape |
 |---|---|
 | `shard_clilocs` | `number` INT PK, `flag`, `text` TEXT |
-| `shard_cliloc_meta` | Singleton (`id = 1`), `payload` JSON (source file, sha256, count, `parserVersion`), `imported_at` |
+| `shard_cliloc_meta` | Singleton (`id = 1`), `payload` JSON (`source` — `bridge` or `file` — the base's fingerprint under `base`, the overlay `hashes`, per-source counts, `parserVersion`), `imported_at` |
 
 Import-owned and all-or-nothing in one transaction, same contract as the atlas — including **`DELETE`,
 not `TRUNCATE`**, for the same reason.
 
-**Sourced from files the operator supplies**, at a path from the `cliloc_client_path` setting falling
-back to `UO_CLIENT_PATH`. Nothing client-derived is committed: UO's strings are EA's, exactly as the
-creature sprites are. A shard with nothing configured is fully supported — names render as ids. Full
-design and operator guide: [`CLILOCS.md`](../../website/CLILOCS.md).
+**The base table comes from the SHARD** on any install with uo-link configured (Protocol 8, phase 2):
+it reads its own client's compressed `Cliloc.enu` and serves the table paged over the bridge, so
+nothing is converted and nothing is copied to the web host. Without a shard link it falls back to a
+converted file on disk at a path from the `cliloc_client_path` setting, then `UO_CLIENT_PATH` — the
+pre-protocol-8 pipeline, deprecated rather than removed so an existing install keeps working.
+
+**Overlays are always the filesystem's**, either way: ServUO has no server-side notion of a custom
+cliloc, so `custom/` is the only place shard-added ids exist and there is nothing on the shard to ask
+for. That gap is in the *game*, not in this pipeline.
+
+Nothing client-derived is committed: UO's strings are EA's, exactly as the creature sprites are. A
+shard with nothing configured is fully supported — names render as ids. Full design and operator
+guide: [`CLILOCS.md`](../../website/CLILOCS.md).
 
 **It reads a SET of sources, not one file**, because shards edit items and add new ones and those
-carry cliloc ids no stock client table has. A base (the converted client table) plus every overlay
-under `custom/` are re-read on every boot and hash-gated **together**, exactly as the atlas re-reads
+carry cliloc ids no stock client table has. A base (from the shard, or a converted file) plus every
+overlay under `custom/` are hash-gated **together**, exactly as the atlas re-reads
 `Regions.xml` + `Locations/*.xml` + `Spawns/*.xml` + `ChampionSpawns.xml`. Later sources win, so an
 overlay both adds ids and overrides stock ones, and adding one custom item never means re-exporting a
 5 MB client file. Scale, measured on the live shard: its script tree references 16,434 cliloc ids and
 only 37 are absent from stock — tens of entries against a 67k base, which is why this is an overlay
 and not a second table.
 
-The conversion step is not avoidable: **every current client ships its cliloc files compressed**
-(first DWORD's high byte `0x8E`), and ServUO's own bundled `Ultima.StringList` cannot read that
-either — so the shard cannot supply names on our behalf. The plain layout and a delimited text export
-are both accepted, sniffed by header rather than extension.
+**The conversion step used to be unavoidable, and is not any more.** Every current client ships its
+cliloc files compressed (first DWORD's high byte `0x8E`) and ServUO's own bundled
+`Ultima.StringList` cannot read that either — which is why, for two protocol versions, the operator
+had to install UOFiddler, build a converter against its `Ultima.dll` and copy a 5 MB file to the web
+host. Protocol 8 phase 2 ported the Mythic decompressor into the overlay, so **the shard reads its
+own client and supplies the names**. The file half survives only as the fallback above, where the
+plain layout and a delimited text export are both accepted, sniffed by header rather than extension.
+
+Two consequences for what this table holds. `shard_cliloc_meta.payload` carries the base's
+fingerprint under `meta.base` (the shard's file size, mtime, hash and `EXTRACTOR_VERSION`) separately
+from the overlay hashes, because on the bridge the old `clilocs.plain` label is *supposed* to
+disappear and a single hash map would read that upgrade as a vanished source. And **boot does not
+import on the bridge path**: a file could be re-hashed locally on every restart, but asking the shard
+would put a sidecar round trip in the boot sequence for a table that changes only when an operator
+patches their client. Importing is an admin action.
 
 Three decisions worth stating: