feat(cartridges): sync bug-filing-mcp adapter/ into the bundled snapshot (#286)

<!--
SPDX-License-Identifier: CC-BY-SA-4.0
-->
## Summary

Syncs the bundled `bug-filing-mcp` cartridge to match the canonical
cartridge's new `adapter/` completion (companion PR in
`boj-server-cartridges`), and documents the
ABI=Idris2/FFI=Zig/Adapter=Zig baseline in `.claude/CLAUDE.md`.

## Changes

- `cartridges/bug-filing-mcp/adapter/` (new) — verbatim sync of the
unified protocol-bridge adapter (ADR-0004 internal-only,
transaction-gated, REST/SSE/GraphQL/gRPC-compat).
- `cartridges/bug-filing-mcp/abi/BugFilingMcp/SafeBugFiling.idr` —
synced exposure-gate proof.
- `cartridges/bug-filing-mcp/ffi/bug_filing_mcp_ffi.zig` — synced `pub
export` fix (Zig 0.15 cross-module import requirement).
- `.claude/CLAUDE.md` — the baseline documented, grounded in this repo's
own cartridge conventions.

## RSR Quality Checklist

### Required

- [x] Tests pass (`idris2 --typecheck` clean; `zig build test` green for
ffi + adapter; `boot_smoke` still OK — 68 tools)
- [x] Code is formatted
- [x] Linter is clean (no new warnings or errors)
- [x] No banned language patterns (no TypeScript, no npm/bun, no
Go/Python)
- [x] No `unsafe` blocks without `// SAFETY:` comments
- [x] No banned functions (`believe_me`, `unsafeCoerce`, `Obj.magic`,
`Admitted`, `sorry`) — `SafeBugFiling.idr` remains `%default total` with
zero escape hatches
- [x] SPDX license headers present on all new/modified source files
- [x] No secrets, credentials, or `.env` files included

### As Applicable

- [ ] `.machine_readable/STATE.a2ml` — no project-state change
(catalogue content only)
- [ ] `.machine_readable/ECOSYSTEM.a2ml` — no integration change
- [ ] `TOPOLOGY.md` — no architecture change
- [ ] `CHANGELOG` — deferring to the squash-merge summary
- [x] New dependencies reviewed — none added
- [x] ABI/FFI changes validated (`src/abi/` and `ffi/zig/` consistent) —
this PR only touches the bundled cartridge snapshot, not the server's
own core ABI/FFI

## Testing

Verified independently, not just copied: `idris2 --typecheck` clean
(0.7.0); `zig build test` green for both `ffi/` and `adapter/` (0.15.2);
`deno run mcp-bridge/tests/boot_smoke.js` still `OK:
serverInfo.name=boj-server, tools=68, exit=0`.

## Refs

Companion PR in `boj-server-cartridges` (canonical adapter completion,
extends #85). Part of #274.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_017LDhR8gtnittEWSafunnrq

---
_Generated by [Claude
Code](https://claude.ai/code/session_017LDhR8gtnittEWSafunnrq)_

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: hyperpolymath

.claude/CLAUDE.md

@@ -34,6 +34,49 @@ Adding to this list requires explicit user approval and an unblock condition. Au
 
 ---
 
+## ABI / FFI / Adapter Baseline (verified 2026-07-17)
+
+Every cartridge's interface stack is three layers, in these languages, no
+exceptions:
+
+| Layer | Language | Role |
+|---|---|---|
+| **ABI** | **Idris2** | Formally verified contract — dependent-type proofs, state machine or exposure-gate invariants, `%default total`, zero `believe_me`/`postulate`/`assert_total` in the trusted core. |
+| **FFI** | **Zig** | C-ABI implementation (ADR-0006 five-symbol pattern: `boj_cartridge_{init,deinit,name,version,invoke}`). |
+| **Adapter** | **Zig** | The base-level API/service surface — see below. |
+
+### The "unified adapter"
+
+The current canonical shape (see `cartridges/k9iser-mcp/adapter/` for the
+reference implementation, or `cartridges/templates/gossamer-mcp/adapter/` in
+`boj-server-cartridges` for the minting template): **one loopback listener**,
+protocol-classified (REST `/invoke`, SSE `/sse`, GraphQL `/graphql`, gRPC-compat
+`/grpc/<Svc>/<Method>`), that funnels every request through a **transaction
+gate** (`exposureSatisfied`, mirroring the cartridge's own Idris2 exposure
+contract when it has one) before a single dispatch call into the one Zig ABI
+(`ffi.boj_cartridge_invoke`). Invariants (from the adapter READMEs, verbatim):
+
+- **Stateless** — all state lives behind the FFI, never in the adapter.
+- **Response passthrough** — whatever the FFI returns goes back to the wire
+  unmodified (no embellishment, no silent recovery).
+- **`cartridge.json` is source of truth** for the tool catalogue; drift between
+  adapter and manifest is a CI failure.
+- **Internal-only, never a public ingress.** Per ADR-0004 the only governed
+  public surface is the `http-capability-gateway` (tier-2) in front of the
+  unified Zig core; adapters bind loopback and sit behind it.
+
+Naming lineage: the fuller 16-protocol-surface pattern is called the
+**Hexadeca-Connector** elsewhere in the estate (`hyperpolymath/hypatia`,
+`hyperpolymath/proven-servers`) — same Idris2-ABI + Zig-FFI substrate, more
+protocol surfaces. It descends from a now-**retired** V-lang reference
+(`developer-ecosystem/v-ecosystem/v_api_interfaces/v_api_interfaces.v`),
+replaced across the estate by Zig+Idris2(+Rust-client where relevant) per the
+V-lang ban (2026-04-10). Cartridge `adapter/` dirs keep a `SIDELINED-*.v.adoc`
+note documenting what was replaced — never resurrect the V version, and never
+substitute anything but Zig for a new adapter.
+
+---
+
 ## PR Workflow
 
 This repo squash-merges PRs. Two consequences worth knowing before pushing follow-ups:

cartridges/bug-filing-mcp/abi/BugFilingMcp/SafeBugFiling.idr

@@ -156,3 +156,47 @@ export
 bf_can_transition : Int -> Int -> Int
 bf_can_transition from to =
   if canTransition (intToFilingState from) (intToFilingState to) then 1 else 0
+
+-- ═══════════════════════════════════════════════════════════════════════════
+-- Exposure / transaction-gating contract (BoJ interface-safety policy)
+-- ═══════════════════════════════════════════════════════════════════════════
+-- A port boundary must never be a gatekeeperless gateway: every adapter
+-- exposes the unified ABI ONLY behind this transaction gate. Mirrors
+-- BojRest.TrustPolicy and K9iserMcp.SafeK9iser's identically-named contract:
+-- caller exposure derived from the cartridge's auth.method, loopback callers
+-- locally trusted, X-Trust-Level enforced otherwise.
+
+||| Caller trust the gateway/sidecar has established.
+public export
+data Exposure = Public | Authenticated | Internal
+
+||| Required exposure inferred from cartridge auth.method.
+||| "none"/absent -> Public; any credential-bearing method -> Authenticated.
+||| bug-filing-mcp's cartridge.json declares auth.method = "none", so this
+||| cartridge's required exposure is Public.
+public export
+requiredExposure : (authMethodIsNone : Bool) -> Exposure
+requiredExposure True  = Public
+requiredExposure False = Authenticated
+
+||| The transaction gate. Loopback callers are locally trusted (mcp-bridge,
+||| local curl). Otherwise the presented X-Trust-Level must meet the
+||| required exposure. This is the total relation the Zig transaction layer
+||| mirrors; no dispatch may occur unless it returns True.
+public export
+exposureSatisfied : (required : Exposure) -> (presented : Exposure) -> (isLocal : Bool) -> Bool
+exposureSatisfied _             _             True  = True
+exposureSatisfied Public        _             _     = True
+exposureSatisfied Authenticated Authenticated _     = True
+exposureSatisfied Authenticated Internal      _     = True
+exposureSatisfied Internal      Internal      _     = True
+exposureSatisfied _             _             _     = False
+
+||| FFI: 1 if dispatch is permitted, 0 if the gate rejects.
+||| req/pres encoding: 0=Public 1=Authenticated 2=Internal; isLocal: 1/0.
+export
+bf_exposure_satisfied : Int -> Int -> Int -> Int
+bf_exposure_satisfied req pres isLocal =
+  let r = case req  of { 0 => Public; 1 => Authenticated; _ => Internal }
+      p = case pres of { 0 => Public; 1 => Authenticated; _ => Internal }
+  in if exposureSatisfied r p (isLocal /= 0) then 1 else 0

cartridges/bug-filing-mcp/adapter/README.adoc

@@ -0,0 +1,51 @@
+// SPDX-License-Identifier: CC-BY-SA-4.0
+// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+= bug-filing-mcp / adapter — protocol bridge
+:orientation: shallow
+
+== Purpose
+
+Exposes this cartridge's FFI over the wire protocols declared in
+`cartridge.json`. Dispatches tool invocations to the C-ABI exports at
+`../ffi/` and formats responses per protocol.
+
+INTERNAL-ONLY unified adapter — not a public ingress. Per ADR-0004 the only
+governed public surface is the `http-capability-gateway` (tier-2); this
+adapter binds loopback (`127.0.0.1:9391`) and sits behind it.
+
+== Files
+
+[cols="1,4"]
+|===
+| File | Role
+
+| `build.zig`  | Zig build graph — depends on the sibling `ffi` target.
+| `bug_filing_mcp_adapter.zig` | Protocol dispatch. Tool catalogue matches `cartridge.json` (`research_feedback`, `synthesize_feedback`, `submit_feedback`).
+|===
+
+== Invariants
+
+* **Stateless** — all state lives behind the FFI, never in the adapter.
+* **Response passthrough** — whatever the FFI returns goes back to the wire
+  unmodified (no embellishment, no silent recovery). Since the FFI itself is
+  an honest delegation stub (see `../ffi/README.adoc` / `../ABI-FFI-README.md`
+  equivalent), every protocol surface here answers with that same delegation
+  notice — this adapter does not paper over what the FFI does not do.
+* **Cartridge.json is source of truth** for the tool catalogue; drift between
+  adapter and manifest is a CI failure.
+* **Transaction-gated** — every request passes `exposureSatisfied` (mirroring
+  `BugFilingMcp.SafeBugFiling.exposureSatisfied` in `../abi/`) before dispatch.
+  `auth.method: "none"` in `cartridge.json` means `requiredExposure = Public`.
+
+== Test/proof surface
+
+Inline Zig tests cover protocol classification, tool extraction per protocol,
+dispatch-to-ABI funneling, and the exposure-gate truth table (cross-checked
+against the Idris2 contract by hand — same truth table, same encoding).
+
+== Read-first
+
+. `bug_filing_mcp_adapter.zig` — dispatch function and per-protocol routers.
+. `../cartridge.json` — the tool manifest the dispatcher mirrors.
+. `../abi/BugFilingMcp/SafeBugFiling.idr` — the Idris2 contract this adapter's
+  gate mirrors.