Skip to content

Commit 55ed590

Browse files
hyperpolymathclaude
hyperpolymath
and
claude
committed
docs(cartridges): per-layer READMEs for 93 remaining cartridges + STATE counter fix
Generator reads actual file contents (line counts, test counts, export counts, stub detection) to produce meaningful per-layer READMEs — not templated boilerplate. Stub FFIs (<100 lines or "Stub" markers) get an explicit Promotion gate section; substantive FFIs don't. Also corrects stale '18/18' .so build counter in STATE.a2ml §maintenance to reflect current 99/99 state. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent 6ac2b0a commit 55ed590

276 files changed

Lines changed: 10373 additions & 1 deletion

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.machine_readable/6a2/STATE.a2ml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -80,7 +80,7 @@ fake-fuzz-placeholder = false # tests/fuzz/placeholder.txt removed 2026-04-04
8080
[maintenance]
8181
must = [
8282
"Order-ticket end-to-end flow test (done)",
83-
"Cartridge .so/.dylib shared library builds (18/18 done)",
83+
"Cartridge .so/.dylib shared library builds (99/99 done — counter corrected 2026-04-18; prior '18/18' was stale from early cohort)",
8484
"CI/CD pipeline (zig-test.yml — done)",
8585
"Hash verification wired to mount (done)",
8686
"Distinct error codes for all failure modes (done)",

‎cartridges/aerie-mcp/abi/README.adoc‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
// SPDX-License-Identifier: PMPL-1.0-or-later
2+
// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
3+
= aerie-mcp / abi — Idris2 ABI layer
4+
:orientation: shallow
5+
6+
== Purpose
7+
8+
Cartridge-local protocol types for `aerie-mcp`. Defines the data, tool, and
9+
transition vocabulary this cartridge speaks. Inherits safety lemmas and the
10+
matrix-cell identifier scheme from the trunk ABI at `src/abi/`.
11+
12+
== Files
13+
14+
1 Idris2 module(s), ~47 lines total. Lead module:
15+
`Protocol.idr`.
16+
17+
No `.ipkg` — consumed directly by wider BoJ callers; type-checks inside the
18+
trunk `boj.ipkg`.
19+
20+
== Invariants
21+
22+
* `%default total` at every module top.
23+
* Zero `believe_me`, `assert_total`, `postulate`, `Admitted`, or
24+
`sorry` (the trunk holds the four declared `believe_me` sites; leaf
25+
cartridges carry none).
26+
27+
== Test/proof surface
28+
29+
Thin module(s), no inline tests. Proof surface = type-check success under the
30+
trunk `idris2 --check`.
31+
32+
== Read-first
33+
34+
. `Protocol.idr` — cartridge-local data records and enums.
35+
. Trunk `src/abi/Boj/Catalogue.idr` for how this cell participates in the
36+
2D matrix.

‎cartridges/aerie-mcp/adapter/README.adoc‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
// SPDX-License-Identifier: PMPL-1.0-or-later
2+
// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
3+
= aerie-mcp / adapter — protocol bridge
4+
:orientation: shallow
5+
6+
== Purpose
7+
8+
Exposes this cartridge's FFI over the wire protocols declared in
9+
`cartridge.json`. Dispatches tool invocations to the C-ABI exports at
10+
`../ffi/` and formats responses per protocol.
11+
12+
== Files
13+
14+
[cols="1,4"]
15+
|===
16+
| File | Role
17+
18+
| `build.zig` | Zig build graph — depends on the sibling `ffi` target.
19+
| `aerie_adapter.zig` | Protocol dispatch (129 lines). Tool catalogue matches `cartridge.json`.
20+
| `SIDELINED-*.v.adoc` | V-lang predecessor(s). Not built — V-lang banned 2026-04-10.
21+
|===
22+
23+
== Invariants
24+
25+
* **Stateless** — all state lives behind the FFI, never in the adapter.
26+
* **Response passthrough** — whatever the FFI returns goes back to the wire
27+
unmodified (no embellishment, no silent recovery).
28+
* **Cartridge.json is source of truth** for the tool catalogue; drift between
29+
adapter and manifest is a CI failure.
30+
31+
== Test/proof surface
32+
33+
No inline tests at the adapter layer — protocol routing is exercised by the
34+
trunk seam tests at `ffi/zig/src/seams.zig`.
35+
36+
== Read-first
37+
38+
. `aerie_adapter.zig` — dispatch function and per-protocol routers.
39+
. `../cartridge.json` — the tool manifest the dispatcher mirrors.

‎cartridges/aerie-mcp/ffi/README.adoc‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
// SPDX-License-Identifier: PMPL-1.0-or-later
2+
// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
3+
= aerie-mcp / ffi — Zig FFI layer **(stub)**
4+
:orientation: shallow
5+
6+
== Purpose
7+
8+
C-ABI exports bridging this cartridge's Idris2 ABI to the runtime. Consumed by
9+
the adapter for protocol dispatch and by the trunk loader for mount.
10+
11+
== Files
12+
13+
[cols="1,4"]
14+
|===
15+
| File | Role
16+
17+
| `build.zig` | Zig build graph — produces `zig-out/lib/libaerie.so`.
18+
| `aerie_ffi.zig` | C-ABI exports (4 exports, 3 inline tests, 43 lines).
19+
|===
20+
21+
== Invariants
22+
23+
* **Null-pointer rejection** on `[*c]const u8` arguments before any
24+
dereference.
25+
* **Negative return values** carry documented error meanings; zero is
26+
success (matching the trunk error-code convention).
27+
* **No allocator leaks** — every allocation path pairs with `defer free`.
28+
29+
== Test/proof surface
30+
31+
3 inline `test "..."` block(s) in `aerie_ffi.zig`. Run with
32+
`cd ffi && zig build test`.
33+
34+
== Read-first
35+
36+
. `aerie_ffi.zig` — C-ABI signatures and guards.
37+
. Trunk `ffi/zig/src/catalogue.zig` for how this `.so` is loaded.
38+
39+
== Promotion gate
40+
41+
Wire these exports to real backing state (not `return 0` / `return 1`
42+
placeholders) before promoting past D.

‎cartridges/affinescript-mcp/abi/README.adoc‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
// SPDX-License-Identifier: PMPL-1.0-or-later
2+
// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
3+
= affinescript-mcp / abi — Idris2 ABI layer
4+
:orientation: shallow
5+
6+
== Purpose
7+
8+
Cartridge-local protocol types for `affinescript-mcp`. Defines the data, tool, and
9+
transition vocabulary this cartridge speaks. Inherits safety lemmas and the
10+
matrix-cell identifier scheme from the trunk ABI at `src/abi/`.
11+
12+
== Files
13+
14+
1 Idris2 module(s), ~165 lines total. Lead module:
15+
`SafeCompiler.idr`.
16+
17+
No `.ipkg` — consumed directly by wider BoJ callers; type-checks inside the
18+
trunk `boj.ipkg`.
19+
20+
== Invariants
21+
22+
* `%default total` at every module top.
23+
* Zero `believe_me`, `assert_total`, `postulate`, `Admitted`, or
24+
`sorry` (the trunk holds the four declared `believe_me` sites; leaf
25+
cartridges carry none).
26+
27+
== Test/proof surface
28+
29+
Thin module(s), no inline tests. Proof surface = type-check success under the
30+
trunk `idris2 --check`.
31+
32+
== Read-first
33+
34+
. `SafeCompiler.idr` — cartridge-local data records and enums.
35+
. Trunk `src/abi/Boj/Catalogue.idr` for how this cell participates in the
36+
2D matrix.

‎cartridges/affinescript-mcp/adapter/README.adoc‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
// SPDX-License-Identifier: PMPL-1.0-or-later
2+
// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
3+
= affinescript-mcp / adapter — protocol bridge
4+
:orientation: shallow
5+
6+
== Purpose
7+
8+
Exposes this cartridge's FFI over the wire protocols declared in
9+
`cartridge.json`. Dispatches tool invocations to the C-ABI exports at
10+
`../ffi/` and formats responses per protocol.
11+
12+
== Files
13+
14+
[cols="1,4"]
15+
|===
16+
| File | Role
17+
18+
| `build.zig` | Zig build graph — depends on the sibling `ffi` target.
19+
| `affinescript_adapter.zig` | Protocol dispatch (212 lines). Tool catalogue matches `cartridge.json`.
20+
| `SIDELINED-*.v.adoc` | V-lang predecessor(s). Not built — V-lang banned 2026-04-10.
21+
|===
22+
23+
== Invariants
24+
25+
* **Stateless** — all state lives behind the FFI, never in the adapter.
26+
* **Response passthrough** — whatever the FFI returns goes back to the wire
27+
unmodified (no embellishment, no silent recovery).
28+
* **Cartridge.json is source of truth** for the tool catalogue; drift between
29+
adapter and manifest is a CI failure.
30+
31+
== Test/proof surface
32+
33+
No inline tests at the adapter layer — protocol routing is exercised by the
34+
trunk seam tests at `ffi/zig/src/seams.zig`.
35+
36+
== Read-first
37+
38+
. `affinescript_adapter.zig` — dispatch function and per-protocol routers.
39+
. `../cartridge.json` — the tool manifest the dispatcher mirrors.

‎cartridges/affinescript-mcp/ffi/README.adoc‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
// SPDX-License-Identifier: PMPL-1.0-or-later
2+
// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
3+
= affinescript-mcp / ffi — Zig FFI layer
4+
:orientation: shallow
5+
6+
== Purpose
7+
8+
C-ABI exports bridging this cartridge's Idris2 ABI to the runtime. Consumed by
9+
the adapter for protocol dispatch and by the trunk loader for mount.
10+
11+
== Files
12+
13+
[cols="1,4"]
14+
|===
15+
| File | Role
16+
17+
| `build.zig` | Zig build graph — produces `zig-out/lib/libaffinescript.so`.
18+
| `affinescript_mcp_ffi.zig` | C-ABI exports (15 exports, 6 inline tests, 369 lines).
19+
|===
20+
21+
== Invariants
22+
23+
* **Null-pointer rejection** on `[*c]const u8` arguments before any
24+
dereference.
25+
* **Negative return values** carry documented error meanings; zero is
26+
success (matching the trunk error-code convention).
27+
* **No allocator leaks** — every allocation path pairs with `defer free`.
28+
29+
== Test/proof surface
30+
31+
6 inline `test "..."` block(s) in `affinescript_mcp_ffi.zig`. Run with
32+
`cd ffi && zig build test`.
33+
34+
== Read-first
35+
36+
. `affinescript_mcp_ffi.zig` — C-ABI signatures and guards.
37+
. Trunk `ffi/zig/src/catalogue.zig` for how this `.so` is loaded.

‎cartridges/agent-mcp/abi/README.adoc‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
// SPDX-License-Identifier: PMPL-1.0-or-later
2+
// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
3+
= agent-mcp / abi — Idris2 ABI layer
4+
:orientation: shallow
5+
6+
== Purpose
7+
8+
Cartridge-local protocol types for `agent-mcp`. Defines the data, tool, and
9+
transition vocabulary this cartridge speaks. Inherits safety lemmas and the
10+
matrix-cell identifier scheme from the trunk ABI at `src/abi/`.
11+
12+
== Files
13+
14+
2 Idris2 module(s), ~367 lines total. Lead module:
15+
`Protocol.idr`.
16+
17+
No `.ipkg` — consumed directly by wider BoJ callers; type-checks inside the
18+
trunk `boj.ipkg`.
19+
20+
== Invariants
21+
22+
* `%default total` at every module top.
23+
* Zero `believe_me`, `assert_total`, `postulate`, `Admitted`, or
24+
`sorry` (the trunk holds the four declared `believe_me` sites; leaf
25+
cartridges carry none).
26+
27+
== Test/proof surface
28+
29+
Thin module(s), no inline tests. Proof surface = type-check success under the
30+
trunk `idris2 --check`.
31+
32+
== Read-first
33+
34+
. `Protocol.idr` — cartridge-local data records and enums.
35+
. Trunk `src/abi/Boj/Catalogue.idr` for how this cell participates in the
36+
2D matrix.

‎cartridges/agent-mcp/adapter/README.adoc‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
// SPDX-License-Identifier: PMPL-1.0-or-later
2+
// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
3+
= agent-mcp / adapter — protocol bridge
4+
:orientation: shallow
5+
6+
== Purpose
7+
8+
Exposes this cartridge's FFI over the wire protocols declared in
9+
`cartridge.json`. Dispatches tool invocations to the C-ABI exports at
10+
`../ffi/` and formats responses per protocol.
11+
12+
== Files
13+
14+
[cols="1,4"]
15+
|===
16+
| File | Role
17+
18+
| `build.zig` | Zig build graph — depends on the sibling `ffi` target.
19+
| `agent_adapter.zig` | Protocol dispatch (144 lines). Tool catalogue matches `cartridge.json`.
20+
| `SIDELINED-*.v.adoc` | V-lang predecessor(s). Not built — V-lang banned 2026-04-10.
21+
|===
22+
23+
== Invariants
24+
25+
* **Stateless** — all state lives behind the FFI, never in the adapter.
26+
* **Response passthrough** — whatever the FFI returns goes back to the wire
27+
unmodified (no embellishment, no silent recovery).
28+
* **Cartridge.json is source of truth** for the tool catalogue; drift between
29+
adapter and manifest is a CI failure.
30+
31+
== Test/proof surface
32+
33+
No inline tests at the adapter layer — protocol routing is exercised by the
34+
trunk seam tests at `ffi/zig/src/seams.zig`.
35+
36+
== Read-first
37+
38+
. `agent_adapter.zig` — dispatch function and per-protocol routers.
39+
. `../cartridge.json` — the tool manifest the dispatcher mirrors.

‎cartridges/agent-mcp/ffi/README.adoc‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
// SPDX-License-Identifier: PMPL-1.0-or-later
2+
// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
3+
= agent-mcp / ffi — Zig FFI layer
4+
:orientation: shallow
5+
6+
== Purpose
7+
8+
C-ABI exports bridging this cartridge's Idris2 ABI to the runtime. Consumed by
9+
the adapter for protocol dispatch and by the trunk loader for mount.
10+
11+
== Files
12+
13+
[cols="1,4"]
14+
|===
15+
| File | Role
16+
17+
| `build.zig` | Zig build graph — produces `zig-out/lib/libagent.so`.
18+
| `agent_ffi.zig` | C-ABI exports (18 exports, 10 inline tests, 406 lines).
19+
|===
20+
21+
== Invariants
22+
23+
* **Null-pointer rejection** on `[*c]const u8` arguments before any
24+
dereference.
25+
* **Negative return values** carry documented error meanings; zero is
26+
success (matching the trunk error-code convention).
27+
* **No allocator leaks** — every allocation path pairs with `defer free`.
28+
29+
== Test/proof surface
30+
31+
10 inline `test "..."` block(s) in `agent_ffi.zig`. Run with
32+
`cd ffi && zig build test`.
33+
34+
== Read-first
35+
36+
. `agent_ffi.zig` — C-ABI signatures and guards.
37+
. Trunk `ffi/zig/src/catalogue.zig` for how this `.so` is loaded.

0 commit comments

Comments
 (0)