feat(rust): RunicNPC as the Rust bundle's third artefact (runicnpc stage 4, D224)

The compose job carries the latest RunicNPC release that answers the API the
bridge's manifest declares (runicnpc_api), verified against its SHA256SUMS
like the other two; none when the bridge needs none, RunicNPC has not
released, or its API is too old, each said in the summary. Walked against a
mock Gitea in all three cases.

The installer reads the optional npc component (older bundles still parse),
fetches and checks RunicNPC's tarball against its manifest, places
RunicNPC.cs before the bridge in each instance's plugins directory, records
it, puts it back on update when edited or deleted, reports it in doctor, and
removes it on uninstall. Its data directory is never touched. Kits joins the
required plugins it reports.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY

.gitea/scripts/compose-bundles.sh

@@ -64,12 +64,14 @@ SERVUO_LINK_REPO="RunicGateway/link"
 SERVUO_OVERLAY_REPO="RunicGateway/servuo-plugins"
 RUST_LINK_REPO="RunicGateway/Rust-Link"
 RUST_PLUGIN_REPO="RunicGateway/Rust-Plugins"
+RUNICNPC_REPO="RunicGateway/runicnpc-rust"
 
 # Fixed top-level directories inside each payload tarball. Deliberately NOT
 # versioned — a versioned prefix would mean parsing the version out of a path in
 # order to read the manifest that declares the version.
 SERVUO_OVERLAY_PREFIX="runicgateway-overlay"
 RUST_PLUGIN_PREFIX="runicgateway-rust-plugin"
+RUNICNPC_PREFIX="runicnpc"
 
 mkdir -p "$WORK" "$PUBLISHED"
 : > "$WORK/summary.md"
@@ -375,6 +377,45 @@ compose_rust() {
   [ "$link_protocol" = "$plugin_protocol" ] || fail \
     "PROTOCOL MISMATCH — Rust-Link ${link_tag} speaks ${link_protocol}, Rust-Plugins ${plugin_tag} declares ${plugin_protocol}. The game link has no 409: a mismatched plugin would mis-parse. Fix: land the matching half and let its release cut, or bump Rust-Plugins/overlay.toml."
 
+  # RunicNPC (docs/runicnpc/PLAN.md D224): a third file, optional until its stage 9.
+  # The bridge's manifest says which RunicNPC API its npc.* commands need
+  # (`runicnpc_api`, from overlay.toml); the latest RunicNPC release is carried
+  # only when it answers at least that. A bridge that needs none carries none: a
+  # RunicNPC it cannot talk to would be an NPC plugin nobody manages.
+  local npc='null' need npc_tag npc_tarball npc_manifest npc_api npc_carried=''
+  need="$(jq -r '.runicnpc_api // 0' "$manifest")"
+  if [ "$need" -gt 0 ]; then
+    rc=0
+    resolve_latest "$RUNICNPC_REPO" runicnpc || rc=$?
+    if [ "$rc" -eq 2 ]; then
+      note "- **Rust**: the bridge needs RunicNPC API ${need}, and RunicNPC has not released yet — the bundle carries none."
+    else
+      npc_tag="$(release_tag runicnpc)"
+      verify_assets runicnpc
+      npc_tarball="$(single_tarball runicnpc)"
+      npc_manifest="$(payload_manifest runicnpc "$npc_tarball" "$RUNICNPC_PREFIX" "$npc_tag")"
+      [ -f "$(dirname "$npc_manifest")/RunicNPC.cs" ] \
+        || fail "the RunicNPC tarball has no ${RUNICNPC_PREFIX}/RunicNPC.cs"
+      npc_api="$(jq -r '.api' "$npc_manifest")"
+      echo "==> rust: RunicNPC ${npc_tag} api=${npc_api} | the bridge needs ${need}"
+      if [ "$npc_api" -lt "$need" ]; then
+        note "- **Rust**: RunicNPC \`${npc_tag}\` answers API ${npc_api} and the bridge needs ${need} — the bundle carries none until RunicNPC releases one that does."
+      else
+        npc="$(jq -n --arg repo "$RUNICNPC_REPO" --arg tag "$npc_tag" --slurpfile m "$npc_manifest" \
+          --argjson asset "$(asset_json runicnpc "$npc_tarball")" \
+          '{ repo: $repo, tag: $tag, version: ($tag | ltrimstr("v")), commit: $m[0].commit, api: $m[0].api,
+             compat: { frameworks: { oxide:  { min_version: $m[0].min_oxide_version },
+                                     carbon: { min_version: $m[0].min_carbon_version } },
+                       requires_plugins: $m[0].requires_plugins },
+             asset: $asset }')"
+        jq -e '([.commit, .compat.frameworks[].min_version] | all(type == "string"))
+               and (.api | type == "number") and (.compat.requires_plugins | type == "array")' <<<"$npc" >/dev/null \
+          || fail "the RunicNPC manifest is missing commit, api, a framework floor, or requires_plugins"
+        npc_carried="$npc_tag"
+      fi
+    fi
+  fi
+
   jq -n \
     --arg link_repo "$RUST_LINK_REPO" --arg link_tag "$link_tag" \
     --argjson assets "$assets" --argjson launcher "$launcher" \
@@ -382,6 +423,7 @@ compose_rust() {
     --slurpfile m "$manifest" \
     --argjson p_asset "$(asset_json rust-plugin "$tarball")" \
     --argjson protocol "$link_protocol" \
+    --argjson npc "$npc" \
     '{ schema: 2, game: "rust", protocol: $protocol,
        sidecar: { repo: $link_repo, tag: $link_tag, version: ($link_tag | ltrimstr("v")),
                   protocol: $protocol, assets: $assets, launcher: $launcher },
@@ -390,7 +432,8 @@ compose_rust() {
                   compat: { frameworks: { oxide:  { min_version: $m[0].min_oxide_version },
                                           carbon: { min_version: $m[0].min_carbon_version } },
                             requires_plugins: $m[0].requires_plugins },
-                  asset: $p_asset } }' > "$WORK/rust-s2.json"
+                  asset: $p_asset } }
+     + (if $npc == null then {} else { npc: $npc } end)' > "$WORK/rust-s2.json"
   # A manifest missing a key would compose a `null` the installer then trusts.
   jq -e '([.payload.compat.frameworks[].min_version, .payload.commit] | all(type == "string"))
          and (.payload.compat.requires_plugins | type == "array")' "$WORK/rust-s2.json" >/dev/null \
@@ -403,7 +446,7 @@ compose_rust() {
   local tag
   tag="$(fresh_tag "$PUBLISHED/v2/rust")"
   publish_doc "$PUBLISHED/v2/rust" "$tag" "$WORK/rust-s2.json"
-  note "- **Rust**: published \`${tag}\` — Rust-Link \`${link_tag}\`, Rust-Plugins \`${plugin_tag}\`, protocol ${link_protocol}."
+  note "- **Rust**: published \`${tag}\` — Rust-Link \`${link_tag}\`, Rust-Plugins \`${plugin_tag}\`, protocol ${link_protocol}${npc_carried:+, RunicNPC \`${npc_tag}\`}."
   echo "rust ${tag}" >> "$WORK/published-games.txt"
 }