Skip to content

Home

Jump to bottom
hyperpolymath edited this page Jun 1, 2026 · 3 revisions

boj-server-cartridges wiki

Canonical home of BoJ cartridges: the registry that hosts (boj-server, panll, others) fetch from on-demand into a host-local cache. This wiki is the operator-facing companion to the source tree at https://github.com/hyperpolymath/boj-server-cartridges.

What this registry is

Each cartridge is a self-contained server unit — MCP / LSP / DAP / BSP / debug / format / lint / build / nesy / agentic / fleet — that a host loads to extend its capabilities. Cartridges are process-isolated (own loopback port per backend) and content-addressable. The repository ships:

  • cartridges/ — 139 cartridge sources, taxonomied across 30 functional domains plus 6 cross-cutting categories plus 1 template.
  • schemas/ — SHA-pinned mirror of the canonical schema.
  • tools/validate-cartridges/ — zero-dep Deno validator + unit tests.
  • audits/ — drift inventories captured at well-known dates.
  • docs/decisions/ — ADRs (currently ADR-001 ratifies the hybrid taxonomy).

Where things live

Concern Location
Cartridge sources cartridges/domains/<domain>/<name>/cartridge.json or cartridges/cross-cutting/<category>/<name>/cartridge.json
Schema (pinned mirror) schemas/cartridge-v1.json
Schema pin record schemas/PINNED-SHA
Schema refresh discipline (in-tree) schemas/SCHEMA-MIRROR.md
Validator tools/validate-cartridges/
Drift inventory audits/cartridge-schema-2026-06-01.md
Taxonomy decision docs/decisions/ADR-001-taxonomy.adoc
Canonical schema (upstream) hyperpolymath/standards
Downstream runtime consumer hyperpolymath/boj-server (scripts/fetch-cartridges.sh, elixir/lib/boj_rest/catalog.ex)

Wiki page index

  • Home — this page.
  • Cartridge Schema Validation — validator command surface, how to interpret output, how the drift inventory is structured, how strict-mode flips on, CI gate behaviour, how to add a new cartridge that passes validation.
  • Refresh Discipline — how to bump the schema mirror from canonical hyperpolymath/standards. PINNED-SHA format, exact gh api invocation for the canonical commit SHA, sha256sum for the content hash.
  • FFI Shim Layout — per-cartridge cartridge_shim.zig discipline (decided in #29 / #31): canonical shim source, build.zig path conventions, when to copy vs. extend.

Refresh the schema mirror

See Refresh Discipline in this wiki, and the in-tree authority at schemas/SCHEMA-MIRROR.md. The wiki page restates the discipline; the in-tree file is the binding source.

Status

Schema-validation foundation landed 2026-06-01. CI gate is live in strict mode as of 2026-06-01: it verifies the pinned SHA-256 of schemas/cartridge-v1.json, runs the validator's unit tests, and walks all 139 manifests — 139 passing, 0 failing (see audits/cartridge-schema-2026-06-01.md). Drift-remediation campaigns #18, #19, #20 all CLOSED, as is the FFI shim-path issue #29.

License

MPL-2.0. Individual cartridges carry their own SPDX identifiers in their cartridge.json.

Clone this wiki locally