0-AI-MANIFEST.a2ml

; 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 PanLL
; Media-Type: application/a2ml

; THIS FILE MUST BE READ FIRST BY ALL AI AGENTS

(manifest
  (identity
    (name "PanLL")
    (full-name "PanLL eNSAID — Neurosymbolic AI Development Environment")
    (version "0.1.0-alpha")
    (repo "https://github.com/hyperpolymath/panll")
    (license "PMPL-1.0-or-later")
    (author "Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>"))

  (purpose
    "Three-panel neurosymbolic workbench (Binary Star co-orbit model).
     Panel-L (Symbolic), Panel-N (Neural/ECHIDNA), Panel-W (World/VeriSimDB).
     Cognitive governance via Anti-Crash, Vexometer, Orbital sync, Contractiles.
     TypeLL provides cross-panel type intelligence as a shared service.")

  ;; ===================================================================
  ;; CONTEXT TIERS — controls what agents should load and when
  ;; ===================================================================

  (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/*.scm, docs/design/
    ; 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/      — auto-generated code
    ;   target/         — build artifacts
    ;   node_modules/   — dependencies
    ;   lib/bs/         — ReScript compiler cache
    ;   *.lock          — lock files
    ;   src-gossamer/target/ — Rust build output
    )

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

  (canonical-locations
    (ai-manifest     "0-AI-MANIFEST.a2ml"         "THIS FILE — read first")
    (ai-instructions ".claude/CLAUDE.md"           "Claude-specific patterns")

    ; Machine-readable checkpoint files (ONLY in .machine_readable/)
    (state           ".machine_readable/STATE.scm")
    (meta            ".machine_readable/META.scm")
    (ecosystem       ".machine_readable/ECOSYSTEM.scm")

    ; Key source files — see .claude/CLAUDE.md for full file table
    (model-root      "src/Model.res"               "Composition root")
    (messages        "src/Msg.res"                  "TEA message variants")
    (update-engine   "src/Update.res"               "State transition kernel")
    (view-root       "src/View.res"                 "Root view renderer")

    ; Infrastructure
    (gossamer-backend "src-gossamer/src/main.rs"    "Rust/Gossamer backend")
    (elixir-backend  "beam/"                        "Elixir/BEAM API layer")
    (rescript-config "rescript.json"                 "ReScript compiler config")
    (deno-config     "deno.json"                    "Deno tasks and import map"))

  ;; ===================================================================
  ;; TECH STACK
  ;; ===================================================================

  (tech-stack
    (primary    "ReScript"      "Gossamer (Rust + Zig + WebKitGTK)")
    (secondary  "Elixir/OTP"    "Deno")
    (testing    "Deno.test")
    (backend-provers "ECHIDNA REST on port 9000")
    (backend-db      "VeriSimDB REST on port 8080"))

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

  (critical-invariants
    ; Architecture
    (rule "TEA pattern: Model -> Msg -> Update -> View — no MVC, no Redux")
    (rule "All state lives in Model.model — no global mutable state")
    (rule "Anti-Crash validates ALL neural tokens — no bypasses")
    (rule "Contractiles evaluate after EVERY state-modifying update")
    (rule "TypeLL is cross-cutting — any panel can call TypeLLService")
    (rule "SCM files ONLY in .machine_readable/ — NEVER in root")
    (rule "Panels, not panes — PanLL uses 'panels' terminology")

    ; Ports
    (rule "Dev server: 8000 | ECHIDNA: 9000 | VeriSimDB: 8080")

    ; Code policy
    (rule "No TypeScript — ReScript only")
    (rule "No npm/bun — Deno only")
    (rule "PMPL-1.0-or-later on all source files"))

  ;; ===================================================================
  ;; STRUCTURE OVERVIEW (detail in CLAUDE.md)
  ;; ===================================================================

  (structure
    "panll/
     ├── 0-AI-MANIFEST.a2ml         # THIS FILE
     ├── src/                        # ReScript source (230 files, TEA)
     │   ├── Model.res, Msg.res, Update.res, View.res, App.res
     │   ├── model/                  # Domain modules (Pane, Echidna, VeriSim, Governance, TypeLL, ...)
     │   ├── core/                   # Engines (AntiCrash, Orbital, Contractiles, TypeLL, Vab, ...)
     │   ├── components/             # 106 panel views
     │   ├── commands/               # Gossamer bridge commands
     │   └── modules/                # Module registry + TypeLLService
     ├── src-gossamer/               # Rust/Gossamer backend
     ├── beam/                       # Elixir/BEAM API layer
     ├── tests/                      # 979 tests, 41 suites
     ├── .machine_readable/          # SCM checkpoint files
     └── .bot_directives/            # Bot instructions")

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

  (lifecycle
    (on-enter
      (step "Read THIS file first")
      (step "Read .claude/CLAUDE.md for build commands and conventions")
      (step "Read .machine_readable/STATE.scm for current status"))

    (on-exit
      (step "Update .machine_readable/STATE.scm if changes were made")
      (step "Summarise outcomes for session continuity")))

  ;; ===================================================================
  ;; CALLING ECHIDNA VIA BOJ
  ;; ===================================================================
  ;; All ECHIDNA calls go through the echidna-llm-mcp BoJ cartridge.
  ;; Never call ECHIDNA directly.
  ;;
  ;; Tools:
  ;;   echidna_list_provers  — discovery: 105 provers with tier/category
  ;;   echidna_prove         — invoke prover on a file path
  ;;   echidna_verify        — verify inline proof content
  ;;   echidna_search        — keyword search over proof corpus
  ;;   echidna_suggest_tactics — advisory tactic suggestions
  ;;   echidna_rank_provers  — advisory prover ranking
  ;;
  ;; Example:
  ;;   { "tool": "echidna_prove", "args": { "file": "/path/proof.lean", "prover": "Lean" } }
  ;;
  ;; Full protocol: boj-server/cartridges/echidna-llm-mcp/docs/CALL-PROTOCOL.adoc

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