boj-server/0-AI-MANIFEST.a2ml at main · hyperpolymath/boj-server · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
; SPDX-License-Identifier: PMPL-1.0-or-later
; SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath)
;
; 0-AI-MANIFEST.a2ml — Universal AI entry point for Bundle of Joy Server
; Media-Type: application/a2ml

; THIS FILE MUST BE READ FIRST BY ALL AI AGENTS

(manifest
  (identity
    (name "boj-server")
    (full-name "Bundle of Joy Server")
    (version "0.1.0")
    (repo "https://github.com/hyperpolymath/boj-server")
    (license "PMPL-1.0-or-later")
    (author "Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>"))

  (purpose
    "Cartridge server and protocol gateway. Three-class architecture:
     Class 1 (Simple) — self-contained cartridges via GitHub Actions.
     Class 2 (Orchestrator) — unified gateways (WS/MQTT/Webhook).
     Class 3 (Multiplier) — Elixir/BEAM for mass concurrency.
     Every cartridge has Idris2 ABI + Zig FFI + V-lang Adapter triple.")

  ;; ===================================================================
  ;; CONTEXT TIERS
  ;; ===================================================================

  (context-tiers
    ; Tier 0 (always load): This file + .claude/CLAUDE.md — orientation only
    ; Tier 1 (load if working on code): README.adoc, EXPLAINME.adoc, Justfile
    ; Tier 2 (load on demand): .machine_readable/*.a2ml, docs/
    ; Tier 3 (never load unless asked): tests/, generated/, CI configs
    ;
    ; DO NOT READ unless specifically asked:
    ;   tests/          — test files (run them, don't read them)
    ;   generated/abi/  — auto-generated C headers
    ;   target/         — build artifacts
    ;   node_modules/   — dependencies
    ;   *.lock          — lock files
    )

  ;; ===================================================================
  ;; CANONICAL LOCATIONS
  ;; ===================================================================

  (canonical-locations
    (ai-manifest     "0-AI-MANIFEST.a2ml"           "THIS FILE")
    (ai-instructions ".claude/CLAUDE.md"             "Claude-specific patterns")
    (state           ".machine_readable/6a2/STATE.a2ml")
    (meta            ".machine_readable/6a2/META.a2ml")
    (ecosystem       ".machine_readable/6a2/ECOSYSTEM.a2ml")
    (anchors         ".machine_readable/anchors/ANCHOR.a2ml")
    (policies        ".machine_readable/policies/")
    (bot-directives  ".machine_readable/bot_directives/")
    (contractiles    ".machine_readable/contractiles/"))

  ;; ===================================================================
  ;; STRUCTURE OVERVIEW
  ;; ===================================================================

  (structure
    "boj-server/
     ├── 0-AI-MANIFEST.a2ml         # THIS FILE
     ├── src/abi/                   # Idris2 ABI (Catalogue, Protocol, Domain, Menu, Federation)
     ├── ffi/zig/                   # Zig FFI (catalogue mount/unmount, loader)
     ├── generated/abi/             # Auto-generated C headers
     ├── adapter/v/                 # V-lang triple adapter (REST+gRPC+GraphQL, port 9000)
     ├── cartridges/                # One dir per matrix cell (database-mcp, nesy-mcp, fleet-mcp, ...)
     ├── container/                 # Stapeln container ecosystem
     ├── panll/src/                 # PanLL panel (ReScript/TEA)
     ├── docs/                      # ARCHITECTURE, CULTURAL-RESPECT, FEDERATION, DEVELOPERS
     └── .machine_readable/         # State, anchors, policies, bots, contractiles")

  ;; ===================================================================
  ;; CRITICAL INVARIANTS
  ;; ===================================================================

  (critical-invariants
    (rule "Three-Layer Stack: every cartridge = Idris2 ABI + Zig FFI + V-lang Adapter")
    (rule "Zero believe_me anywhere in src/abi/ or cartridges/*/abi/")
    (rule "%default total on all Idris2 files")
    (rule "IsUnbreakable proof required for Ready cartridges")
    (rule "Class 1 foundation MUST NOT be damaged by advanced features")
    (rule "Cultural respect: Teranga, Umoja, Ayo terminology is permanent")
    (rule "SCM files ONLY in .machine_readable/ — never in root")
    (rule "Container: Chainguard base, Containerfile not Dockerfile, Podman not Docker")
    (rule "PMPL-1.0-or-later on all source files"))

  ;; ===================================================================
  ;; SESSION LIFECYCLE
  ;; ===================================================================

  (lifecycle
    (on-enter
      (step "Read THIS file first")
      (step "Read .machine_readable/6a2/STATE.a2ml for current status")
      (step "Check for blockers before starting"))

    (on-exit
      (step "Update .machine_readable/6a2/STATE.a2ml if changes made")
      (step "Summarise outcomes")))

  (format-meta
    (version "2.1.0")
    (media-type "application/a2ml")
    (created "2026-03-02")
    (last-updated "2026-03-24")
    (maintained-by "Jonathan D.A. Jewell / hyperpolymath")
    (protocol "https://github.com/hyperpolymath/0-ai-gatekeeper-protocol")))