boj-server-cartridges

Canonical home of BoJ cartridges. Hosts (boj-server, panll, others) fetch cartridges from here on demand into a host-local cache; this repository ships the source tree.

Machine-readable summary: 0-AI-MANIFEST.a2ml.

Table of Contents

• Status
• What is a cartridge?
• Taxonomy
• Cartridge roles
• Schema
• Validation
• Versioning + on-demand fetch
• Inventory
• Toolchain
• FFI / Zig shim layout
• Contributing
• Further reading
• License

Status

This is the canonical registry for the original BoJ server. BoJ MK2 is publicly archived; development is concentrated on this registry and boj-server. The 7 September 2026 validation covers 142 manifests (141 installable cartridges and one template), 217 native build/test/install roots, and 115 Idris proof checks. These denominators describe different checks, not 217 working tools.

The pinned toolchains are Zig 0.16.0, Idris 0.8.0 and Bun 1.3.14. The editor panel uses ReScript 11.1.4. Active sources damaged by the AffineScript conversion have been restored or explicitly retired; see restoration provenance and limits.

Use bash scripts/check-javascript.sh, bash scripts/build-native.sh, bash scripts/typecheck-proofs.sh and bash scripts/check-trusted-base.sh for actual gates. The active orchestration adapter also has its own locked mix test suite. Unimplemented legacy recipes fail explicitly.

Host readiness is per tool and per artifact. A manifest, successful build or process exit does not establish that an operation works. The original server currently qualifies a small pure native profile; network integrations, persistent language sessions and unwired SDK adapters need their own execution contracts and evidence before admission. Install a coherent registry snapshot, including shared cartridges/lib modules, rather than copying directories alone.

What is a cartridge?

See the canonical spec: standards/cartridges/CARTRIDGE-FORMAT.adoc and JSON schema: cartridge-v1.json.

A cartridge is a self-contained server unit consumed by a host to extend its tool surface (MCP), language-server reach (LSP), debug-adapter capabilities (DAP), build-tool integration (BSP), or other server-role mode. Cartridges are process-isolated (each backend listens on its own loopback port) and content-addressable.

Taxonomy

Hybrid layout ratified in docs/decisions/ADR-001-taxonomy.adoc:

cartridges/
├── domains/                  ← cartridges grouped by functional domain
│   ├── cloud/                ← 10 cartridges (umbrella + 9 providers)
│   ├── database/             ← 12 cartridges (umbrella + 11 providers)
│   ├── ci-cd/, languages/, security/, research/, …  (31 domains total)
├── cross-cutting/            ← cartridges not bound to a single domain
│   ├── agentic/              ← agent-mcp, claude-ai-mcp, model-router-mcp, …
│   ├── build/                ← bsp-mcp (generic BSP server)
│   ├── debug/                ← dap-mcp (generic DAP server)
│   ├── fleet/                ← fleet-mcp
│   ├── health/               ← boj-health-mcp
│   ├── nesy/                 ← nesy-mcp, ml-mcp
│   └── orchestration/        ← stack-orchestrator-mcp
└── templates/                ← canonical scaffolds for new cartridges
    └── gossamer-mcp/         ← reference template

Cartridge roles

A cartridge name ends in a canonical role suffix:

Suffix	Role
-mcp	Model Context Protocol
-lsp	Language Server Protocol
-dap	Debug Adapter Protocol
-bsp	Build Server Protocol
-debug	Debugger (when not strictly DAP)
-format	Code formatter
-lint	Linter / static analyser
-build	Build orchestration
-nesy	Neurosymbolic reasoning
-agentic	Agent harness
-fleet	Fleet orchestrator

A single domain may have multiple cartridges across roles, e.g. database-mcp
database-lsp + database-format.

Schema

schemas/cartridge-v1.json mirrors the canonical spec at hyperpolymath/standards. The mirror is SHA-pinned via schemas/PINNED-SHA (see also schemas/SCHEMA-MIRROR.md).

Validation

The pinned mirror is verified against schemas/PINNED-SHA on every CI run, then every cartridge.json is checked against schemas/cartridge-v1.json by the in-tree Bun/Ajv validator under tools/validate-cartridges/:

Task	Behaviour
bun tools/validate-cartridges/main.js --audit	Reports schema violations without failing for invalid manifests.
bun tools/validate-cartridges/main.js --strict	Fails for schema violations, duplicate names, malformed JSON, missing/empty input and schema-pin drift.

CI (.github/workflows/cartridge-schema.yml) runs the validator in strict mode — any manifest that fails schema validation blocks the PR. Audit output is still tee’d into the workflow summary for browsability. The drift-remediation campaigns (#18 missing category, #19 auth.method enum mismatches, #20 canonical-only / missing top-level fields / name-pattern renames) all closed alongside this gate flip; audits/cartridge-schema-2026-06-01.md records the 139/139 baseline as it stood on 2026-06-01. The tree has grown since: the current baseline is 142/142. Run just validate for the live figure rather than quoting either number.

Canonical schema home: hyperpolymath/standards.

Versioning + on-demand fetch

Each cartridge has a declared semantic version. The original server pins an exact registry Git revision in CARTRIDGES-REVISION and installs a coherent snapshot preserving shared imports. Its qualification document additionally binds each admitted tool to manifest, binary and runtime hashes.

Inventory

• 142 cartridge.json manifests: 141 cartridges + 1 template scaffold (templates/gossamer-mcp, which is not shippable and is excluded from the public catalogue).

• 31 functional domains + 7 cross-cutting categories (agentic, build, debug, fleet, health, nesy, orchestration) + 1 template.

• Every cartridge.json validates strictly against schemas/cartridge-v1.json.

• Availability fields are author declarations. The host requires separate, tool-specific artifact evidence; a successful build or manifest flag does not authorize execution.

These figures come from the tree, not from a stored constant. Recount with just validate (manifest total) and just catalog (catalogue total).

Toolchain

.tool-versions is authoritative:

Tool	Pin	Used by
zig	0.16.0	All ffi/ and native adapter/ build roots
bun	1.3.14	tools/validate-cartridges, tools/build-catalog, tools/cartridge-minter
idris2	0.8.0	abi/ contracts

FFI / Zig shim layout

Cartridges with a Zig FFI carry their own cartridge_shim.zig beside ffi/build.zig. Build configs resolve the shim with b.path("cartridge_shim.zig") (and b.path("../ffi/cartridge_shim.zig") for adapter siblings) — the per-cartridge layout is the de facto pattern (#29 / #31).

The canonical shim source is cartridges/templates/gossamer-mcp/ffi/cartridge_shim.zig.

116 shims are in the tree; 115 are byte-identical to canon. The one exception, cartridges/domains/gaming/npc-mcp/ffi/cartridge_shim.zig, is a stale copy that differs only in comments — rewrapped prose and an older heading style. Its API surface is identical: the same seven RC_* constants and the same three helpers (invokeArgsNull, toolIs, writeResult). Nothing behavioural turns on it.

(The figure previously printed here, "112 of 114", did not match the tree.)

Shim drift is not currently enforced. Nothing in CI compares a shim against canon, so a divergent copy would land silently — which is how the npc-mcp one persisted. A sync script and a shim-drift gate are part of #109; until that merges, copy the canonical file verbatim when adding an FFI cartridge and check it by hand:

find cartridges -name cartridge_shim.zig -exec md5sum {} + \
  | awk '{print $1}' | sort -u | wc -l   # 1 == no drift

The five-symbol ABI the shim implements is documented in ADR-0006.

Contributing

Full guide: docs/cartridge-authoring.adoc. In short:

1. Mint from the canonical template — write a minter.toml, then just mint path/to/minter.toml. (Don’t cp -r the template by hand; the minter also does the name substitutions.)

2. Update the manifest to reflect your cartridge’s name (role-suffixed), domain, protocols, tools.

3. just validate — new cartridges must validate cleanly against schemas/cartridge-v1.json. This is the CI gate.

4. just catalog — regenerate the public catalogue so the site matches the tree.

5. Open a PR; auto-merge is enabled by default for this repo.

Read docs/known-issues/adapters.adoc before you spend time on the adapter/ directory your mint produces.

Further reading

In-tree — versions alongside the code:

• docs/cartridge-authoring.adoc — layer contract, the five-symbol ABI, minting, gates.

• docs/known-issues/adapters.adoc — why adapter/ cannot be trusted.

• docs/decisions/ — ADRs, including the ADR-0006 pointer.

On the wiki — narrative and operational material, kept in a separate git repository (…/boj-server-cartridges.wiki.git), which is why it is not in this tree:

• Refresh Discipline — how hosts re-fetch.

• Schema Validation — working through manifest drift.

• FFI Shim Layout.

License

MPL-2.0. Cartridges retain their individual SPDX identifiers per cartridge.json.