Merge pull request 'feat(bridge)!: protocol 4 — guild rosters and per-member leaves (Teams cutover 1/6)' (#14 ) from edge into main

Reviewed-on: #14 Reviewed-by: Colby Whitlock <whitlocktech@gmail.com>
Merge pull request 'feat(bridge): carry guild rank on roster members' (#13 ) from feat/protocol4-guild-rank into edge
2026-08-19 08:54:43 +00:00 · 2026-08-17 22:49:10 +00:00 · 2026-08-17 17:34:51 -05:00 · 2026-08-17 19:28:40 +00:00 · 2026-08-17 12:52:07 -05:00 · 2026-08-07 21:32:13 +00:00
13 changed files with 1739 additions and 31 deletions
--- a/.gitea/workflows/release.yml
+++ b/.gitea/workflows/release.yml
@@ -0,0 +1,535 @@
+# Automated release for the deployable ServUO overlay.
+#
+# Trigger: every push to `main` (i.e. every merged PR).
+#
+# Why this exists: the Runic Gateway installer deploys the plugin from a release
+# tarball, not from git — the shard host gets no git and no Gitea credentials
+# (docs/installer/PLAN.md §1, §5 Phase 0.1). Until this workflow, `link` was the
+# only repo that published releases, so there was nothing for the installer to
+# fetch. This is Phase 0 item 1.
+#
+# Flow (two conceptual halves, kept separate on purpose):
+#
+#   ┌── RELEASE ENGINE (language-agnostic) ─────────────────────────────┐
+#   │  reads: latest v* git tag + conventional-commit subjects          │
+#   │  produces: next version, changelog, and (at the end) the release  │
+#   └───────────────────────────────────────────────────────────────────┘
+#   ┌── OVERLAY ADAPTER (the only repo-specific part) ──────────────────┐
+#   │  consumes: the version                                            │
+#   │  produces: runicgateway-overlay-<ver>.tar.gz + SHA256SUMS         │
+#   └───────────────────────────────────────────────────────────────────┘
+#
+# The engine is `link/.gitea/workflows/release.yml`'s, reused as its own header
+# anticipated — the plan and release steps consume only {version, changelog,
+# artifacts} and know nothing about what is inside the artifacts.
+#
+# ── Three differences from link's copy, all forced by this repo ──────────────
+#
+# 1. NO BUILD. The plugin ships as C# source and ServUO compiles it at boot; it
+#    needs ServUO reference assemblies, so there is no way to compile it here.
+#    The build gates are replaced by the structural gates below, which is the
+#    most this repo can honestly assert about an artifact.
+#
+# 2. NO BUMP COMMIT, and so no push to `main`. link has to write the version
+#    into Cargo.toml because the binary embeds it; a tarball embeds nothing but
+#    the manifest.json this job generates, so the git tag IS the version. That
+#    removes a failure mode outright: this workflow never needs `main` to accept
+#    a direct push, so no branch-protection exception is required for it.
+#
+# 3. A MANIFEST. The tarball carries manifest.json — version, commit, declared
+#    protocol version, ServUO compatibility, and a SHA256 for every file. The
+#    installer needs it because the plugin announces no version on the wire and
+#    none is queryable before ServUO boots (PLAN.md §2.6): the manifest is the
+#    only thing that lets the bundle CI verify sidecar/overlay protocol
+#    agreement BEFORE an operator installs the pair (PLAN.md §7.1, gate 1).
+#
+# Version bump (conventional commits since the last v* tag):
+#   feat!: / BREAKING CHANGE  -> major     feat: -> minor     fix|perf: -> patch
+#   nothing releasable        -> no release is cut (a docs:/chore:-only merge
+#                                deliberately does NOT cut one — PLAN.md §7.3)
+#   (first ever run, no tag)  -> releases SEED_VERSION below
+#
+# Prerequisites (Settings → Actions → Secrets on RunicGateway/servuo-plugins):
+#   REGISTRY_TOKEN  — Gitea access token with `write:repository`, to push the
+#                     tag and create the release. The final step also dispatches
+#                     RunicGateway/installer's bundle workflow, so the token
+#                     ideally has write there too — a nicety, not a requirement:
+#                     without it the step warns and that repo's nightly cron
+#                     picks the release up instead.
+#   REGISTRY_USER   — the Gitea username that token belongs to.
+#
+# These are checked by an explicit preflight step rather than left to fail
+# wherever they happen to be used first — see the comment on that step for why
+# an absent token does NOT simply fail the tag push.
+#
+# The final step POSTs to the installer repo's bundle workflow, so a new overlay
+# release recomposes the compat matrix immediately instead of waiting for that
+# repo's nightly cron (PLAN.md §7.2). It was deliberately absent until Phase 0
+# item 3 landed something to dispatch — a step that 404s on every release is
+# worse than no step.
+
+name: Release overlay
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch: {}
+
+concurrency:
+  group: release-overlay
+  cancel-in-progress: false
+
+env:
+  GITEA_HOST: gitea.whitlocktech.com
+  REPO: RunicGateway/servuo-plugins
+  # Artifact naming per PLAN.md §3.
+  ARTIFACT: runicgateway-overlay
+  # Used only for the very first release, when no v* tag exists yet. Matches the
+  # house style set by link (pre-1.0; the release version is independent of the
+  # protocol version, which lives in overlay.toml).
+  SEED_VERSION: "0.1.0"
+  # Notified after a release so the installer's compat matrix picks up this
+  # overlay immediately rather than at its next nightly run (PLAN.md §7.2).
+  INSTALLER_REPO: RunicGateway/installer
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out full history (need tags + commit log for the bump)
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      # ── RELEASE ENGINE: decide the next version + changelog ──────────────
+      - name: Plan the release (version + changelog)
+        id: plan
+        env:
+          REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+        run: |
+          set -euo pipefail
+          mkdir -p dist
+          git fetch --tags --force >/dev/null 2>&1 || true
+
+          LAST_TAG="$(git describe --tags --match 'v*' --abbrev=0 2>/dev/null || true)"
+          if [ -n "$LAST_TAG" ]; then RANGE="${LAST_TAG}..HEAD"; else RANGE="HEAD"; fi
+
+          SUBJECTS="$(git log --no-merges --format='%s' $RANGE || true)"
+          BODIES="$(git log --no-merges --format='%B' $RANGE || true)"
+
+          BUMP=none
+          if echo "$BODIES"   | grep -qE 'BREAKING[ -]CHANGE'          ; then BUMP=major; fi
+          if echo "$SUBJECTS" | grep -qE '^[a-z]+(\([^)]+\))?!:'       ; then BUMP=major; fi
+          if [ "$BUMP" = none ] && echo "$SUBJECTS" | grep -qE '^feat(\([^)]+\))?:'      ; then BUMP=minor; fi
+          if [ "$BUMP" = none ] && echo "$SUBJECTS" | grep -qE '^(fix|perf)(\([^)]+\))?:'; then BUMP=patch; fi
+
+          bump() { # <x.y.z> <major|minor|patch> -> bumped
+            IFS=. read -r MA MI PA <<< "$1"
+            case "$2" in
+              major) echo "$((MA+1)).0.0" ;;
+              minor) echo "${MA}.$((MI+1)).0" ;;
+              patch) echo "${MA}.${MI}.$((PA+1))" ;;
+            esac
+          }
+
+          RELEASE=true
+          if [ -z "$LAST_TAG" ]; then
+            VERSION="$SEED_VERSION"                  # first release: seed
+          elif [ "$BUMP" = none ]; then
+            RELEASE=false                            # no feat/fix/breaking since last tag
+            VERSION="${LAST_TAG#v}"
+          else
+            VERSION="$(bump "${LAST_TAG#v}" "$BUMP")"
+          fi
+
+          # An existing tag is NOT automatically "nothing to do". A tag with no
+          # release behind it means a previous run tagged and then died before
+          # publishing — which is exactly what happened on the first run here,
+          # when the missing REGISTRY_* secrets took the release API call to 401
+          # after the tag had already been pushed. Standing down on the tag alone
+          # would make that state permanent: every later run would see the tag,
+          # set RELEASE=false, and the release would never appear. So distinguish
+          # the two cases and finish the job the earlier run started.
+          # Note this OVERRIDES the RELEASE=false decided just above. With the tag
+          # already in place there are no releasable commits after it, so the
+          # normal path stands down — which is precisely why the stuck state
+          # could never clear itself. Recovery has to be able to say "yes,
+          # publish" for a version the bump logic considers already done.
+          REUSE_TAG=false
+          if git rev-parse -q --verify "refs/tags/v${VERSION}" >/dev/null; then
+            REL_HTTP="$(curl -s -o /dev/null -w '%{http_code}' \
+              -H "Authorization: token $(printf '%s' "${REGISTRY_TOKEN:-}" | tr -d '\r\n')" \
+              "https://${GITEA_HOST}/api/v1/repos/${REPO}/releases/tags/v${VERSION}" || echo 000)"
+            if [ "$REL_HTTP" = "200" ]; then
+              echo "Tag v${VERSION} already has a release — nothing to do."
+              RELEASE=false
+            elif [ "$REL_HTTP" = "404" ]; then
+              echo "::warning::Tag v${VERSION} exists but has no release — a previous run failed after tagging. Reusing the tag and publishing the release it is missing."
+              REUSE_TAG=true
+              RELEASE=true
+            else
+              # Anything else (000 from a network failure, 401/403 from a bad
+              # token) is not evidence of absence. Guessing "no release" here
+              # would re-publish over a good one, so refuse instead.
+              echo "::error::Could not determine whether a release exists for v${VERSION} (HTTP ${REL_HTTP}). Refusing to guess."
+              exit 1
+            fi
+          fi
+
+          # Changelog range. A recovery run has nothing after the tag, so
+          # summarize what the tag itself contains rather than emitting an empty
+          # list: the range that produced it, i.e. previous-tag..this-tag.
+          if [ "$REUSE_TAG" = true ]; then
+            PREV_TAG="$(git describe --tags --match 'v*' --abbrev=0 "v${VERSION}^" 2>/dev/null || true)"
+            if [ -n "$PREV_TAG" ]; then CL_RANGE="${PREV_TAG}..v${VERSION}"; else CL_RANGE="v${VERSION}"; fi
+            SINCE="$PREV_TAG"
+          else
+            CL_RANGE="$RANGE"
+            SINCE="$LAST_TAG"
+          fi
+          CL_SUBJECTS="$(git log --no-merges --format='%s' $CL_RANGE || true)"
+
+          {
+            echo "## ${ARTIFACT} v${VERSION}"
+            echo
+            FEATS="$(echo "$CL_SUBJECTS" | grep -E '^feat'        || true)"
+            FIXES="$(echo "$CL_SUBJECTS" | grep -E '^(fix|perf)'  || true)"
+            [ -n "$FEATS" ] && { echo "### Features";  echo "$FEATS" | sed 's/^/- /'; echo; }
+            [ -n "$FIXES" ] && { echo "### Fixes";     echo "$FIXES" | sed 's/^/- /'; echo; }
+            echo "### All changes"
+            if [ -n "$SINCE" ]; then echo "Since ${SINCE}:"; fi
+            echo "$CL_SUBJECTS" | sed 's/^/- /'
+          } > dist/CHANGELOG.md
+
+          echo "version=${VERSION}"     >> "$GITHUB_OUTPUT"
+          echo "tag=v${VERSION}"        >> "$GITHUB_OUTPUT"
+          echo "release=${RELEASE}"     >> "$GITHUB_OUTPUT"
+          echo "bump=${BUMP}"           >> "$GITHUB_OUTPUT"
+          echo "reuse_tag=${REUSE_TAG}" >> "$GITHUB_OUTPUT"
+          echo "==> release=${RELEASE} version=${VERSION} bump=${BUMP} reuse_tag=${REUSE_TAG} last_tag=${LAST_TAG:-<none>}"
+
+      # ── Credential preflight ─────────────────────────────────────────────
+      # Runs BEFORE anything is built or pushed, and only when this run intends
+      # to publish, so a docs:/chore:-only merge stays green on a repo that has
+      # no secrets.
+      #
+      # This exists because of how the first run failed. REGISTRY_USER and
+      # REGISTRY_TOKEN were empty, but the tag push SUCCEEDED anyway:
+      # actions/checkout leaves an `http.<host>.extraheader` credential in the
+      # local git config, so `git remote set-url` to a URL with empty
+      # credentials still authenticated through that leftover header. The
+      # release API call had no such fallback and returned 401 — so the run
+      # tagged the repo and then failed, which is the worst of both outcomes.
+      # Checking the secrets up front turns that into an immediate, legible
+      # failure instead of a half-published release.
+      - name: Verify release credentials are configured
+        if: ${{ steps.plan.outputs.release == 'true' }}
+        env:
+          REGISTRY_USER: ${{ secrets.REGISTRY_USER }}
+          REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+        run: |
+          set -euo pipefail
+          MISSING=""
+          [ -n "$(printf '%s' "${REGISTRY_USER:-}"  | tr -d '\r\n')" ] || MISSING="${MISSING} REGISTRY_USER"
+          [ -n "$(printf '%s' "${REGISTRY_TOKEN:-}" | tr -d '\r\n')" ] || MISSING="${MISSING} REGISTRY_TOKEN"
+          if [ -n "$MISSING" ]; then
+            echo "::error::Missing Actions secret(s):${MISSING}. Set them under Settings → Actions → Secrets on ${REPO}. REGISTRY_TOKEN needs the write:repository scope to push the tag and create the release."
+            exit 1
+          fi
+          echo "Release credentials present."
+
+      - name: Install jq
+        if: ${{ steps.plan.outputs.release == 'true' }}
+        run: |
+          set -euo pipefail
+          command -v jq >/dev/null 2>&1 && exit 0
+          SUDO=""; [ "$(id -u)" -ne 0 ] && SUDO="sudo"
+          $SUDO apt-get update -qq
+          $SUDO apt-get install -y -qq --no-install-recommends jq
+
+      # ── OVERLAY ADAPTER: gates ───────────────────────────────────────────
+      # There is no compiler to run, so these assert the things that CAN be
+      # checked without a ServUO tree — and each one has actually been a way to
+      # ship a broken overlay:
+      #
+      #   • overlay/ mirrors the server root; if Bridge.cfg or the Bridge scripts
+      #     go missing the deploy silently no-ops (PLAN.md §2.1).
+      #   • overlay/Scripts/Scripts.csproj is Phase 0 of the plugin itself — it
+      #     overwrites a stock file to fix ServUO's silent script-build bug. An
+      #     overlay shipped without it installs code that never compiles, and
+      #     ServUO reports success anyway.
+      #   • a malformed .patch is invisible until an operator runs the patch tier
+      #     on their live shard. `git apply --stat` parses the diff without
+      #     needing the target files present.
+      #   • each patch's companion .cs must exist, since it references symbols
+      #     the patch introduces and is meaningless without it (PLAN.md §2.2).
+      #   • patches/tier.json must describe every .patch and nothing but. That
+      #     table is what tells the installer which patches form one unit, which
+      #     companion follows which, and whether a CORE rebuild is needed — a
+      #     patch added without it would be shipped and silently never offered.
+      - name: Validate the overlay and patch tier
+        if: ${{ steps.plan.outputs.release == 'true' }}
+        run: |
+          set -euo pipefail
+          fail() { echo "::error::$*"; exit 1; }
+
+          [ -f overlay/Config/Bridge.cfg ]        || fail "overlay/Config/Bridge.cfg is missing"
+          [ -f overlay/Scripts/Scripts.csproj ]   || fail "overlay/Scripts/Scripts.csproj is missing (the silent-build-bug fix)"
+          [ -d overlay/Scripts/Custom/Bridge ]    || fail "overlay/Scripts/Custom/Bridge/ is missing"
+
+          CS_COUNT="$(find overlay/Scripts/Custom/Bridge -name '*.cs' | wc -l)"
+          [ "$CS_COUNT" -gt 0 ] || fail "overlay/Scripts/Custom/Bridge/ contains no .cs files"
+          echo "overlay: ${CS_COUNT} bridge script(s)"
+
+          for p in patches/*.patch; do
+            [ -e "$p" ] || fail "patches/ contains no .patch files"
+            echo "--- ${p}"
+            git apply --stat "$p" || fail "${p} is not a parseable unified diff"
+          done
+
+          # The tier table, checked in BOTH directions. A patch missing from
+          # tier.json ships but is never offered to an operator; a tier.json
+          # entry naming a file that is not there makes the installer report a
+          # feature it cannot apply. Neither surfaces until someone runs the
+          # tier on a live shard, so both fail the release here instead.
+          [ -f patches/tier.json ] || fail "patches/tier.json is missing (the patch-tier declaration)"
+          jq -e . patches/tier.json >/dev/null || fail "patches/tier.json is not valid JSON"
+
+          DESCRIBED="$(jq -r '.features[].patches[].file' patches/tier.json | LC_ALL=C sort)"
+          PRESENT="$(cd patches && ls *.patch | LC_ALL=C sort)"
+          if [ "$DESCRIBED" != "$PRESENT" ]; then
+            echo "described by tier.json:"; echo "$DESCRIBED" | sed 's/^/  /'
+            echo "present in patches/:";    echo "$PRESENT"   | sed 's/^/  /'
+            fail "patches/tier.json and patches/*.patch disagree — every patch must be described by exactly one feature"
+          fi
+
+          # Each patch's declared target must be the file its diff actually
+          # edits. The installer cross-checks the same pair at install time and
+          # refuses on a mismatch, so catching it here saves an operator the run.
+          while IFS=$'\t' read -r PFILE PTARGET; do
+            DIFF_TARGET="$(sed -n 's|^+++ b/||p' "patches/${PFILE}" | head -1 | tr -d '\r')"
+            [ "$DIFF_TARGET" = "$PTARGET" ] \
+              || fail "patches/${PFILE} edits ${DIFF_TARGET} but tier.json declares ${PTARGET}"
+          done < <(jq -r '.features[].patches[] | [.file, .target] | @tsv' patches/tier.json)
+
+          # Companions can only be copied after their feature's patches land, so
+          # they live here rather than in overlay/ — and a missing one turns a
+          # successfully patched shard into one that does not compile.
+          for f in $(jq -r '.features[].companions[].file' patches/tier.json); do
+            [ -f "patches/${f}" ] || fail "patches/${f} is missing (a feature's companion source)"
+          done
+
+          for r in $(jq -r '.features[].rebuild' patches/tier.json); do
+            case "$r" in
+              core|scripts) ;;
+              *) fail "tier.json declares rebuild=\"${r}\"; only \"core\" or \"scripts\" are understood" ;;
+            esac
+          done
+          echo "patch tier: $(jq -r '.features | length' patches/tier.json) feature(s), $(echo "$PRESENT" | wc -l) patch(es)"
+
+          [ -f overlay.toml ] || fail "overlay.toml is missing (protocol + ServUO declarations)"
+
+      # ── OVERLAY ADAPTER: stage, manifest, package ────────────────────────
+      # The tarball has a FIXED top-level directory (runicgateway-overlay/), not a
+      # versioned one: the installer extracts and then looks for overlay/,
+      # patches/ and manifest.json at known paths, and a version-dependent prefix
+      # would make it parse the very version it is trying to read.
+      #
+      # tar flags pin ownership, mtime and member order so the same tree produces
+      # a byte-identical tarball — a checksum that changes only when content
+      # changes is worth more than one that changes every run.
+      - name: Build manifest.json and the release tarball
+        if: ${{ steps.plan.outputs.release == 'true' }}
+        run: |
+          set -euo pipefail
+          VERSION="${{ steps.plan.outputs.version }}"
+          STAGE="dist/stage/${ARTIFACT}"
+
+          mkdir -p "${STAGE}"
+          cp -r overlay  "${STAGE}/overlay"
+          cp -r patches  "${STAGE}/patches"
+
+          # tier.json is folded into manifest.json below, so the staged copy is
+          # removed: shipping it twice would give the tarball two statements of
+          # the same table, one of which nothing reads and both of which are
+          # free to drift.
+          rm -f "${STAGE}/patches/tier.json"
+
+          # Declarations from overlay.toml. Read, don't hardcode — the point of
+          # that file is that the protocol number lives in one place.
+          PROTOCOL="$(grep -m1 -E '^protocol[[:space:]]*=' overlay.toml | sed -E 's/[^0-9]//g')"
+          MIN_SERVUO="$(grep -m1 -E '^min_servuo_version[[:space:]]*=' overlay.toml | sed -E 's/.*"([^"]+)".*/\1/')"
+          PATCHED_AGAINST="$(grep -m1 -E '^patches_verified_against[[:space:]]*=' overlay.toml | sed -E 's/.*"([^"]+)".*/\1/')"
+          [ -n "$PROTOCOL" ] || { echo "::error::could not read protocol from overlay.toml"; exit 1; }
+          [ -n "$MIN_SERVUO" ] || { echo "::error::could not read min_servuo_version from overlay.toml"; exit 1; }
+          [ -n "$PATCHED_AGAINST" ] || { echo "::error::could not read patches_verified_against from overlay.toml"; exit 1; }
+          echo "==> protocol=${PROTOCOL} min_servuo=${MIN_SERVUO} patches_verified_against=${PATCHED_AGAINST}"
+
+          # The patch tier, folded in verbatim minus its comment block. Paths are
+          # rewritten to be relative to the tarball root (`patches/<file>`), which
+          # is where the installer will find them after extraction — tier.json
+          # names them relative to patches/ because that is where a maintainer
+          # editing it is looking.
+          TIER="$(jq '
+            del(._comment)
+            | .features |= map(
+                .patches    |= map(.file |= "patches/" + .)
+              | .companions |= map(.file |= "patches/" + .)
+              )' patches/tier.json)"
+
+          # Per-file SHA256 of everything shipped, as a {path: sha} object. The
+          # installer records these in install.json so a later `doctor` can tell
+          # "operator edited a deployed file" from "the overlay drifted".
+          # The `\*?` is not paranoia: sha256sum marks binary mode by prefixing the
+          # path with `*` (`<hash> *path`) instead of the two-space text-mode
+          # separator. Coreutils on Linux defaults to text mode, but a build host
+          # that doesn't would otherwise put a leading `*` on EVERY key here and
+          # silently produce a manifest whose paths match nothing.
+          FILES="$(cd "${STAGE}" \
+            && find overlay patches -type f -print0 | LC_ALL=C sort -z | xargs -0 sha256sum \
+            | jq -R -s '
+                split("\n") | map(select(length > 0))
+                | map(capture("^(?<sha>[0-9a-f]+)[ \t]+\\*?(?<path>.+)$"))
+                | map({ (.path): .sha }) | add')"
+
+          jq -n \
+            --arg    component "servuo-plugins-overlay" \
+            --arg    version   "${VERSION}" \
+            --arg    commit    "${GITHUB_SHA}" \
+            --arg    repo      "${REPO}" \
+            --argjson protocol "${PROTOCOL}" \
+            --arg    min_servuo "${MIN_SERVUO}" \
+            --arg    patched_against "${PATCHED_AGAINST}" \
+            --argjson tier     "${TIER}" \
+            --argjson files    "${FILES}" \
+            '{
+               component: $component,
+               version:   $version,
+               commit:    $commit,
+               repo:      $repo,
+               protocol:  $protocol,
+               servuo: {
+                 min_version:              $min_servuo,
+                 patches_verified_against: $patched_against
+               },
+               patch_tier: $tier,
+               files: $files
+             }' > "${STAGE}/manifest.json"
+
+          echo "----- manifest.json (files elided) -----"
+          jq 'del(.files) + {file_count: (.files | length)}' "${STAGE}/manifest.json"
+
+          TARBALL="${ARTIFACT}-${VERSION}.tar.gz"
+          tar --sort=name --mtime='UTC 1970-01-01' \
+              --owner=0 --group=0 --numeric-owner \
+              -czf "dist/${TARBALL}" -C dist/stage "${ARTIFACT}"
+
+          ( cd dist && sha256sum "${TARBALL}" > SHA256SUMS )
+          echo "tarball=${TARBALL}" >> "$GITHUB_OUTPUT"
+          ls -l dist && echo "----" && cat dist/SHA256SUMS
+        id: package
+
+      # ── RELEASE ENGINE: tag ──────────────────────────────────────────────
+      # Tag only — no bump commit, so `main` is never pushed to (see header).
+      - name: Push the release tag
+        if: ${{ steps.plan.outputs.release == 'true' }}
+        env:
+          REGISTRY_USER: ${{ secrets.REGISTRY_USER }}
+          REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+        run: |
+          set -euo pipefail
+          TAG="${{ steps.plan.outputs.tag }}"
+          # Secrets can arrive with a trailing newline (depending on how they were
+          # pasted); a stray CR/LF corrupts the remote URL ("credential url cannot
+          # be parsed"). Strip line breaks before building the URL.
+          CI_USER="$(printf '%s' "${REGISTRY_USER}" | tr -d '\r\n')"
+          CI_TOKEN="$(printf '%s' "${REGISTRY_TOKEN}" | tr -d '\r\n')"
+          git config user.name  "servuo-plugins-ci"
+          git config user.email "ci@whitlocktech.com"
+          git remote set-url origin \
+            "https://${CI_USER}:${CI_TOKEN}@${GITEA_HOST}/${REPO}.git"
+
+          # The tag may already exist when we are finishing a run that died after
+          # tagging (see the plan step). `git tag` on an existing name fails under
+          # `set -e`, and pushing an identical existing tag is a harmless no-op —
+          # so create it only if it is new, then push either way. A push that
+          # fails here means the remote tag points somewhere else, which SHOULD
+          # stop the run.
+          if git rev-parse -q --verify "refs/tags/${TAG}" >/dev/null; then
+            echo "Tag ${TAG} already exists — reusing it."
+          else
+            git tag "${TAG}"
+          fi
+          git push origin "${TAG}"
+
+      # ── RELEASE ENGINE: create the Gitea release + upload assets ─────────
+      - name: Create Gitea release and upload assets
+        if: ${{ steps.plan.outputs.release == 'true' }}
+        env:
+          REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+        run: |
+          set -euo pipefail
+          TAG="${{ steps.plan.outputs.tag }}"
+          TARBALL="${{ steps.package.outputs.tarball }}"
+          API="https://${GITEA_HOST}/api/v1/repos/${REPO}"
+          BODY="$(cat dist/CHANGELOG.md)"
+          # Same newline hygiene as the tag step: a stray CR/LF in the token would
+          # corrupt the Authorization header.
+          CI_TOKEN="$(printf '%s' "${REGISTRY_TOKEN}" | tr -d '\r\n')"
+
+          REL_ID="$(curl -sSf -X POST "${API}/releases" \
+            -H "Authorization: token ${CI_TOKEN}" \
+            -H "Content-Type: application/json" \
+            -d "$(jq -n --arg tag "$TAG" --arg body "$BODY" \
+                   '{tag_name:$tag, name:$tag, body:$body, draft:false, prerelease:false}')" \
+            | jq -r '.id')"
+          echo "Created release ${TAG} (id=${REL_ID})"
+
+          for f in "${TARBALL}" SHA256SUMS; do
+            curl -sSf -X POST "${API}/releases/${REL_ID}/assets?name=${f}" \
+              -H "Authorization: token ${CI_TOKEN}" \
+              -F "attachment=@dist/${f}" >/dev/null
+            echo "  uploaded ${f}"
+          done
+
+      # ── Recompose the installer's bundle manifest ────────────────────────
+      # The installer does not resolve "latest" at run time — it deploys the
+      # exact overlay named by a published bundle (docs/installer/PLAN.md §7.1).
+      # An overlay release that nobody recomposes around is therefore a release
+      # no operator will ever be offered. This tells the installer repo to
+      # rebuild that manifest now rather than leaving the new version invisible
+      # until its nightly cron.
+      #
+      # That job re-reads this tarball's manifest.json and checks its declared
+      # `protocol` against the sidecar's PROTOCOL_VERSION before publishing
+      # anything (PLAN.md §7.1, gate 1) — which is the check this repo cannot
+      # perform for itself, since the C# plugin announces no version on the wire.
+      #
+      # DISPATCH, DON'T WAIT (PLAN.md §7.3). Gitea's workflow-dispatch endpoint
+      # returns no run handle, so there is nothing to poll: a waiting step would
+      # have to guess which run is its own and hold a runner idle to do it.
+      #
+      # A failure here is a WARNING, never a failure of this job. The release is
+      # already published and correct by this point, and failing the run would
+      # misreport that. The installer's nightly cron recomposes from whatever the
+      # latest releases actually are, so a dropped dispatch costs latency, not
+      # correctness.
+      - name: Ask the installer repo to recompose its bundle
+        if: ${{ steps.plan.outputs.release == 'true' }}
+        env:
+          REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+        run: |
+          set -euo pipefail
+          CI_TOKEN="$(printf '%s' "${REGISTRY_TOKEN}" | tr -d '\r\n')"
+          HTTP="$(curl -s -o /dev/null -w '%{http_code}' -X POST \
+            -H "Authorization: token ${CI_TOKEN}" \
+            -H "Content-Type: application/json" \
+            -d '{"ref":"main"}' \
+            "https://${GITEA_HOST}/api/v1/repos/${INSTALLER_REPO}/actions/workflows/bundle.yml/dispatches" || echo 000)"
+          case "$HTTP" in
+            20*) echo "Dispatched ${INSTALLER_REPO} bundle.yml (HTTP ${HTTP}) — not waiting for it." ;;
+            403|404)
+              echo "::warning::Could not dispatch ${INSTALLER_REPO} bundle.yml (HTTP ${HTTP}). REGISTRY_TOKEN likely lacks write:repository on that repo. Release ${{ steps.plan.outputs.tag }} is published and fine; its bundle will be composed by the installer's nightly cron instead." ;;
+            *)
+              echo "::warning::Dispatching ${INSTALLER_REPO} bundle.yml returned HTTP ${HTTP}. Release ${{ steps.plan.outputs.tag }} is published and fine; the nightly cron will recompose the bundle." ;;
+          esac
--- a/.gitignore
+++ b/.gitignore
@@ -7,3 +7,4 @@ obj/
 *.exe
 *.pdb
 *.log
+dist/
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -33,6 +33,13 @@ under `overlay/` (or `patches/` for changes to stock ServUO files) and deploy:
 .\deploy.ps1 -ServerPath C:\path\to\servuo
 ```

+`deploy.ps1` deploys from *this working tree*, which is what you want while
+developing. It is not how a shard is set up: operators run the
+[Runic Gateway installer](https://gitea.whitlocktech.com/RunicGateway/installer),
+which syncs the released overlay tarball and installs the sidecar alongside it.
+Changes here reach shards through a [release](README.md#releases), so a change
+that only works when `deploy.ps1` copies it is a change that does not ship.
+
 - `overlay/` — copied over an install (the only thing `deploy.ps1` deploys).
 - `patches/` — unified diffs against stock ServUO for files we must modify.
 - `tools/` — never deployed: test scaffolding and stub sidecars.
--- a/README.md
+++ b/README.md
@@ -26,7 +26,9 @@ integration guide, protocol spec, research — with full history preserved).
 | `overlay/` | Mirrors the ServUO server root. Everything here — and **only** this — copies over an install. |
 | `patches/` | Unified diffs against stock ServUO for files we must modify rather than add. |
 | `tools/` | Never deployed. Test scaffolding (C# probes + PowerShell stub sidecars) and anything else that must not reach a server. |
-| `deploy.ps1` | Copies `overlay/` into a server root. `-Verify` diffs instead of writing. |
+| `deploy.ps1` | **Developer tool** — copies `overlay/` from this working tree into a server root. `-Verify` diffs instead of writing. Operators use the [installer](https://gitea.whitlocktech.com/RunicGateway/installer); see [Deploy](#deploy). |
+| `overlay.toml` | Release metadata: the wire-protocol version this overlay speaks, and its ServUO compatibility. Read by CI into the release manifest — see [Releases](#releases). |
+| `.gitea/workflows/release.yml` | Publishes `runicgateway-overlay-<ver>.tar.gz` on every merge to `main`. |
 | [INTEGRATION.md](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/link/INTEGRATION.md) | **Website integration guide** — the WebSocket feed, REST endpoints, auth, event catalog, and examples. |
 | [PLAN.md](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/link/PLAN.md) | Implementation plan, measured performance budget, and the full data catalog. |
 | [RESEARCH.md](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/link/RESEARCH.md) | Original source-level research. Partly superseded — see the corrections table in `PLAN.md` §8. |
@@ -37,13 +39,17 @@ Anything under `overlay/` is authoritative. Do not edit files in the server tree
 ## Sidecar & deployment

 The Rust sidecar is the other half of the bridge and lives in **[RunicGateway/link](https://gitea.whitlocktech.com/RunicGateway/link)**.
-The two are deployed **together** but built **independently**:
+The two are deployed **together** — by the
+[installer](https://gitea.whitlocktech.com/RunicGateway/installer), in one run — but built
+**independently**:

- **This plugin** is deployed as *source* — `deploy.ps1` copies `overlay/` into the ServUO server
-  root, and ServUO compiles it at boot (`Scripts.csproj`; see [Phase 0](#phase-0--what-it-fixes)).
-  There is no separate build artifact and no CI build — it cannot be compiled standalone without the
-  ServUO reference assemblies.
- **The sidecar** is a standalone Rust binary, released from its own repo.
+- **This plugin** is deployed as *source*: `overlay/` is copied into the ServUO server root and
+  ServUO compiles it at boot (`Scripts.csproj`; see [Phase 0](#phase-0--what-it-fixes)). There is
+  **no CI build** — it cannot be compiled standalone without the ServUO reference assemblies. CI
+  publishes a *source* tarball, which is what the installer fetches and syncs; see
+  [Releases](#releases).
+- **The sidecar** is a standalone Rust binary, released from its own repo and installed from that
+  release.

 The **only** coupling is the loopback JSON protocol (the shard dials out to the sidecar on
 `127.0.0.1`). Compatibility is a **protocol** concern, not a build-order one: keep the event/command
@@ -54,11 +60,77 @@ without the sidecar running.

 ## Deploy

+**On a shard, use the [Runic Gateway installer](https://gitea.whitlocktech.com/RunicGateway/installer).**
+One binary syncs this overlay from the release tarball below, offers the patch tier, installs the
+uo-link sidecar as a service, and prints the values your website needs — cross-platform, with a
+`doctor` afterwards to tell a copied file from a working bridge:
+
+```bash
+sudo ./runicgateway-installer-linux-x86_64 install
+```
+
+Guide: [installer/INSTALL.md](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/installer/INSTALL.md).
+To place the overlay yourself instead — a host that cannot run the binary, or you want to see every
+file land — [Appendix A2](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/installer/INSTALL.md#a2-deploy-the-plugin-overlay)
+is the same copy done by hand, and stays supported.
+
+### `deploy.ps1` — the developer path
+
+`deploy.ps1` deploys from a **working tree**, which is what you want while writing plugin code and
+is the one thing the installer cannot do (it deploys from a release):
+
 ```powershell
 .\deploy.ps1 -ServerPath <servuo> -Verify   # show what would change
 .\deploy.ps1 -ServerPath <servuo>           # write
 ```

+It is Windows-only and stays developer-facing; it never installs the sidecar, registers a service,
+or checks the protocol pairing. Nothing shipped to an operator depends on it.
+
+## Releases
+
+Every merge to `main` that carries a releasable conventional commit (`feat:`, `fix:`, `perf:`, or a
+breaking change — a `docs:`/`chore:`-only merge deliberately cuts nothing) publishes a Gitea release:
+
+```
+runicgateway-overlay-<ver>.tar.gz
+└── runicgateway-overlay/
+    ├── manifest.json
+    ├── overlay/        # exactly what deploy.ps1 would copy
+    └── patches/        # the opt-in stock-file diffs + their companion sources
+SHA256SUMS
+```
+
+This is a **source** tarball, not a build — nothing here is compiled. It exists so the installer can
+deploy the plugin onto a shard host that has no git and no Gitea credentials.
+
+`manifest.json` is what makes the tarball self-describing:
+
+```json
+{
+  "component": "servuo-plugins-overlay",
+  "version": "0.1.0",
+  "commit": "968b526…",
+  "protocol": 3,
+  "servuo": { "min_version": "57.4", "patches_verified_against": "57.4" },
+  "files": { "overlay/Config/Bridge.cfg": "32718424…", … }
+}
+```
+
+- **`protocol`** comes from `overlay.toml` and is the plugin half of the compatibility contract. The
+  plugin announces no version on the wire and none is queryable before ServUO boots, so this
+  declaration is the only way the installer can check it against the sidecar's `PROTOCOL_VERSION`
+  *before* an operator installs the pair. **When the protocol changes, bump it in the same PR that
+  changes the emitters.**
+- **`files`** carries a SHA256 per shipped file, so a deployment can later tell "an operator edited
+  this" from "the overlay moved on".
+
+The version is derived from git tags — there is no version to maintain by hand and no bump commit,
+so this workflow never pushes to `main`.
+
+The tarball is byte-reproducible for a given tree (`tar --sort=name`, pinned mtime and ownership), so
+its checksum changes only when its contents do.
+
 ## Status

 | Phase | State |
--- a/overlay.toml
+++ b/overlay.toml
@@ -0,0 +1,42 @@
+# Release metadata for the deployable overlay.
+#
+# Consumed by .gitea/workflows/release.yml, which folds these values into the
+# manifest.json shipped inside runicgateway-overlay-<ver>.tar.gz. The Runic
+# Gateway installer reads that manifest to decide what it is deploying and
+# whether it is compatible with the sidecar it is about to install
+# (docs/installer/PLAN.md §5 Phase 0, §7.1).
+#
+# There is deliberately NO version key here. The release version is derived from
+# git tags and conventional commits by the release workflow, so there is no bump
+# commit to keep in sync and no way for this file to disagree with the tag.
+
+# ── The loopback wire-protocol version this overlay speaks ───────────────────
+#
+# This is the plugin half of the compatibility contract. It MUST equal the
+# sidecar's PROTOCOL_VERSION (link/sidecar/src/main.rs) for a deployment to
+# work: the sidecar rejects a mismatch with 409 rather than mis-parsing.
+#
+# The C# plugin has no queryable version before ServUO boots — it does not
+# announce one on the wire — so this declaration is the only thing that lets the
+# installer's bundle CI check the pair BEFORE an operator installs them
+# (docs/installer/PLAN.md §2.6, §7.1 gate 1). Keeping it honest is therefore a
+# manual duty: when the protocol changes, bump it here in the same PR that
+# changes the emitters, exactly as link bumps PROTOCOL_VERSION.
+#
+# Current: 4 — see docs/link/v4.md (guild.roster, guild.leave).
+protocol = 4
+
+# ── ServUO compatibility ─────────────────────────────────────────────────────
+#
+# The base overlay (Config/Bridge.cfg + Scripts/Custom/Bridge/*.cs) only ADDS
+# files and is expected to work on any reasonably current ServUO. This is the
+# oldest version it is known good on.
+min_servuo_version = "57.4"
+
+# The patches/ tier is a different matter: those are unified diffs against STOCK
+# ServUO files, so they are verified against exactly one version and nothing
+# else. On any other version the installer skips the whole tier with a warning
+# and completes the base install (docs/installer/PLAN.md §1, §2.2) — losing
+# vendor.sale events and in-game moderation-audit forwarding, but never
+# half-patching an unknown tree.
+patches_verified_against = "57.4"
--- a/overlay/Config/Bridge.cfg
+++ b/overlay/Config/Bridge.cfg
@@ -34,6 +34,18 @@ PageSweepSeconds=5
 # interval (emit guild.update / guild.remove). Guild membership moves slowly; 60s is ample.
 GuildSweepSeconds=60

+# Members per guild.roster frame (Protocol 4). A roster is the only fat frame the bridge emits
+# (~69 bytes per member) and the sidecar reads a line with no length bound, so this caps it; a
+# guild over the cap is split across continuation frames carrying seq/more. 500 members is ~35 KB,
+# past any realistic guild, so the split path is an edge case rather than the norm.
+GuildRosterMembersPerLine=500
+
+# Guilds that may emit a roster in one sweep. Every guild looks changed right after a sidecar
+# reconnect, and building hundreds of fat frames in a single Core-thread pass is exactly the stall
+# the bridge exists to avoid. The sweep re-arms itself every 2s while a baseline is draining, so
+# lowering this slows the catch-up without making the site wait a full sweep interval per batch.
+GuildRosterGuildsPerTick=25
+
 # Town-governor poll. Each city's Governor / election is diffed on this interval to emit
 # city.update on change. Governors turn over on the order of weeks, so a slow sweep is fine.
 # Idle (emits nothing) unless the City Loyalty system is enabled (CityLoyalty.Enabled).
@@ -83,6 +95,29 @@ PointsProfileEnabled=true
 # board for anyone in the top N.
 PointsProfileRank=false

+# Player-vendor market index (https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/link/v3.md §8). Every player vendor's shop name,
+# owner, location and priced inventory, published as one vendor.listing frame per vendor so the
+# website can offer the search the in-game Vendor Search gump offers. Honours each player's own
+# in-game opt-out (the vendor's VendorSearch flag) — hide your vendor in game and it is hidden
+# on the site too.
+MarketEnabled=true
+
+# Sweep interval. UNLIKE every other sweep here, a tick does NOT walk the whole world: it
+# inventories at most MarketSweepBatch vendors and a persistent cursor round-robins through the
+# rest, so the per-tick cost is bounded by the batch rather than by how many vendors exist. Full
+# coverage takes ceil(vendors / batch) x MarketSweepSeconds — 500 vendors at the defaults is one
+# complete pass every 20 minutes, and the site labels the data with how stale it may be.
+#
+# Lower this (or raise the batch) for faster coverage; both trade directly against per-tick cost,
+# and the expensive part is the item walk, which recurses into every container a vendor is selling.
+MarketSweepSeconds=60
+MarketSweepBatch=25
+
+# Per-vendor listing cap, after which the frame carries "truncated": true. A commodity reseller
+# with thousands of stacked resources is a real thing, and an uncapped frame for one is measured
+# in megabytes. Clamped to 1..5000.
+MarketMaxListings=250
+
 # Shard ruleset (https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/link/v3.md §5). One world.ruleset frame — expansion, which
 # systems are on, skill/stat caps, account and house limits, champion scroll rules —
 # emitted on every sidecar connect (and on [bridge reload), so the website's rules page
--- a/overlay/Scripts/Custom/Bridge/BridgeBoot.cs
+++ b/overlay/Scripts/Custom/Bridge/BridgeBoot.cs
@@ -166,6 +166,7 @@ namespace Server.Custom.Bridge
                    BridgePresence.Rearm();
                    BridgeHousing.Rearm();
                    BridgePoints.Rearm();
+                    BridgeMarket.Rearm();
                    // Not a sweep, so it has nothing to re-arm — but an operator who just edited a
                    // .cfg wants the change on the site now, not after a shard restart.
                    BridgeRuleset.Emit();
@@ -186,6 +187,7 @@ namespace Server.Custom.Bridge
                    BridgePresence.SweepOnce();
                    BridgeHousing.SweepOnce();
                    BridgePoints.SweepOnce();
+                    BridgeMarket.SweepOnce();
                    e.Mobile.SendMessage("Bridge: ran one sweep of each stream.");
                    e.Mobile.SendMessage("Bridge: {0}", BridgeSweeps.Status());
                    e.Mobile.SendMessage("Bridge: {0}", BridgeChamps.Status());
@@ -194,6 +196,7 @@ namespace Server.Custom.Bridge
                    e.Mobile.SendMessage("Bridge: {0}", BridgePresence.Status());
                    e.Mobile.SendMessage("Bridge: {0}", BridgeHousing.Status());
                    e.Mobile.SendMessage("Bridge: {0}", BridgePoints.Status());
+                    e.Mobile.SendMessage("Bridge: {0}", BridgeMarket.Status());
                    break;

                default:
@@ -209,6 +212,7 @@ namespace Server.Custom.Bridge
                    e.Mobile.SendMessage("Bridge: {0}", BridgePresence.Status());
                    e.Mobile.SendMessage("Bridge: {0}", BridgeHousing.Status());
                    e.Mobile.SendMessage("Bridge: {0}", BridgePoints.Status());
+                    e.Mobile.SendMessage("Bridge: {0}", BridgeMarket.Status());
                    e.Mobile.SendMessage("Bridge: {0}", BridgePages.Status());
                    e.Mobile.SendMessage("Bridge: {0}", BridgeRuleset.Status());
                    break;
--- a/overlay/Scripts/Custom/Bridge/BridgeConfig.cs
+++ b/overlay/Scripts/Custom/Bridge/BridgeConfig.cs
@@ -36,6 +36,16 @@ namespace Server.Custom.Bridge
        public static int PresenceSweepSeconds { get; private set; }
        public static int HousingSweepSeconds { get; private set; }
        public static int PointsSweepSeconds { get; private set; }
+        public static int MarketSweepSeconds { get; private set; }
+
+        // ---- guild rosters (Protocol 4) ----
+        public static int GuildRosterMembersPerLine { get; private set; }
+        public static int GuildRosterGuildsPerTick { get; private set; }
+
+        // ---- player-vendor market index (https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/link/v3.md §8) ----
+        public static bool MarketEnabled { get; private set; }
+        public static int MarketSweepBatch { get; private set; }
+        public static int MarketMaxListings { get; private set; }

        // ---- points / loyalty leaderboards (https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/link/v3.md §7) ----
        public static bool PointsLeaderboardEnabled { get; private set; }
@@ -108,6 +118,24 @@ namespace Server.Custom.Bridge
            if (GuildSweepSeconds < 1)
                GuildSweepSeconds = 1;

+            // A roster line is the only fat frame this plugin emits — measured at roughly 69 bytes
+            // per member — and the sidecar reads a line with no length bound. The cap turns an
+            // unbounded frame into a bounded one; a guild above it is split across continuation
+            // lines. 500 members is ~35 KB, comfortably past any real guild, so the split path is
+            // an edge case rather than the norm.
+            GuildRosterMembersPerLine = Config.Get("Bridge.GuildRosterMembersPerLine", 500);
+            if (GuildRosterMembersPerLine < 16)
+                GuildRosterMembersPerLine = 16;
+
+            // How many guilds may emit a roster in a single sweep. Every guild re-emits after a
+            // reconnect (the diff caches are cleared), and building a few hundred fat JSON frames in
+            // one Core-thread pass is exactly the stall this bridge exists to avoid. The sweep
+            // re-arms itself promptly while a baseline is still draining, so this throttles the work
+            // without making the site wait a full sweep interval per batch.
+            GuildRosterGuildsPerTick = Config.Get("Bridge.GuildRosterGuildsPerTick", 25);
+            if (GuildRosterGuildsPerTick < 1)
+                GuildRosterGuildsPerTick = 1;
+
            CitySweepSeconds = Config.Get("Bridge.CitySweepSeconds", 300);
            if (CitySweepSeconds < 1)
                CitySweepSeconds = 1;
@@ -149,6 +177,36 @@ namespace Server.Custom.Bridge
            // on every profile build. See BridgeProfile.WritePoints.
            PointsProfileRank = Config.Get("Bridge.PointsProfileRank", false);

+            // Player-vendor market index. Unlike every other sweep, this one does NOT walk its whole
+            // collection per tick: MarketSweepBatch caps how many vendors are inventoried, and a
+            // persistent cursor round-robins through the rest, so the per-tick cost is bounded by
+            // the batch rather than by how many vendors the world holds.
+            MarketEnabled = Config.Get("Bridge.MarketEnabled", true);
+
+            MarketSweepSeconds = Config.Get("Bridge.MarketSweepSeconds", 60);
+            if (MarketSweepSeconds < 1)
+                MarketSweepSeconds = 1;
+
+            // Bounded below at 1 (a batch of 0 would advance the cursor nowhere and publish nothing,
+            // silently) and above at 500, past which the batch stops bounding anything on any
+            // realistic shard and the tick is a whole-world pass by another name.
+            MarketSweepBatch = Config.Get("Bridge.MarketSweepBatch", 25);
+            if (MarketSweepBatch < 1)
+                MarketSweepBatch = 1;
+            if (MarketSweepBatch > 500)
+                MarketSweepBatch = 500;
+
+            // Per-vendor listing cap. BridgeJson.Parse caps INBOUND frames at 1 MB; outbound is
+            // uncapped and the sidecar's read_line will allocate whatever arrives, so the cap here
+            // is what keeps one commodity reseller with 8,000 stacked resources from emitting a
+            // multi-megabyte frame. Over the cap the frame carries "truncated": true and the site
+            // says so.
+            MarketMaxListings = Config.Get("Bridge.MarketMaxListings", 250);
+            if (MarketMaxListings < 1)
+                MarketMaxListings = 1;
+            if (MarketMaxListings > 5000)
+                MarketMaxListings = 5000;
+
            // The ruleset frame is not a sweep — it is emitted once per sidecar connect (and on
            // `[bridge reload`), so it has no interval. PublicConnectAddress is the ONE connection
            // detail the bridge will publish, and only because an operator typed it here for that
--- a/overlay/Scripts/Custom/Bridge/BridgeJson.cs
+++ b/overlay/Scripts/Custom/Bridge/BridgeJson.cs
@@ -85,14 +85,153 @@ namespace Server.Custom.Bridge
        public static StringBuilder Actor(this StringBuilder sb, string name, Mobile m)
        {
            sb.Append(",\"").Append(name).Append("\":");
+            WriteActor(sb, m);
+            return sb;
+        }

+        /// <summary>
+        ///     Writes a named array of actor objects — a guild roster (Protocol 4) being the first
+        ///     caller. Every other outbound helper here emits a leading `,"name":`, so an array
+        ///     element needs the bare object; that is why <see cref="WriteActor"/> exists separately
+        ///     rather than <see cref="Actor"/> being reused.
+        ///
+        ///     `count` bounds how many are written, because a roster frame must stay a bounded line
+        ///     (Bridge.GuildRosterMembersPerLine). A null entry in the sequence is skipped rather
+        ///     than written as null, so the array is always a list of real members and a caller can
+        ///     trust its length.
+        ///
+        ///     `withGuildRank` adds each member's guild rank to their object. It is a parameter
+        ///     rather than always-on because rank is a property of a mobile's membership of THIS
+        ///     guild, not of the mobile — every other actor this bridge writes is a bystander,
+        ///     a killer, a governor, and guild rank is meaningless on all of them.
+        /// </summary>
+        public static StringBuilder Actors(
+            this StringBuilder sb, string name, IList<Mobile> mobiles, int start, int count,
+            bool withGuildRank = false)
+        {
+            sb.Append(",\"").Append(name).Append("\":[");
+
+            if (mobiles != null)
+            {
+                var end = Math.Min(start + count, mobiles.Count);
+                bool first = true;
+
+                for (int i = start; i < end; i++)
+                {
+                    var m = mobiles[i];
+
+                    if (m == null)
+                        continue;
+
+                    if (!first)
+                        sb.Append(',');
+
+                    if (withGuildRank)
+                        WriteGuildMember(sb, m);
+                    else
+                        WriteActor(sb, m);
+
+                    first = false;
+                }
+            }
+
+            sb.Append(']');
+            return sb;
+        }
+
+        /// <summary>
+        ///     A roster member: the standard actor object plus the member's rank in their guild.
+        ///
+        ///     **Only the raw rank is emitted, never a resolved label.** ServUO names the five
+        ///     standard ranks with cliloc ids (1062959–1062963) and ships no text for them, so the
+        ///     shard cannot produce "Warlord" without a client-file table it does not have. The
+        ///     website module does have one, and resolving a game term is its job in any case.
+        ///
+        ///     `rank` is the numeric rank, 0–4, with 4 being Leader (`RankDefinition.Ranks`). A
+        ///     custom rank definition may carry a literal string instead of a cliloc, so `rankName`
+        ///     is written when there is one and `rankCliloc` when there is not; a shard that has
+        ///     replaced the rank table therefore keeps its own naming rather than being flattened
+        ///     into the stock five.
+        ///
+        ///     A member with no readable rank — a mobile that is not a PlayerMobile, or one whose
+        ///     GuildRank is null — is written with no rank fields at all rather than a fabricated
+        ///     default. Absent means "not known", and a consumer that treated a missing rank as 0
+        ///     would silently demote them.
+        ///
+        ///     **Staff are deliberately written with no rank, and this is not a rounding error.**
+        ///     `PlayerMobile.GuildRank` returns `RankDefinition.Leader` for anyone at GameMaster or
+        ///     above, whatever their actual rank — a gameplay convenience so staff can operate a
+        ///     guild stone, and emphatically not a claim about who leads the guild. The true value
+        ///     is in a private field with no accessor, so the only honest options are "Leader" and
+        ///     "not known", and publishing a staff member as a guild leader on a public roster is
+        ///     the worse of the two by a wide margin. A staff account that genuinely leads its guild
+        ///     shows as an unranked member, which is a visible gap rather than a false claim.
+        /// </summary>
+        private static void WriteGuildMember(StringBuilder sb, Mobile m)
+        {
            if (m == null)
            {
                sb.Append("null");
-                return sb;
+                return;
            }

-            sb.Append("{\"serial\":\"0x").Append(m.Serial.Value.ToString("X")).Append('"');
+            sb.Append('{');
+            WriteActorFields(sb, m);
+
+            var pm = m as Server.Mobiles.PlayerMobile;
+            var rank = pm == null || pm.AccessLevel >= AccessLevel.GameMaster ? null : pm.GuildRank;
+
+            if (rank != null)
+            {
+                sb.Append(",\"rank\":").Append(rank.Rank);
+
+                if (!string.IsNullOrEmpty(rank.Name.String))
+                {
+                    sb.Append(",\"rankName\":");
+                    Escape(sb, rank.Name.String);
+                }
+                else if (rank.Name.Number > 0)
+                {
+                    sb.Append(",\"rankCliloc\":").Append(rank.Name.Number);
+                }
+            }
+
+            sb.Append('}');
+        }
+
+        /// <summary>
+        ///     One bare actor object, with no leading field name: serial, name, account (when there
+        ///     is one), the linked webId (when the account is linked), and the player flag. A `null`
+        ///     mobile writes null.
+        ///
+        ///     `acct` and `webId` are the site-identity fields, and they are emitted here
+        ///     unconditionally by design — the sidecar is a forwarder, and deciding who may see them
+        ///     is the website's job (it projects per the shard visibility rungs). Note that `acct` is
+        ///     genuinely optional: a PlayerMobile can have no Account at all.
+        /// </summary>
+        private static void WriteActor(StringBuilder sb, Mobile m)
+        {
+            if (m == null)
+            {
+                sb.Append("null");
+                return;
+            }
+
+            sb.Append('{');
+            WriteActorFields(sb, m);
+            sb.Append('}');
+        }
+
+        /// <summary>
+        ///     The actor fields, with no braces, so a caller can add its own.
+        ///
+        ///     Split out for <see cref="WriteGuildMember"/>, which is the same object plus guild
+        ///     rank. Note the first field is written WITHOUT a leading comma and every later one
+        ///     with, so this must be the first thing inside its object.
+        /// </summary>
+        private static void WriteActorFields(StringBuilder sb, Mobile m)
+        {
+            sb.Append("\"serial\":\"0x").Append(m.Serial.Value.ToString("X")).Append('"');

            sb.Append(",\"name\":");
            Escape(sb, m.Name ?? "");
@@ -112,8 +251,6 @@ namespace Server.Custom.Bridge
            }

            sb.Append(",\"player\":").Append(m.Player ? "true" : "false");
-            sb.Append('}');
-            return sb;
        }

        /// <summary>Closes the object. The trailing newline is the frame delimiter.</summary>
--- a/overlay/Scripts/Custom/Bridge/BridgeMarket.cs
+++ b/overlay/Scripts/Custom/Bridge/BridgeMarket.cs
@@ -0,0 +1,591 @@
+using System;
+using System.Collections.Generic;
+using System.Text;
+
+using Server.Items;
+using Server.Mobiles;
+using Server.Multis;
+using Server.Engines.VendorSearching;
+
+namespace Server.Custom.Bridge
+{
+    /// <summary>
+    ///     The shard-wide player-vendor index (https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/link/v3.md §8). Every player vendor's
+    ///     shop name, owner, location and priced inventory, published as one authoritative
+    ///     <c>vendor.listing</c> frame per vendor, so the website can offer the search the in-game
+    ///     Vendor Search gump offers — from outside the game.
+    ///
+    ///     ---- Why this is a sweep and not an RPC ----
+    ///
+    ///     The obvious shape is a <c>market.snapshot</c> request/reply like vendor.snapshot next
+    ///     door. It cannot work: the sidecar's rpc router correlates on the FIRST frame carrying a
+    ///     matching reqId and resolves a single oneshot, so a chunked reply sharing one reqId would
+    ///     deliver chunk 1 to the HTTP caller and LEAK chunks 2..N onto the broadcast feed. A
+    ///     whole-world snapshot in one frame is not an option either — the reply timeout is 10 s and
+    ///     40,000 listings do not serialize in time.
+    ///
+    ///     So it is a diff sweep on the broadcast stream, shaped like <see cref="BridgeHousing"/>:
+    ///     one frame per vendor, authoritative for that vendor, plus vendor.listing.remove when one
+    ///     goes away. The per-account <c>vendor.snapshot</c> RPC is untouched; the player portal
+    ///     keeps using it.
+    ///
+    ///     ---- The two perf traps, and what this does about them ----
+    ///
+    ///     1. **VendorSearch.GetItemName is a packet builder, not a field read.** It constructs an
+    ///        ObjectPropertyList, calls GetProperties, serialises it and then byte-parses the
+    ///        resulting packet — PER ITEM. Across a full pass that is a multi-hundred-millisecond
+    ///        stall on the Core thread. It is never called here. The frame carries `itemId`, `hue`,
+    ///        `amount`, `price`, the plain `item.Name` field (null for most items) and
+    ///        `item.LabelNumber`; the website resolves display names against its own cliloc table,
+    ///        exactly as char.profile.equipment already does.
+    ///
+    ///        (On any modern client the call would not even work: every current client ships its
+    ///        Cliloc.* files compressed, ServUO's bundled Ultima.StringList reads only the old plain
+    ///        layout, so VendorSearch.StringList is null and GetItemName returns item.Name anyway.
+    ///        The in-game gump has the same gap.)
+    ///
+    ///     2. **A full pass is unbounded in world size.** 500 vendors × 80 listings is ~40,000 item
+    ///        reads, and the reusable public GetItems(Container, List&lt;Item&gt;) recurses into
+    ///        sub-containers, so the real count runs ABOVE the top-level pack.Items a naive estimate
+    ///        would use. So the sweep is amortized: a persistent round-robin cursor over
+    ///        PlayerVendor.PlayerVendors advances at most MarketSweepBatch vendors per tick, which
+    ///        makes the PER-TICK cost bounded independently of how many vendors exist. Full coverage
+    ///        takes ceil(vendors / batch) × MarketSweepSeconds. This is the one genuinely new pattern
+    ///        versus the other sweeps, which all walk their whole collection every tick.
+    ///
+    ///     ---- Privacy ----
+    ///
+    ///     `pv.VendorSearch` is ServUO's own per-vendor opt-out and DoSearch filters on it, so a
+    ///     player who hid their vendor in game is hidden on the website too: an opted-out vendor is
+    ///     skipped entirely and the seen-set removal then drops it from the board. Map.Internal and
+    ///     a null Backpack are skipped for the same reason DoSearch skips them.
+    ///
+    ///     Owner is written as flat `ownerSerial`/`ownerName` — never through BridgeJson.Actor,
+    ///     which would add `acct` and `webId`. Same argument BridgePoints makes: this is the widest-
+    ///     audience surface the bridge has, and the site resolves serial → user from its own
+    ///     shard_account_links mirror when staff need it.
+    /// </summary>
+    public static class BridgeMarket
+    {
+        private static Timer _timer;
+
+        // vendor serial -> last-emitted signature.
+        private static readonly Dictionary<Serial, string> _last = new Dictionary<Serial, string>();
+
+        // Round-robin cursor: an INDEX into PlayerVendor.PlayerVendors, not a serial. The list is
+        // mutated by placement/deletion between ticks, so the cursor is a hint, not a promise — it
+        // is wrapped and clamped every tick, and a shifted list at worst re-visits or defers a
+        // vendor by one cycle. Tracking a serial instead would cost a lookup to find "where was I"
+        // and buy nothing: the sweep is idempotent per vendor.
+        private static int _cursor;
+
+        private static long _sweeps, _emitted, _removed, _scanned, _skipped, _truncated;
+
+        // Per-tick cost, in milliseconds. Reported by `[bridge status` because the
+        // whole design of this sweep is a claim about that number — the batch cap is what makes it
+        // independent of world size — and an operator tuning MarketSweepBatch is otherwise tuning
+        // blind. `_maxMs` is the one that matters: the Core thread runs this between frames, so the
+        // worst tick is the budget, not the average.
+        private static double _lastMs, _maxMs;
+        private static readonly System.Diagnostics.Stopwatch _clock = new System.Diagnostics.Stopwatch();
+
+        // Reused across ticks. The item walk is single-threaded (Core thread) and the list is
+        // cleared before each vendor, so one buffer serves the whole sweep — the alternative is a
+        // fresh List<Item> per vendor per tick, which at 25 vendors × every 60 s is pure garbage.
+        private static readonly List<Item> _items = new List<Item>();
+
+        public static void Initialize()
+        {
+            if (!BridgeConfig.Enabled)
+                return;
+
+            EventSink.ServerStarted += OnServerStarted;
+        }
+
+        private static void OnServerStarted()
+        {
+            BridgeLink.Connected_Core += OnConnected;
+            Rearm();
+        }
+
+        private static void OnConnected()
+        {
+            // A new sidecar knows nothing, so drop the diff state and start the round-robin from
+            // the top. The re-emit of the whole world is self-throttled by the batch window — this
+            // is the one place the amortized sweep pays for itself twice, because a reconnect on a
+            // whole-world sweep would otherwise be the biggest burst the bridge ever produces.
+            _last.Clear();
+            _cursor = 0;
+        }
+
+        /// <summary>Stops and recreates the timer from current config. Called by `[bridge reload`.</summary>
+        public static void Rearm()
+        {
+            Stop();
+
+            _timer = Timer.DelayCall(
+                TimeSpan.FromSeconds(BridgeConfig.MarketSweepSeconds),
+                TimeSpan.FromSeconds(BridgeConfig.MarketSweepSeconds),
+                MarketSweep);
+        }
+
+        public static void Stop()
+        {
+            if (_timer != null) { _timer.Stop(); _timer = null; }
+        }
+
+        /// <summary>
+        ///     A bare (key-less) string value, or JSON null.
+        ///
+        ///     <see cref="BridgeJson.Escape"/> takes a non-null string — it dereferences
+        ///     <c>value.Length</c> immediately — and <see cref="BridgeJson.Str"/> writes the `,"key":`
+        ///     prefix itself, so neither serves a value written inside a hand-built object. Most of
+        ///     what this frame writes is legitimately null (an item's plain Name is null for nearly
+        ///     every item, a vendor standing in the street has no house), so this is the common path
+        ///     rather than an edge case.
+        /// </summary>
+        private static void Text(StringBuilder sb, string value)
+        {
+            if (value == null)
+                sb.Append("null");
+            else
+                BridgeJson.Escape(sb, value);
+        }
+
+        public static string Status()
+        {
+            var all = PlayerVendor.PlayerVendors;
+
+            return String.Format(
+                "market(enabled={0} sweeps={1} scanned={2} emitted={3} removed={4} skipped={5} truncated={6} tracked={7} vendors={8} cursor={9} batch={10} lastMs={11:F2} maxMs={12:F2})",
+                BridgeConfig.MarketEnabled, _sweeps, _scanned, _emitted, _removed, _skipped,
+                _truncated, _last.Count, all == null ? 0 : all.Count, _cursor,
+                BridgeConfig.MarketSweepBatch, _lastMs, _maxMs);
+        }
+
+        /// <summary>Runs one sweep now. Wired into `[bridge sweepnow`.</summary>
+        public static void SweepOnce()
+        {
+            MarketSweep();
+        }
+
+        /// <summary>
+        ///     One tick: at most <c>MarketSweepBatch</c> vendors starting at the cursor, then the
+        ///     removal pass.
+        ///
+        ///     The removal pass is the part the batching makes subtle. `_last` holds every vendor
+        ///     seen in ANY previous tick, but this tick only visited a window — so "not in this
+        ///     tick's seen set" does NOT mean gone. Removals are therefore decided against the
+        ///     CURRENT vendor list (plus the opt-out/validity rules), not against the window, which
+        ///     is a cheap pass over serials rather than a second inventory walk.
+        /// </summary>
+        private static void MarketSweep()
+        {
+            try
+            {
+                if (!BridgeConfig.MarketEnabled)
+                    return;
+
+                _sweeps++;
+
+                if (!BridgeLink.Connected)
+                    return; // nothing is listening; do not fill the queue with perishable snapshots
+
+                _clock.Restart();
+
+                var all = PlayerVendor.PlayerVendors;
+
+                if (all == null || all.Count == 0)
+                {
+                    Reap(null);
+                    return;
+                }
+
+                // A live set of every serial that SHOULD be on the board right now, built as the
+                // window is walked plus a cheap pass over the rest. Built here rather than reusing
+                // a field so a throwing vendor cannot leave a half-built set behind.
+                var present = new HashSet<Serial>();
+
+                var count = all.Count;
+                var batch = Math.Min(BridgeConfig.MarketSweepBatch, count);
+
+                if (_cursor >= count)
+                    _cursor = 0;
+
+                for (int i = 0; i < count; i++)
+                {
+                    var vendor = all[i];
+
+                    if (Eligible(vendor))
+                        present.Add(vendor.Serial);
+                }
+
+                for (int n = 0; n < batch; n++)
+                {
+                    var index = (_cursor + n) % count;
+                    var vendor = all[index];
+
+                    if (!Eligible(vendor))
+                    {
+                        _skipped++;
+                        continue;
+                    }
+
+                    // One bad vendor must not cost the rest of the window: the item walk touches
+                    // arbitrary Item subclasses on a shard running modified scripts.
+                    try
+                    {
+                        SweepVendor(vendor);
+                    }
+                    catch (Exception ex)
+                    {
+                        Console.WriteLine("[Bridge] market sweep threw for 0x{0:X}: {1}",
+                            vendor.Serial.Value, ex.Message);
+                    }
+                }
+
+                _cursor = count == 0 ? 0 : (_cursor + batch) % count;
+
+                Reap(present);
+            }
+            catch (Exception ex)
+            {
+                Console.WriteLine("[Bridge] market sweep threw: {0}", ex.Message);
+            }
+            finally
+            {
+                // In `finally` so a throwing tick still records what it cost — a sweep that blows
+                // the budget and then throws is exactly the one worth seeing in the status line.
+                if (_clock.IsRunning)
+                {
+                    _clock.Stop();
+                    _lastMs = _clock.Elapsed.TotalMilliseconds;
+                    if (_lastMs > _maxMs)
+                        _maxMs = _lastMs;
+
+                    WarnIfSlow();
+                }
+            }
+        }
+
+        /// <summary>
+        ///     Per-tick budget, milliseconds. The batch cap exists to hold a tick under this
+        ///     regardless of world size, so exceeding it means MarketSweepBatch is too large for
+        ///     this shard's shops — the one thing an operator needs told, and the one thing
+        ///     `[bridge status` cannot tell them unprompted. Generous: a tick is off the frame
+        ///     budget, and the alternative to a rare 50 ms tick is a permanently stale market.
+        /// </summary>
+        private const double SlowTickMs = 50.0;
+
+        // At most one warning a minute. A shard whose batch is genuinely too big would otherwise
+        // print every MarketSweepSeconds forever, and a log nobody can read is a log nobody reads.
+        private static DateTime _lastWarn = DateTime.MinValue;
+
+        private static void WarnIfSlow()
+        {
+            if (_lastMs <= SlowTickMs)
+                return;
+
+            var now = DateTime.UtcNow;
+
+            if (now - _lastWarn < TimeSpan.FromMinutes(1))
+                return;
+
+            _lastWarn = now;
+
+            Console.WriteLine(
+                // ASCII only. The ServUO console writes in the OS code page, so an em dash here
+                // renders as "???" in the log an operator would paste into an issue.
+                "[Bridge] market sweep took {0:F1} ms (budget {1:F0} ms) - lower Bridge.MarketSweepBatch (now {2}) if this persists",
+                _lastMs, SlowTickMs, BridgeConfig.MarketSweepBatch);
+        }
+
+        /// <summary>
+        ///     The same filter DoSearch applies, so the website's index is the in-game index.
+        ///     <c>VendorSearch</c> is the player's own opt-out toggle and is honoured first.
+        /// </summary>
+        private static bool Eligible(PlayerVendor vendor)
+        {
+            return vendor != null
+                && !vendor.Deleted
+                && vendor.VendorSearch
+                && vendor.Map != null
+                && vendor.Map != Map.Internal
+                && vendor.Backpack != null;
+        }
+
+        /// <summary>
+        ///     Drops from the board every tracked vendor that is no longer eligible.
+        ///     <paramref name="present"/> null means "there are no vendors at all", which clears it.
+        /// </summary>
+        private static void Reap(HashSet<Serial> present)
+        {
+            if (_last.Count == 0)
+                return;
+
+            List<Serial> gone = null;
+
+            foreach (var serial in _last.Keys)
+            {
+                if (present != null && present.Contains(serial))
+                    continue;
+
+                if (gone == null)
+                    gone = new List<Serial>();
+
+                gone.Add(serial);
+            }
+
+            if (gone == null)
+                return;
+
+            for (int i = 0; i < gone.Count; i++)
+            {
+                _last.Remove(gone[i]);
+                BridgeLink.Emit(BridgeJson.Begin("vendor.listing.remove").Ser("serial", gone[i]).End());
+                _removed++;
+            }
+        }
+
+        private static void SweepVendor(PlayerVendor vendor)
+        {
+            _scanned++;
+
+            CollectItems(vendor);
+
+            var sig = Signature(vendor);
+
+            string prior;
+            if (_last.TryGetValue(vendor.Serial, out prior) && prior == sig)
+                return; // nothing about this shop changed since it was last published
+
+            _last[vendor.Serial] = sig;
+            BridgeLink.Emit(WriteVendor(vendor));
+            _emitted++;
+        }
+
+        /// <summary>
+        ///     Every sellable item on one vendor, into the shared buffer.
+        ///
+        ///     Mirrors VendorSearch's own private GetItems(PlayerVendor): the vendor's own movable
+        ///     equipment (minus the backpack itself and hair layers, which are not merchandise)
+        ///     followed by a recursive walk of the backpack. The recursion uses the PUBLIC
+        ///     GetItems(Container, List&lt;Item&gt;) rather than a hand-rolled one so that ServUO's
+        ///     rule about which containers are sold whole (quivers, seed boxes, jewelry boxes, …)
+        ///     stays ServUO's to define — the predicate that decides it is private, and a copy here
+        ///     would silently diverge the first time that list changes.
+        /// </summary>
+        private static void CollectItems(PlayerVendor vendor)
+        {
+            _items.Clear();
+
+            var own = vendor.Items;
+
+            if (own != null)
+            {
+                for (int i = 0; i < own.Count; i++)
+                {
+                    var item = own[i];
+
+                    if (item == null || !item.Movable || item == vendor.Backpack)
+                        continue;
+
+                    if (item.Layer == Layer.Hair || item.Layer == Layer.FacialHair)
+                        continue;
+
+                    _items.Add(item);
+                }
+            }
+
+            if (vendor.Backpack != null)
+                VendorSearch.GetItems(vendor.Backpack, _items);
+        }
+
+        /// <summary>
+        ///     A listing's price, and whether it was priced by an enclosing container.
+        ///
+        ///     ServUO prices a container as a unit: an item inside a priced bag has no VendorItem of
+        ///     its own and inherits the bag's price, which DoSearch surfaces as `isChild`. Reproduced
+        ///     exactly, because a website that priced every item in a 40k bag at 40k would be lying
+        ///     about the shard.
+        /// </summary>
+        private static int PriceOf(PlayerVendor vendor, Item item, out bool child)
+        {
+            child = false;
+
+            var vi = vendor.GetVendorItem(item);
+
+            if (vi != null)
+                return vi.Price;
+
+            var parent = item.Parent as Container;
+
+            while (parent != null)
+            {
+                vi = vendor.GetVendorItem(parent);
+
+                if (vi != null)
+                {
+                    child = true;
+                    return vi.Price;
+                }
+
+                parent = parent.Parent as Container;
+            }
+
+            return 0;
+        }
+
+        /// <summary>
+        ///     The diff key. Location, shop name and owner are in it because they move a vendor's
+        ///     row on the site; every listing's serial, price and amount are in it because those are
+        ///     what a shopper searches on.
+        ///
+        ///     Built over the SAME buffer the frame is written from, in the same order, so a
+        ///     signature match really does mean an identical frame — a cheaper hash (count + a sum
+        ///     of serial^price, as §8.3 first proposed) collides on the common case of two items
+        ///     swapping prices, which is exactly what re-pricing a shop looks like.
+        /// </summary>
+        private static string Signature(PlayerVendor vendor)
+        {
+            var sb = new StringBuilder(256);
+
+            sb.Append(vendor.ShopName ?? "").Append('|');
+            sb.Append(vendor.Owner == null ? 0 : vendor.Owner.Serial.Value).Append('|');
+            sb.Append(vendor.Map == null ? "" : vendor.Map.Name).Append('|');
+            sb.Append(vendor.X).Append(',').Append(vendor.Y).Append('|');
+
+            var limit = Math.Min(_items.Count, BridgeConfig.MarketMaxListings);
+
+            sb.Append(_items.Count).Append('|');
+
+            for (int i = 0; i < limit; i++)
+            {
+                var item = _items[i];
+
+                if (item == null || item.Deleted)
+                    continue;
+
+                bool child;
+                var price = PriceOf(vendor, item, out child);
+
+                if (price <= 0)
+                    continue;
+
+                sb.Append(item.Serial.Value.ToString("X")).Append(':')
+                  .Append(price).Append(':')
+                  .Append(item.Amount).Append(';');
+            }
+
+            return sb.ToString();
+        }
+
+        /// <summary>
+        ///     One vendor frame — authoritative for that vendor, so the website replaces its whole
+        ///     listing set from it rather than merging.
+        ///
+        ///     `location` is one nested object rather than flat map/x/y/region because it is ONE
+        ///     admin-configurable field on the site (`market.location`): the visibility projection
+        ///     matches literal JSON keys, so a nested object is what lets a single rule hide a
+        ///     vendor's whereabouts on both the live frame and the stored read model. Flat keys
+        ///     would need five rules that could drift apart.
+        ///
+        ///     `count` is the number of listings PUBLISHED, and `truncated` says the shop holds
+        ///     more. A shop over the cap is a real thing (commodity resellers run thousands of
+        ///     stacks) and the site says so rather than quietly showing a partial shop as complete.
+        /// </summary>
+        private static string WriteVendor(PlayerVendor vendor)
+        {
+            var sb = BridgeJson.Begin("vendor.listing")
+                .Ser("serial", vendor.Serial)
+                .Str("shopName", vendor.ShopName);
+
+            var owner = vendor.Owner;
+
+            if (owner != null)
+            {
+                sb.Ser("ownerSerial", owner.Serial);
+                sb.Str("ownerName", owner.Name);
+            }
+
+            sb.Append(",\"location\":{\"map\":");
+            Text(sb, vendor.Map == null ? null : vendor.Map.Name);
+            sb.Append(",\"x\":").Append(vendor.X);
+            sb.Append(",\"y\":").Append(vendor.Y);
+            sb.Append(",\"z\":").Append(vendor.Z);
+
+            var region = vendor.Region;
+            sb.Append(",\"region\":");
+            Text(sb, region == null ? null : region.Name);
+
+            // The house name is the sign's, which is what a player would be told to look for
+            // ("Bob's Villa"), not the house type. Null for a vendor standing outside one.
+            var house = vendor.House;
+            var sign = house == null ? null : house.Sign;
+            sb.Append(",\"house\":");
+            Text(sb, sign == null ? null : sign.GetName());
+
+            sb.Append('}');
+
+            var max = BridgeConfig.MarketMaxListings;
+            var published = 0;
+            var considered = 0;
+
+            var items = new StringBuilder(512);
+
+            for (int i = 0; i < _items.Count; i++)
+            {
+                var item = _items[i];
+
+                if (item == null || item.Deleted)
+                    continue;
+
+                bool child;
+                var price = PriceOf(vendor, item, out child);
+
+                // Unpriced items are inventory, not listings — DoSearch drops them the same way.
+                if (price <= 0)
+                    continue;
+
+                considered++;
+
+                if (published >= max)
+                    continue;
+
+                if (published > 0)
+                    items.Append(',');
+
+                items.Append("{\"serial\":\"0x").Append(item.Serial.Value.ToString("X")).Append('"');
+                items.Append(",\"itemId\":").Append(item.ItemID);
+                items.Append(",\"hue\":").Append(item.Hue);
+                items.Append(",\"amount\":").Append(item.Amount);
+                items.Append(",\"price\":").Append(price);
+
+                // The PLAIN Name field, which is null for most items — never GetItemName, which
+                // builds and parses a property packet per item. LabelNumber is the cliloc the
+                // website resolves against its own table.
+                items.Append(",\"name\":");
+                Text(items, item.Name);
+                items.Append(",\"cliloc\":").Append(item.LabelNumber);
+
+                if (child)
+                    items.Append(",\"child\":true");
+
+                items.Append('}');
+
+                published++;
+            }
+
+            sb.Num("count", published);
+            sb.Num("total", considered);
+            sb.Bool("truncated", considered > published);
+
+            if (considered > published)
+                _truncated++;
+
+            sb.Append(",\"items\":[").Append(items).Append(']');
+
+            return sb.End();
+        }
+    }
+}
--- a/overlay/Scripts/Custom/Bridge/BridgeSocial.cs
+++ b/overlay/Scripts/Custom/Bridge/BridgeSocial.cs
@@ -15,10 +15,14 @@ namespace Server.Custom.Bridge
    ///     A guild that vanishes (or disbands — Disbanded == leader gone) leaves via `guild.remove`.
    ///
    ///     On top of the board we emit a real-time `guild.join` from EventSink.JoinGuild, so a "so-and-
-    ///     so joined" feed does not wait for the next sweep. A membership change also moves the board
-    ///     signature (member count + serial sum), so a *leave* surfaces as the member count dropping in
-    ///     the next `guild.update`; per-member leave events would need a core tap and are a later
-    ///     refinement (§10.1).
+    ///     so joined" feed does not wait for the next sweep.
+    ///
+    ///     Protocol 4 adds the membership half that §10.1 deferred. The sweep holds each guild's
+    ///     member serial **set** rather than a sum of it, so a change is detected by set comparison
+    ///     (no hash collisions, unlike the old sum where two offsetting changes could cancel) and the
+    ///     departures are recoverable by difference — which is what makes a per-member `guild.leave`
+    ///     possible without a core tap. A changed set also re-emits `guild.roster`, the full member
+    ///     list, so the board self-corrects and nothing downstream has to replay deltas to stay right.
    ///
    ///     "Created" is derived sidecar-side from a first-seen id (as champs derive it), rather than a
    ///     wire event — otherwise a sidecar reconnect, which clears the diff cache and re-emits every
@@ -32,7 +36,16 @@ namespace Server.Custom.Bridge
        // was cleared on reconnect), so its next sweep counts as a change.
        private static readonly Dictionary<int, string> _last = new Dictionary<int, string>();

-        private static long _sweeps, _emitted, _removed, _joins;
+        // guild id -> last-emitted member serial set (Protocol 4). Held rather than summed so a
+        // departure can be recovered as a set difference; see the class remarks.
+        private static readonly Dictionary<int, HashSet<int>> _members =
+            new Dictionary<int, HashSet<int>>();
+
+        private static long _sweeps, _emitted, _removed, _joins, _rosters, _leaves;
+
+        // Set while a post-reconnect baseline is still draining, so the sweep re-arms promptly
+        // instead of leaving the site a sweep interval behind. See GuildSweep.
+        private static bool _draining;

        public static void Initialize()
        {
@@ -52,6 +65,7 @@ namespace Server.Custom.Bridge
        private static void OnConnected()
        {
            _last.Clear();
+            _members.Clear();
        }

        /// <summary>Stops and recreates the timer from current config. Called by `[bridge reload`.</summary>
@@ -72,8 +86,9 @@ namespace Server.Custom.Bridge

        public static string Status()
        {
-            return String.Format("guilds(sweeps={0} emitted={1} removed={2} joins={3} tracked={4})",
-                _sweeps, _emitted, _removed, _joins, _last.Count);
+            return String.Format(
+                "guilds(sweeps={0} emitted={1} removed={2} joins={3} rosters={4} leaves={5} tracked={6} draining={7})",
+                _sweeps, _emitted, _removed, _joins, _rosters, _leaves, _last.Count, _draining);
        }

        /// <summary>Runs one sweep now. Wired into `[bridge sweepnow`.</summary>
@@ -93,6 +108,12 @@ namespace Server.Custom.Bridge

                var seen = new HashSet<int>();

+                // Guilds whose roster this sweep is still allowed to emit. Every guild looks changed
+                // right after a reconnect, and a roster is this plugin's only fat frame, so the
+                // baseline is spread over several passes rather than built in one Core-thread tick.
+                var rosterBudget = BridgeConfig.GuildRosterGuildsPerTick;
+                var deferred = false;
+
                foreach (var bg in BaseGuild.List.Values)
                {
                    var g = bg as Guild;
@@ -104,15 +125,64 @@ namespace Server.Custom.Bridge

                    seen.Add(g.Id);

+                    var current = MemberSerials(g);
+
+                    HashSet<int> priorMembers;
+                    var known = _members.TryGetValue(g.Id, out priorMembers);
+                    var membersChanged = !known || !priorMembers.SetEquals(current);
+
                    var sig = Signature(g);

                    string prior;
-                    if (_last.TryGetValue(g.Id, out prior) && prior == sig)
+                    var sigChanged = !_last.TryGetValue(g.Id, out prior) || prior != sig;
+
+                    if (!sigChanged && !membersChanged)
                        continue; // unchanged since last emit

-                    _last[g.Id] = sig;
-                    BridgeLink.Emit(WriteGuild(g));
-                    _emitted++;
+                    if (sigChanged)
+                    {
+                        _last[g.Id] = sig;
+                        BridgeLink.Emit(WriteGuild(g));
+                        _emitted++;
+                    }
+
+                    if (!membersChanged)
+                        continue;
+
+                    // Over budget: leave _members untouched so this guild is still "changed" next
+                    // pass and gets its roster then. The guild.update above has already gone, so the
+                    // board's counts are current either way.
+                    if (rosterBudget <= 0)
+                    {
+                        deferred = true;
+                        continue;
+                    }
+
+                    rosterBudget--;
+
+                    // Departures, per member, before the roster that supersedes them: a consumer
+                    // building a "so-and-so left" feed needs the individual events, while a consumer
+                    // holding the membership table only needs the roster. On the very first sweep for
+                    // a guild there is no prior set, so nothing is reported as having left — an
+                    // unknown roster becoming known is not 155 people leaving.
+                    if (known)
+                    {
+                        foreach (var serial in priorMembers)
+                        {
+                            if (current.Contains(serial))
+                                continue;
+
+                            BridgeLink.Emit(BridgeJson.Begin("guild.leave")
+                                .Num("id", g.Id)
+                                .Str("name", g.Name)
+                                .Ser("who", (Serial)serial)
+                                .End());
+                            _leaves++;
+                        }
+                    }
+
+                    EmitRoster(g);
+                    _members[g.Id] = current;
                }

                // Anything tracked last sweep but not seen now has disbanded or been removed.
@@ -120,9 +190,19 @@ namespace Server.Custom.Bridge
                foreach (var id in gone)
                {
                    _last.Remove(id);
+                    _members.Remove(id);
                    BridgeLink.Emit(BridgeJson.Begin("guild.remove").Num("id", id).End());
                    _removed++;
                }
+
+                // Re-arm promptly while a baseline is still draining. Without this the remaining
+                // guilds would each wait a full GuildSweepSeconds, so a 200-guild shard would take
+                // hours to publish its rosters after a reconnect instead of seconds. The sweep is
+                // idempotent, so an extra pass that finds nothing changed costs a few field reads.
+                _draining = deferred;
+
+                if (deferred)
+                    Timer.DelayCall(TimeSpan.FromSeconds(2.0), GuildSweep);
            }
            catch (Exception ex)
            {
@@ -130,14 +210,15 @@ namespace Server.Custom.Bridge
            }
        }

-        // The volatile fields that define a meaningful change: name, abbreviation, leader, member
-        // count, the member set (order-independent serial sum), and alliance.
-        private static string Signature(Guild g)
+        /// <summary>
+        ///     The guild's live member serials. Held per guild between sweeps so a membership change
+        ///     yields both the fact that it changed and *who* left (Protocol 4).
+        /// </summary>
+        private static HashSet<int> MemberSerials(Guild g)
        {
-            long memberSum = 0;
-            int count = 0;
-
+            var set = new HashSet<int>();
            var members = g.Members;
+
            if (members != null)
            {
                for (int i = 0; i < members.Count; i++)
@@ -145,8 +226,28 @@ namespace Server.Custom.Bridge
                    var m = members[i];
                    if (m == null)
                        continue;
-                    count++;
-                    unchecked { memberSum += (uint)m.Serial.Value; }
+                    set.Add(m.Serial.Value);
+                }
+            }
+
+            return set;
+        }
+
+        // The volatile fields that define a meaningful change to the *board row*: name, abbreviation,
+        // leader, member count and alliance. Membership is no longer folded in here as a serial sum —
+        // the sweep compares the real member set instead, which cannot collide the way a sum can when
+        // one member joins and another leaves between two passes.
+        private static string Signature(Guild g)
+        {
+            int count = 0;
+
+            var members = g.Members;
+            if (members != null)
+            {
+                for (int i = 0; i < members.Count; i++)
+                {
+                    if (members[i] != null)
+                        count++;
                }
            }

@@ -157,7 +258,6 @@ namespace Server.Custom.Bridge
                g.Abbreviation ?? "", "|",
                leaderSerial.ToString(), "|",
                count.ToString(), "|",
-                memberSum.ToString(), "|",
                g.Alliance == null ? "" : (g.AllianceName ?? ""));
        }

@@ -191,6 +291,55 @@ namespace Server.Custom.Bridge
            return sb.End();
        }

+        /// <summary>
+        ///     Emits the guild's full member list as one or more `guild.roster` frames (Protocol 4).
+        ///
+        ///     A roster is the only fat frame this plugin produces — roughly 69 bytes per member — and
+        ///     the sidecar reads a line with no length bound, so the member count per line is capped
+        ///     (Bridge.GuildRosterMembersPerLine). A guild over the cap is split, and each frame
+        ///     carries `seq` plus `more` so a consumer can tell a complete roster from a partial one:
+        ///     `seq` 0 begins a roster and replaces whatever was held, and `more` false ends it. A
+        ///     guild inside the cap — every realistic one — emits exactly one frame with `seq` 0 and
+        ///     `more` false, which is the same shape as if chunking did not exist.
+        /// </summary>
+        private static void EmitRoster(Guild g)
+        {
+            var members = g.Members;
+            var total = members == null ? 0 : members.Count;
+            var perLine = BridgeConfig.GuildRosterMembersPerLine;
+
+            var seq = 0;
+            var start = 0;
+
+            // do/while, not while: a guild with no members must still emit one empty roster frame,
+            // or a consumer could never learn that a roster it holds has emptied.
+            do
+            {
+                var more = start + perLine < total;
+
+                var sb = BridgeJson.Begin("guild.roster")
+                    .Num("id", g.Id)
+                    .Str("name", g.Name)
+                    .Str("abbr", g.Abbreviation)
+                    .Num("total", total)
+                    .Num("seq", seq)
+                    .Bool("more", more);
+
+                // `withGuildRank` — the roster is the one place a member's rank in THIS guild is
+                // meaningful, and the only frame that carries it. Leadership is rank 4
+                // (RankDefinition.Ranks), and a guild can have several members at it, which is why
+                // the board's single `leader` field was never enough to answer "who leads this".
+                sb.Actors("members", members, start, perLine, withGuildRank: true);
+
+                BridgeLink.Emit(sb.End());
+                _rosters++;
+
+                start += perLine;
+                seq++;
+            }
+            while (start < total);
+        }
+
        // ---- real-time join ----

        private static void OnJoinGuild(JoinGuildEventArgs e)
--- a/patches/README.md
+++ b/patches/README.md
@@ -9,6 +9,14 @@ git apply --check patches/<name>.patch   # dry run
 git apply         patches/<name>.patch
 ```

+## `tier.json` — adding or changing a patch
+
+A `.patch` file does not say enough on its own. The Runic Gateway installer's patch tier also has to know which patches form **one all-or-nothing unit**, which companion `.cs` may only be copied once that unit has landed, whether the change needs a **core** solution rebuild or just the dynamic script build, and what the operator loses by declining. None of that is derivable from a diff, so it is declared in [`tier.json`](tier.json).
+
+**Adding a patch means adding it there in the same PR.** The release workflow checks the table in both directions — every `.patch` described by exactly one feature, every named patch and companion present, every `target` equal to the file the diff actually edits — so a patch without an entry fails the release rather than shipping a tier that silently never offers it.
+
+`tier.json` is folded into the tarball's `manifest.json` as `patch_tier` and removed from the staged `patches/` directory, so the artifact carries exactly one copy of the table and it is the one the installer reads. Installers older than this key ignore it; an installer newer than the overlay it is deploying falls back to a built-in copy. See `docs/installer/PLAN.md` §2.2 and §7.0.
+
 ## Phase 7 — player-vendor sale (a coupled unit)

 Player-vendor purchases raise **no** EventSink. `ValidVendorPurchase` / `ValidVendorSell` cover NPC vendors only. The commit point is `PlayerVendorBuyGump.OnResponse`, the only place where buyer, vendor **owner**, price, and commission are all in scope — exactly what cheat detection needs. See [PLAN.md](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/link/PLAN.md) §6.
--- a/patches/tier.json
+++ b/patches/tier.json
@@ -0,0 +1,69 @@
+{
+  "_comment": [
+    "The patch tier, described for the Runic Gateway installer.",
+    "",
+    "A .patch file on its own does not say enough to run the tier safely. The installer",
+    "additionally has to know which patches form ONE all-or-nothing unit (the two",
+    "vendor-sale patches are useless apart), which companion .cs may only be copied once",
+    "that unit has landed, whether the change needs a CORE solution rebuild or just the",
+    "dynamic script build, and what capability the operator loses by declining. None of",
+    "that is derivable from the diffs, so it is declared here.",
+    "",
+    "This file is the maintainer-facing source of truth. release.yml folds it into",
+    "manifest.json as `patch_tier` and removes it from the staged patches/ directory, so",
+    "the tarball carries exactly one copy and it is the one the installer reads",
+    "(docs/installer/PLAN.md §7.0). CI also asserts that every .patch here is named by",
+    "exactly one feature and every named patch and companion exists — adding a patch",
+    "without describing it fails the release rather than shipping a tier that silently",
+    "ignores it.",
+    "",
+    "Older installers ignore `patch_tier` entirely, and an installer newer than the",
+    "overlay it is deploying falls back to its own built-in copy of this table."
+  ],
+
+  "features": [
+    {
+      "name": "vendor-sale",
+      "summary": "vendor.sale events — player-vendor purchases with buyer, owner, item, price and commission",
+      "lost": "no vendor.sale events",
+      "rebuild": "core",
+      "patches": [
+        {
+          "name": "playervendor-sale-eventsink",
+          "file": "playervendor-sale-eventsink.patch",
+          "target": "Server/EventSink.cs"
+        },
+        {
+          "name": "playervendor-sale-gump",
+          "file": "playervendor-sale-gump.patch",
+          "target": "Scripts/Gumps/PlayerVendorGumps.cs"
+        }
+      ],
+      "companions": [
+        {
+          "file": "BridgeVendorSale.cs",
+          "install_to": "Scripts/Custom/Bridge/BridgeVendorSale.cs"
+        }
+      ]
+    },
+    {
+      "name": "moderation-audit",
+      "summary": "in-game moderation actions ([ban, [kick, [bcast) forwarded to the website as admin.audit",
+      "lost": "no in-game moderation audit forwarding",
+      "rebuild": "scripts",
+      "patches": [
+        {
+          "name": "commandlogging-event",
+          "file": "commandlogging-event.patch",
+          "target": "Scripts/Commands/Logging.cs"
+        }
+      ],
+      "companions": [
+        {
+          "file": "BridgeModerationAudit.cs",
+          "install_to": "Scripts/Custom/Bridge/BridgeModerationAudit.cs"
+        }
+      ]
+    }
+  ]
+}