feat(gateway): add static policy, catalog-integration design, roadmap

Static verb-governance policy for boj-server's 5-route surface
(container/gateway-policy.yaml, DSL v1 for http-capability-gateway).
Phase 1: all invoke calls public. Phase 2: catalog-mode replaces it.

Design doc (docs/gateway-catalog-integration.adoc) specifies the
PolicyLoader.load_from_boj_catalog/1 addition to http-capability-gateway:
reads BOJ_CARTRIDGES_ROOT/*/cartridge.json at boot, infers per-cartridge
invoke exposure from auth.method (none→public, api-key→authenticated).
No cartridge.json schema changes required.

ROADMAP.adoc: mark mod.js/cartridge.json parity complete (2026-04-25),
add v1.1.0 milestone for JS dispatch + gateway sidecar.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: hyperpolymath

ROADMAP.adoc

@@ -73,11 +73,27 @@ metadata parity before Grade C dogfooding.
 === v1.0.1 — Adapter Migration Recovery (P0, In Progress)
 
 * [ ] Remove remaining V-lang adapters across `cartridges/` (56 `.v` files as of 2026-04-12)
-* [ ] Ensure every cartridge has `cartridge.json` metadata (currently 65 files)
-* [ ] Ensure every cartridge has `mod.js` tool handlers (currently 64 files)
+* [x] Ensure every cartridge has `cartridge.json` metadata (all 106 cartridges covered 2026-04-25)
+* [x] Ensure every cartridge has `mod.js` tool handlers (all 106 cartridges covered 2026-04-25)
 * [ ] Re-run cartridge matrix build/tests and update `TEST-NEEDS.md` with current evidence
 * [ ] Refresh repo documentation claims after migration closure (counts, completion text, handover docs)
 
+=== v1.1.0 — JS Dispatch + Gateway Sidecar
+
+JS cartridge dispatch (the large remaining gap — 99 of 106 cartridges use `mod.js`, not Zig `.so`):
+
+* [ ] `BojRest.JsInvoker` — shells out to `deno run mod.js` per invocation (Phase 1: fork-per-call, ~50 ms overhead acceptable for initial traffic)
+* [ ] Router dispatch branch: if `cart["ffi"]` key present → `Invoker` (Zig path); else → `JsInvoker` (Deno path)
+* [ ] Fix `cartridge_so_path/1` to read `cart["ffi"]["so_path"]` from the manifest instead of hardcoding the derivation
+* [ ] End-to-end test: `curl POST /cartridge/boj-health/invoke` (Zig) + `curl POST /cartridge/local-memory-mcp/invoke` (JS)
+
+Gateway sidecar (`http-capability-gateway` in front of boj-server):
+
+* [ ] Add `gateway-policy.yaml` (done — `container/gateway-policy.yaml`) to dev compose as optional sidecar
+* [ ] Implement `PolicyLoader.load_from_boj_catalog/1` in `http-capability-gateway` — reads `BOJ_CARTRIDGES_ROOT/*/cartridge.json` at boot, infers per-cartridge invoke exposure from `auth.method` (`none` → `public`, `api-key`/`bearer` → `authenticated`). Zero manual policy maintenance thereafter. See `docs/gateway-catalog-integration.adoc`.
+* [ ] Update `compose.dev.yaml` with gateway sidecar entry (port 7800 → boj-rest:7700)
+* [ ] Retire static `gateway-policy.yaml` once catalog mode is live
+
 == Future Directions
 
 * **oDNS relay**: Distributed Oblivious DNS as a network service (research problem)

container/gateway-policy.yaml

@@ -0,0 +1,70 @@
+# SPDX-License-Identifier: PMPL-1.0-or-later
+# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+#
+# BoJ Server — http-capability-gateway verb governance policy (DSL v1)
+#
+# Sits in front of boj-server (port 7700). Gateway listens on port 7800
+# (override PORT env var). Backend: BACKEND_URL=http://127.0.0.1:7700
+#
+# Route surface (all 5 boj-server routes are covered):
+#   GET  /health                        — public, liveness probe
+#   GET  /menu                          — public, cartridge menu
+#   GET  /cartridges                    — public, cartridge name list
+#   GET  /cartridge/:name               — public, cartridge metadata
+#   POST /cartridge/:name/invoke        — auth-required for keyed cartridges
+#                                         (public fallback until catalog-mode lands)
+#
+# Phase 1 (this file): static policy, all invoke calls public.
+# Phase 2 (catalog-mode): gateway reads BOJ_CARTRIDGES_ROOT/*/cartridge.json
+#   at boot and auto-derives per-cartridge exposure from auth.method:
+#     "none"    → "public"
+#     "api-key" → "authenticated"
+#   Replaces this file entirely; zero ongoing maintenance.
+# See ROADMAP.adoc §v1.1.0 and docs/gateway-catalog-integration.adoc.
+
+dsl_version: "1"
+
+governance:
+  # Global default: only GET is allowed on any path not listed below.
+  # Prevents stray PUT / PATCH / DELETE / OPTIONS from reaching boj-server.
+  global_verbs:
+    - GET
+
+  routes:
+    # Liveness + readiness probe
+    - path: "^/health$"
+      verbs: [GET]
+      exposure: public
+      narrative: "Liveness probe — no auth required"
+
+    # Cartridge menu (human-readable catalogue with tiers)
+    - path: "^/menu$"
+      verbs: [GET]
+      exposure: public
+      narrative: "Cartridge menu — public read"
+
+    # Cartridge name list
+    - path: "^/cartridges$"
+      verbs: [GET]
+      exposure: public
+      narrative: "Cartridge inventory — public read"
+
+    # Per-cartridge metadata (cartridge.json contents)
+    - path: "^/cartridge/[^/]+$"
+      verbs: [GET]
+      exposure: public
+      narrative: "Cartridge metadata — public read"
+
+    # Tool invocation — POST only, no other verbs.
+    # Phase 1: public exposure (no auth wired yet in boj-server).
+    # Phase 2: replaced by per-cartridge rules generated from auth.method.
+    - path: "^/cartridge/[^/]+/invoke$"
+      verbs: [POST]
+      exposure: public
+      narrative: "Tool invocation — Phase 1 public; Phase 2 auto-derived from cartridge auth.method"
+
+stealth:
+  # Return 404 (not 403) for denied requests so the route surface does
+  # not advertise which paths exist to unauthenticated callers.
+  enabled: true
+  status_code: 404

docs/gateway-catalog-integration.adoc

@@ -0,0 +1,151 @@
+// SPDX-License-Identifier: PMPL-1.0-or-later
+// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+= BoJ Gateway — Catalog-Driven Auto-Policy (Design)
+:toc:
+:toc-placement: preamble
+
+Describes how `http-capability-gateway` will auto-derive its verb-governance
+policy from the BoJ cartridge catalog so that adding a cartridge never
+requires a manual policy update.
+
+== The Drift Problem
+
+`container/gateway-policy.yaml` handles boj-server's five routes.  The four
+read-only routes (`/health`, `/menu`, `/cartridges`, `/cartridge/:name`) are
+permanently public and never change.
+
+The fifth route, `POST /cartridge/:name/invoke`, is different: some cartridges
+require credentials (`api-key`, `bearer`) while others are fully public.
+Without auto-sync, operators must remember to update the gateway policy every
+time a keyed cartridge is added.  In an estate with 100+ cartridges this is an
+inevitable maintenance failure mode.
+
+== The Fix: `PolicyLoader.load_from_boj_catalog/1`
+
+A new loader mode in `http-capability-gateway` reads
+`$BOJ_CARTRIDGES_ROOT/*/cartridge.json` at startup and synthesises per-cartridge
+invoke rules.  The source of truth is already present in every
+`cartridge.json`:
+
+[source,json]
+----
+"auth": {
+  "method": "none"        // → exposure: public
+}
+----
+
+[source,json]
+----
+"auth": {
+  "method": "api-key",    // → exposure: authenticated
+  "env_var": "GITHUB_TOKEN"
+}
+----
+
+=== Exposure Inference Table
+
+[cols="2,2"]
+|===
+| `auth.method` | Gateway exposure
+
+| `none`        | `public`
+| `api-key`     | `authenticated`
+| `bearer`      | `authenticated`
+| `oauth`       | `authenticated`
+| _(anything else)_ | `authenticated` (fail-safe)
+|===
+
+=== Generated Policy Shape
+
+For each cartridge the loader emits two rules:
+
+[source,yaml]
+----
+# metadata read — always public
+- path: "^/cartridge/boj-health$"
+  verbs: [GET]
+  exposure: public
+
+# tool invocation — derived from auth.method
+- path: "^/cartridge/boj-health/invoke$"
+  verbs: [POST]
+  exposure: public       # because auth.method = "none"
+----
+
+[source,yaml]
+----
+- path: "^/cartridge/notifyhub-mcp/invoke$"
+  verbs: [POST]
+  exposure: authenticated  # because auth.method = "api-key"
+----
+
+These are merged with the static base rules for `/health`, `/menu`,
+`/cartridges`.
+
+No changes to `cartridge.json` schema are needed.  The inference is fully
+deterministic from existing fields.
+
+== Gateway Changes Required
+
+Two changes to `http-capability-gateway`:
+
+=== 1. `PolicyLoader.load_from_boj_catalog/1`
+
+[source,elixir]
+----
+@spec load_from_boj_catalog(catalog_root :: String.t()) :: {:ok, map()} | {:error, String.t()}
+def load_from_boj_catalog(catalog_root) do
+  # Scan cartridges/*/cartridge.json, infer per-cartridge rules,
+  # merge with static base policy for /health /menu /cartridges.
+end
+----
+
+=== 2. Config trigger
+
+[source,elixir]
+----
+config :http_capability_gateway,
+  catalog_integration: [
+    enabled: true,
+    root: System.get_env("BOJ_CARTRIDGES_ROOT", "/app/cartridges")
+  ]
+----
+
+When `enabled: true`, `Application.start/2` calls `load_from_boj_catalog/1`
+instead of `load_from_file/1`.  The static `gateway-policy.yaml` is retained
+only as a fallback if the catalog root is unreachable.
+
+== Compose / Container Integration
+
+[source,yaml]
+----
+services:
+  boj-gateway:
+    image: http-capability-gateway:latest
+    ports: ["7800:4000"]
+    environment:
+      BACKEND_URL: http://boj-rest:7700
+      BOJ_CARTRIDGES_ROOT: /workspace/cartridges
+      CATALOG_INTEGRATION_ENABLED: "true"
+    volumes:
+      - ..:/workspace:ro,z   # same mount as boj-rest dev compose
+----
+
+The gateway shares the read-only workspace mount and reads the same
+`cartridge.json` files boj-server uses.  No extra file sync needed.
+
+== Rollout Plan
+
+. *Phase 1 (done)*: static `container/gateway-policy.yaml`, all invoke calls
+  public.  Ships with boj-server; usable immediately when gateway is deployed.
+. *Phase 2*: implement `PolicyLoader.load_from_boj_catalog/1` in
+  `http-capability-gateway`.  Update `compose.dev.yaml` to add gateway
+  sidecar.  Retire the static file.
+. *Phase 3*: wire `:authenticated` trust check in boj-server's Invoker so
+  keyed-cartridge invoke calls that lack the credential are rejected at the
+  Elixir layer too (defence-in-depth behind the gateway).
+
+== Non-Changes
+
+`cartridge.json` schema is **not** extended.  The inference table above is
+the complete spec.  No new `"gateway"` section, no new fields.