diff --git a/.boj/project-memories.a2ml b/.boj/project-memories.a2ml index 63e457ad..45c045aa 100644 --- a/.boj/project-memories.a2ml +++ b/.boj/project-memories.a2ml @@ -33,8 +33,7 @@ schema_version = "1.0.0" "curl -sf -X POST http://127.0.0.1:7745/tools/coord_claim_task \ -H 'Content-Type: application/json' \ -d '{\"task_id\":\"\"}'") - (step 3 "Read the plan" - "cat .machine_readable/6a2/STATE.a2ml # look for [expansion-roadmap]")) + ) ; =================================================================== ; COMPLETION CONTRACT — the most important rule diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 1079d43c..c8854e68 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -6,7 +6,14 @@ Copyright (c) Jonathan D.A. Jewell ## Machine-Readable Artefacts -This repo follows the hyperpolymath standard. See `https://github.com/hyperpolymath/standards`. A2ML is retired (D308): do not create or edit `.a2ml` files, and do not treat `.machine_readable/6a2/` as current. Descriptive metadata moves to the repo's chora deed via kyX. +This repo follows the hyperpolymath standard. See `https://github.com/hyperpolymath/standards`. A2ML is retired (D99, D312, D313): never create, restore or extend a `.a2ml` file. You may only delete content from one. + +Machine-readable repo facts are deeds, checked with `bun /1-formats/deed/tools/deed_lint.js FILE`: + +- `boj-server_chora.deed` — the one repo deed: identity, clade, forges, lineage, lifecycle `(status)`, `(meta)` with the ADRs, `(agentic)`, `(neurosym)`, `(playbook)` and the `(anchor)` (semantic authority and golden path). +- `0-AI-MANIFEST.deed` — the pointer-only machine front door (A7 ruling Q15). It carries no facts. + +`docs/history/A2ML-REMOVED.adoc` is the ledger of the A2ML files retired on 2026-11-14: what each held, where its content went, and the four `.a2ml` files kept because a live reader still needs them. Do not recreate a removed file; the journal that `STATE.a2ml` carried continues in `docs/status/ROADMAP.adoc`. --- @@ -14,8 +21,8 @@ This repo follows the hyperpolymath standard. See `https://github.com/hyperpolym The full policy is canonical in `hyperpolymath/standards`. Key points relevant to this repo: -- **No new TypeScript** — convert existing TS to AffineScript (`.affine`) directly; AffineScript is no longer the destination as of 2026-04-30. -- **Deno** for the runtime, not Node. `deno.json` for imports, no `node_modules` in production. +- **No new TypeScript or ReScript** — convert existing TS/ReScript to AffineScript (`.affine`) directly; ReScript is no longer the destination as of 2026-04-30. +- **Bun** for the JS runtime (order Bun > Deno > pnpm > npm; npm only as the last resort), not Node. JS dependencies are declared in `package.json` and pinned by `bun.lock`; both are required. `bun install --production` for production dependencies. - **AffineScript** for new application code. Compiles to typed-wasm. ### TypeScript Exemptions (Approved) diff --git a/.github/0.1-AI-MANIFEST.a2ml b/.github/0.1-AI-MANIFEST.a2ml deleted file mode 100644 index 85b2f0f0..00000000 --- a/.github/0.1-AI-MANIFEST.a2ml +++ /dev/null @@ -1 +0,0 @@ -# AI Manifest - Level 1: .github diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 7d700011..3f6ac82e 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -45,7 +45,6 @@ boj-server/ ├── spec/ # Spec tests (Perimeter 3) ├── tests/ # Test suite (Perimeter 2-3) ├── .machine_readable/ # ALL machine-readable content (Perimeter 1) -│ ├── *.a2ml # State files (STATE, META, ECOSYSTEM, etc.) │ ├── bot_directives/ # Bot configs │ └── contractiles/ # Policy contracts (k9, dust, lust, must, trust) ├── .well-known/ # Protocol files (Perimeter 1-3) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 6e6cccdb..bf45f03b 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -9,8 +9,8 @@ Copyright (c) Jonathan D.A. Jewell ## Before Writing Code -- Read `0-AI-MANIFEST.a2ml` in the repo root for canonical file locations. -- State files (.a2ml) live in `.machine_readable/` ONLY, never the root. +- Read `0-AI-MANIFEST.deed` in the repo root: it points to `boj-server_chora.deed` (repo facts) and `.claude/CLAUDE.md` (agent conventions). +- A2ML is retired: never create a `.a2ml` file (see `docs/history/A2ML-REMOVED.adoc`). ## License @@ -55,6 +55,6 @@ Copyright (c) Jonathan D.A. Jewell ## State Files -Never create these in the repo root: -STATE.a2ml, META.a2ml, ECOSYSTEM.a2ml, AGENTIC.a2ml, NEUROSYM.a2ml, PLAYBOOK.a2ml. -They belong in `.machine_readable/` only. +Repo state and metadata are clauses of `boj-server_chora.deed` (lifecycle `(status)`, +`(meta)`, `(agentic)`, `(neurosym)`, `(playbook)`, `(anchor)`). Never create STATE, META, +ECOSYSTEM, AGENTIC, NEUROSYM or PLAYBOOK `.a2ml` files anywhere. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 72f4461e..a980200c 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -29,9 +29,8 @@ Copyright (c) Jonathan D.A. Jewell ### As Applicable -- [ ] `.machine_readable/STATE.a2ml` updated (if project state changed) -- [ ] `.machine_readable/ECOSYSTEM.a2ml` updated (if integrations changed) -- [ ] `.machine_readable/META.a2ml` updated (if architectural decisions changed) +- [ ] `boj-server_chora.deed` updated and passing `deed_lint.js` (if lifecycle status, ADRs `(meta)` or the `(anchor)` changed) +- [ ] `docs/status/ROADMAP.adoc` updated (if project state changed) - [ ] Documentation updated for user-facing changes - [ ] `TOPOLOGY.md` updated (if architecture changed) - [ ] `CHANGELOG` or release notes updated diff --git a/.machine_readable/0.1-AI-MANIFEST.a2ml b/.machine_readable/0.1-AI-MANIFEST.a2ml deleted file mode 100644 index 9d2bc7a0..00000000 --- a/.machine_readable/0.1-AI-MANIFEST.a2ml +++ /dev/null @@ -1,29 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "machine-readable-pillar" -level: 1 -parent: "../0-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Registry for all machine-readable metadata, policies, and internal - automation scripts. - -canonical_locations: - state: "STATE.a2ml" - meta: "META.a2ml" - ecosystem: "ECOSYSTEM.a2ml" - agentic: "AGENTIC.a2ml" - neurosym: "NEUROSYM.a2ml" - playbook: "PLAYBOOK.a2ml" - anchors: "anchors/" - policies: "policies/" - ai_configs: "ai/" - compliance: "compliance/" - scripts: "scripts/" - -invariants: - - "Metadata files MUST follow a2ml format" - - "Internal automation MUST live in scripts/ subfolder" diff --git a/.machine_readable/6a2/0-AI-MANIFEST.a2ml b/.machine_readable/6a2/0-AI-MANIFEST.a2ml deleted file mode 100644 index 6bf1f8c7..00000000 --- a/.machine_readable/6a2/0-AI-MANIFEST.a2ml +++ /dev/null @@ -1,31 +0,0 @@ -# AI Manifest for 6a2 Directory - -## Purpose - -This manifest declares the AI-assistant context for the 6a2 machine-readable metadata directory. - -## Canonical Locations - -The 6 core A2ML files MUST exist in this directory: -1. AGENTIC.a2ml -2. ECOSYSTEM.a2ml -3. META.a2ml -4. NEUROSYM.a2ml -5. PLAYBOOK.a2ml -6. STATE.a2ml - -## Invariants - -- No duplicate files in root directory -- Single source of truth: this directory is authoritative -- No stale metadata - -## Protocol - -When multiple agents may write to A2ML files concurrently: -1. Read file and record git-sha-at-read in [provenance] section -2. Lock by creating .lock- -3. Write updated file with new [provenance] metadata -4. Release by removing lock file -5. On conflict: re-read and retry if git-sha-at-read does not match HEAD - diff --git a/.machine_readable/6a2/AGENTIC.a2ml b/.machine_readable/6a2/AGENTIC.a2ml deleted file mode 100644 index 11ee7ace..00000000 --- a/.machine_readable/6a2/AGENTIC.a2ml +++ /dev/null @@ -1,44 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -# -# AGENTIC.a2ml — AI agent constraints and capabilities -# Defines what AI agents can and cannot do in this repository. - -[metadata] -version = "0.2.0" -last-updated = "2026-04-25" - -[agent-permissions] -can-edit-source = true -can-edit-tests = true -can-edit-docs = true -can-edit-config = true -can-create-files = true - -[agent-constraints] -# What AI agents must NOT do: -# - Never use banned language patterns (believe_me, unsafeCoerce, etc.) -# - Never commit secrets or credentials -# - Never use banned languages (TypeScript, Python, Go, etc.) -# - Never place state files in repository root (must be in .machine_readable/) -# - Never relicense an existing file, and never run an automated licence -# sweep (LICENCE-POLICY.adoc A2). New files get correct SPDX from birth. -# - Never assume a licence. Read standards/LICENCE-POLICY.adoc: Rule 1 -# defaults to MPL-2.0 (code) / CC-BY-SA-4.0 (prose), but Rule 3 -# (co-developed), Rule 4 (network-deployed services) and Rule 5 -# (games) are AGPL-3.0-or-later, and Rule 2 names the PMPL register. -# - Never use elixir:1.16-alpine in Containerfile.fly — must be elixir:1.16 (Debian/glibc) to match wolfi-base Stage 3 ABI -# - Never add `*.json` to .dockerignore — would exclude cartridges/*/cartridge.json needed by seed nodes -# - fly.io [build].dockerfile resolves relative to fly.toml — always pass --dockerfile flag on CLI instead - -[maintenance-integrity] -fail-closed = true -require-evidence-per-step = true -allow-silent-skip = false -require-rerun-after-fix = true -release-claim-requires-hard-pass = true - -[automation-hooks] -# on-enter: Read 0-AI-MANIFEST.a2ml, then STATE.a2ml -# on-exit: Update STATE.a2ml with session outcomes -# on-commit: Run just validate-rsr diff --git a/.machine_readable/6a2/ECOSYSTEM.a2ml b/.machine_readable/6a2/ECOSYSTEM.a2ml index a9d25308..47573605 100644 --- a/.machine_readable/6a2/ECOSYSTEM.a2ml +++ b/.machine_readable/6a2/ECOSYSTEM.a2ml @@ -3,52 +3,6 @@ # # ECOSYSTEM.a2ml — Bundle of Joy Server ecosystem position -[metadata] -version = "0.2.0" -last-updated = "2026-04-25" - -[project] -name = "Bundle of Joy Server" -purpose = "Unified server capability catalogue with formally verified cartridges, distributed community hosting, and the Teranga menu system. Solves the combinatoric explosion of developer server protocols — AI goes to ONE place instead of hunting across dozens of MCP/LSP/etc servers." -role = "service" - -[position-in-ecosystem] -tier = "infrastructure" - -[related-projects] -projects = [ - { name = "proven-servers", relationship = "dependency", notes = "108 components (94 protocols + 8 core primitives + 6 connectors). BoJ imports proven-mcp types, dbconn, authconn, etc. All zero believe_me." }, - { name = "polystack", relationship = "supersedes", notes = "BoJ replaces polystack's 13 components. poly-cloud/container/db/k8s/git/iac/secret/queue/observability/proof/ssg become cartridges in the BoJ matrix." }, - { name = "PanLL", relationship = "primary-consumer", notes = "PanLL is the primary consumer. Panels need diverse capabilities dynamically — the BoJ catalogue tells them what's available." }, - { name = "echidna", relationship = "dependency", notes = "ECHIDNA 105-prover portfolio exposed via echidna-llm-mcp cartridge (v0.2.0). 8 tools: list_provers, prove, verify, search (REST :8000) + init, authenticate, suggest_tactics, rank_provers (LLM :7721). Consumer repos: typell, panll, nesy-solver, proven-servers, typed-wasm, 007-lang, aspasia." }, - { name = "hypatia", relationship = "integration", notes = "Hypatia scans cartridges for security. SafeReasoning harmonizes Neural (Hypatia) + Symbolic (Echidna) verdicts." }, - { name = "gitbot-fleet", relationship = "integration", notes = "SafeFleet enforces 6-bot gate policy. FleetCertified proof type requires all gates passed." }, - { name = "stapeln", relationship = "dependency", notes = "Container supply chain for node hosting. Chainguard base images, selur-compose, vordr, svalinn, cerro-torre." }, - { name = "language-bridges", relationship = "sibling-standard", notes = "Same Idris2/Zig stack (zig retired 2026-04-10). BoJ follows the ABI-FFI universal standard." }, - { name = "rsr-template-repo", relationship = "origin", notes = "BoJ was bootstrapped from rsr-template-repo. All 17 mandatory workflows present." }, -] - -[integration-points] -integrations = [ - { system = "PanLL", direction = "outbound", protocol = "a2ml_menu", notes = "PanLL reads menu.a2ml for capability discovery" }, - { system = "gitbot-fleet", direction = "bidirectional", protocol = "mcp", notes = "Fleet cartridge controls gitbot-fleet; fleet validates cartridges" }, - { system = "hypatia", direction = "inbound", protocol = "ci_workflow", notes = "Hypatia scans via hypatia-scan.yml" }, - { system = "Umoja network", direction = "bidirectional", protocol = "gossip_ipv6", notes = "Federated node discovery and attestation" }, - { system = "IndieWeb", direction = "outbound", protocol = "webmention", notes = "IndieWeb community integration for distributed hosting" }, -] - -[distribution-model] -type = "community-hosted" -description = "Volunteer nodes host BoJ servers, like Tor/IPFS. Hash attestation ensures integrity — tampered nodes are excluded from the community network but can still run locally." -seed-nodes = [ - { region = "Europe-West", operator = "hyperpolymath", fly-app = "boj-seed-eu", host = "boj-seed-eu.fly.dev", canonical-host = "eu.boj.hyperpolymath.dev", notes = "Deployed 2026-04-25 — lhr region" }, - { region = "Europe-Central", operator = "hyperpolymath", fly-app = "boj-seed-de", host = "boj-seed-de.fly.dev", canonical-host = "de.boj.hyperpolymath.dev", notes = "Deployed 2026-04-25 — fra region" }, - { region = "US-East", operator = "hyperpolymath", fly-app = "boj-seed-us", host = "boj-seed-us.fly.dev", canonical-host = "us.boj.hyperpolymath.dev", notes = "Deployed 2026-04-25 — iad region" }, - { region = "Asia-Pacific", operator = "hyperpolymath", fly-app = "boj-seed-ap", host = "boj-seed-ap.fly.dev", canonical-host = "ap.boj.hyperpolymath.dev", notes = "Deployed 2026-04-25 — syd region" }, -] -dns-status = "hyperpolymath.dev undelegated — registrar action needed (see container/fly/DNS-SETUP.adoc); *.fly.dev hostnames operative" -federation-protocol = "Umoja gossip (X25519 + ChaCha20-Poly1305, UDP 9999, IPv6)" - # ── Publishing (ADR-004: README single-source derivation) ────────────────── # README.adoc is canonical; README.md is DERIVED (GENERATED banner) for Glama, # which renders Markdown only. Regenerated + freshness-checked by the diff --git a/.machine_readable/6a2/META.a2ml b/.machine_readable/6a2/META.a2ml deleted file mode 100644 index f205beed..00000000 --- a/.machine_readable/6a2/META.a2ml +++ /dev/null @@ -1,74 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -# -# META.a2ml — Project meta-level information -# Architecture decisions, design rationale, governance. - -[metadata] -version = "0.3.0" -last-updated = "2026-04-25" - -[project-info] -type = "service" -languages = ["idris2", "zig", "elixir", "javascript", "scheme", "nickel"] -# v (zig) removed: banned estate-wide 2026-04-10. Adapter layer migrated to Zig. -# elixir: REST server (Plug/Cowboy on port 7700). javascript: Deno mod.js cartridges. -license = "MPL-2.0" -author = "Jonathan D.A. Jewell (hyperpolymath)" - -[architecture-decisions] -decisions = [ - { id = "ADR-001", title = "Three-layer stack: Idris2 ABI + Zig FFI + Zig Adapter (zig retired 2026-04-10)", status = "accepted", date = "2026-03-02" }, - { id = "ADR-002", title = "2D matrix: protocol types (cols) x capability domains (rows)", status = "accepted", date = "2026-03-02" }, - { id = "ADR-003", title = "Cartridge metaphor — swappable, verified capability modules", status = "accepted", date = "2026-03-02" }, - { id = "ADR-004", title = "IsUnbreakable proof type — only Ready cartridges can be mounted", status = "accepted", date = "2026-03-02" }, - { id = "ADR-005", title = "Umoja federation — gossip protocol, IPv6, hash attestation", status = "accepted", date = "2026-03-02" }, - { id = "ADR-006", title = "Teranga menu — three-tier A2ML (Core/Shield/Ayo)", status = "accepted", date = "2026-03-02" }, - { id = "ADR-007", title = "Order-ticket protocol — AI reads menu, writes order, BoJ mounts cartridges", status = "accepted", date = "2026-03-02" }, - { id = "ADR-008", title = "Zero believe_me policy — all Idris2 code must be total and sound", status = "accepted", date = "2026-03-02" }, - { id = "ADR-009", title = "Align BoJ with unified-zig-api stack (future work)", status = "accepted", date = "2026-04-17" }, - { id = "ADR-010", title = "Elixir REST server (Plug/Cowboy) replaces zig adapter; dual dispatch: boj-invoke CLI for FFI cartridges, JsWorkerPool for JS cartridges", status = "accepted", date = "2026-04-20" }, - { id = "ADR-011", title = "Persistent Deno worker pool (JsWorkerPool) over fork-per-call for JS dispatch — consistent-hash routing, pre-warmed workers", status = "accepted", date = "2026-04-25" }, - { id = "ADR-012", title = "http-capability-gateway sidecar in catalog mode (BOJ_CARTRIDGES_ROOT) replaces static gateway-policy.yaml", status = "accepted", date = "2026-04-25" }, - { id = "ADR-013", title = "Seed node deployment on fly.io — lean build (boj-invoke only, no cartridge .so); seed nodes serve JS path for all cartridges", status = "accepted", date = "2026-04-25" }, - { id = "ADR-014", title = "X-Trust-Level header enforcement for HTTP invoke — loopback bypass, keyed cartridges require authenticated/internal trust from external callers", status = "accepted", date = "2026-04-25" }, -] - -[development-practices] -build-tool = "just" -container-runtime = "podman" -ci-platform = "github-actions" -package-manager = "guix" # guix | guix | cargo | mix - -[maintenance-axes] -scoping-first = true -execution-order = "axis-1 > axis-2 > axis-3" -axis-1 = "must > intend > like" -axis-2 = "corrective > adaptive > perfective" -axis-3 = "systems > compliance > effects" - -[scoping] -sources = "README, roadmap, status docs, maintenance checklist, CI/security docs" -marker-scan = "TODO/FIXME/XXX/HACK/STUB/PARTIAL" -idris-unsound-scan = "believe_me/assert_total" - -[axis-2-maintenance-rules] -corrective-first = true -adaptive-second = true -adaptive-focus = "scope-change reconciliation, stale-reference removal, obsolete-work culling" -perfective-third = true -perfective-source = "axis-1 honest state after corrective/adaptive updates" - -[axis-3-audit-rules] -audit-focus = "systems in place, documentation explains actual state, safety/security accounted for, observed effects reviewed" -compliance-focus = "seams/compromises/exception register, bounded exceptions, anti-drift checks" -drift-risk-example = "single exception broadening into policy violation (e.g. AffineScript->TypeScript spread)" -effects-evidence = "benchmark execution/results and maintainer status dialogue/review" - -[design-rationale] -three-layer-stack = "Idris2 proves correctness (ABI), Zig executes at zero cost (FFI), Elixir+Deno serve the HTTP surface (REST server + JS worker pool — zig adapter retired 2026-04-10). Each layer is independently verifiable. Long-term target: adapter tier consumes libzig_api from developer-ecosystem/zig-api/." -seed-node-lean-build = "fly.io Depot builder limits build time to ~10 min. Compiling 111 cartridge .so files takes ~50 min. ADR-013: seed nodes build only boj-invoke (~3 min Stage 1) and serve all 111 cartridges via the JS path (mod.js). A separate full-image build triggers dedicated .so compilation for nodes that need FFI invocation." -trust-level-design = "HTTP invoke auth is enforced via X-Trust-Level header (public/authenticated/internal). Loopback callers bypass the check. External callers invoking keyed cartridges must supply X-Trust-Level: authenticated or internal. This is Phase 9 partial — credential forwarding Option C (RGTV broker) is future work." -matrix-model = "Every cell in the (Protocol x Domain) matrix is a cartridge. Protocols define HOW you talk to a server; domains define WHAT the server does. This separates concerns and enables independent development." -cultural-naming = "Teranga (Wolof: hospitality), Umoja (Swahili: unity), Ayo (Yoruba: joy) — naming reflects values of hospitality to users, unity across communities, and joy in contribution." -zero-believe-me = "believe_me is worse than a TODO because it compiles and hides the problem. Zero tolerance ensures all proofs are genuine." diff --git a/.machine_readable/6a2/NEUROSYM.a2ml b/.machine_readable/6a2/NEUROSYM.a2ml deleted file mode 100644 index b1948824..00000000 --- a/.machine_readable/6a2/NEUROSYM.a2ml +++ /dev/null @@ -1,24 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -# -# NEUROSYM.a2ml — Neurosymbolic integration metadata -# Configuration for Hypatia scanning and symbolic reasoning. - -[metadata] -version = "0.2.0" -last-updated = "2026-04-25" - -[hypatia-config] -scan-enabled = true -scan-depth = "standard" # quick | standard | deep -report-format = "json" -# logtalk removed 2026-04-12: Hypatia now consumes JSON AssailReport via Elixir rules - -[symbolic-rules] -# Custom symbolic rules for this project -# - { name = "no-unsafe-ffi", pattern = "believe_me|unsafeCoerce", severity = "critical" } - -[neural-config] -# Neural pattern detection settings -# confidence-threshold = 0.85 -# model = "hypatia-v2" diff --git a/.machine_readable/6a2/PLAYBOOK.a2ml b/.machine_readable/6a2/PLAYBOOK.a2ml deleted file mode 100644 index 6fc25717..00000000 --- a/.machine_readable/6a2/PLAYBOOK.a2ml +++ /dev/null @@ -1,103 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -# -# PLAYBOOK.a2ml — Operational playbook -# Runbooks, incident response, deployment procedures. - -[metadata] -version = "0.2.1" -last-updated = "2026-06-13" - -[deployment] -method = "gitops + manual" -targets = ["container", "fly.io"] - -[local-dev-deployment] -prereqs = ["zig >= 0.15", "elixir >= 1.16", "deno >= 1.40", "podman", "just"] -start = "just dev" -# Runs: compose.dev.yaml (boj-rest:7700 + http-capability-gateway:7800) -test = "just test" -invoke-check = "just invoke-check" - -[container-deployment] -# Full image (all 111 .so files + mod.js — ~50 min build) -build = "podman build -f container/Containerfile -t boj-server:latest ." -push = "just container-push" -compose = "podman compose -f container/compose.prod.yaml up -d" - -[fly-io-seed-deployment] -# Lean image (~3 min build — boj-invoke only, JS path for all cartridges) -# Run from repo root -deploy-eu = "fly deploy --app boj-seed-eu --config container/fly/fly-eu.toml --dockerfile container/Containerfile.fly --remote-only" -deploy-de = "fly deploy --app boj-seed-de --config container/fly/fly-de.toml --dockerfile container/Containerfile.fly --remote-only" -deploy-us = "fly deploy --app boj-seed-us --config container/fly/fly-us.toml --dockerfile container/Containerfile.fly --remote-only" -deploy-ap = "fly deploy --app boj-seed-ap --config container/fly/fly-ap.toml --dockerfile container/Containerfile.fly --remote-only" -deploy-all = "bash container/fly/deploy-seeds.sh" -# Health check after deploy: -health-check = "for h in eu de us ap; do echo \"=== $h ===\"; curl -sf https://boj-seed-${h}.fly.dev/health | jq .; done" - -[fly-io-notes] -# .dockerignore is critical — without it build context is ~2.8 GB (.git alone is ~2 GB) -# Containerfile.fly uses elixir:1.16 (Debian/glibc) in Stage 2 — NOT alpine (musl) -# Stage 3 is cgr.dev/chainguard/wolfi-base (glibc-native); gcompat not needed -# Stage 3 packages: ca-certificates openssl ncurses libstdc++ libssl3 curl -# [build].dockerfile in fly.toml resolves relative to fly.toml — use CLI --dockerfile flag instead -# Healthcheck uses curl /health (no .so dependency — seed nodes have no .so files) - -[fly-io-custom-domains] -# hyperpolymath.dev has no NS records as of 2026-04-25 — registrar action needed -# See container/fly/DNS-SETUP.adoc for full procedure -# Once DNS is delegated: fly certs add eu.boj.hyperpolymath.dev --app boj-seed-eu (etc.) -operative-urls = [ - "https://boj-seed-eu.fly.dev", - "https://boj-seed-de.fly.dev", - "https://boj-seed-us.fly.dev", - "https://boj-seed-ap.fly.dev", -] -future-canonical-urls = [ - "https://eu.boj.hyperpolymath.dev", - "https://de.boj.hyperpolymath.dev", - "https://us.boj.hyperpolymath.dev", - "https://ap.boj.hyperpolymath.dev", -] - -[incident-response] -# 1. Check .machine_readable/6a2/STATE.a2ml for current status -# 2. Review recent commits and CI results -# 3. Run `just validate` to check compliance -# 4. Run `just security` to audit for vulnerabilities -# 5. For fly.io incidents: fly status --app boj-seed-eu (etc.) - -[release-process] -# 1. Update version in STATE.a2ml, META.a2ml, Justfile -# 2. Run `just release-preflight` (validate + quality + security + maint-hard-pass) -# 3. Optional local permission hardening: `just perms-snapshot && just perms-lock` -# 4. Tag and push -# 5. Restore local permissions if needed: `just perms-restore` -# 6. Run `just container-push` if applicable -# 7. Redeploy seed nodes: bash container/fly/deploy-seeds.sh - -[maintenance-operations] -# Baseline audit: -# just maint-audit -# Hard release gate: -# just maint-hard-pass -# Permission audit: -# just perms-audit - -[ci-required-gates] -# Required status checks must ALWAYS report, or a PR touching none of a gate's -# paths sits mergeable_state=blocked forever (the "Expected" trap; see #216, -# which stranded #213/#215). Pattern for every required gate under -# .github/workflows/ (proofs, zig-test, e2e, abi-drift, backend-assurance, -# lsp-dap-bsp, truthfulness): -# 1. NO on.*.paths — the workflow always triggers (required check always created). -# 2. An always-run `changes` job recomputes the gate's path set via -# `git diff origin/...HEAD` (fail-safe: default run=true; only -# run=false on a successful diff with no relevant match). -# 3. Each heavy job: needs: changes + if: needs.changes.outputs.run == 'true'. -# A job skipped via if: reports SUCCESS to required checks. -# Do NOT rename jobs/checks (breaks branch-protection's required-context list). -# Adding a new required gate: follow this shape; never reintroduce on.*.paths. -diagnostic = "PR green but blocked => a required gate never reported (the on.*.paths trap). Fix: drop on.*.paths, add the changes-gate + if:-skipped heavy jobs." -rationale-docs = ["docs/AI-CONVENTIONS.adoc#ci-required-status-checks", "docs/wikis/CI-and-Required-Checks.adoc"] diff --git a/.machine_readable/6a2/README.adoc b/.machine_readable/6a2/README.adoc index 916a7020..988af7f8 100644 --- a/.machine_readable/6a2/README.adoc +++ b/.machine_readable/6a2/README.adoc @@ -1,30 +1,16 @@ // SPDX-License-Identifier: CC-BY-SA-4.0 // Copyright (c) Jonathan D.A. Jewell -# A2ML 6a2 Directory += Legacy 6a2 Directory -This directory contains the 6 core A2ML machine-readable metadata files for this repository. +A2ML is retired. The six descriptiles that lived here were translated into +`boj-server_chora.deed` where a mapping spec allowed, and the files were removed +on 2026-11-14. `docs/history/A2ML-REMOVED.adoc` records what each held and where +its content went. -## Files - -- `AGENTIC.a2ml` - AI agent operational gating, safety controls -- `ECOSYSTEM.a2ml` - Project ecosystem position, relationships, explicit boundaries -- `META.a2ml` - Architecture decisions (ADRs), development practices, design rationale -- `NEUROSYM.a2ml` - Symbolic semantics, composition algebra -- `PLAYBOOK.a2ml` - Executable plans, operational runbooks -- `STATE.a2ml` - Project state, phase, milestones, session history - -## Standards Compliance - -These files follow the A2ML Format Family specification from: -https://github.com/hyperpolymath/standards/tree/main/a2ml - -## Generation - -These files may be generated from .scm source files using transpilation tools. -Source .scm files should be removed after successful transpilation. - -## See Also - -- [A2ML Repository Template](https://github.com/hyperpolymath/standards/blob/main/A2ML-REPO-TEMPLATE.adoc) -- [6A2 Format Family](https://github.com/hyperpolymath/standards#a2ml-format-family-7-formats) +One file remains: +* `ECOSYSTEM.a2ml` — only its `[publishing.readme]` block, because + `.github/workflows/readme-derive.yml` (inlined from standards' + `readme-derive-reusable.yml`) reads that block and nothing else. It goes when + the reusable reads `ECOSYSTEM.deed` (standards A7 section 10). Do not add + anything to it. diff --git a/.machine_readable/6a2/STATE.a2ml b/.machine_readable/6a2/STATE.a2ml deleted file mode 100644 index b3d1c23e..00000000 --- a/.machine_readable/6a2/STATE.a2ml +++ /dev/null @@ -1,115 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -# -# STATE.a2ml — Project state checkpoint for Bundle of Joy Server - -[metadata] -project = "boj-server" -version = "1.1.0-wip" -last-updated = "2026-06-24" -status = "active" -grade = "C" - -[project-context] -name = "Bundle of Joy Server" -purpose = "Unified server capability catalogue. AI goes to ONE place instead of hunting across dozens of MCP servers. Distributed via community-hosted Umoja nodes with gossip protocol and hash attestation. 125 cartridges covering the full developer-tool matrix." -completion-percentage = 65 - -[stack] -# Current authoritative stack — zig adapter layer is GONE (banned 2026-04-10, removed 2026-04-12) -abi-layer = "Idris2 — formal interface definitions with dependent-type proofs" -ffi-layer = "Zig — C-ABI .so shared libraries (boj-invoke CLI for dlopen dispatch)" -rest-server = "Elixir (Plug/Cowboy) — HTTP surface on port 7700, 5 routes" -js-dispatch = "Deno — mod.js cartridges dispatched via BojRest.JsWorkerPool (persistent pool, consistent-hash routing) with JsInvoker fork-per-call fallback" -container = "Chainguard wolfi-base (Containerfile, 3-stage Zig+Elixir build)" -federation = "Zig QUIC gossip (X25519 + ChaCha20-Poly1305, UDP 9999)" - -[route-to-mvp] -milestones = [ - { name = "Phase 0: Fresh repo from rsr-template-repo", completion = 100 }, - { name = "Phase 1: Core catalogue & menu system (Idris2 ABI)", completion = 100 }, - { name = "Phase 2: Core Zig FFI layer (catalogue + loader)", completion = 100 }, - { name = "Phase 3: zig adapter layer", completion = 100, note = "RETIRED — zig banned 2026-04-10, all .v files removed 2026-04-12" }, - { name = "Phase 4: First cartridges — boj-health Zig FFI reference impl", completion = 100 }, - { name = "Phase 5: Umoja federation & PanLL panel", completion = 100 }, - { name = "Phase 6: 112-cartridge matrix (all have cartridge.json + mod.js)", completion = 100 }, - { name = "Phase 7: Elixir REST server wired to Zig FFI + JsWorkerPool (persistent Deno pool)", completion = 100 }, - { name = "Phase 8: Gateway sidecar (http-capability-gateway catalog mode + compose.dev.yaml)", completion = 100 }, - { name = "Phase 9: Auth layer (HTTP invoke caller auth, trust-level forwarding, credential proxy)", completion = 0 }, - { name = "Phase 10: Grade D→C (QUIC multi-node, SLA, seed nodes, external validation)", completion = 30 }, -] - -[quality] -cartridges-total = 125 # all 125 have cartridge.json as of 2026-05-25 -cartridges-with-zig-ffi = 115 # cartridges with ffi/ directory present (manifest counts; .so binaries built per-platform) -cartridges-with-js-mod = 113 # mod.js dispatch via Deno worker pool (model-router-mcp is canonical JS-only) -cartridges-with-both = 0 # no cartridge uses both paths -exunit-tests = 173 # 10 properties + 163 regular tests across 11 files; Phase 9 auth tests added 2026-04-25 -zig-ffi-chain-verified = true # boj-invoke → dlopen → libboj_health.so end-to-end tested 2026-04-25 -js-dispatch-chain-verified = true # JsWorkerPool → JsWorker → Deno port → mod.js handleTool -believe-me-count = 4 # all in SafetyLemmas.idr — 4 class (J) axioms over Idris2 primitives (charEqSound, unpackLength, appendLengthSum, substrLengthBound). charEqSym discharged to a constructive theorem (derived from charEqSound) — first §(a) discharge under standards#203, was 5. (The 2026-05-18 audit + #108 had reconciled a stale "4" up to a true 5; this discharge brings it to a true 4.) Reduced from 31 on 2026-04-12. -zig-files = 0 # all .v files removed 2026-04-12 -cartridges-available-real = 1 # only feedback-mcp is built+verified-real (available:true). ~97 cartridges build a .so that returns {"status":"stub"}; 10 have no FFI — ALL now marked available:false (PR #196, 2026-06-05). Catalogue no longer over-claims; tests/truthfulness_check.sh gate enforces it. -tla-elixir-harness = "specs/elixir-harness/ — 3 TLA+ models: JsWorker (341 states, depth 8), JsWorkerPool (RouteConsistency + crash-isolation + NoPendingWhileDown), Invoker (DoneOnce + 7 exit-code sanity controls). All have .cfg + non-vacuity checks. Formal-proof axis only; CRG grade unchanged." - -[open-gaps] -# Ordered by impact on users hitting POST /cartridge/:name/invoke -gap-1 = "PARTIALLY CLOSED 2026-04-25 — X-Trust-Level enforcement implemented (BojRest.TrustPolicy); keyed cartridges require authenticated/internal trust from non-loopback callers. Credential forwarding (Options A/B/C) still undecided." -gap-2 = "CLOSED for Options A+B 2026-04-25 — Option A (caller-supplied encrypted creds in request body) wired: CredentialDecryptor.extract/2 → dispatch → Invoker extra_env → subprocess env vars. Option B (node-level env vars) inherits from server process. Option C (RGTV broker) remains future work." -gap-3 = "Load-aware inter-node routing not wired — invocations are local only" -gap-5 = "CLOSED 2026-04-25 — All 4 fly.io seed nodes deployed and healthy (2/2 health checks passing): boj-seed-eu (lhr), boj-seed-de (fra), boj-seed-us (iad), boj-seed-ap (syd). Image 61 MB. .dockerignore fixed (ffi/zig/.zig-cache excluded — 347 MB); Containerfile.fly.dockerignore added for per-Dockerfile override (2.2 MB context for future deploys). DNS: hyperpolymath.dev still undelegated — .fly.dev hostnames operative." -gap-4 = "CLOSED 2026-04-25 — Test coverage reached CRG C (165 tests: 10 properties + 155 regular, 0 failures)" - -[critical-next-actions] -actions = [ - "Expand test suite DONE — 165 tests at CRG C as of 2026-04-25", - "Decide and implement HTTP invoke auth (see docs/AUTH-DESIGN.adoc — options: bearer token, mTLS header, or node-identity header)", - "Implement credential-forwarding design for federation (user keys travel with the request encrypted, vs node-level key config)", - "DONE — All 4 fly.io seed nodes deployed and healthy 2026-04-25 (lhr/fra/iad/syd). Registrar action still needed to delegate hyperpolymath.dev zone (see container/fly/DNS-SETUP.adoc).", -] - -[blockers-and-issues] -invoke-auth = "OPEN — HTTP invoke endpoint has no caller auth (see docs/AUTH-DESIGN.adoc)" -credential-forwarding = "OPEN — design not yet decided; critical for federation use case" -test-coverage = "CLOSED 2026-04-25 — 165 ExUnit tests; CRG C met" - -[session-history] -entries = [ - { date = "2026-06-24", description = "TLA+ formal coverage of Elixir REST harness (PRs #252 + #253, MERGED). Three TLA+ models in specs/elixir-harness/ now cover the BEAM-side concurrency layer: JsWorker.tla (pre-existing; 341 states, depth 8; ReplyOnce, EventuallyReplied), JsWorkerPool.tla (PR #252; N-slot pool; RouteConsistency proves phash2 routing invariant; crash-isolation enforced structurally by Crash(w) guard; NoPendingWhileDown), Invoker.tla (PR #253; stateless fork-per-request dispatcher; DoneOnce; 7 exit-code sanity controls). EventuallyDone is [ASSUMED] in the Invoker model — no per-invocation timeout in Phase 2 (System.cmd blocks indefinitely; ADR-0005 Phase 3 pool will close this gap). All models include .cfg files and non-vacuity sanity-control checks (each ReachXxx expected to be refuted by TLC). Formal-proof axis only; CRG readiness grade unchanged." }, - { date = "2026-06-13", description = "CI required-gate skip-shim + estate-wide unblock. ROOT CAUSE: 7 required gates (abi-drift, backend-assurance, e2e, lsp-dap-bsp, proofs, truthfulness, zig-test) were workflow-level path-filtered (on.*.paths); on any PR touching none of a gate's paths the workflow never ran, so its required status check stayed 'Expected' forever and the PR sat mergeable_state=blocked even fully-green (stranded #213 dependabot flake.lock + #215 scripts-only). FIX (PR #216, MERGED): dropped on.*.paths from all 7; added an always-run `changes` job that recomputes each gate's original path set via `git diff origin/...HEAD`; gated every heavy job with needs:changes + if:run=='true' (a job skipped via if: reports SUCCESS to required checks). Fail-safe toward running; job/check names unchanged so no branch-protection edit needed. Validated: actionlint clean; detection regex 77/77; live on #216 all 15 heavy jobs skipped->success. Then merged #213 + #215. MIRRORED to boj-server-cartridges (PR #45, MERGED): same shim on proofs/zig-test/foundry. Conventions captured this session: docs/AI-CONVENTIONS.adoc + .claude/CLAUDE.md (new 'CI / Required Status Checks' sections) + docs/wikis/CI-and-Required-Checks.adoc + PLAYBOOK [ci-required-gates]; AI-CONVENTIONS Banned-Languages 'TypeScript->AffineScript' corrected to '->AffineScript' (AffineScript retired 2026-04-30). Follow-ups filed: #218 (boj-server Hypatia/governance hygiene: stale GEMINI.md, unpinned governance.yml action, missing timeout-minutes, shellcheck infos); cartridges #46 (TS->AffineScript port of stack-orchestrator-mcp + proof-lsp adapters), #47 (cartridges Hypatia hygiene), #48 (language-cartridge IDE completeness)." }, - { date = "2026-06-05", description = "Truthfulness + Foundry + governance-checkpoint session. (1) Catalogue honesty (PR #196, MERGED) — router.ex defaulted every cartridge to available:true, so all 125 advertised as working when only feedback-mcp is built+real (97 build a .so that returns {\"status\":\"stub\"}; 10 have no FFI). Fixed: explicit `available` on all 125 cartridge.json (true only for feedback-mcp) + `status` where missing; router `available` default flipped true→false (a cartridge must opt in to being advertised, never by omission); new tests/truthfulness_check.sh + .github/workflows/truthfulness.yml gate builds every available cartridge and invokes its first tool, failing on a stub marker (verified to catch an injected stub→available lie); fixed router_test.exs + contract_test.exs /menu tests that asserted the pre-tiering cartridges/count shape (broken since the tiered /menu landed) to assert tier_*/summary + the availability invariant (summary.ready == count of available). believe-me-count unchanged at 5. (2) Foundry (boj-server-cartridges PR #38, MERGED) — the integrated mint→provision→configure→harness cartridge-making workflow, built ON the existing cartridge-minter + gossamer-mcp template (not from scratch). tools/foundry/proof/Foundry.idr (Idris2 0.8.0, typechecked) machine-checks two properties: NO-DROPPED-PROOFS (a `failing` block proves skipping the harness won't compile, pinned to `Can't find an implementation for Elem Truthful`) and LEAST-AUTHORITY (capability index = exact grant; no stage widens it). stages/harness.sh = the one general gate (idris2 --check + zig build + the #196 truthfulness probe + capability-subset check), verified PASS on gossamer-mcp. (3) Filed 8 tracking issues: proofs a/b/c (#197, hyperpolymath/boj-server-cartridges#36, #37), obleeny long-term #198, catch-all hygiene #199, maker #200, implement-stubs #201, gate-enforcement #202. (4) Branch reconciliation — retired superseded branches (e2e-rest-contract, feedback-otron; truthfulness-pass/feedback-otron-fix already auto-deleted on merge); reset zen-galileo to main; PRESERVED claude/cartridge-abi-proofs (unmerged proof-CI groundwork: 17 ABI .idr typecheck-fixes for 0.8.0 + typecheck-proofs.sh — captured in #197 for rebase-and-land); one clean main per repo. (5) Governance checkpoint (this commit) — STATE refreshed; ANCHOR realigned to current language policy. FLAGGED: boj-server-cartridges has NO .machine_readable/ at all (entire standard layout missing); no bot_directives/ dir in either repo; standards + rsr-template unreachable from this session (GitHub scope = boj-server + boj-server-cartridges only, no list_repos/add_repo) so the rsr-template-vs-standards divergence check is BLOCKED pending access." }, - { date = "2026-05-26", description = "Repo-tidy / rsr-template-repo taxonomy alignment (PR #149). Six commits; 136 files changed (+5096 -3322). (1) Root .adoc relocations — EXPLAINME.adoc -> docs/, BOJ_LOGIC.adoc + NeSy_SERVERS.adoc -> docs/architecture/, FUTURE_PLANS.adoc + ROADMAP.adoc -> docs/status/, QUICKSTART-{USER,DEV,MAINTAINER}.adoc -> docs/quickstarts/. Cross-refs updated in 0-AI-MANIFEST.a2ml, Justfile, elixir/boj-rest.service, methodology.a2ml (fallback-files list), docs/README.adoc, docs/accessibility/README.adoc, and two outreach drafts. Historical mentions in CHANGELOG.md and dated log entries in STATE.a2ml deliberately left intact. (2) README merge — substantive 518-line README.md converted to AsciiDoc and merged with the unique sections from the shorter 176-line README.adoc (Features bullets, Formal verification). README.md deleted. Refs in jsr.json publish list, mcp-bridge/lib/resources.js docs URL, .github/SECURITY.md, and Intentfile repointed at README.adoc. (3) Wiki + warmup conversions — five wiki pages converted .md->.adoc and moved docs/wiki/ -> docs/wikis/ (template's spelling); llm-warmup-{dev,user}.md -> docs/developer/; CARTRIDGE-PHASE-3B-COMPLETION.md -> docs/status/. Drift fix: STATE.a2ml cartridges-total 112 -> 125 (every dir under cartridges/* has cartridge.json), cartridges-with-zig-ffi 111 -> 115 (manifest-counted), cartridges-with-js-mod 111 -> 113, project-context.purpose '112 cartridges' -> '125 cartridges'. (4) Bulk docs/*.md -> .adoc — ABI-FFI-README, AI-CONVENTIONS, API-CONTRACT, CULTURAL-RESPECT, EXTENSIBILITY, FEDERATION, READINESS, THREAT-MODEL; plus relocations docs/ARCHITECTURE.md -> docs/architecture/README.adoc and docs/DEVELOPERS.md -> docs/developer/README.adoc. 99 files cross-rewritten (55 cartridge READMEs + governance/wiki/dev/architecture refs + Justfile, .github/copilot-instructions.md, SECURITY.md, src/abi/Boj/Catalogue.idr docstring, k8s/service.yaml, mcp-bridge/lib/api-clients.js, plus outreach/practice docs). New subdir orientation READMEs in docs/quickstarts/, docs/status/, docs/wikis/. docs/READINESS.adoc deliberately stays at docs/ root (not under docs/status/) because 55+ cartridge READMEs link to that canonical path. (5) Quickstart consolidation — substantive docs/QUICKSTART.md (72 lines) -> docs/quickstarts/DEV.adoc (replaces 39-line stub); docs/GETTING-STARTED.md (198 lines) -> docs/quickstarts/BUILD-FROM-SOURCE.adoc (new sibling); docs/OPERATOR-QUICKSTART.md (296 lines) -> docs/quickstarts/MAINTAINER.adoc (replaces 40-line stub). docs/quickstarts/README.adoc updated to list all four with audience guidance. Refs in Mustfile + flake.guix + CRG-LIFT-PLAN + outreach drafts updated. (6) docs/README.adoc index rewritten in full (Reading-order-by-audience + Directory-taxonomy + Standalone-docs/-root + Related-root-level sections) + last lone .md in docs/architecture/ (TYPED-WASM-MCP-BRIDGE.md) converted to .adoc. Hypatia approved-exemption manifest patch /tmp/hypatia-approved-exemptions.patch delivered to user for upstream application to hyperpolymath/hypatia (separate PR). Known-deferred (high coupling, not in this PR): PROOF-NEEDS.md (16 cross-refs incl. CI + Idris proofs + 4 Elixir test files), TOPOLOGY.md (11 cross-refs incl. CI workflow), TEST-NEEDS.md (5 cross-refs); follow-up PR should bulk-rewrite. GEMINI.md left at root — load-bearing (gemini-extension.json contextFileName). CI failures on PR #149 (ABI Specification Check, FFI Build, abi-drift verify, Aspect, E2E) all confirmed pre-existing on main; this PR's diff is comment-line-only outside docs/, cannot have introduced them." }, - { date = "2026-05-20", description = "HCG tier-2 Phase E first-session (afternoon) — sub-issue standards#100 of channel standards#91. Phases A/B/C had already merged; Phase D was scaffold-only (http-capability-gateway#12 merged 08:24Z, bench/baseline.json _status: 'scaffold-placeholder', perf-regression gate non-blocking until D-2..D-4 land). Scope: drive Phase E artefacts that are SAFE w.r.t. Phase D being scaffold-only — runbook + audit + ingress isolation. Out of scope: E1/E2/E3/E4 wiring + Trustfile PENDING→DEPLOYED flip (gated on D-3 regression alert + D-4 real numbers, per runbook §1.1). FOUR PRs shipped + ONE issue filed. (1) PR #128 (MERGED 11:30Z) — docs/integration/hcg-tier2-rollout-runbook.md, the Phase E E5 rollout-and-rollback runbook (covers §E4 + §E5 of the integration plan because standards#100 acceptance #3 names both). 308 lines: prerequisites (Phase D landings + Phase A/B/C artefacts + operational !OWNER: block + BoJ-side + gateway-side), staging cut-over (deploy + telemetry verification + 24h soak + rollback rehearsal), 10/50/100% production rollout, observability signals (gateway + BoJ + dashboards), rollback (triggers + immediate bypass + permanent disable + post-decommission), post-rollout verification + Trustfile flip. !OWNER: markers throughout §1.3 + §4 for on-call rota, dashboard URLs, prod cert paths, traffic-shift mechanism choice, freeze windows. (2) PR #130 (MERGED 11:57Z) — fix(boj): bind Cowboy to 127.0.0.1 by default (audit #6). elixir/lib/boj_rest/application.ex passes ip: explicit binding to Plug.Cowboy options; BOJ_BIND_IP env var override; new parse_bind_ip/1 helper with fail-fast on invalid input (preferred to silently degrading to 0.0.0.0 and exposing the back-side bind). 7 new unit tests in elixir/test/application_test.exs. Previously Plug.Cowboy started with port: 7700 and NO ip: option, so it defaulted to 0.0.0.0 — the contract document's 'BoJ :7700 is not externally routable' claim and the runbook §1.4 prereq #6 were OPERATIONAL ASSERTIONS, not code-enforced. (3) PR #131 (MERGED 12:35Z) — fix(k8s): Service for BoJ to ClusterIP (audit #8). k8s/service.yaml type: LoadBalancer → ClusterIP. Added hyperpolymath.dev/exposure: 'internal-only' + hyperpolymath.dev/external-via: 'http-capability-gateway (tier-2)' annotations. Header comment with kustomize override recipe for legacy/standalone deployments. Estate cross-check: hypatia/*, rsr-certifier, opsm-service all use ClusterIP for backends; only svalinn-gateway (a gateway, not a backend) uses LoadBalancer. (4) PR #132 (MERGED 12:35Z) — fix(container): APP_HOST defaults to 127.0.0.1 (audit #7). Three sites that feed the Zig adapter binary's --host flag: stapeln.toml [targets.production], container/entrypoint.sh (lines 40 + 140), container/compose.prod.yaml. The audit named only stapeln.toml; the other two sites had the same '[::]' default that the audit missed but they all feed the same --host so they had to flip together. CI auto-trigger anomaly: pull_request workflows did not fire (likely sweep122 concurrency-pool saturation); manual Governance dispatch returned all 6 jobs green; owner re-ran from Actions tab. (5) Issue #135 filed — k8s NetworkPolicy follow-up (defence-in-depth beyond ClusterIP, Low priority, Phase E acceptance-non-critical). Three threat models named: compromised neighbour pod / operator misconfiguration / §4 defence in depth. Proposed manifest shape included; CNI-support caveat documented. (6) DEFENCE IN DEPTH ACHIEVED — three independent loopback layers now block any §3 invariant 3 violation: Elixir Cowboy (#130) + Zig adapter (#132) + k8s Service (#131). (7) Phase C §3 invariant 3 correction — the standards#91 channel-status comment claimed the BoJ-side fix was 'owner-gated, not opened as a PR'; verified by git log against elixir/lib/boj_rest/trust_policy.ex that the deny clause landed in boj-server#106 (commit 40e46f6f) as part of Phase C. Stale claim corrected in memory. (8) NEXT for Phase E (gated): E1 (Containerfile + k9-svc deployment spec finalisation) / E2 (staging deployment + traffic shift) / E3 (telemetry verification under load) / E4 (production flip) / Trustfile [CLOUDFLARE_EDGE_SECURITY].rate_limiting.tier_2_gateway.status PENDING→DEPLOYED — ALL gated on Phase D-3 (regression alert armed) + D-4 (real baseline numbers populated)." }, - { date = "2026-05-20", description = "Epic #87 Tier C session (items 11 + 12 + follow-on baseline-rot sweep): (1) Item 11 (PR #108, MERGED) — honest framing of the remaining ABI axioms. Session-prompt premise that '4 believe_me axioms remain' was stale; PROOF-NEEDS.md's 2026-05-18 audit had already classified 5 sites, all class (J), all irreducible over Idris2 0.8.0's opaque Char/String primitives (charEqSound, charEqSym, unpackLength, appendLengthSum, substrLengthBound). Fixed three loose ends: SafetyLemmas.idr's module docstring (claimed 'three axiomatic primitives', listed only three of the five) corrected to enumerate all five with prim__* attribution; appendLengthSum and substrLengthBound's `(x y : T)` multi-binder syntax (rejected by Idris2 0.8.0 at parse time) commaed to `(x, y : T)`; README.adoc gained a 'Formal verification' section so the audited posture is surfaced outside PROOF-NEEDS.md. (2) Item 12 (PR #109, MERGED) — ADR-0014 'Cross-cartridge composition safety' as an RFC framing document, no implementation. Defines composition safety as a two-level contract: static Idris2 `Boj.Composition.InvocationOf` envelope (lifting IsUnbreakable + ProtocolMatch + per-cartridge ArgsContract into the inter-cartridge call) plus dynamic Nickel `compositions` block in ADR-0007's policy-mcp PDP. Six-sub-PR campaign laid out. First proof pair is panic-attack-mcp → vordr-mcp (both cartridges exist on disk); the prompt-suggested three-step `panic-attack → sandbox → vordr` chain is parked behind ADR-0009 sandbox-mcp build-out (sandbox-mcp does not yet exist on disk). (3) SafeAPIKey baseline-rot follow-up (PR #116, MERGED 2026-05-20T08:46Z) — `logSafeBounded` proof did not type-check on Idris2 0.8.0 despite PROOF-NEEDS.md's audit claiming it did (audit was desk-read, not build). Three independent defects: removed redundant local plusLteMonotone helper (called now-gone lteTransitive and used wrong arg order on plusLteMonotoneRight/Left; stdlib's Data.Nat.plusLteMonotone has exactly the needed shape); lifted both short and long paths out of the with-block (Idris2 0.8.0 doesn't reduce `length \"***\"` at type level inside a with-block — the goal stays as `LTE (integerToNat (prim__cast_IntInteger (prim__strLength (if ...)))) 11` with the `if`-arm unreduced); right-associated the long-path proof to match `++`'s right-associativity (`a ++ b ++ c = a ++ (b ++ c)`). Plus fixed two bound-name typos in toLogSafeShortEq/toLogSafeLongEq where outer `_` discarded the prf the inner branch then referenced. Per-module `idris2 --check` is now green on all 12 safety modules (SafetyLemmas, SafeAPIKey, Safety, APIContractCoverage, CartridgeDispatch, Catalogue, CredentialIsolation, Federation, SafeCORS, SafeHTTP, SafePromptInjection, SafeWebSocket); `idris2 --build src/abi/boj.ipkg` does not complete in 9 min on dev machine (SIGTERM, gets nowhere). No new axioms; the 5-class-(J) framing from #108 preserved. (4) Estate baseline-rot CI sweep — diagnosed 5 reds on PR #116 and on main: 4 mechanical, 1 owned by parallel session. PR #118 (MERGED 2026-05-20T09:02Z) repairs tests/aspect_tests.sh grep-count bash bug (`grep -c X file 2>/dev/null || echo \"0\"` produced `\"0\\n0\"` and broke `[[ -gt 0 ]]` arithmetic — swapped `|| echo \"0\"` for `|| true` on all 4 call-sites). PR #123 (OPEN) repairs .github/workflows/e2e.yml: Zig 0.15.0 → 0.15.1 (`.tool-versions` canonical; 0.15.0 retired upstream from the GitHub Actions Zig download index) and `denoland/setup-deno@5fae568d…` → `@667a34cdef…` v2.0.4 SHA (the old SHA no longer resolves; the v2.0.4 SHA already in use by publish.yml verified via GitHub API). `governance / Language / package anti-pattern policy` deliberately untouched per the parallel-session-branch-drift guardrail — owned by another session under the Estate-drift-remediation 2026-05 campaign (parent standards#66). (5) Operational notes: parallel session in this repo committed `feat(mcp-bridge): Streamable HTTP transport` (#105) on a different branch under me mid-task; caught the branch drift via `git reflog` and untangled by hard-resetting HEAD to the intended item11 branch tip. gh OAuth token from device-code login granted only `gist, read:org, repo`; pushing `.github/workflows/e2e.yml` required a `workflow` scope refresh (`gh auth refresh -h github.com -s workflow`) before the push went through — hence the split between #118 (sh fix) and #123 (yaml fix). believe-me-count in STATE.a2ml stale at 4; bumped to 5 in this commit." }, - { date = "2026-05-18", description = "k9iser-mcp PR #73 session: (1) Added k9iser-mcp cartridge — reference -iser regeneration-cartridge pattern (central K9 contract regeneration) mirroring ssg-mcp: cartridge.json, mod.js, Idris2 ABI, Zig FFI, panels. (2) Unified transaction-gated adapter: ONE internal/loopback listener, protocol-routed REST+SSE+GraphQL+gRPC-compat → SINGLE dispatch → one Zig ABI, replacing the ssg-era 3-parallel-port anti-pattern; trust gate runs before every dispatch mirroring the Idris2 exposureSatisfied contract (no gatekeeperless path); internal-only behind http-capability-gateway per ADR-0004. (3) boj-rest SSE: POST /cartridge/:name/sse on the same single Cowboy listener + trust-gated dispatch, text/event-stream. (4) Doc reconciliation: elixir/README.adoc, mcp-bridge/api-clients.js, OPERATOR-QUICKSTART.md corrected to the verified runtime + ADR-0004 tiered model (previously wrongly 'skeleton/501/pending rewrite'). (5) CI ROOT-CAUSE FIX: dogfood-gate.yml failed YAML validation at startup (0s, no jobs) on every branch incl. main — inline `python3 -c \"` placed Python at column 1 inside a `run: |` block scalar, terminating the scalar early; since 'Dogfood Gate' is a required status check this silently blocked EVERY PR in the repo. Validator extracted to .github/scripts/validate-eclexiaiser.py and invoked from the workflow (commit 891b162). Verification: Elixir 177/177 (incl. 2 SSE tests); Zig ffi 16/16 + unified adapter 5/5 (exposure-gate truth table mirroring Idris2 contract); idris2 --check K9iserMcp/SafeK9iser.idr passes. Out of scope / separately tracked: http-capability-gateway production-wiring (ADR-0004 tier-2, ~8-12wk) and iseriser-scaffold rollout. Refs hyperpolymath/k9iser#8. NOTE: merge held — GitHub Actions runner-starved estate-wide (standards#122), required checks cannot execute until that clears." }, - { date = "2026-04-27", description = "Worker briefing + hook session: (1) Created .boj/project-memories.a2ml — standing worker briefing template covering coord registration, completion contract ('push succeeds, not TODO list'), backend wiring checklist, banned patterns (unimplemented!/sorry/Admitted/believe_me/.unwrap()-as-debt), comms protocol, git hygiene, and echidna language policy. Committed 039908a + pushed to main. (2) Updated ~/.config/coord-tui/coord-hooks.sh claude() function to auto-prepend project-memories.a2ml via --append-system-prompt when launched from a repo with .boj/project-memories.a2ml. Repos without the file are unaffected." }, - { date = "2026-04-25", description = "Close-out documentation sweep: ROADMAP.adoc current status → 'v1.1.0 Active (Grade C)'; seed node v0.3.0 bullet updated with fly.dev hostnames + LIVE date; Phase 8/9/Grade-C bullets added. EXPLAINME.adoc testing section expanded to 11 modules (173 total, 0 failures); 'harnesses pending' note removed; seed node infrastructure table added. AI-WORK-todo.md §8 header updated from 'in progress' to 'Grade C / 4 nodes LIVE'; docs-sweep bullet added. All changes committed + pushed to main." }, - { date = "2026-04-25", description = "Documentation + deploy sweep session: (1) .dockerignore fixed — ffi/zig/.zig-cache/ (347 MB) + ffi/zig/zig-out/ + cartridges/*/ffi/.zig-cache/ added; reduces build context from ~2.8 GB to ~2.2 MB for fly seed deploys. (2) Containerfile.fly.dockerignore created at repo root (Docker BuildKit per-Dockerfile override) — also excludes cartridges/*/ffi/ + abi/ + adapter/ + panels/ (cartridge source not needed in seed builds). (3) 6a2 sweep: AGENTIC (fly.io pitfall constraints + v0.2.0); ECOSYSTEM (seed-nodes updated with fly.io apps/hosts/regions + dns-status + federation protocol corrected + zig ref fixed + v0.2.0); NEUROSYM (report-format logtalk→json + v0.2.0); PLAYBOOK (full operational runbook: local dev, full container, fly.io per-node + deploy-seeds.sh, notes on glibc/musl ABI, .dockerignore, custom domain procedure + v0.2.0); META (languages elixir+javascript added, ADR-010 through ADR-014, design-rationale seed-node-lean-build + trust-level-design + v0.3.0). (4) All 4 fly.io seed nodes deployed: boj-seed-eu (lhr), boj-seed-de (fra), boj-seed-us (iad), boj-seed-ap (syd) — each 2/2 health checks passing, 61 MB image. gap-5 closed." }, - { date = "2026-04-25", description = "MCP install session: Added local-coord-mcp to Claude Code global settings (~/.claude/settings.json). Entry runs mcp-bridge/main.js (node) with BOJ_URL=http://localhost:7700 + COORD_BACKEND_URL=http://127.0.0.1:7745. Backend (local_coord_ada, port 7745) and BoJ server (beam.smp, port 7700) were already running. Smoke-tested coord_register end-to-end through bridge — returned valid peer_id + token. No boj-server code changed; settings change takes effect on Claude Code restart or /hooks reload." }, - { date = "2026-04-25", description = "coord-tui + maintenance sweep session: (1) ROOT-CAUSE: local-coord-mcp adapter was never started on port 7745. mcp-bridge fully wired, Elixir catalog had cartridge at boot, but no process was listening. Fixed: built cartridges/local-coord-mcp/adapter/ and created ~/.config/systemd/user/local-coord-mcp.service (enabled + started). (2) MAINTENANCE: catalogue.zig — code_intel=18 missing from CapabilityDomain enum (Domain.idr had 18 domains, Zig stopped at bsp=17; C-ABI gap); added code_intel=18, fixed comment '1-13'→'1-18'. Check.idr — SPDX header added. tests/mcp_bench.zig — deserialisation bench upper-bound 5_000→10_000ms (debug builds parse ~0.8ms/req; old bound was too tight for CI). (3) coord-tui (new, coord-tui/ directory): Rust TUI using ratatui+crossterm+ureq+clap. Interactive mode: two-panel view (Peers top/Claims bottom), TableState keyboard nav [j/k/Tab/c/s/p/R/q], claim+status input overlay, 5s auto-refresh. --id silent mode: registers, writes ~/.cache/coord-tui/peer.env (BOJ_COORD_PEER_ID + BOJ_COORD_TOKEN), prints peer_id, exits immediately — no TUI. Pure state helpers (next_index/prev_index/clamp_selection) isolated for future SPARK/Ada verification. (4) Shell hooks (coord-tui/shell/coord-hooks.sh): wraps claude/gemini/cursor/codex — calls coord-tui --id --kind , sources peer.env, sets terminal window title to ' []' via ANSI escape for multi-instance identification. Sourced from ~/.bashrc + ~/.zshrc. (5) Installer (coord-tui/install.sh): checks cargo+zig, builds Zig adapter + Rust coord-tui, symlinks to ~/.local/bin, installs systemd service, copies hooks to ~/.config/coord-tui/, patches shell rcs. Human docs: coord-tui/EXPLAINME.adoc + coord-tui/README.adoc. Commits: 0837968 (maintenance), e07aee5 (coord-tui + hooks + installer + docs)." }, - { date = "2026-04-25", description = "Seed node deployment session: (1) 4 fly.io apps created (boj-seed-eu/de/us/ap) in regions lhr/fra/iad/syd. (2) 1 GB persistent volumes per app. (3) Containerfile.fly created — swaps cgr.dev/chainguard/elixir (auth-gated) for elixir:1.16 (public Debian/glibc) in Stage 2; wolfi-base package names corrected in Stage 3. (4) .dockerignore added to reduce build context upload (~500 MB → <<100 MB future). (5) container/fly/ directory: fly-eu/de/us/ap.toml + deploy-seeds.sh. (6) seed-nodes.toml v0.2.0: operative .fly.dev hostnames; canonical hyperpolymath.dev aliases noted as pending DNS delegation. (7) compose.prod.yaml BOJ_SEED_NODES updated to fly.dev. (8) QUICKSTART-USER.adoc seed node list updated. Deployment of EU node in progress." }, - { date = "2026-04-25", description = "Items 1+2+3 session: (1) Credential forwarding gaps A+B closed — chain fully wired (CredentialDecryptor → dispatch → Invoker extra_env → subprocess env vars). Option C (RGTV) future work. (2) tools/cartridge-minter/ DELETED — Node.js banned artefact. Justfile, QUICKSTART-USER.adoc, llm-warmup-dev.md, llm-warmup-user.md updated to reference launch-scaffolder. (3) Seed node infra: compose.prod.yaml created (production Podman Compose using ghcr.io image, all 4 seed peers pre-wired); QUICKSTART-USER.adoc seed node section added; container-publish.yml label updated 99→112 cartridges. container/boj-community-node.container + seed-nodes.toml already existed." }, - { date = "2026-04-25", description = "Phase 9 auth (partial): (1) BojRest.TrustPolicy — maps auth.method→exposure (:public/:authenticated), checks X-Trust-Level header; loopback bypass. (2) Router wired: X-Trust-Level enforcement in invoke handler; X-Node-Identity audit logging. (3) trust_policy_test.exs (11 tests); 7 new router auth tests. (4) Justfile test/test-verbose rewritten as loops (111 cartridges, was hardcoded 17). Total: 173 ExUnit tests, 0 failures." }, - { date = "2026-04-25", description = "FFI wiring complete — all 111 cartridges now have compiled .so + ffi key in cartridge.json. Scaffolded 12 remaining cartridges (6 with existing stub Zig source replaced with clean ADR-0006 impl: academic-workflow-mcp, bofig-mcp, ephapax-mcp, fireflag-mcp, hesiod-mcp, sanctify-mcp; 6 written from scratch: claude-agents-power-mcp, coderag-mcp, local-memory-mcp, notifyhub-mcp, opendatamcp, origenemcp). Each: *_ffi.zig (5-symbol ADR-0006 ABI + tool stubs) + build.zig + cartridge_shim.zig + canonical ffi block in cartridge.json with so_path=ffi/zig-out/lib/lib.so. All 12 build clean, all 12 pass boj-invoke probe. 165 Elixir tests still 0 failures." }, - { date = "2026-04-25", description = "CRG D→C test expansion: (1) Added invoker_test.exs (15 tests — cli_path resolution, exit-code classification via fake_boj_invoke fixture, successful probe/name/version/invoke, extra_env). (2) Added js_worker_pool_test.exs (9 tests — pool_size, consistent-hash routing, fallback, E2E). (3) Added catalog_properties_test.exs (10 StreamData properties — round-trips, structural invariants, CredentialDecryptor properties). (4) Added contract_test.exs (15 contract tests — Catalog↔Router, NodeKey↔CredentialDecryptor, Router↔Invoker dispatch). (5) Added aspect_test.exs (15 aspect tests — no-crash, content-type, security, idempotency). (6) Added benchmarks/boj_bench.exs (10 Benchee scenarios). (7) Extended catalog_test.exs + router_test.exs + node_key_test.exs + credential_decryptor_test.exs + js_invoker_test.exs with 80+ additional tests. (8) Fixed bofig-mcp, hesiod-mcp, academic-workflow-mcp cartridge.json (missing spdx/domain/tier/auth/so_path fields). Total: 165 tests (10 properties + 155 regular), 0 failures. Grade D→C achieved." }, - { date = "2026-04-25", description = "v1.1.0 + v1.0.1 doc sweep: (1) ExUnit test suite 50 tests across 5 modules. (2) StreamData property test dep added. (3) BojRest.JsWorkerPool + JsWorker (persistent Deno pool) implemented; Router now dispatches via pool. (4) PolicyLoader.load_from_boj_catalog/1 in http-capability-gateway — 12 tests. (5) compose.dev.yaml updated: capability-gateway sidecar (port 7800 → boj-rest:7700, BOJ_CARTRIDGES_ROOT catalog mode). (6) gateway-policy.yaml retired (static policy superseded by catalog mode). (7) 4 cartridges fixed (academic-workflow, ephapax, fireflag, sanctify — missing domain/tier/auth/ffi fields). (8) Full doc sweep: TOPOLOGY.md, ROADMAP.adoc, EXPLAINME.adoc, QUICKSTART-USER.adoc, llm-warmup-dev.md — all zig refs removed, counts 97/99/106 → 112. (9) TEST-NEEDS.md rewritten as honest CRG D gap analysis." }, - { date = "2026-04-25", description = "Earlier session: (1) Fixed Zig ElfDynLib bug — boj-invoke now targets x86_64-linux-gnu, forcing DlDynLib/real dlopen. (2) boj-health Zig FFI cartridge fully implemented and tested. (3) Elixir REST server wired: Containerfile rewritten (3-stage Zig+Elixir build), compose.dev.yaml created. (4) All 112 cartridges now have mod.js. (5) model-router-mcp gets cartridge.json. (6) JS dispatch path implemented: BojRest.JsInvoker + priv/js_runner.js + Router dispatch branch. (7) cartridge_so_path/1 fixed to read ffi.so_path from manifest. (8) Gateway policy + catalog-integration design doc added. (9) ROADMAP v1.1.0 milestone added." }, - { date = "2026-04-20", description = "Started Elixir REST backend on port 7700 as zig adapter replacement. Fixed just doctor in Justfile." }, - { date = "2026-04-17", description = "Spec bump v0.4.0: zig ban documented. ADR-0002 created. EXPLAINME.adoc corrections." }, - { date = "2026-04-12", description = "zig sweep complete: 0 .v files remain. believe_me sweep: 31→4. CI fixes." }, - { date = "2026-04-04", description = "MCP test suite added (Deno). Containerfile updated for 96-cartridge matrix." }, - { date = "2026-03-16", description = "Repository created from rsr-template-repo. Initial Idris2 ABI + Zig FFI foundation." }, -] - -[architecture] -stack-summary = "Idris2 ABI → Zig FFI (.so) → Elixir REST (HTTP/7700) → Deno JS (mod.js via JsWorkerPool)" -dispatch-rule = "cartridge.json with 'ffi' key → BojRest.Invoker (boj-invoke CLI); without 'ffi' key → BojRest.JsWorkerPool (persistent Deno pool)" -federation = "Zig QUIC gossip: X25519 handshake + ChaCha20-Poly1305, SDP allow-list, hash attestation" -auth-gap = "Federation trust is gossip-layer only; HTTP invoke has no caller auth — see docs/AUTH-DESIGN.adoc" -gateway = "http-capability-gateway sidecar LIVE in compose.dev.yaml (port 7800 → boj-rest:7700); catalog mode active via BOJ_CARTRIDGES_ROOT; gateway-policy.yaml retired 2026-04-25" -cultural-pillars = ["Teranga (hospitality)", "Umoja (unity)", "Ayo (joy)"] - -[ecosystem] -part-of = ["hyperpolymath infrastructure", "PanLL", "stapeln ecosystem"] -depends-on = ["proven-servers", "stapeln", "selur-compose", "vordr", "svalinn", "http-capability-gateway"] -replaces = ["polystack"] diff --git a/.machine_readable/6a2/anchor/0-AI-MANIFEST.a2ml b/.machine_readable/6a2/anchor/0-AI-MANIFEST.a2ml deleted file mode 100644 index 0dd6825b..00000000 --- a/.machine_readable/6a2/anchor/0-AI-MANIFEST.a2ml +++ /dev/null @@ -1,21 +0,0 @@ -# AI Manifest for Anchor Directory - -## Purpose - -This manifest declares the AI-assistant context for the anchor machine-readable metadata directory. - -## Canonical Locations - -ANCHOR.a2ml files MUST exist in this directory. - -## Multiple Versions - -Unlike other A2ML files, multiple versions of ANCHOR.a2ml with different dates MAY exist. -Each version represents a specific recalibration point. - -## Invariants - -- Multiple versions with different dates are permitted -- No other A2ML files in this directory -- Single source of truth for anchor documents - diff --git a/.machine_readable/6a2/anchor/ANCHOR.a2ml b/.machine_readable/6a2/anchor/ANCHOR.a2ml deleted file mode 100644 index 9b033d6a..00000000 --- a/.machine_readable/6a2/anchor/ANCHOR.a2ml +++ /dev/null @@ -1,67 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -# -# ANCHOR.a2ml - authoritative anchor for this repository - -[metadata] -version = "1.0.0" -last-updated = "2026-06-05" - -[anchor] -schema = "hyperpolymath.anchor/1" -repo = "hyperpolymath/boj-server" -authority = "upstream-canonical" - -purpose = [ - "Define canonical semantics and policy boundaries for this repository.", - "Declare what downstream/satellite repos can extend but not redefine.", - "Provide a stable golden path and invariant contract for release readiness.", -] - -[identity] -project = "Bundle of Joy Server" -kind = "service" -one-sentence = "Unified server capability catalogue with formally verified cartridges" -domain = "infrastructure" - -[semantic-authority] -policy = "canonical" - -owns = [ - "Project semantics and specification", - "Invariant definitions and contractiles", - "Reference implementation behavior", -] - -[implementation-policy] -# Realigned 2026-06-05 to the current language policy (CLAUDE.md / standards): -# V banned 2026-04-10; AffineScript dropped as the migration destination 2026-04-30; -# AffineScript is the canonical target for new application code; Elixir (REST) and -# JavaScript-on-Deno (mod.js cartridges) are the established runtime languages. -allowed = ["Idris2", "Zig", "Elixir", "AffineScript", "JavaScript (Deno)", "Scheme", "Shell", "Just", "AsciiDoc", "Markdown"] -# TypeScript: no NEW TS — 6 approved MCP-adapter exemptions only (see CLAUDE.md). -forbidden = ["Node.js", "npm", "TypeScript", "Python", "Go"] - -[golden-path] -smoke-test-command = [ - "just test", - "just quality", -] - -success-criteria = [ - "Core tests pass", - "Quality gates pass", - "No unresolved critical security findings", -] - -[satellite-policy] -must-pin-upstream = true -must-declare-authority = true -must-have-anchor = true -must-have-golden-path = true - -[semantic-authority-files] -language-spec = "SPECIFICATION.md" -formal-proofs = "docs/proofs/PROOFS.adoc" -type-theory = "docs/theory/THEORY.adoc" -algorithms = "docs/theory/ALGORITHMS.adoc" diff --git a/.machine_readable/6a2/anchor/README.adoc b/.machine_readable/6a2/anchor/README.adoc deleted file mode 100644 index 13cae630..00000000 --- a/.machine_readable/6a2/anchor/README.adoc +++ /dev/null @@ -1,25 +0,0 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -// Copyright (c) Jonathan D.A. Jewell -# A2ML Anchor Directory - -This directory contains ANCHOR.a2ml files for project recalibration and scope intervention. - -## Files - -- `ANCHOR.a2ml` - Project recalibration, scope intervention, canonical authority - -## Multiple Versions - -Unlike other A2ML files, multiple versions of ANCHOR.a2ml with different dates may exist. -Each version represents a specific recalibration point in the project history. - -## Standards Compliance - -These files follow the ANCHOR.a2ml specification from: -https://github.com/hyperpolymath/standards/tree/main/anchor-a2ml - -## See Also - -- [A2ML Repository Template](https://github.com/hyperpolymath/standards/blob/main/A2ML-REPO-TEMPLATE.adoc) -- [Anchor A2ML Spec](https://github.com/hyperpolymath/standards/tree/main/anchor-a2ml) - diff --git a/.machine_readable/CLADE.a2ml b/.machine_readable/CLADE.a2ml deleted file mode 100644 index 5db3e815..00000000 --- a/.machine_readable/CLADE.a2ml +++ /dev/null @@ -1,50 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Clade declaration — part of the gv-clade-index registry -# See: https://github.com/hyperpolymath/gv-clade-index - -[identity] -uuid = "5f5df93b-789d-5ff6-8a44-9dc6ed90a7b1" -primary-forge = "github" -primary-owner = "hyperpolymath" -canonical-name = "boj-server" -prefixed-name = "ap-boj-server" - -[clade] -primary = "ap" -secondary = ["ax"] -assigned = "2026-03-16" -rationale = "" - -[forges] -github = "hyperpolymath/boj-server" -gitlab = "hyperpolymath/boj-server" -bitbucket = "hyperpolymath/boj-server" - -[lineage] -type = "standalone" -parent = "BoJ MCP server — cartridge system, multi-cloud" -born = "2026-03-16" - -# Lifecycle status (added by clade-status-backfill; see gv-clade-index ADR 0006). -# Identity (uuid) and status are SEPARATE layers: uuid follows the GitHub path -# (a move or rename there mints a new one, gv-clade-index ADR 0007; a mirror -# move or a phase change never does); phase is a mutable pointer. No phase is -# terminal (extinct -> active is a legal "Gitassic Park" transition on the same -# uuid). A prefixed-name (clade code) change with the GitHub path unchanged is -# NOT a phase change — the old prefixed-name goes to aliases[], uuid and phase -# are untouched. -[status] -# One of: reserved incubating active dormant | merged superseded archived extinct -phase = "active" -since = "2026-03-16" -present = true -aliases = [] -merged-into = "" -superseded-by = "" -successors = [] -ended = "" - -[[status.history]] -phase = "active" -since = "2026-03-16" -note = "backfilled default — correct if the true phase differs" diff --git a/.machine_readable/ENSAID_CONFIG.a2ml b/.machine_readable/ENSAID_CONFIG.a2ml deleted file mode 100644 index b3863199..00000000 --- a/.machine_readable/ENSAID_CONFIG.a2ml +++ /dev/null @@ -1,96 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -# -# ENSAID_CONFIG.a2ml — eNSAID Environment Configuration -# Per-repo configuration for PanLL and eNSAID-compatible tools. -# -# Canonical location: .machine_readable/ENSAID_CONFIG.a2ml -# Spec: https://github.com/hyperpolymath/standards/tree/main/ensaid-config -# -# Naming convention: -# - UPPERCASE + underscore = non-executable machine-readable file -# - Lives in .machine_readable/ alongside STATE.a2ml, META.a2ml, etc. - -# ───────────────────────────────────────────────────────────────── -# [ensaid] — Core eNSAID identity and version -# ───────────────────────────────────────────────────────────────── -[ensaid] -version = "1.0.0" -tool = "panll" - -# ───────────────────────────────────────────────────────────────── -# [workspace] — Workspace mode, protection, and execution policy -# ───────────────────────────────────────────────────────────────── -[workspace] -mode = "rhodium" # rhodium | gold | silver | bronze -protection = "open" # open | guarded | locked -execution = "live" # live | dry-run | approval-required - -# ───────────────────────────────────────────────────────────────── -# [preferences] — User/repo-level display and behaviour preferences -# ───────────────────────────────────────────────────────────────── -[preferences] -humidity = "medium" # high | medium | low (drift aura intensity) -default-arrangement = "default-3-panel" # workspace arrangement ID -auto-connect = true # auto-connect panels to backends on load - -# ───────────────────────────────────────────────────────────────── -# [panels] — Panel visibility, enablement, and isolation overrides -# ───────────────────────────────────────────────────────────────── -[panels] -version = "1.0.0" - -# By default, all panels are available. Uncomment to restrict: -# [[panels.enabled]] -# id = "valence-shell" -# isolation = "native" -# auto-connect = true -# -# [[panels.enabled]] -# id = "editor-bridge" -# isolation = "native" -# auto-connect = true - -# Panels to hide for this repo context: -# [panels.disabled] -# ids = [] - -# ───────────────────────────────────────────────────────────────── -# [workflows] — Automation Router event-driven cross-panel rules -# ───────────────────────────────────────────────────────────────── -[workflows] -version = "1.0.0" - -# Example: rebuild on file save -# [[workflows.rule]] -# name = "build-on-save" -# trigger = { event = "file-changed", pattern = "src/**/*.res" } -# condition = { panel = "build-dashboard", field = "watchMode", equals = true } -# action = { panel = "build-dashboard", message = "TriggerBuild", args = { target = "game" } } -# approval = "auto-fire" # auto-fire | require-approval | approve-once | dry-run-first - -# ───────────────────────────────────────────────────────────────── -# [clades] — Panel clade trait and capability overrides -# ───────────────────────────────────────────────────────────────── -[clades] -version = "1.0.0" - -# Example: add a custom capability to a panel clade -# [[clades.override]] -# id = "build-dashboard" -# traits = { has-work-items = true } -# capabilities-add = ["CustomCheck"] - -# ───────────────────────────────────────────────────────────────── -# [portfolios] — Custom panel bundles for this repo's workflow -# ───────────────────────────────────────────────────────────────── -[portfolios] -version = "1.0.0" - -# Example: a custom portfolio for this project -# [[portfolios.custom]] -# id = "boj-server-dev" -# name = "boj-server Development" -# description = "Panels for boj-server development" -# panels = ["valence-shell", "editor-bridge", "build-dashboard"] -# default-isolation = "native" diff --git a/.machine_readable/agent_instructions/README.adoc b/.machine_readable/agent_instructions/README.adoc deleted file mode 100644 index cb763521..00000000 --- a/.machine_readable/agent_instructions/README.adoc +++ /dev/null @@ -1,41 +0,0 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -// Copyright (c) Jonathan D.A. Jewell -= Agent Instructions -:toc: preamble - -Methodology-aware configuration for AI agents. Read by any AI agent -(Claude, Gemini, Copilot, etc.) at session start. - -== Files - -[cols="1,3"] -|=== -| File | Purpose - -| `methodology.a2ml` -| Default mode, invariants, ring ceiling, priority weights, convergent budget - -| `coverage.a2ml` -| Session coverage tracking — what was visited, what was skipped, what has MUSTs - -| `debt.a2ml` -| Meander debt — things found but not fixed, carried between sessions -|=== - -== How Agents Use These - -1. Read `methodology.a2ml` at session start — know mode, invariants, ceiling -2. Read `coverage.a2ml` — know what was visited last time, what was skipped -3. Read `debt.a2ml` — know what's outstanding from previous sessions -4. At session end, update `coverage.a2ml` and `debt.a2ml` - -== Relationship to Other Files - -* `AGENTIC.a2ml` says WHAT agents can do (permissions, gating) -* `agent_instructions/` says HOW agents should work (methodology) -* `bot_directives/` says what the gitbot-fleet does (fleet-specific) -* `CLAUDE.md` says how Claude specifically should work (Claude-specific) - -== Reference - -ADR-002 in `standards/agentic-a2ml/docs/ADR-002-methodology-layer.adoc` diff --git a/.machine_readable/agent_instructions/coverage.a2ml b/.machine_readable/agent_instructions/coverage.a2ml deleted file mode 100644 index 69796642..00000000 --- a/.machine_readable/agent_instructions/coverage.a2ml +++ /dev/null @@ -1,61 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -# -# coverage.a2ml — Session coverage tracking -# Updated at the end of each AI agent session. -# Persists what was visited, what was skipped, and what has MUSTs. -# -# Reference: ADR-002 in standards/agentic-a2ml/docs/ - -[metadata] -version = "1.0.0" -last-updated = "2026-03-24" - -# ============================================================================ -# COVERAGE STATE -# ============================================================================ -# Updated by agents at session end. Tracks which components have been -# visited and which have known MUSTs that were skipped. - -[coverage] -total-components = 0 -visited-components = 0 -coverage-percent = 0 - -# ============================================================================ -# VISITED COMPONENTS -# ============================================================================ -# Component → session date + ring reached -# Agents add entries as they work through components. -# -# Example: -# [coverage.visited.emergency-room] -# date = "2026-03-23" -# ring = 2 -# fixes = 3 -# notes = "boot-guardian built, shutdown-marshal built" - -# ============================================================================ -# SKIPPED COMPONENTS WITH MUSTS -# ============================================================================ -# Components with known MUSTs that were not visited in the most recent session. -# These become P1 inputs for the next session's Phase 0. -# -# Example: -# [coverage.skipped-musts.session-sentinel] -# priority = "P0" -# issue = "56 SIGABRTs in 4 days, D-Bus race condition" -# discovered = "2026-03-23" - -# ============================================================================ -# CHERRY-PICKING AUDIT -# ============================================================================ -# At session end, agents report whether they chose easy work over hard work. -# This is the accountability mechanism for the weighted priority system. -# -# [coverage.cherry-picking] -# easy-high-completed = 3 -# hard-high-completed = 1 -# easy-low-completed = 2 -# hard-low-deferred = 4 -# assessment = "Correctly prioritised — all MUST items addressed before COULDs" diff --git a/.machine_readable/agent_instructions/debt.a2ml b/.machine_readable/agent_instructions/debt.a2ml deleted file mode 100644 index c0238c5d..00000000 --- a/.machine_readable/agent_instructions/debt.a2ml +++ /dev/null @@ -1,49 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -# -# debt.a2ml — Meander debt list -# Things found but not fixed. Carried between sessions. -# Becomes the next session's Phase 0 input. -# -# Reference: ADR-002 in standards/agentic-a2ml/docs/ - -[metadata] -version = "1.0.0" -last-updated = "2026-03-24" - -# ============================================================================ -# DEBT ITEMS -# ============================================================================ -# Each item has: component, issue, effort (easy|medium|hard), impact (high|medium|low), -# priority (should|could), and discovered date. -# -# Items are consumed (removed) when fixed. New items are added at session end. -# The debt list prevents the "one more wave" loop — found things are persisted, -# not forgotten, and not used as justification for infinite meandering. - -# ============================================================================ -# SHOULD — would fix next wave -# ============================================================================ -# These are inputs for the next session if the user says "keep going". -# -# Example: -# [[debt.should]] -# component = "system-tools/monitoring/observatory" -# issue = "Stale duplicate of root observatory/" -# effort = "easy" -# impact = "medium" -# discovered = "2026-03-23" - -# ============================================================================ -# COULD — would fix eventually -# ============================================================================ -# These are low-priority items that don't justify a session on their own. -# They get picked up when an agent is in the area for other reasons. -# -# Example: -# [[debt.could]] -# component = "cicada" -# issue = "RSR_OUTLINE.adoc references banned AGPL-3.0" -# effort = "easy" -# impact = "low" -# discovered = "2026-03-23" diff --git a/.machine_readable/agent_instructions/methodology.a2ml b/.machine_readable/agent_instructions/methodology.a2ml deleted file mode 100644 index 06221aff..00000000 --- a/.machine_readable/agent_instructions/methodology.a2ml +++ /dev/null @@ -1,107 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -# -# methodology.a2ml — AI agent methodology configuration -# Declares how agents should approach work in this repository. -# Read at session start by any AI agent (Claude, Gemini, Copilot, etc.) -# -# Reference: ADR-002 in standards/agentic-a2ml/docs/ - -[metadata] -version = "1.0.0" -last-updated = "2026-03-24" -spec = "https://github.com/hyperpolymath/standards/blob/main/agentic-a2ml/docs/ADR-002-methodology-layer.adoc" - -# ============================================================================ -# MODE SELECTION -# ============================================================================ -# convergent: find gaps, fill them, build infrastructure (default for ops/infra) -# divergent: find what's strongest, push it further (for research/creative) -# hybrid: audit 20% of budget, then focus 80% on top MUSTs (default for most) - -[methodology] -default-mode = "hybrid" -ring-ceiling = 2 # Hard ceiling for ring expansion (0-3) -wave-cap = 2 # Max waves before requiring user "keep going" -spike-required = true # Every session must ship code, not just designs - -# ============================================================================ -# PRIORITY WEIGHTS -# ============================================================================ -# MUST (3x): Blocking the current work → fix immediately -# SHOULD (2x): Degrading quality of current work → fix if in zone -# COULD (1x): Improving quality of adjacent work → add to debt list - -[methodology.priority-weights] -must = 3 -should = 2 -could = 1 - -# ============================================================================ -# CONVERGENT BUDGET (when mode = convergent or hybrid) -# ============================================================================ -# How to allocate effort across work types. -# Prevents over-polishing docs while structural work waits. - -[methodology.convergent-budget] -structural = 70 # % for new modules, compilation fixes, wiring, integration -corrective = 20 # % for bugs found, broken imports, stale references -perfective = 10 # % for SPDX headers, doc updates, formatting, style - -# ============================================================================ -# UNIQUE STRENGTH (when mode = divergent) -# ============================================================================ -# What makes this project special. Agents should DEEPEN this, not broaden it. -# Customise this per project — the template default is generic. - -[methodology.unique-strength] -description = "{{PROJECT_UNIQUE_STRENGTH}}" -deepen-not-broaden = true - -# ============================================================================ -# DIVERGENT INVARIANTS -# ============================================================================ -# Constraints that divergent mode must NOT violate. -# These are the riverbanks — diverge within them, not across. -# "Amplify uniqueness" means deepen, not broaden. -# -# Test before any divergent action: -# "Does this deepen the existing strength, or add a parallel strength?" -# If parallel → stop. Note as cross-project insight. - -[methodology.divergent-invariants] -rules = [ - # Customise per project. Examples: - # "Idris2 only for formal verification — no Lean4, Coq, Agda", - # "believe_me count must remain zero", - # "FFI architecture: Idris2 → RefC → Zig → C ABI (no shortcuts)", -] - -# Optional: language invariant for the core strength -# If set, divergent mode will not introduce other languages for this purpose -# language-invariant = "idris2" - -# ============================================================================ -# CONSTRAINT HINTS -# ============================================================================ -# Help Phase 0 find the critical chain faster. -# Updated at session end with newly discovered constraints. - -[methodology.known-constraints] -constraints = [ - # Customise per project. Examples: - # "End-to-end build has never been verified", - # "libproject.so does not exist yet — all bindings call stubs", -] - -# ============================================================================ -# STATE FILE VALIDATION -# ============================================================================ -# Phase 0 reads STATE.a2ml first but it may be broken. -# These rules detect corrupt/template/stale state files. - -[methodology.state-validation] -reject-if-contains = ["{{PLACEHOLDER}}", "{{PROJECT}}", "rsr-template-repo"] -reject-if-project-name-mismatch = true -staleness-threshold-days = 90 -fallback-files = ["TODO.md", "TODO.adoc", "docs/status/ROADMAP.adoc", "README.adoc"] diff --git a/.machine_readable/ai/README.adoc b/.machine_readable/ai/README.adoc index 7d90fea3..439bee11 100644 --- a/.machine_readable/ai/README.adoc +++ b/.machine_readable/ai/README.adoc @@ -9,16 +9,15 @@ Examples: * `CLAUDE.md` * `COPILOT.md` * `GEMINI.md` -* `AI.a2ml` * `AI.djot` Avoid scattering agent instruction files around the repo root. Recommended machine read order: -* `.machine_readable/anchors/ANCHOR.a2ml` -* `.machine_readable/policies/MAINTENANCE-AXES.a2ml` -* `.machine_readable/policies/MAINTENANCE-CHECKLIST.a2ml` -* `.machine_readable/policies/SOFTWARE-DEVELOPMENT-APPROACH.a2ml` -* `.machine_readable/STATE.a2ml` -* `.machine_readable/META.a2ml` +* `0-AI-MANIFEST.deed` (pointer-only front door) +* `boj-server_chora.deed` (`(status)`, `(meta)`, `(agentic)`, `(anchor)`) +* `docs/maintenance/MAINTENANCE-CHECKLIST.adoc` +* `docs/practice/SOFTWARE-DEVELOPMENT-APPROACH.adoc` + +A2ML is retired: never add a `.a2ml` file here (`docs/history/A2ML-REMOVED.adoc`). diff --git a/.machine_readable/configs/0.2-AI-MANIFEST.a2ml b/.machine_readable/configs/0.2-AI-MANIFEST.a2ml deleted file mode 100644 index 6e41e6c2..00000000 --- a/.machine_readable/configs/0.2-AI-MANIFEST.a2ml +++ /dev/null @@ -1,11 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "configs-registry" -level: 2 -parent: "../0.1-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Sub-registry for configs metadata. diff --git a/.machine_readable/contractiles/adjust/Adjustfile.a2ml b/.machine_readable/contractiles/adjust/Adjustfile.a2ml deleted file mode 100644 index dcdc660f..00000000 --- a/.machine_readable/contractiles/adjust/Adjustfile.a2ml +++ /dev/null @@ -1,86 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -// Adjustfile.a2ml — Accessibility & Digital Justice contract for boj-server -// -// ADJUST = Accessibility & Digital Justice for Universal Software & Technology -// Standard: WCAG 2.2 Level AA (minimum). Violating ADJUST is a MUST violation. - -@abstract: -Accessibility invariants for boj-server. These apply to all user-facing interfaces: -GUI, TUI, CLI, web, mobile, documentation, error messages, and installation flows. -LLM/SLM agents MUST NOT violate these invariants. -@end - -@requires: -- section: Visual -- section: Keyboard -- section: CLI-TUI -@end - -## Visual - -- colour-contrast-ratio >= 4.5:1 for normal text -- colour-contrast-ratio >= 3:1 for large text (18pt+ or 14pt+ bold) -- no information conveyed by colour alone -- no flashing or strobing content (3 flashes/second max) -- text resizable to 200% without loss of content or function -- focus indicators visible on all interactive elements - -## Keyboard - -- all interactive elements reachable via keyboard (Tab/Shift+Tab) -- no keyboard traps — user can always Tab away -- skip navigation link present on pages with repeated blocks -- logical focus order follows visual reading order - -## Screen-Reader - -- all images have meaningful alt text (or alt='' if decorative) -- all form inputs have associated labels -- ARIA landmarks used for page regions (main, nav, banner, etc.) -- dynamic content updates announced via aria-live regions -- semantic HTML used (headings, lists, tables) — not div soup - -## Interactive - -- touch targets minimum 44x44px on mobile/touch interfaces -- error messages identify the field and describe the error -- error messages not conveyed by colour or position alone -- form validation provides suggestions for correction - -## Media - -- video has captions (closed or open) -- audio-only content has text transcript -- no autoplay of media with sound - -## Motion - -- animations respect prefers-reduced-motion media query -- no content depends on motion to convey meaning - -## CLI-TUI - -- CLI output must not rely solely on colour (use symbols: [OK] [FAIL]) -- TUI must support high-contrast mode -- all CLI commands support --help with plain-text output -- error messages written in plain language, not jargon or codes alone - -## Documentation - -- docs use clear language, short sentences, logical structure -- code examples include comments explaining non-obvious steps -- diagrams have text descriptions or alt text - -## Enforcement - -- ci: accessibility linting in quality.yml workflow -- pr-block: PR blocked if accessibility regression detected -- tool: axe-core or pa11y for automated checks on web UI -- tool: CLI output inspected for colour-only signalling -- manual: manual screen reader test before major releases - -## Notes - -These are MINIMUM requirements (WCAG 2.2 AA). Exceeding them (AAA) is encouraged. -Accessibility is not optional polish — it is a structural requirement. diff --git a/.machine_readable/contractiles/adjust/adjust.ncl b/.machine_readable/contractiles/adjust/adjust.ncl index 58861800..736cffc6 100644 --- a/.machine_readable/contractiles/adjust/adjust.ncl +++ b/.machine_readable/contractiles/adjust/adjust.ncl @@ -1,7 +1,9 @@ # SPDX-License-Identifier: MPL-2.0 # adjust.ncl — accessibility invariant runner for boj-server # -# Pairs with: Adjustfile.a2ml (same directory) +# Pairs with: Adjustfile.deed (same directory; A7 8.1). Not yet written: the +# legacy Adjustfile.a2ml was retired 2026-11-14 with no mapping +# spec to translate it (docs/history/A2ML-REMOVED.adoc). # Verb: adjust # Semantics: verify all user-facing interfaces meet WCAG 2.2 AA minimum. # Runner applies automated accessibility probes and hard-gates on @@ -26,7 +28,7 @@ name = "adjust-runner", version = "1.0.0", description = "Verifies WCAG 2.2 AA compliance across all user-facing interfaces. Hard-gates on critical regressions.", - paired_xfile = "Adjustfile.a2ml", + paired_xfile = "Adjustfile.deed", standard = "WCAG-2.2-AA", author = "Jonathan D.A. Jewell ", }, diff --git a/.machine_readable/contractiles/bust/Bustfile.a2ml b/.machine_readable/contractiles/bust/Bustfile.a2ml deleted file mode 100644 index 62af44e6..00000000 --- a/.machine_readable/contractiles/bust/Bustfile.a2ml +++ /dev/null @@ -1,28 +0,0 @@ -// Bustfile.a2ml — meta-repo bust contractile (breakage / rollback) -// SPDX-License-Identifier: MPL-2.0 - -Bust { - name: "boj-server" - version: "1.0.0" - description: "Rollback procedures when something breaks in the meta-repo" - - scenarios: { - "bad-pointer-bump": "git revert in meta-repo; child repo itself untouched" - "submodule-pointer-points-at-missing-sha": "git submodule update --init --checkout resets child to parent-recorded SHA; OR revert the stale bump commit" - "submodule-orphan-after-local-only-commit": "roll back locally with git reset to before the stranded commit; fix remote situation before re-attempting" - "accidental-private-repo-content-leaked-to-public-submodule": "hard-rotate the leaked secret immediately; git-filter-repo or BFG on the submodule's own history; public re-publication only after rotation complete" - } - - escalation-ladder: [ - "1. revert the meta-repo commit (reversible, low blast radius)", - "2. reset the local submodule clone (affects only local workspace)", - "3. force-push to main — PROHIBITED without explicit user confirmation (violates branch protection)", - "4. registry-level (delete/archive the GitHub repo) — human-only action, never by AI" - ] - - backup-points: [ - "GitHub serves as the durable backup for every submodule's own history", - "Meta-repo history on origin/main is the durable backup for pointer state", - "Local backup tags (backup/pre--) retained on risky rewrites" - ] -} diff --git a/.machine_readable/contractiles/bust/bust.ncl b/.machine_readable/contractiles/bust/bust.ncl index fc8cb8cd..82171e0f 100644 --- a/.machine_readable/contractiles/bust/bust.ncl +++ b/.machine_readable/contractiles/bust/bust.ncl @@ -1,7 +1,9 @@ # SPDX-License-Identifier: MPL-2.0 # Bust — error-handling / failure-recovery runner # -# Pairs with: Bustfile.a2ml (same directory) +# Pairs with: Bustfile.deed (same directory; A7 8.1). Not yet written: the +# legacy Bustfile.a2ml was retired 2026-11-14 with no mapping +# spec to translate it (docs/history/A2ML-REMOVED.adoc). # Verb: bust # Semantics: every declared failure mode must have a recovery path that has # been exercised. Runner injects failures (via declared probes) @@ -33,7 +35,7 @@ let base = import "../_base.ncl" in name = "bust-runner", version = "1.0.0", description = "Exercises declared failure modes and verifies recovery paths. Hard-gates on any failure mode without working recovery.", - paired_xfile = "Bustfile.a2ml", + paired_xfile = "Bustfile.deed", author = "Jonathan D.A. Jewell ", }, }, diff --git a/.machine_readable/contractiles/dust/Dustfile.a2ml b/.machine_readable/contractiles/dust/Dustfile.a2ml deleted file mode 100644 index 8c61f268..00000000 --- a/.machine_readable/contractiles/dust/Dustfile.a2ml +++ /dev/null @@ -1,20 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Dustfile (A2ML Canonical) - -@abstract: -Recovery and rollback paths for boj-server. -Declares how to undo significant state changes. -@end - -@requires: -- section: Source -@end - -## Source - -### source-rollback -- description: Revert all source changes to last commit -- rollback: git checkout HEAD -- . -- blast_radius: file -- precondition: git stash -- notes: Stashes uncommitted work before reverting diff --git a/.machine_readable/contractiles/dust/dust.ncl b/.machine_readable/contractiles/dust/dust.ncl index fda0f000..821f55a1 100644 --- a/.machine_readable/contractiles/dust/dust.ncl +++ b/.machine_readable/contractiles/dust/dust.ncl @@ -1,11 +1,13 @@ # SPDX-License-Identifier: MPL-2.0 # dust.ncl — cleanup and hygiene runner for boj-server # -# Pairs with: Dustfile.a2ml (same directory) +# Pairs with: Dustfile.deed (same directory; A7 8.1). Not yet written: the +# legacy Dustfile.a2ml was retired 2026-11-14 with no mapping +# spec to translate it (docs/history/A2ML-REMOVED.adoc). # Verb: dust # Semantics: verify cleanup policies are met and all recovery paths are declared. # Runner checks for stale branches, stale artefacts, dead code, and -# that each recovery scenario in Dustfile.a2ml has a verified path. +# that each recovery scenario in the Dustfile has a verified path. # CLI: `contractile dust check` → run hygiene checks # `contractile dust sweep` → execute safe cleanup operations # @@ -26,7 +28,7 @@ name = "dust-runner", version = "1.0.0", description = "Verifies cleanup policies and all declared recovery rollback paths. Sweep mode applies only reversible cleanup.", - paired_xfile = "Dustfile.a2ml", + paired_xfile = "Dustfile.deed", author = "Jonathan D.A. Jewell ", }, }, diff --git a/.machine_readable/contractiles/intend/Intentfile.a2ml b/.machine_readable/contractiles/intend/Intentfile.a2ml deleted file mode 100644 index fc1e7374..00000000 --- a/.machine_readable/contractiles/intend/Intentfile.a2ml +++ /dev/null @@ -1,61 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -// Intentfile.a2ml — Purpose and scope contract for boj-server - -@abstract: -Declared intent, purpose, and scope for Bundle of Joy (BoJ) Server. -LLM/SLM agents: understand what this repo IS and IS NOT before acting. -@end - -@requires: -- section: Purpose -- section: Anti-Purpose -- section: Architectural-Invariants -@end - -## Purpose - -BoJ (Bundle of Joy) is a unified MCP server that consolidates all hyperpolymath -tooling into a single endpoint. It provides Claude Code integration for GitHub, -GitLab, Cloudflare, Vercel, Verpex, Gmail, Calendar, browser automation, research, -ML, and 125 open-source cartridges. It implements a three-class architecture: -- Class 1 (Simple Track): zero-infrastructure CLI/curl workflows -- Class 2 (Orchestrator Track): HMAC-SHA256 webhooks and real-time MQTT/WS -- Class 3 (Multiplier Track): Elixir/BEAM mass concurrency - -## Anti-Purpose - -BoJ is NOT: -- A general-purpose API gateway or reverse proxy -- A standalone application — it serves LLM/MCP tool consumers -- A replacement for direct API access when MCP is not involved -- A container for business logic for connected services (GitHub, GitLab, etc.) -- A standalone MCP server outside the BoJ architecture (all MCP goes through BoJ) - -## Architectural-Invariants - -These must not be reversed without an explicit ADR: -- Three-class architecture: Class 1 must never be broken by Class 2/3 features -- MCP bridge is the sole entry point for Claude Code integration -- REST API on port 7700 for all cartridge invocations -- Self-contained cartridges with own adapters in cartridges//adapter/ -- All MCP through BoJ only — no standalone MCP servers permitted -- Firefox first for browser automation (not Chrome) -- HMAC-SHA256 webhook verification for Class 2 orchestrator track -- Target runtime: Zig→WASM typed bridge (Node.js mcp-bridge is transitional) - -## Sensitive-Areas - -Ask before touching: -- mcp-bridge/ — MCP protocol bridge; changes affect all Claude Code integration -- adapter/ — service adapters (GitHub, GitLab, Cloudflare, etc.); API contract changes -- cartridges/ — self-contained service cartridges; each has own adapter -- ffi/ — Idris2 ABI + Zig FFI interface layer -- .machine_readable/ — checkpoint files, format is specified -- ai-plugin.json — cartridge metadata; must remain valid for discovery - -## Ecosystem - -- belongs-to: standalone server (not a library) -- depends-on: github-api, gitlab-api, cloudflare-api, vercel-api, verpex-api -- depended-on-by: claude-code, panll, hypatia, ambientops diff --git a/.machine_readable/contractiles/intend/intend.ncl b/.machine_readable/contractiles/intend/intend.ncl index 61856fe4..c8da565a 100644 --- a/.machine_readable/contractiles/intend/intend.ncl +++ b/.machine_readable/contractiles/intend/intend.ncl @@ -1,7 +1,9 @@ # SPDX-License-Identifier: MPL-2.0 # intend.ncl — purpose/scope verification runner for boj-server # -# Pairs with: Intentfile.a2ml (same directory) +# Pairs with: Intentfile.deed (same directory; A7 8.1). Not yet written: the +# legacy Intentfile.a2ml was retired 2026-11-14 with no mapping +# spec to translate it (docs/history/A2ML-REMOVED.adoc). # Verb: intend # Semantics: verify the repo matches its declared purpose; detect scope-creep # by checking for anti-purpose violations (banned languages, banned @@ -26,7 +28,7 @@ name = "intend-runner", version = "1.0.0", description = "Verifies repo aligns with declared purpose. Hard-gates on anti-purpose violations.", - paired_xfile = "Intentfile.a2ml", + paired_xfile = "Intentfile.deed", author = "Jonathan D.A. Jewell ", }, }, diff --git a/.machine_readable/contractiles/must/Mustfile.a2ml b/.machine_readable/contractiles/must/Mustfile.a2ml deleted file mode 100644 index b16f5e0a..00000000 --- a/.machine_readable/contractiles/must/Mustfile.a2ml +++ /dev/null @@ -1,59 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Mustfile (A2ML Canonical) -# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) - -@abstract: -Physical State contract for boj-server — MCP server for Butler of Joy. -Ensures required files exist, no banned patterns, and SPDX compliance. -@end - -@requires: -- section: Checks -@end - -## Checks - -### license-present -- description: LICENSE file must exist -- run: test -f LICENSE -- severity: critical - -### readme-present -- description: README must exist -- run: test -f README.adoc || test -f README.md -- severity: critical - -### security-md-present -- description: SECURITY.md must exist -- run: test -f SECURITY.md -- severity: critical - -### justfile-present -- description: Justfile must exist -- run: test -f Justfile -- severity: critical - -### package-json-present -- description: package.json must exist (MCP server entry point) -- run: test -f package.json -- severity: critical - -### no-banned-files -- description: No Dockerfiles or Makefiles -- run: test ! -f Dockerfile && test ! -f Makefile -- severity: critical - -### no-env-files -- description: No .env files committed -- run: test ! -f .env && test ! -f .env.local -- severity: critical - -### spdx-headers -- description: JS source files should have SPDX headers -- run: find . -name '*.js' -not -path '*/node_modules/*' | head -20 | xargs -r grep -L 'SPDX-License-Identifier' | wc -l | grep -q '^0$' -- severity: warning - -### mcp-bridge-exists -- description: MCP bridge entry point must exist -- run: test -f mcp-bridge/main.js -- severity: critical diff --git a/.machine_readable/contractiles/must/must.ncl b/.machine_readable/contractiles/must/must.ncl index 5de41747..e01f2467 100644 --- a/.machine_readable/contractiles/must/must.ncl +++ b/.machine_readable/contractiles/must/must.ncl @@ -1,7 +1,9 @@ # SPDX-License-Identifier: MPL-2.0 # must.ncl — baseline invariant runner for boj-server # -# Pairs with: Mustfile.a2ml (same directory) +# Pairs with: Mustfile.deed (same directory; A7 8.1). Not yet written: the +# legacy Mustfile.a2ml was retired 2026-11-14 with no mapping +# spec to translate it (docs/history/A2ML-REMOVED.adoc). # Verb: must # Semantics: every declared invariant must pass. Runner evaluates physical-state # checks (file existence, no banned patterns, SPDX headers, etc.) and @@ -26,7 +28,7 @@ name = "must-runner", version = "1.0.0", description = "Evaluates all declared must-invariants. Blocks merge on critical failure. K9 validator is the authoritative CI enforcement.", - paired_xfile = "Mustfile.a2ml", + paired_xfile = "Mustfile.deed", k9_validator = ".machine_readable/svc/self-validating/boj-server-metadata.k9.ncl", author = "Jonathan D.A. Jewell ", }, diff --git a/.machine_readable/contractiles/trust/Trustfile.a2ml b/.machine_readable/contractiles/trust/Trustfile.a2ml deleted file mode 100644 index 4a684faa..00000000 --- a/.machine_readable/contractiles/trust/Trustfile.a2ml +++ /dev/null @@ -1,1224 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# ============================================================================= -# A2ML Trustfile — Bundle of Joy Server -# Formally verified capability catalogue for developer server protocols. -# ============================================================================= - ---- -### [META] -id: "did:web:github.com:hyperpolymath:boj-server" -version: "2026.2.5-final" -context: - - "https://a2ml.org/ns/v3" - - "https://idris-lang.org/ns/v2" # TODO: replace with canonical URL once published - - "https://hypatia.scans/ns/v1" - - "https://w3id.org/security/v4" - - "https://w3id.org/transparency/v1" -meta: - generated: "2026-02-16T00:00:00Z" - expires: "2027-02-16T00:00:00Z" - signature: - algorithm: "Ed448+Dilithium5" - value: | - -----BEGIN HYBRID SIGNATURE----- - BASE64_Ed448+Dilithium5_SIGNATURE_OF_THIS_FILE - -----END HYBRID SIGNATURE----- - signedBy: "did:web:github.com:hyperpolymath:boj-server#primary-sig" - proof: "https://github.com/hyperpolymath/boj-server/proofs/meta.idr" - fallbackSignature: - algorithm: "SPHINCS+" - value: | - -----BEGIN SPHINCS+ SIGNATURE----- - BASE64_SPHINCS+_SIGNATURE_OF_THIS_FILE - -----END SPHINCS+ SIGNATURE----- - integrity: - sha3-512: "HEX_SHA3_512_OF_THIS_FILE" - shake256: "BASE32_SHAKE256_OF_THIS_FILE" - zonemd: "2026021601;SHA512;BASE64_SHA512_OF_ZONE;SHAKE256;BASE32_SHAKE256_OF_ZONE" - ci_cd: - github_actions: "https://github.com/hyperpolymath/boj-server/blob/main/.github/workflows/trustfile.yml" - gitbot_fleet: "https://gitbot-fleet.hyperpolymath.dev/hooks/trustfile" - hypatia_scan: "https://hypatia.scans/repos/boj-server" - automation: - hashing: ["SHA3-512", "SHAKE256", "BLAKE3"] - diffing: "alert-on-unexpected-changes" - integrity: ["zonemd-consistency", "transparency-log-continuity", "idris2-proof-validity"] - ---- -### [CARTRIDGE_SPEC_REF] -spec: "docs/specification/cartridges/README.md" -tools_spec: "docs/specification/cartridge-tools/README.md" -abi_core: "src/abi/Boj/Catalogue.idr" -note: "cartridge-level claims in this Trustfile defer to the cartridge spec for normative shape" - ---- -### [THREAT_MODEL] -adversaries: - - type: "APT" - mitigations: - - "Capability-based auth → No lateral movement." - - "Idris2 proofs → No exploit primitives." - - "Transparency logs → Immediate detection." - - type: "Ransomware" - mitigations: - - "Consent-Aware HTTP → No bulk exfiltration." - - "SDP (CAdRE Router) → Resource isolation." - - "Immutable logs → Instant rollback." - - type: "Quantum Adversary" - mitigations: - - "Kyber1024 + Dilithium5 → PQ-resistant crypto." - - "SPHINCS+ fallback → Crypto agility." - - "GitBot-Fleet → Automated key rotation." - - type: "DDoS" - mitigations: - - "Cloudflare edge network → Absorbs volumetric attacks." - - "HTTP DDoS Managed Ruleset → Auto-mitigation at max sensitivity." - - "Challenge Passage TTL → Rate-limits challenge solvers." - - "Security Level → Adjustable based on threat intelligence." - - type: "AI Scraper" - mitigations: - - "Bot Fight Mode → Challenges known bot patterns." - - "Block AI Bots → Blocks verified AI crawlers + similar unverified." - - "AI Labyrinth → Traps scrapers in infinite maze of AI-generated decoy content." - - "AI Crawl Control → Per-crawler blocking and monitoring." - - "Managed robots.txt → Programmatic crawl directives." - - type: "Credential Stuffer" - mitigations: - - "Browser Integrity Check → Rejects headless/automated browsers." - - "Challenge Passage TTL → Forces re-challenge after 30 min." - - "HSTS preload → Prevents SSL-stripping MITM for credential capture." - - "Leaked credentials detection → (Enterprise; noted for upgrade path)." - - type: "Email Spoofing" - mitigations: - - "SPF hard fail (-all) → Rejects unauthorized senders." - - "DMARC p=reject → Instructs receivers to drop spoofed mail." - - "DKIM signing → Cryptographic message authentication." - - "CAA records → Restricts certificate issuance to authorized CAs." - ---- -### [DNS] -dnssec: - enabled: true - algorithm: "ECDSAP256SHA256" - ds_record: "PENDING" - key_tag: "PENDING" - digest_type: "SHA-256" - policy: "DNSSEC MUST be enabled on all zones. DS records propagated to registrar." - security: - proof: "DNS.DNSSEC.idr" - ci_cd: "verify-dnssec-propagation" -soa: - mname: "ns1.cloudflare.com." - rname: "admin.hyperpolymath.dev." - serial: 2026021601 - refresh: 10800 - retry: 3600 - expire: 604800 - minimumTTL: 3600 - zonemd: "2026021601;SHA512;BASE64_SHA512_OF_ZONE;SHAKE256;BASE32_SHAKE256_OF_ZONE" -records: - - type: "A" - name: "@" - value: "192.0.2.1" - ttl: 3600 - proxied: true - security: - zonemd: "2026021601;SHA512;BASE64_SHA512;SHAKE256;BASE32_SHAKE256" - proof: "DNS.Core.A_Record.idr" - hypatia: "scan-dns-record" - ci_cd: "auto-hash-on-push" - - type: "AAAA" - name: "@" - value: "2001:db8::1" - ttl: 3600 - proxied: true - security: - proof: "DNS.Core.AAAA_Record.idr" - - type: "HTTPS" - name: "@" - value: '1 . alpn="h3,h2" ipv4hint=192.0.2.1 ipv6hint=2001:db8::1' - ttl: 3600 - security: - proof: "DNS.HTTPS.idr" - - type: "SVCB" - name: "@" - value: '1 . alpn="h3,h2" port=443 ipv4hint=192.0.2.1 ipv6hint=2001:db8::1' - ttl: 3600 - security: - proof: "DNS.SVCB.idr" - - type: "TXT" - name: "@" - value: '"v=DMARC1; p=reject; rua=mailto:j.d.a.jewell@open.ac.uk; ruf=mailto:j.d.a.jewell@open.ac.uk"' - ttl: 3600 - security: - proof: "Email.DMARC.idr" - - type: "CAA" - name: "@" - value: '0 issue "letsencrypt.org"' - ttl: 3600 - - type: "CAA" - name: "@" - value: '0 issue "digicert.com"' - ttl: 3600 - - type: "CAA" - name: "@" - value: '0 iodef "mailto:j.d.a.jewell@open.ac.uk"' - ttl: 3600 - - type: "TLSA" - name: "_443._tcp" - value: "3 1 1 D2ABDE240D7CD3EE6B4B28C54DF034B97983A1D16E8A410E4561CB106618E971" - ttl: 3600 - - type: "TLSA" - name: "_443._tcp" - value: "3 3 1 BASE32_SHAKE256_CERT_HASH" - ttl: 3600 - - type: "TXT" - name: "_cyberwar-trap" - value: '"🎣 This system is formally verified. Good luck, script kiddie."' - ttl: 3600 - security: - hypatia: "scan-for-apt-activity" - proof: "Psychological.Warfare.idr" - - type: "TXT" - name: "_capabilities" - value: '"v=OCAP1; endpoint=https://github.com/hyperpolymath/boj-server/cap"' - ttl: 3600 - security: - proof: "HTTP.Capabilities.idr" - - type: "TXT" - name: "_consent" - value: '"v=CAdRE1; endpoint=https://github.com/hyperpolymath/boj-server/.well-known/consent"' - ttl: 3600 - security: - proof: "HTTP.Consent.idr" - gitbot: "validate-consent-endpoint" - # Email Security Records - - type: "TXT" - name: "@" - value: '"v=spf1 -all"' - ttl: 3600 - notes: "Hard fail. No servers authorized to send. Override per-domain if email is used." - security: - proof: "Email.SPF.idr" - - type: "TXT" - name: "_dmarc" - value: '"v=DMARC1; p=reject; sp=reject; adkim=s; aspf=s; rua=mailto:j.d.a.jewell@open.ac.uk; ruf=mailto:j.d.a.jewell@open.ac.uk; fo=1"' - ttl: 3600 - notes: "Strict alignment. Reject all unauthenticated. Forensic reports on any failure." - security: - proof: "Email.DMARC.idr" - ci_cd: "validate-dmarc-alignment" - - type: "TXT" - name: "*._domainkey" - value: '"v=DKIM1; p="' - ttl: 3600 - notes: "Empty public key = revoked. Prevents DKIM pass on spoofed mail for non-sending domains." - security: - proof: "Email.DKIM.idr" - - type: "TXT" - name: "_mta-sts" - value: '"v=STSv1; id=20260302"' - ttl: 3600 - notes: "MTA-STS policy ID. Rotate on policy change." - - type: "TXT" - name: "_smtp._tls" - value: '"v=TLSRPTv1; rua=mailto:j.d.a.jewell@open.ac.uk"' - ttl: 3600 - notes: "SMTP TLS Reporting (RFC 8460). Receive reports on TLS failures." - ---- -### [EMAIL_SECURITY] -overview: | - Email security posture for domains that do NOT send email. - All records configured to reject/block spoofed mail. - For domains that DO send email, override SPF with authorized senders, - configure DKIM signing keys, and set DMARC to quarantine during rollout. -policy: - non_sending_domains: - spf: "v=spf1 -all" - dmarc: "p=reject; sp=reject; adkim=s; aspf=s; fo=1" - dkim: "revoked (empty public key)" - mta_sts: "mode: enforce; max_age: 604800" - sending_domains: - spf: "v=spf1 include:_spf.google.com include:_spf.cloudflare.com -all" - dmarc: "p=reject; sp=reject; adkim=s; aspf=s; pct=100; fo=1" - dkim: "2048-bit RSA minimum; rotate annually" - mta_sts: "mode: enforce; max_age: 604800" -email_routing: - provider: "Cloudflare Email Routing" - features: - - "Custom address forwarding" - - "DMARC enforcement (rejects unauthenticated inbound)" - - "IPv6 support" - - "Automatic MX/SPF/DKIM record creation" - security: - proof: "Email.Routing.idr" -security: - proof: "Email.Policy.idr" - ci_cd: "validate-email-records-on-push" - ---- -### [TRUSTFILE] -issuer: "did:web:github.com:hyperpolymath:boj-server" -keys: - - id: "#primary-sig" - type: "HybridKey2024" - classical: - algorithm: "Ed448" - publicKeyJwk: - kty: "OKP" - crv: "Ed448" - x: "BASE64URL_Ed448_PUBLIC_KEY" - postQuantum: - algorithm: "Dilithium5" - publicKeyJwk: - kty: "OKP" - crv: "Dilithium5" - x: "BASE64URL_Dilithium5_PUBLIC_KEY" - fallback: - algorithm: "SPHINCS+" - publicKeyJwk: - kty: "OKP" - crv: "SPHINCS+" - x: "BASE64URL_SPHINCS+_PUBLIC_KEY" - usage: ["authentication", "assertion"] - security: - proof: "Crypto.HybridKey.idr" - hypatia: "scan-keys" - ci_cd: "rotate-keys-on-compromise" -algorithms: - hashing: ["SHA3-512", "SHAKE256", "BLAKE3"] - kdf: "HKDF-SHAKE512" - rng: "ChaCha20-DRBG" - passwordHashing: "Argon2id (512 MiB, 8 iter, 4 lanes)" - security: - proof: "Crypto.Algorithms.idr" -policies: - dns: - rego: | - package trustfile.dns - default allow = false - allow { - input.record.security.proof != "" - input.record.security.zonemd != "" - } - idris2: "Policies.DNS.idr" - ci_cd: "validate-dns-policies-on-push" - http: - rego: | - package trustfile.http - default allow = false - allow { - input.consent.granted - valid_capability(input.capability) - } - idris2: "Policies.HTTP.idr" - php: - rego: | - package trustfile.php - default allow = false - allow { - input.php.aegis_enabled - input.php.sanctify_enabled - } - idris2: "Policies.PHP.idr" -fallbacks: - signatures: ["Ed448+Dilithium5", "SPHINCS+"] - keyExchange: ["Kyber1024-X25519", "X25519"] - ---- -### [VERIFICATION_LADDER] -overview: | - Four-tier verification claim ladder. Each capability in this Trustfile - MUST declare which tier it sits at. Claims at a tier require the evidence - at that tier; no claim may be made stronger than the evidence supports. -tiers: - - id: "idris2-proven" - description: "Formal proofs in Idris2 with %default total. IsUnbreakable or equivalent proof required before activation." - evidence_required: "Idris2 module, compiler version recorded, axioms declared, last-check date." - - id: "zig-assured" - description: "Zig boundary calls into proven-sourced safety primitives (safePathDefault, safeHeaderDefault, etc). Defense-in-depth; not formal proof but grounded in Idris2-proven predicates." - evidence_required: "Declared primitive + reference to proven-side Idris2 proof." - - id: "elixir-disciplined" - description: "Supervision trees + session-typed protocols + dialyzer + Gleam where applicable. Pattern-conforming, not proven." - evidence_required: "Supervisor module, session type declaration, dialyzer clean." - - id: "external-trust" - description: "Unverified-by-construction layer: HATs, external CLIs, third-party services. Acknowledged trust, isolated via circuit breakers." - evidence_required: "Documented trust boundary + isolation mechanism." - ---- -### [HAT_PERIMETER] -overview: | - HATs (Hardware Attached on Top — per docs/papers/boj-architecture-paper.md §6 - and docs/specification/cartridges/README.md §5) sit OUTSIDE the safety - perimeter. HATs are unverified-by-construction. IsUnbreakable proof - for a cartridge still holds regardless of HAT presence. -policy: - per_hat_attestation: "each HAT declared here with its external-tool + isolation mechanism" - circuit_breaker: "every HAT isolated by per-cartridge circuit breaker; HAT failure trips breaker, not core" - threat_model: "HAT compromise = bounded blast radius (one cartridge affected)" -hats: [] -security: - tier: "external-trust" - proof: "HATPerimeter.Policy.idr" - ---- -### [SURFACE_EPHEMERALITY] -overview: | - Three-axis transport model per docs/specification/cartridges/README.md §6 - and §7. Unused transports are default-locked: not listening, not registered, - not reachable. On-demand spin-up when a legitimate caller uses one. -axes: - possible_transports: - description: "Declared in cartridge Nickel manifest (supported_transports)" - enforcement: "manifest validation at cartridge mount" - preferred_transports: - description: "Ordered preference list per cartridge (security_grade + provenance)" - enforcement: "gateway honours ordering when multiple transports active" - active_transports: - description: "Runtime set — currently in use by callers" - enforcement: "default-locked; spin up on valid capability+manifest match; drain-down when unused" -transaction_ephemerality: - capability_tokens: "per-transaction, destroyed at end of transaction" - session_state: "NONE spanning requests" - long_lived_streams: "WebSocket/SSE framed with per-message capability gates" -security: - tier: "zig-assured" - proof: "SurfaceEphemerality.Policy.idr" - ---- -### [BEAM_SUPERVISION] -overview: | - All-Elixir architecture. No scalable/individual bifurcation — BEAM scales - down (Nerves) so one architecture covers single-user through enterprise. - BEAM provides: lightweight process-per-cartridge-invocation, supervisor - trees for fault isolation, mailbox back-pressure, hot code swap. -declared_2026_04_17: true -supervision: - shape: "OTP supervision tree" - policy: "one_for_one or rest_for_one per subtree; cartridge-subtree isolation" - crash_containment: "individual cartridge crash does not affect others; supervisor restarts" -session_types: - policy: "inter-cartridge messaging uses session-typed protocols where feasible" - status: "progressive adoption; dialyzer-clean baseline" -runtime_isolation: - per_cartridge: "BEAM process (not OS process, not thread)" - blast_radius: "one cartridge crash → supervisor restart; no cascade" -back_pressure: - preferred: "fail fast with clear 'try later' over unbounded queuing" - mailbox_limits: "declared per cartridge" -security: - tier: "elixir-disciplined" - proof: "BEAMSupervision.Policy.idr" - ---- -### [SEAMS] -overview: | - A seam is an integration boundary between two components that can be - independently versioned, built, or deployed. Every seam MUST be declared - here with: contract owner, test coverage, failure mode on mismatch. - See docs/SEAMS-SPEC.adoc for the full spec. -seams: - - id: "proven-zig-api" - description: "Idris2 proven library ↔ Zig FFI boundary" - from: "verification-ecosystem/proven" - to: "src/abi/Boj/Catalogue.idr + ffi/zig/" - contract: "src/abi/Boj/Catalogue.idr" - test_ref: "tests/seam/proven-zig-api.test" - failure_mode: "fail-closed" - tier: "zig-assured" - notes: "" - - id: "zig-api-boj" - description: "Zig FFI boundary ↔ BoJ Elixir core" - from: "ffi/zig/" - to: "lib/boj/" - contract: "src/abi/Boj/Catalogue.idr" - test_ref: "tests/seam/zig-api-boj.test" - failure_mode: "fail-closed" - tier: "zig-assured" - notes: "" - - id: "cartridge-hat" - description: "Cartridge core ↔ HAT (external tool)" - from: "lib/boj/cartridge/" - to: "external HAT" - contract: "docs/specification/cartridges/README.md §5" - test_ref: "tests/seam/cartridge-hat.test" - failure_mode: "fail-closed (circuit breaker)" - tier: "external-trust" - notes: "HAT failure trips circuit breaker; core unaffected" - - id: "cartridge-beam-supervisor" - description: "Cartridge process ↔ BEAM OTP supervisor" - from: "lib/boj/cartridge/" - to: "lib/boj/supervisor/" - contract: "OTP supervisor protocol" - test_ref: "tests/seam/cartridge-supervisor.test" - failure_mode: "fail-closed (supervisor restart)" - tier: "elixir-disciplined" - notes: "" - - id: "gateway-boj-gnosis" - description: "http-capability-gateway ↔ BoJ unified Zig API gnosis handler" - from: "web-ecosystem/http-capability-gateway" - to: "src/zig-api/ (gnosis handler)" - contract: "docs/integration/http-capability-gateway-boj-contract.md" - test_ref: "web-ecosystem/http-capability-gateway:test/e2e_boj_integration_test.exs" - failure_mode: "fail-closed (circuit breaker)" - tier: "elixir-disciplined" - notes: "Phase C (hyperpolymath/standards#98). Tier-2 HTTP governance seam declared per ADR 0004; the gateway resolves trust at the transport (mTLS, Phase B) and forwards an authoritative X-Trust-Level to the gnosis handler. E2E seam test lives in the gateway repo because that is the side that owns the policy pipeline and the proxy." -policy: - seam_check: "every PR that touches either side of a declared seam MUST exercise the P2P test for that seam before merge" -security: - proof: "Seams.Policy.idr" - ---- -### [SECRETS_HYGIENE] -at_rest: - pattern: "SOPS+age" - template_location: "web-ecosystem/lcb-website/" - adoption_status: "template + estate intent — per-repo adoption tracked below" - per_repo_adoption: - - repo: "lcb-website" - status: "DEPLOYED" - - repo: "boj-server" - status: "DEPLOYED — .sops.yaml + .env.example wired 2026-04-25" - pre_commit_hooks: - - "gitleaks" - - "plaintext detector" -delivery: - mechanism: "environment variable injection at container start" - scope: "SOPS-decrypted secrets → ROKUR_SECRET_ env vars; containers never read plaintext from disk" -gate: - tool: "Rokur" - role: "policy engine — validates required secrets present, audits, rate-limits, fail-closed" - features: - - "per-IP sliding window rate limiting (60/min general, 5/min auth-fail)" - - "structured JSONL audit logging" - - "X-Request-Id tracing" - - "policy backends: builtin or external (Ephapax adapter)" - - "SIGHUP hot-reload" -llm_agents: - tool: "RGTV" - status: "ALPHA — NOT production-ready, see RGTV/README.adoc known-unsafe list" - scope: "LLM-agent credential brokering only — opaque one-use grants" - enabled_here: "false — RGTV not wired into BoJ; BoJ itself doesn't broker LLM-agent credentials" -security: - proof: "Secrets.Hygiene.idr" - ci_cd: "validate-secrets-flow-on-push" - ---- -### [CI_CD] -github_actions: - name: "Trustfile Validation" - on: ["push", "pull_request"] - jobs: - validate: - runs-on: "ubuntu-latest" - steps: - - uses: "actions/checkout@v4" - - name: "Validate A2ML" - run: "a2ml validate Trustfile.a2ml" - - name: "Run Idris2 Proofs" - run: "idris2 --build trust.ipkg" - - name: "Hypatia Scan" - run: "hypatia scan --config hypatia.yml" - - name: "GitBot-Fleet Passover" - run: "gitbot-fleet passover --file Trustfile.a2ml" - update_integrity: - runs-on: "ubuntu-latest" - steps: - - name: "Update Hashes" - run: | - NEW_SHA3=$(sha3sum -a 512 Trustfile.a2ml | awk '{print $1}') - NEW_SHAKE=$(shake256sum Trustfile.a2ml | awk '{print $1}' | base32) - sed -i "s|sha3-512:.*|sha3-512: \"$NEW_SHA3\"|" Trustfile.a2ml - sed -i "s|shake256:.*|shake256: \"$NEW_SHAKE\"|" Trustfile.a2ml - - name: "Commit and Push" - run: | - git config --global user.name "GitBot-Fleet" - git config --global user.email "gitbot@hyperpolymath.dev" - git add Trustfile.a2ml - git commit -m "Auto-update integrity hashes [skip ci]" - git push -gitbot_fleet: - hooks: - - type: "pre-commit" - script: "a2ml validate Trustfile.a2ml" - - type: "post-merge" - script: "gitbot-fleet diff --file Trustfile.a2ml" -hypatia: - config: "hypatia.yml" - scans: - - type: "dns" - frequency: "daily" - - type: "crypto" - frequency: "weekly" - - type: "php" - frequency: "on-push" - ---- -### [IDRIS2_PROOFS] -theorems: - - name: "dns_correctness" - file: "DNS.Core.idr" - description: "All DNS records are conflict-free and correctly signed." - status: "proven" - ci_cd: "reprove-on-dns-change" - - name: "tls_handshake_safety" - file: "TLS.Handshake.idr" - description: "TLS 1.3 + Kyber1024 handshake resists downgrade attacks." - status: "proven" - - name: "consent_aware_http_soundness" - file: "HTTP.Consent.idr" - description: "Consent-Aware HTTP (CAdRE) enforces user intent." - status: "proven" - - name: "capability_gateway_correctness" - file: "HTTP.Capabilities.idr" - description: "OCAP-style capability gateway is safe." - status: "proven" - - name: "php_hardening_no_bypasses" - file: "PHP.Hardening.idr" - description: "PHP-Aegis + Sanctify-PHP blocks all unsafe functions." - status: "proven" - - name: "edge_ssl_no_downgrade" - file: "Cloudflare.SSL.idr" - description: "TLS 1.3 + HSTS preload prevents protocol downgrade at edge." - status: "proven" - ci_cd: "reprove-on-ssl-change" - - name: "bot_defense_coverage" - file: "Cloudflare.Bots.idr" - description: "Bot Fight Mode + AI Labyrinth + Block AI Bots covers all free-plan bot vectors." - status: "proven" - - name: "email_anti_spoofing" - file: "Email.Policy.idr" - description: "SPF -all + DMARC reject + revoked DKIM prevents email spoofing on non-sending domains." - status: "proven" - ci_cd: "reprove-on-email-record-change" - - name: "response_headers_complete" - file: "Cloudflare.ResponseHeaders.idr" - description: "All OWASP-recommended response headers enforced at edge." - status: "proven" - - name: "dnssec_chain_valid" - file: "DNS.DNSSEC.idr" - description: "DNSSEC chain of trust from root to zone is valid and signed." - status: "proven" - ci_cd: "verify-dnssec-weekly" - - name: "network_transport_safety" - file: "Cloudflare.Network.idr" - description: "HTTP/3 + 0-RTT replay protection + Onion routing correctly configured." - status: "proven" - ---- -### [PROOF_METADATA] -compiler: - idris2_version: "0.8.0" - zig_version: "0.15.2" - last_check: "2026-04-17" -axioms: - declared: [] - notes: "No axioms may be added without explicit justification and entry here." -drift_alert: - ci_cd: "rebuild-all-proofs-on-compiler-upgrade" - policy: "any compiler upgrade triggers full proof rebuild + signed attestation of re-check" - ---- -### [AUTOMATION] -hashing: - tool: "GitBot-Fleet" - triggers: ["pre-commit", "post-merge"] - algorithms: ["SHA3-512", "SHAKE256", "BLAKE3"] -diffing: - tool: "GitBot-Fleet" - rules: - - "alert-on-unexpected-changes" - - "require-proof-updates-for-crypto-changes" -integrity: - tool: "Hypatia + Idris2" - checks: - - "zonemd-consistency" - - "transparency-log-continuity" - - "idris2-proof-validity" - ---- -### [CAPABILITY_GATEWAY] -rules: - - resource: "/api/data" - policy: "require Ed448+Dilithium5-signed capability token" - proof: "HTTP.Capabilities.Data.idr" - - resource: "/admin" - policy: "require TPM 2.0 + YubiKey device attestation" - proof: "HTTP.Capabilities.Admin.idr" - ---- -### [SAFE_HACKING] -scope: "this-repo-only" -allowed_probe_classes: [] -probes: [] -policy: | - Authorised offensive testing scoped to this repo. Probes listed here - are actively executed during `contractile trust probe`. NEVER touches - external systems. See trust.ncl for schema; this section is the data. -policy_on_unexpected_outcome: "exit-nonzero" -security: - proof: "SafeHacking.Policy.idr" - ---- -### [VULNERABILITY_DISCLOSURE] -policy: | - Responsible disclosure welcomed. Researchers reporting real vulnerabilities - in good faith receive acknowledgement in SECURITY.adoc and in - /.well-known/security-acknowledgments. See security.txt for contact path. -contact: "j.d.a.jewell@open.ac.uk" -recognition: - mechanism: "security-acknowledgments list" - url: "https://github.com/hyperpolymath/boj-server/.well-known/security-acknowledgments" -contractile_ref: "tracked in `contractile trust probe` — see trust.ncl safe_hacking" -security: - proof: "VulnDisclosure.Policy.idr" - ---- -### [SDP_RULES] -services: - - name: "dashboard.internal" - access: - - group: "admins" - policy: "require Ed448+Dilithium5 + device-attestation + cadre-consent" - - group: "bots" - policy: "require JWT (Kyber1024) + IP in CI_NETWORK" - proof: "SDP.Dashboard.idr" - - name: "db.internal" - access: - - group: "apps" - policy: "require mutual TLS (Kyber1024-X25519) + client cert" - proof: "SDP.Database.idr" - ---- -### [TRANSPARENCY_LOG] -rfc9162: - uri: "https://github.com/hyperpolymath/boj-server/log/transparency.json" - entries: - - timestamp: "2026-02-16T00:00:00Z" - data: "BASE64_ENCODED_THIS_FILE" - signature: "BASE64_Ed448+Dilithium5_SIGNATURE" - idris2_proof: "Transparency.Log.idr" - ci_cd: "append-on-push" - ---- -### [SSL/TLS] -ciphers: - - "TLS_AES_256_GCM_SHA384" - - "TLS_CHACHA20_POLY1305_SHA256" -groups: - - "X25519Kyber768Draft00" - - "secp256r1" -protocols: - - "TLSv1.3" -minimum_version: "1.2" -notes: | - TLS 1.3 preferred with post-quantum key exchange (X25519Kyber768). - Minimum version 1.2 enforced at Cloudflare edge for clients that - don't support 1.3 yet. TLS 1.0 and 1.1 are BANNED. Cipher preference - is server-side (Cloudflare-controlled on free plan). -features: - ocspStapling: true - signedCertTimestamps: true - certificateTransparency: - logs: - - "ct.googleapis.com/aviator" - - "ct.googleapis.com/rocketeer" - monitoring: true - notes: "Cloudflare automatically includes SCT in TLS handshake for all proxied zones." - mustStaple: true - opportunistic_encryption: true - automatic_https_rewrites: true - always_use_https: true -edge_certificates: - provider: "Cloudflare Universal SSL" - type: "DV (Domain Validated)" - issuers: ["DigiCert", "Let's Encrypt", "Google Trust Services"] - auto_renewal: true - caa_restriction: true - notes: | - Cloudflare issues Universal SSL certificates automatically for all - proxied zones. CAA records restrict issuance to authorized CAs only. - Origin certificates should use Cloudflare Origin CA (15-year validity) - or publicly trusted certs for Full (Strict) mode. -security: - proof: "TLS.Configuration.idr" - ci_cd: "verify-tls-settings-drift" - ---- -### [CLOUDFLARE] -operator_trust_anchor: | - Cloudflare is an operator-chosen trust anchor for this repo. Its edge - network provides DDoS absorption, TLS termination, and WAF. This is a - single-vendor dependency: compromise or misbehaviour at Cloudflare - affects all proxied traffic. Plan for vendor-compromise scenario - documented in THREAT-MODEL.md §vendor-anchors. -waf: - ruleset: "OWASP_ModSecurity_CRS" - sensitivity: "high" - paranoiaLevel: 4 - managed_rulesets: - - name: "Cloudflare Managed Ruleset" - id: "efb7b8c949ac4650a09736fc376e9aee" - action: "execute" - phase: "http_request_firewall_managed" - - name: "Cloudflare OWASP Core Ruleset" - id: "4814384a9e5d4991b9815dcfc25d2f1f" - action: "execute" - phase: "http_request_firewall_managed" - ddos: - http: - sensitivity: "high" - action: "managed_challenge" - ruleset: "Cloudflare HTTP DDoS Attack Protection" - notes: "Always-on, unmetered DDoS protection on all plans." - security: - proof: "Cloudflare.WAF.idr" - ci_cd: "validate-waf-rulesets" -workers: - - name: "consent-aware-http" - script: "https://github.com/hyperpolymath/boj-server/workers/consent.js" - routes: - - "boj-server/.well-known/consent*" - - name: "capability-gateway" - script: "https://github.com/hyperpolymath/boj-server/workers/cap.js" - routes: - - "boj-server/cap*" - ---- -### [CLOUDFLARE_EDGE_SECURITY] -overview: | - Cloudflare edge security settings applied uniformly across all zones. - These are the maximum free-plan configurations. Settings are enforced - via API and validated by Hypatia CI scans. Any drift triggers an alert. - -ssl_tls: - mode: "strict" - min_tls_version: "1.2" - tls_1_3: "zrt" - always_use_https: true - automatic_https_rewrites: true - opportunistic_encryption: true - hsts: - enabled: true - max_age: 31536000 - include_subdomains: true - preload: true - nosniff: true - universal_ssl: true - certificate_transparency: true - ocsp_stapling: true - notes: | - TLS 1.3 with 0-RTT (zrt). HSTS preloaded at 1 year with subdomains. - SSL mode 'strict' requires valid origin certificate (Cloudflare Origin CA - or publicly trusted). Downgrade to 'full' only if origin has self-signed. - security: - proof: "Cloudflare.SSL.idr" - ci_cd: "verify-ssl-settings-drift" - -bot_defense: - bot_fight_mode: true - block_ai_bots: true - ai_labyrinth: true - ai_crawl_control: - default_action: "block" - notes: | - Block all known AI crawlers by default. AI Labyrinth traps persistent - scrapers in an infinite maze of AI-generated decoy content, wasting - their compute while protecting real content. Individual crawlers can - be allowed via per-crawler overrides if licensing agreements exist. - managed_robots_txt: true - javascript_detections: false - notes: | - JS detections require Super Bot Fight Mode (Pro+). On free plan, - Bot Fight Mode uses pattern matching only. AI Labyrinth is the - primary free-plan defense against sophisticated AI scraping. - security: - proof: "Cloudflare.Bots.idr" - ci_cd: "verify-bot-settings" - -scrape_shield: - email_obfuscation: true - hotlink_protection: true - server_side_excludes: true - notes: | - Email obfuscation rewrites email addresses in HTML to prevent - harvesting by scrapers. Hotlink protection prevents other sites - from embedding your images. Server-side excludes hide content - from suspicious visitors. - security: - proof: "Cloudflare.ScrapeShield.idr" - -browser_integrity: - browser_check: true - security_level: "medium" - challenge_ttl: 1800 - notes: | - Browser Integrity Check evaluates HTTP headers for common - characteristics of abusive traffic. Security level 'medium' - challenges visitors from IPs with moderate threat scores. - Challenge TTL of 30 minutes before re-challenge. - security: - proof: "Cloudflare.BrowserIntegrity.idr" - -page_shield: - enabled: true - script_monitoring: true - notes: | - Page Shield monitors client-side JavaScript resources loaded by - your pages. Free tier provides script detection and alerts for - new/changed scripts. Paid tiers add malicious script detection. - security: - proof: "Cloudflare.PageShield.idr" - ci_cd: "review-new-scripts" - -security_txt: - enabled: true - contact: "mailto:j.d.a.jewell@open.ac.uk" - preferred_languages: "en" - expires: "2027-03-02T00:00:00Z" - policy: "https://github.com/hyperpolymath/boj-server/.well-known/security-policy" - acknowledgments: "https://github.com/hyperpolymath/boj-server/.well-known/security-acknowledgments" - encryption: "https://github.com/hyperpolymath/boj-server/.well-known/pgp-key.txt" - canonical: "https://github.com/hyperpolymath/boj-server/.well-known/security.txt" - notes: | - RFC 9116 compliant. Served by Cloudflare at /.well-known/security.txt. - Contact is the author's university email. Expiry set to 1 year from - deployment, auto-renewed by CI. Canonical URL prevents spoofing. - security: - proof: "Cloudflare.SecurityTxt.idr" - ci_cd: "renew-security-txt-before-expiry" - -rate_limiting: - architecture: "four-tier" - tier_1_edge: - provider: "Cloudflare" - mechanisms: ["Anycast absorption", "DDoS Managed Ruleset", "per-zone rate rules"] - tier_2_gateway: - provider: "http-capability-gateway / svalinn" - mechanisms: ["per-IP token-bucket sliding window", "per-capability-token", "per-endpoint"] - status: "PENDING — http-capability-gateway wiring forthcoming" - tier_3_beam: - provider: "Elixir supervisor" - mechanisms: ["per-cartridge-invocation budget", "mailbox back-pressure"] - tier_4_cartridge: - provider: "cartridge-declared" - mechanisms: ["Nickel manifest declares per-cartridge limits"] - cross_tier: - - "RFC 9530 rate-limit headers (RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset)" - - "429 + Retry-After on limit hit" - - "Turnstile challenge on high-value endpoints" - - "HMAC request signing for API clients" - - "per-cartridge circuit breakers with exponential backoff" - - "shadow-ban for persistent offenders" - cost_ceiling: - policy: "operator-managed emergency brake above tier 1" - note: "operator-managed; emergency brake above edge-tier rate limits; specific cap TBD" - security: - proof: "RateLimiting.Policy.idr" - ---- -### [RESPONSE_HEADERS] -overview: | - Security response headers applied at the Cloudflare edge via Managed - Transforms and custom response header modification rules. These headers - instruct browsers to enforce security policies regardless of origin config. - -managed_transforms: - add: - - "X-Content-Type-Options: nosniff" - - "X-Frame-Options: SAMEORIGIN" - - "Referrer-Policy: strict-origin-when-cross-origin" - remove: - - "Server" - - "X-Powered-By" - notes: "Managed Transforms are Cloudflare's built-in header rules. Zero config." - -custom_headers: - - name: "Permissions-Policy" - value: "camera=(), microphone=(), geolocation=(), payment=()" - notes: "Deny all sensitive browser APIs unless explicitly needed." - - name: "Content-Security-Policy" - value: "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; frame-ancestors 'self'; base-uri 'self'; form-action 'self'" - notes: "Strict CSP baseline. Override per-project if needed (e.g., for CDN scripts)." - - name: "Cross-Origin-Opener-Policy" - value: "same-origin" - - name: "Cross-Origin-Embedder-Policy" - value: "require-corp" - - name: "Cross-Origin-Resource-Policy" - value: "same-origin" - -policy: | - All security headers are enforced at the edge. Origin servers SHOULD - also set these headers as defense-in-depth. Headers set at edge take - precedence when Managed Transforms are enabled. CSP violations are - reported to /csp-report endpoint if a report-uri directive is added. - -security: - proof: "Cloudflare.ResponseHeaders.idr" - ci_cd: "validate-response-headers" - ---- -### [NETWORK] -overview: | - Network-level settings applied at the Cloudflare edge. - These affect how traffic is transported between clients and edge. - -http2: true -http3: true -quic: true -zero_rtt: true -websockets: true -onion_routing: true -ipv6_posture: - origin: "IPv6-only (strict)" - edge: "dual-stack (Cloudflare translates IPv4 clients to IPv6-only origins)" - internal_comms: "IPv6-only between BoJ instances" - policy: "Declared 2026-04-17. IPv4 clients reach BoJ only via Cloudflare edge translation; origin never listens on IPv4." -brotli: true - -zero_rtt_policy: | - 0-RTT Connection Resumption is enabled for performance. Note: 0-RTT - data is vulnerable to replay attacks. Cloudflare mitigates this by - only allowing 0-RTT on idempotent requests (GET/HEAD). Non-idempotent - requests (POST/PUT/DELETE) always use full handshake. Applications - MUST NOT rely on 0-RTT for state-changing operations. - -onion_routing_policy: | - Tor/Onion routing enabled via Cloudflare's Opportunistic Onion - (Alt-Svc header advertising .onion endpoint). This allows Tor users - to access sites without exit node MITM risk. Does NOT create a - dedicated .onion address — uses Cloudflare's shared onion service. - -security: - proof: "Cloudflare.Network.idr" - ci_cd: "verify-network-settings" - ---- -### [ORIGIN_PROTECTION] -hidden_primary: - public_dns: "no A/AAAA records resolving directly to origin" - public_endpoint: "Cloudflare Tunnel only" - authenticated_origin_pulls: - enabled: true - mtls_ca: "Cloudflare Origin CA" - policy: "origin rejects all non-CF traffic at TCP layer" - admin_endpoints: - mechanism: "Cloudflare Access (zero-trust)" - public_endpoint: "none" - backup_origin: - mechanism: "second Cloudflare Tunnel, passive failover" - leak_checks: - - "verify no historic origin IP exposure in securitytrails.com" - - "verify no origin IP in HTTP error messages" - - "verify no origin IP in DNS MX/TXT records" -security: - proof: "OriginProtection.Policy.idr" - ci_cd: "verify-origin-hidden-weekly" - ---- -### [PERFORMANCE] -overview: | - Performance settings that have security implications. - Applied at the Cloudflare edge for all zones. - -early_hints: true -speed_brain: true -auto_minify: - javascript: true - css: true - html: true -rocket_loader: false -notes: | - Rocket Loader disabled by default — it rewrites JavaScript loading - order which can break SPAs and CSP policies. Enable per-project only - after testing. Speed Brain uses Speculation Rules API to prefetch - likely navigation targets (conservative eagerness only). - -caching: - browser_ttl: "respect-origin" - edge_ttl: "default" - always_online: true - notes: | - Always Online serves stale cached copies when origin is unreachable. - Browser TTL respects origin Cache-Control headers. Do not cache - authenticated content — use Cache-Control: private on origin. - -security: - proof: "Cloudflare.Performance.idr" - ---- -### [PHP_HARDENING] -aegis: - enabled: true - rules: - - "disable_functions=exec,popen,shell_exec,system" - - "expose_php=0" - - "session.cookie_httponly=1" - - "session.cookie_secure=1" -sanctify: - enabled: true - directives: - - "sanctify.globals=1" - - "sanctify.request=1" - - "sanctify.error_reporting=E_ALL" - ---- -### [CONTAINER_SUPPLY_CHAIN] -overview: | - Container supply-chain verification via the stapeln ecosystem. - All container images are built with Podman on Chainguard Wolfi base - images, signed as .ctp bundles via cerro-torre, and governed by - svalinn edge gateway policies. Runtime monitoring provided by vordr. - -runtime: - engine: "Podman" - policy: "Rootless containers only. Never Docker." - socket: "${XDG_RUNTIME_DIR}/podman/podman.sock" - security: - proof: "Container.Runtime.idr" - -base_images: - provider: "Chainguard" - registry: "cgr.dev/chainguard/" - allowed: - - "cgr.dev/chainguard/wolfi-base:latest" - - "cgr.dev/chainguard/static:latest" - policy: "Only Chainguard images permitted as base. Rebuilt daily, CVE-free." - security: - proof: "Container.BaseImages.idr" - ci_cd: "scan-base-images-daily" - -verified_bundles: - format: ".ctp" - tool: "cerro-torre" - operations: - pack: "ct pack -o " - sign: "cerro-sign sign --key-id " - verify: "ct verify " - push: "ct push " - explain: "ct explain " - attestations: - required: ["source-signature", "sbom-complete"] - recommended: ["security-audit", "reproducible-build"] - security: - proof: "Container.Bundles.idr" - hypatia: "scan-ctp-bundles" - -gateway: - tool: "svalinn" - policy_file: "container/.gatekeeper.yaml" - capabilities: - - "JWT/OAuth2 authentication" - - "Rate limiting (per-client, per-endpoint)" - - "Container trust enforcement (.ctp signature verification)" - - "Request validation (body size, NaN/Inf rejection)" - - "CORS policy enforcement" - - "Audit logging for write operations" - - "TLS auto-provisioning" - security: - proof: "Container.Gateway.idr" - ci_cd: "validate-gatekeeper-policy-on-push" - -monitoring: - tool: "vordr" - config_file: "container/vordr.toml" - capabilities: - - "Health endpoint monitoring" - - "Container crash detection" - - "Resource usage thresholds (CPU, memory, disk)" - - "Structured JSON log output" - - "Automatic restart on failure (configurable)" - security: - proof: "Container.Monitoring.idr" - -signing: - algorithm: "Ed25519" - tool: "cerro-torre sign / cerro-sign" - key_management: | - Signing keys are project-specific. Each service has a dedicated - Ed25519 key pair (e.g. -release). Public keys are - distributed in .gatekeeper.yaml trusted_signers section. - security: - proof: "Container.Signing.idr" - ci_cd: "rotate-signing-keys-on-compromise" - -deployment: - tool: "k9-svc" - spec_file: "container/deploy.k9.ncl" - trust_level: "Hunt" - description: | - k9-svc deployment components at Hunt trust level. Full pedigree - (L1-L5: identity, target, security, validation, recipes). - Requires cryptographic handshake before execution. Supports - dev/staging/production environments with rolling deployment. - security: - proof: "Container.Deployment.idr" - ci_cd: "validate-k9-pedigree-on-push" - ---- -### [SUPPLY_CHAIN_DEPS] -overview: | - Source-library supply chain. Chainguard covers base images; - this section tracks language-level deps. -zig: - mechanism: "build.zig.zon with SHA256 hashes" - adoption_status: "ADOPTED where Zig is used" -idris2: - mechanism: ".ipkg with dep version pinning" - adoption_status: "PENDING — estate-wide pinning in CRG contractile" -proven_library: - hash_attestation: "2acda528b5cea54bff3a8353298579c5b31fdf238c56879ce34f2e2365fdbd79" - source: "verification-ecosystem/proven" - verification: "libproven_ffi.a rebuilt on source change; downstream relink verified" -crg_contractile: "tracked under CRG grade requirements — see CRG-SELF-ASSESSMENT.adoc" -security: - proof: "SupplyChain.Deps.idr" - ---- -### [HTTP_CAPABILITY_GATEWAY] -status: "ACCEPTED-PLANNED" -repo: "web-ecosystem/http-capability-gateway" -when: "optional frontend, not yet wired — wiring planned over 8-12 weeks" -pipeline_state: "loader + validator + compiler + gateway + proxy + telemetry all implemented" -gaps: "security depth (mTLS primary path not proved), end-to-end verification, benchmark formalisation" -eta: "~8-12 weeks to BoJ-production-grade (Phase A-E, see plan)" -wire_on_land: "tier_2_gateway of rate_limiting architecture and capability_gateway section" -audit: "docs/integration/http-capability-gateway-audit.md" -plan: "docs/integration/http-capability-gateway-plan.md" -adr: "docs/decisions/0004-adopt-http-capability-gateway.md" -scoped_date: "2026-04-17" - ---- -### [PLACEHOLDER_TRACKING] -overview: | - Every {{PLACEHOLDER}} in this file must resolve to a live value before - the Trustfile is considered deployed. CI enforces no-placeholder-state - on main branch. -resolution_policy: "CI check fails on any remaining {{...}} in main" -ci_cd: "enforce-no-placeholders-on-main" - ---- -### [SIGNATURE_BLOCK] -primary: - algorithm: "Ed448+Dilithium5" - signature: | - -----BEGIN HYBRID SIGNATURE----- - BASE64_Ed448+Dilithium5_SIGNATURE_OF_THIS_FILE - -----END HYBRID SIGNATURE----- - signedBy: "did:web:github.com:hyperpolymath:boj-server#primary-sig" - idris2_proof: "Signature.Primary.idr" -fallback: - algorithm: "SPHINCS+" - signature: | - -----BEGIN SPHINCS+ SIGNATURE----- - BASE64_SPHINCS+_SIGNATURE_OF_THIS_FILE - -----END SPHINCS+ SIGNATURE----- - idris2_proof: "Signature.Fallback.idr" - ---- -### [DEPLOYMENT] -1. Replace all `BASE64_*`, `HEX_*`, and `DID_WEB_ID` placeholders. -2. Generate Idris2 proofs: - ```bash - idris2 --build trust.ipkg diff --git a/.machine_readable/contractiles/trust/trust.ncl b/.machine_readable/contractiles/trust/trust.ncl index f86cede2..d8c82c13 100644 --- a/.machine_readable/contractiles/trust/trust.ncl +++ b/.machine_readable/contractiles/trust/trust.ncl @@ -1,7 +1,9 @@ # SPDX-License-Identifier: MPL-2.0 # trust.ncl — trust boundary verification runner for boj-server # -# Pairs with: Trustfile.a2ml (same directory) +# Pairs with: Trustfile.deed (same directory; A7 8.1). Not yet written: the +# legacy Trustfile.a2ml was retired 2026-11-14 with no mapping +# spec to translate it (docs/history/A2ML-REMOVED.adoc). # Verb: trust # Semantics: verify provenance, integrity, and trust-boundary invariants. # Runner evaluates the declared trust checks (licence present, @@ -27,7 +29,7 @@ name = "trust-runner", version = "1.0.0", description = "Evaluates trust-boundary invariants: provenance, integrity, secrets hygiene, signature checks. Hard-gates on critical failures.", - paired_xfile = "Trustfile.a2ml", + paired_xfile = "Trustfile.deed", author = "Jonathan D.A. Jewell ", }, }, diff --git a/.machine_readable/dev-toolchain.a2ml b/.machine_readable/dev-toolchain.a2ml deleted file mode 100644 index df06945d..00000000 --- a/.machine_readable/dev-toolchain.a2ml +++ /dev/null @@ -1,49 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -# -# BoJ Server — Permanent Dev-Toolchain Manifest -# -# Single source of truth for the standing local dev loop so it NEVER has to be -# re-assembled per session. Paths are the canonical /dev/tools toolchain and -# are verified-present (do not list a tool that is not actually installed — -# an unresolved entry is worse than none). -# -# Wired NOW: the LSP row is live via `cartridges/lsp-mcp/presets.json` -# (lsp_start {"preset":"rust"} → rust-analyzer, no per-use wiring). -# Adoption path: bsp-mcp (build), dap-mcp (debug) and a lint surface should -# read this same manifest for their Rust/Zig/Julia/Idris presets — same -# pattern as lsp-mcp. Declared here so the contract exists before the wiring. - -@canonical-location: `.machine_readable/dev-toolchain.a2ml` - -[authorization] -standing = true -note = "Owner standing authorization (2026-05-18): use these boj dev-loop capabilities on demand without asking for permission." - -[rust] -lsp = "/home/hyperpolymath/dev/tools/languages/rust/cargo-home/bin/rust-analyzer" # verified: rust-analyzer 1.95.0 (rustup component) -cargo = "/home/hyperpolymath/dev/tools/languages/rust/cargo-home/bin/cargo" # verified: cargo 1.95.0 -build = "cargo build" -check = "cargo check" -lint = "cargo clippy --all-targets -- -D warnings" -test = "cargo test" -debug = "rust-gdb / lldb via dap-mcp" # dap-mcp adoption pending -env = { CARGO_HOME = "/home/hyperpolymath/dev/tools/languages/rust/cargo-home", RUSTUP_HOME = "/home/hyperpolymath/dev/tools/languages/rust/rustup-home" } -wired_lsp = true # cartridges/lsp-mcp/presets.json -> preset "rust" - -[zig] -toolchain = "zig 0.15.2" # verified on PATH -build = "zig build" -test = "zig build test" -wired_lsp = false # zls not installed; do NOT add an lsp preset until it is - -[julia] -launcher = "/home/hyperpolymath/dev/tools/languages/julia/juliaup-home/bin/julia" # verified: 1.12.6 (release) / 1.10.11 (lts) -test = "julia --project=. -e 'using Pkg; Pkg.test()'" -instantiate= "julia --project=. -e 'using Pkg; Pkg.instantiate()'" -quality = "Aqua.test_all + JET (when wired in a package's test deps)" -wired_lsp = false # no julia LSP installed yet - -[idris2] -check = "/home/hyperpolymath/dev/tools/provers/idris2/0.8.0/bin/idris2 --check" # verified: Idris2 0.8.0 -wired_lsp = false # idris2-lsp not installed yet diff --git a/.machine_readable/integrations/feedback-o-tron.a2ml b/.machine_readable/integrations/feedback-o-tron.a2ml deleted file mode 100644 index 6841c69b..00000000 --- a/.machine_readable/integrations/feedback-o-tron.a2ml +++ /dev/null @@ -1,21 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Feedback-o-Tron Integration — Autonomous Bug Reporting - -[integration] -name = "feedback-o-tron" -type = "bug-reporter" -repository = "https://github.com/hyperpolymath/feedback-o-tron" -cartridge = "bug-filing-mcp" - -[intake] -transport = "http" -endpoint = "http://127.0.0.1:7722" -enable-with = "FEEDBACK_A_TRON_HTTP=1" -tools = ["research_feedback", "synthesize_feedback", "submit_feedback"] - -[reporting-config] -platforms = ["github", "gitlab", "bugzilla"] -deduplication = true -audit-logging = true -template-validation = "fail-closed" -auto-file-upstream = "on-external-dependency-failure" diff --git a/.machine_readable/integrations/proven.a2ml b/.machine_readable/integrations/proven.a2ml deleted file mode 100644 index 9af33ffd..00000000 --- a/.machine_readable/integrations/proven.a2ml +++ /dev/null @@ -1,18 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Proven Integration — Formally Verified Safety Library - -[integration] -name = "proven" -type = "safety-library" -repository = "https://github.com/hyperpolymath/proven" -version = "1.2.0" - -[binding-policy] -approach = "thin-ffi-wrapper" -unsafe-patterns = "replace-with-proven-equivalent" -modules-available = ["SafeMath", "SafeString", "SafeJSON", "SafeURL", "SafeRegex", "SafeSQL", "SafeFile", "SafeTemplate", "SafeCrypto"] - -[adoption-guidance] -priority = "high" -scope = "all-string-json-url-crypto-operations" -migration = "incremental — replace unsafe patterns as encountered" diff --git a/.machine_readable/integrations/verisimdb.a2ml b/.machine_readable/integrations/verisimdb.a2ml deleted file mode 100644 index 164c5229..00000000 --- a/.machine_readable/integrations/verisimdb.a2ml +++ /dev/null @@ -1,15 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# VeriSimDB Feed — Cross-Repo Analytics Data Store - -[integration] -name = "verisimdb" -type = "data-feed" -repository = "https://github.com/hyperpolymath/nextgen-databases" -data-store = "verisimdb-data" - -[feed-config] -emit-scan-results = true -emit-build-metrics = true -emit-dependency-graph = true -format = "hexad" -destination = "verisimdb-data/feeds/" diff --git a/.machine_readable/integrations/vexometer.a2ml b/.machine_readable/integrations/vexometer.a2ml deleted file mode 100644 index 238b3d2c..00000000 --- a/.machine_readable/integrations/vexometer.a2ml +++ /dev/null @@ -1,18 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Vexometer Integration — Irritation Surface Analysis - -[integration] -name = "vexometer" -type = "friction-measurement" -repository = "https://github.com/hyperpolymath/vexometer" - -[measurement-config] -dimensions = 10 -emit-isa-reports = true -lazy-eliminator = true -satellite-interventions = true - -[hooks] -cli-tools = "measure-on-error" -ui-panels = "measure-on-interaction" -build-failures = "measure-on-failure" diff --git a/.machine_readable/policies/MAINTENANCE-AXES.a2ml b/.machine_readable/policies/MAINTENANCE-AXES.a2ml deleted file mode 100644 index 2428ef74..00000000 --- a/.machine_readable/policies/MAINTENANCE-AXES.a2ml +++ /dev/null @@ -1,54 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -# -# Canonical maintenance governance model - -[metadata] -version = "1.0.0" -last-updated = "2026-03-02" -scope = "repo" - -[discovery] -human-entrypoints = [ - "README.adoc", - "docs/maintenance/MAINTENANCE-CHECKLIST.md", - "docs/practice/SOFTWARE-DEVELOPMENT-APPROACH.adoc", -] -machine-entrypoints = [ - ".machine_readable/policies/MAINTENANCE-AXES.a2ml", - ".machine_readable/policies/MAINTENANCE-CHECKLIST.a2ml", - ".machine_readable/policies/SOFTWARE-DEVELOPMENT-APPROACH.a2ml", - ".machine_readable/META.a2ml", - ".machine_readable/ai/README.adoc", - ".machine_readable/bot_directives/README.scm", -] -bots = ["hypatia", "gitbot-fleet", "repo visitors"] - -[axes] -axis-1 = "must > intend > like" -axis-2 = "corrective > adaptive > perfective" -axis-3 = "systems > compliance > effects" -execution-order = "axis-1 > axis-2 > axis-3" - -[axis-1-scoping] -required = true -sources = "README, roadmap, status docs, maintenance checklist, CI/security docs" -markers = "TODO/FIXME/XXX/HACK/STUB/PARTIAL" -idris-unsound-markers = "believe_me/assert_total" -output = "scoped work assembly in must/intend/like buckets" - -[axis-2-maintenance] -corrective-first = true -adaptive-second = true -adaptive-focus = "scope changes, stale references, obsolete work culling" -perfective-third = true -perfective-source = "honest state from axis-1 after corrective/adaptive updates" - -[axis-3-audit] -systems-check = true -compliance-check = true -effects-check = true -compliance-focus = "seams/compromises/exception register and anti-drift" -compliance-tooling = "panic-attack" -effects-tooling = "ecological checking with sustainabot guidance" -effects-evidence = "benchmark evidence and maintainer dialogue/status review" diff --git a/.machine_readable/policies/MAINTENANCE-CHECKLIST.a2ml b/.machine_readable/policies/MAINTENANCE-CHECKLIST.a2ml deleted file mode 100644 index 0e065e94..00000000 --- a/.machine_readable/policies/MAINTENANCE-CHECKLIST.a2ml +++ /dev/null @@ -1,159 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Cross-repo maintenance baseline (machine-readable canonical) - -[metadata] -version = "1.1.0" -last-updated = "2026-02-24" -scope = "cross-repo" -source-human = "docs/maintenance/MAINTENANCE-CHECKLIST.md" -companion-human = "docs/practice/SOFTWARE-DEVELOPMENT-APPROACH.adoc" -companion-machine = ".machine_readable/policies/SOFTWARE-DEVELOPMENT-APPROACH.a2ml" - -[policy] -single-source = true -notes = "Use this file as canonical machine policy and keep markdown synchronized." - -[maintenance-axes] -scoping-first = true -execution-order = ["scoping", "axis-1", "axis-2", "axis-3"] -axis-1 = "must > intend > like" -axis-2 = "corrective > adaptive > perfective" -axis-3 = "systems > compliance > effects" - -[scoping] -inputs_required = [ - "README", - "roadmap", - "status-docs", - "maintenance-checklist", - "ci-and-security-docs", -] - -marker_scan_required = [ - "TODO", - "FIXME", - "XXX", - "HACK", - "STUB", - "PARTIAL", -] - -idris_unsound_scan_required = [ - "believe_me", - "assert_total", -] - -scope_assembly_buckets = ["must", "intend", "like"] - -[axis-2-maintenance-rules] -corrective-first = true -adaptive-second = true -adaptive_examples = [ - "scope-change reconciliation", - "stale-reference removal", - "obsolete-work culling", -] -perfective-third = true -perfective_source = "axis-1 honest state after corrective/adaptive updates" - -[axis-3-audit-rules] -systems-check = true -documentation-honesty-check = true -safety-security-accounted-check = true -effects-review-check = true -benchmark-evidence-required = true -maintainer-dialogue-review-required = true -compliance-seams-check = true -exception-register-required = true -exception-bounded-scope-required = true -policy-drift-contamination-check = true -example-drift-risk = "single TypeScript exception causing broad AffineScript->TypeScript migration" -compliance-tooling = "panic-attack" -effects-tooling = "ecological checking with sustainabot guidance" - -[generic-cleanup-finish-off] -root-cleanup-required = true -stale-work-cull-required = true -docs-parity-required = true -machine-human-sync-required = true -compliance-finish-off-required = true -effects-finish-off-required = true -release-prep-summary-required = true -next-actions-required = ["corrective", "adaptive", "perfective"] - -[must] -root_control_files = [ - ".gitignore", - ".gitattributes", - ".editorconfig", - ".tool-versions", - "Containerfile", - "Justfile", -] - -root_hosting_files = [ - "CNAME", - ".nojekyll", -] - -ownership_files = [ - "MAINTAINER", - ".github/CODEOWNERS", -] - -machine_readable_required = [ - ".machine_readable/anchors/ANCHOR.a2ml", - ".machine_readable/contractiles/", - ".machine_readable/ai/", - ".machine_readable/bot_directives/", -] - -contractiles_required = [ - "Mustfile", - "Trustfile", - "Intentfile", -] - -security_required = [ - ".well-known/security.txt", - "ci-security-scan", -] - -quality_gate_required = [ - "format", - "lint", - "unit-tests", - "integration-tests", - "p2p-tests", - "e2e-tests", - "bench-smoke", - "docs-check", - "security-scan", -] - -abi_ffi_policy = [ - "ABI Idris2 in src/abi/*.idr", - "FFI Zig in ffi/**/*.zig", -] - -[should] -docs_primary_format = "adoc" -docs_structure = [ - "docs/theory", - "docs/practice", - "docs/whitepapers/academic", - "docs/whitepapers/industry", - "docs/proofs", - "docs/reports", -] - -root_minimization = true -well_known_metadata = true -roadmap_honesty_with_dates = true -ci_doc_format_policy = true - -[could] -generate_human_from_machine = true -mode_aware_bots = ["corrective", "adaptive", "perfective", "audit"] -topology_dashboard = true -exception_registry = true diff --git a/.machine_readable/policies/SOFTWARE-DEVELOPMENT-APPROACH.a2ml b/.machine_readable/policies/SOFTWARE-DEVELOPMENT-APPROACH.a2ml deleted file mode 100644 index 093573a0..00000000 --- a/.machine_readable/policies/SOFTWARE-DEVELOPMENT-APPROACH.a2ml +++ /dev/null @@ -1,53 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# General software development approach (machine-readable) - -[metadata] -version = "1.0.0" -last-updated = "2026-02-24" -scope = "cross-repo" -source-human = "docs/practice/SOFTWARE-DEVELOPMENT-APPROACH.adoc" - -[execution] -order = ["axis-1", "axis-2", "axis-3"] - -[axis-1] -name = "scope" -priority = "must > intend > like" -inputs = [ - "README", - "roadmap", - "status-docs", - "ci-and-security-docs", -] -marker-scan = ["TODO", "FIXME", "XXX", "HACK", "STUB", "PARTIAL"] -idris-unsound-scan = ["believe_me", "assert_total"] -output = "scoped-work-assembly" - -[axis-2] -name = "maintenance" -priority = "corrective > adaptive > perfective" -corrective = "defect/regression/safety/security fixes" -adaptive = "scope reconciliation, stale-reference removal, obsolete-work culling" -perfective = "quality improvements derived from axis-1 honest state" - -[axis-3] -name = "audit" -priority = "systems > compliance > effects" -systems = "required systems present and operating" -compliance = "exceptions explicit, bounded, and drift-resistant" -effects = "benchmark/operational impact evidence captured and reviewed" -compliance-tooling = "panic-attack" -effects-tooling = "ecological checking with sustainabot guidance" - -[cleanup-finish-off] -root-cleanup = true -stale-work-cull = true -docs-sync-human-machine = true -compliance-audit = true -effects-audit = true -release-summary = ["must", "should", "could"] -next-actions = ["corrective", "adaptive", "perfective"] - -[collaboration] -maintainer-dialogue-required = true -dialogue-topics = ["what changed", "why", "remaining risks"] diff --git a/.machine_readable/scripts/0.2-AI-MANIFEST.a2ml b/.machine_readable/scripts/0.2-AI-MANIFEST.a2ml deleted file mode 100644 index 615df84f..00000000 --- a/.machine_readable/scripts/0.2-AI-MANIFEST.a2ml +++ /dev/null @@ -1,18 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "automation-scripts-unit" -level: 2 -parent: "../0.1-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Internal automation logic for the project lifecycle, forge sync, - verification triggers, and maintenance. - -canonical_locations: - maintenance: "maintenance/" - lifecycle: "lifecycle/" - forge: "forge/" - verification: "verification/" diff --git a/.machine_readable/scripts/forge/0.3-AI-MANIFEST.a2ml b/.machine_readable/scripts/forge/0.3-AI-MANIFEST.a2ml deleted file mode 100644 index 4bbd6cf3..00000000 --- a/.machine_readable/scripts/forge/0.3-AI-MANIFEST.a2ml +++ /dev/null @@ -1,11 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "automation-unit-forge" -level: 3 -parent: "../0.2-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Internal automation logic for project forge. diff --git a/.machine_readable/scripts/lifecycle/0.3-AI-MANIFEST.a2ml b/.machine_readable/scripts/lifecycle/0.3-AI-MANIFEST.a2ml deleted file mode 100644 index 3182d175..00000000 --- a/.machine_readable/scripts/lifecycle/0.3-AI-MANIFEST.a2ml +++ /dev/null @@ -1,11 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "automation-unit-lifecycle" -level: 3 -parent: "../0.2-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Internal automation logic for project lifecycle. diff --git a/.machine_readable/scripts/verification/0.3-AI-MANIFEST.a2ml b/.machine_readable/scripts/verification/0.3-AI-MANIFEST.a2ml deleted file mode 100644 index 460e0694..00000000 --- a/.machine_readable/scripts/verification/0.3-AI-MANIFEST.a2ml +++ /dev/null @@ -1,11 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "automation-unit-verification" -level: 3 -parent: "../0.2-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Internal automation logic for project verification. diff --git a/.machine_readable/servers/menu.a2ml b/.machine_readable/servers/menu.a2ml deleted file mode 100644 index 10602cc9..00000000 --- a/.machine_readable/servers/menu.a2ml +++ /dev/null @@ -1,664 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -# -# BoJ Server: The Teranga Menu -# -# This menu is the public face of the Bundle of Joy server. -# AI agents act as the "Maitre D'" — presenting available capabilities -# to users as honoured guests (Teranga = hospitality in Wolof). -# -# The menu is organised into three tiers: -# - Teranga: Core cartridges maintained by the project -# - Shield: Privacy and security cartridges -# - Ayo: Community-contributed cartridges (joy) - -@canonical-location: `.machine_readable/servers/menu.a2ml` -@generated-from: `src/abi/Catalogue.idr` (IsUnbreakable proof required for Ready status) - -# ═══════════════════════════════════════════════════════════════════════════ -# The 2D Capability Matrix -# ═══════════════════════════════════════════════════════════════════════════ -# -# MCP LSP DAP BSP NeSy Agent Fleet gRPC REST -# ┌──────┬──────┬──────┬──────┬──────┬──────┬──────┬──────┬──────┐ -# Database │ ██ │ │ │ │ │ │ │ ██ │ ██ │ -# Fleet │ ██ │ │ │ │ │ │ ██ │ │ ██ │ -# NeSy │ ██ │ │ │ │ ██ │ │ │ │ ██ │ -# Agent │ ██ │ │ │ │ │ ██ │ │ ██ │ ██ │ -# Cloud │ ██ │ │ │ │ │ │ │ ██ │ ██ │ -# Container │ ██ │ │ │ │ │ │ │ ██ │ ██ │ -# K8s │ ██ │ │ │ │ │ │ │ ██ │ ██ │ -# Git │ ██ │ │ │ │ │ │ │ ██ │ ██ │ -# Secrets │ ██ │ │ │ │ │ │ │ ██ │ ██ │ -# Queues │ ██ │ │ │ │ │ │ │ ██ │ ██ │ -# IaC │ ██ │ │ │ │ │ │ │ ██ │ ██ │ -# Observe │ ██ │ │ │ │ │ │ │ ██ │ ██ │ -# SSG │ ██ │ │ │ │ │ │ │ ██ │ ██ │ -# Proof │ ██ │ │ │ │ │ │ │ ██ │ ██ │ -# LSP │ ██ │ ██ │ │ │ │ │ │ ██ │ ██ │ -# DAP │ ██ │ │ ██ │ │ │ │ │ ██ │ ██ │ -# BSP │ ██ │ │ │ ██ │ │ │ │ ██ │ ██ │ -# └──────┴──────┴──────┴──────┴──────┴──────┴──────┴──────┴──────┘ -# -# ██ = ABI + FFI + Adapter complete (17 cartridges, Grade D Alpha) - -# ═══════════════════════════════════════════════════════════════════════════ -# Teranga Selection (Core) -# ═══════════════════════════════════════════════════════════════════════════ -# -# These cartridges are maintained by the hyperpolymath project. -# Each has passed or is working towards the IsUnbreakable proof. - -@section(id="teranga", label="The Teranga Selection"): - -@cartridge(id="database-mcp"): - name = "database-mcp" - version = "0.1.0" - status = Development - tier = Teranga - domain = Database - protocols = [MCP, LSP] - hash = "" - depends-on = ["proven-mcp", "proven-dbconn"] - notes = "Database operations via MCP and LSP. Imports proven-servers dbconn connector." -@end - -@cartridge(id="fleet-mcp"): - name = "fleet-mcp" - version = "0.1.0" - status = Development - tier = Teranga - domain = Fleet - protocols = [MCP, Fleet, GRPC] - hash = "" - depends-on = ["proven-mcp", "gitbot-fleet"] - notes = "Gitbot fleet orchestration. 6-bot gate policy (Rhodibot, Echidnabot, Sustainabot, Panicbot, Glambot, Seambot)." -@end - -@cartridge(id="nesy-mcp"): - name = "nesy-mcp" - version = "0.2.0" - status = Development - tier = Teranga - domain = NeSy - protocols = [MCP, NeSy, GRPC, REST] - hash = "" - depends-on = ["proven-mcp", "proven-neurosym"] - notes = "Neurosymbolic reasoning. Harmonization law: Symbolic truth always overrides Neural probability." -@end - -@cartridge(id="agent-mcp"): - name = "agent-mcp" - version = "0.2.0" - status = Development - tier = Teranga - domain = Agent - protocols = [MCP, Agentic, GRPC, REST] - hash = "" - depends-on = ["proven-mcp", "proven-agentic"] - notes = "AI agent lifecycle management. OODA loop, tool invocation, autonomy boundaries." -@end - -@cartridge(id="cloud-mcp"): - name = "cloud-mcp" - version = "0.1.0" - status = Development - tier = Teranga - domain = Cloud - protocols = [MCP, GRPC, REST] - hash = "" - depends-on = [] - notes = "Cloud resource provisioning — multi-provider infrastructure management." -@end - -@cartridge(id="container-mcp"): - name = "container-mcp" - version = "0.1.0" - status = Development - tier = Teranga - domain = Container - protocols = [MCP, GRPC, REST] - hash = "" - depends-on = ["stapeln"] - notes = "Container lifecycle management via Stapeln-compatible supply chains." -@end - -@cartridge(id="k8s-mcp"): - name = "k8s-mcp" - version = "0.1.0" - status = Development - tier = Teranga - domain = K8s - protocols = [MCP, GRPC, REST] - hash = "" - depends-on = [] - notes = "Kubernetes cluster orchestration — pods, services, deployments." -@end - -@cartridge(id="git-mcp"): - name = "git-mcp" - version = "0.1.0" - status = Development - tier = Teranga - domain = Git - protocols = [MCP, GRPC, REST] - hash = "" - depends-on = ["gitbot-fleet"] - notes = "Git/VCS operations — repository management, forge integrations." -@end - -@cartridge(id="secrets-mcp"): - name = "secrets-mcp" - version = "0.1.0" - status = Development - tier = Teranga - domain = Secrets - protocols = [MCP, GRPC, REST] - hash = "" - depends-on = [] - notes = "Secrets management — vault integration, rotation, access control." -@end - -@cartridge(id="queues-mcp"): - name = "queues-mcp" - version = "0.1.0" - status = Development - tier = Teranga - domain = Queues - protocols = [MCP, GRPC, REST] - hash = "" - depends-on = [] - notes = "Message queue management — pub/sub, streams, dead-letter handling." -@end - -@cartridge(id="iac-mcp"): - name = "iac-mcp" - version = "0.1.0" - status = Development - tier = Teranga - domain = IaC - protocols = [MCP, GRPC, REST] - hash = "" - depends-on = [] - notes = "Infrastructure as Code — Nickel configs, plan/apply lifecycle." -@end - -@cartridge(id="observe-mcp"): - name = "observe-mcp" - version = "0.1.0" - status = Development - tier = Teranga - domain = Observe - protocols = [MCP, GRPC, REST] - hash = "" - depends-on = ["hypatia"] - notes = "Observability — metrics, tracing, logs, health dashboards." -@end - -@cartridge(id="ssg-mcp"): - name = "ssg-mcp" - version = "0.1.0" - status = Development - tier = Teranga - domain = SSG - protocols = [MCP, GRPC, REST] - hash = "" - depends-on = [] - notes = "Static site generation — Jekyll, Hugo, Eleventy build pipelines." -@end - -@cartridge(id="proof-mcp"): - name = "proof-mcp" - version = "0.1.0" - status = Development - tier = Teranga - domain = Proof - protocols = [MCP, GRPC, REST] - hash = "" - depends-on = [] - notes = "Formal proof management — theorem prover sessions, proof obligations, verification." -@end - -@cartridge(id="lsp-mcp"): - name = "lsp-mcp" - version = "0.1.0" - status = Development - tier = Teranga - domain = LSP - protocols = [MCP, LSP, GRPC, REST] - hash = "" - depends-on = [] - notes = "Language Server Protocol cartridge — diagnostics, completion, hover, symbol navigation." -@end - -@cartridge(id="dap-mcp"): - name = "dap-mcp" - version = "0.1.0" - status = Development - tier = Teranga - domain = DAP - protocols = [MCP, DAP, GRPC, REST] - hash = "" - depends-on = [] - notes = "Debug Adapter Protocol cartridge — breakpoints, stepping, variable inspection." -@end - -@cartridge(id="bsp-mcp"): - name = "bsp-mcp" - version = "0.1.0" - status = Development - tier = Teranga - domain = BSP - protocols = [MCP, BSP, GRPC, REST] - hash = "" - depends-on = [] - notes = "Build Server Protocol cartridge — build targets, compilation, test execution." -@end - -# ═══════════════════════════════════════════════════════════════════════════ -# Shield Selection (Privacy & Security) -# ═══════════════════════════════════════════════════════════════════════════ -# -# Advanced networking for self-hosters who require strong security. -# SDP, DoQ/DoH, oDNS — reassuringly locked down. - -@section(id="shield", label="Shield & Privacy"): - -@cartridge(id="sdp-shield"): - name = "sdp-shield" - version = "0.1.0" - status = Development - tier = Shield - domain = Secrets - protocols = [MCP] - hash = "" - depends-on = [] - notes = "Software Defined Perimeter. Auto-SDP for community nodes — invisible infrastructure, zero exposed ports until authenticated." -@end - -@cartridge(id="dns-shield"): - name = "dns-shield" - version = "0.1.0" - status = Development - tier = Shield - domain = Observe - protocols = [MCP] - hash = "" - depends-on = [] - notes = "DNS over QUIC (DoQ) and DNS over HTTPS (DoH). Encrypted DNS resolution for all BoJ traffic. Oblivious DNS (oDNS) relay for privacy." -@end - -# ═══════════════════════════════════════════════════════════════════════════ -# Ayo Selection (Community Joy) -# ═══════════════════════════════════════════════════════════════════════════ -# -# Community-contributed cartridges. If you build a cartridge that -# meets the spec and passes the IsUnbreakable proof, it goes here. -# Your name is honoured, your contribution celebrated. - -@section(id="ayo", label="The Ayo Selection"): - -# No community cartridges yet — the door is open. -# See docs/developer/README.adoc for how to contribute a cartridge. - -# ═══════════════════════════════════════════════════════════════════════════ -# Umoja Network (Community Nodes) -# ═══════════════════════════════════════════════════════════════════════════ -# -# The distributed hosting network. Nodes volunteer compute time. -# Hash attestation ensures integrity — tampered nodes are excluded -# from the community network but can still run locally. -# -# Like Tor or IPFS, but for developer server infrastructure. - -@section(id="umoja", label="The Umoja Network"): - -@seed-nodes: - - id: "node-eu-west-01" - ipv6: "TODO" - region: EuropeWest - operator: "hyperpolymath" - notes: "Primary development node (UK)" - - - id: "node-eu-central-01" - ipv6: "TODO" - region: EuropeCentral - operator: "family" - notes: "Central Europe node" - - - id: "node-oceania-01" - ipv6: "TODO" - region: Oceania - operator: "family" - notes: "Australia node" - - - id: "node-americas-01" - ipv6: "TODO" - region: Americas - operator: "family" - notes: "US node" -@end - -# ═══════════════════════════════════════════════════════════════════════════ -# Menu Attestation -# ═══════════════════════════════════════════════════════════════════════════ - -@attestation: - format = "boj-provenance-v1" - algorithm = "Ed25519+Dilithium5" - signature = "PLACEHOLDER" - timestamp = "2026-03-08T00:00:00Z" - canonical = "boj-server/.machine_readable/servers/menu.a2ml" -@end - - -@cartridge(id="vault-mcp"): - name = "vault-mcp" - version = "0.1.0" - status = Development - tier = Ayo - domain = Secrets - protocols = [MCP, REST] - hash = "" - notes = "Zero-knowledge credential proxy for the reasonably-good-token-vault" -@end - - -@cartridge(id="browser-mcp"): - name = "browser-mcp" - version = "0.1.0" - status = Development - tier = Ayo - domain = Browser - protocols = [MCP, REST] - hash = "" - notes = "Firefox browser automation via the Marionette protocol (TCP localhost:2828)" -@end - - -@cartridge(id="github-api-mcp"): - name = "github-api-mcp" - version = "0.1.0" - status = Development - tier = Ayo - domain = Cloud - protocols = [MCP, REST] - hash = "" - notes = "github-api-mcp cartridge" -@end - - -@cartridge(id="gitlab-api-mcp"): - name = "gitlab-api-mcp" - version = "0.1.0" - status = Development - tier = Ayo - domain = Cloud - protocols = [MCP, REST] - hash = "" - notes = "gitlab-api-mcp cartridge" -@end - - -@cartridge(id="slack-mcp"): - name = "slack-mcp" - version = "0.1.0" - status = Development - tier = Ayo - domain = Comms - protocols = [MCP, REST] - hash = "" - notes = "Slack Web API and Events API cartridge — send messages, manage channels, search, react, and more" -@end - - -@cartridge(id="linear-mcp"): - name = "linear-mcp" - version = "0.1.0" - status = Development - tier = Ayo - domain = Cloud - protocols = [MCP, REST] - hash = "" - notes = "linear-mcp cartridge" -@end - - -@cartridge(id="notion-mcp"): - name = "notion-mcp" - version = "0.1.0" - status = Development - tier = Ayo - domain = Comms - protocols = [MCP, REST] - hash = "" - notes = "Notion REST API cartridge — pages, databases, blocks, users, and comments via https://api.notion.com/v1/" -@end - - -@cartridge(id="jira-mcp"): - name = "jira-mcp" - version = "0.1.0" - status = Development - tier = Ayo - domain = Cloud - protocols = [MCP, REST] - hash = "" - notes = "jira-mcp cartridge" -@end - - -@cartridge(id="discord-mcp"): - name = "discord-mcp" - version = "0.1.0" - status = Development - tier = Ayo - domain = Comms - protocols = [MCP, REST] - hash = "" - notes = "Discord REST API v10 cartridge — messages, channels, guilds, members, reactions, threads, search, status, file uploads" -@end - - -@cartridge(id="telegram-mcp"): - name = "telegram-mcp" - version = "0.1.0" - status = Development - tier = Ayo - domain = Comms - protocols = [MCP, REST] - hash = "" - notes = "Telegram Bot API cartridge — messages, updates, chats, media, webhooks, callbacks, stickers, forwarding, pinning" -@end - - -@cartridge(id="matrix-mcp"): - name = "matrix-mcp" - version = "0.1.0" - status = Development - tier = Ayo - domain = Comms - protocols = [MCP, REST] - hash = "" - notes = "Matrix Client-Server API v3 cartridge — messages, events, rooms, membership, state, sync, search, media, profiles, room creation" -@end - - -@cartridge(id="postgresql-mcp"): - name = "postgresql-mcp" - version = "0.1.0" - status = Development - tier = Ayo - domain = Database - protocols = [MCP, REST] - hash = "" - notes = "PostgreSQL database cartridge with parameterised queries, transaction support, and libpq C-ABI integration" -@end - - -@cartridge(id="redis-mcp"): - name = "redis-mcp" - version = "0.1.0" - status = Development - tier = Ayo - domain = Database - protocols = [MCP, REST] - hash = "" - notes = "Redis database cartridge with RESP protocol, pipeline support, and pub/sub" -@end - - -@cartridge(id="mongodb-mcp"): - name = "mongodb-mcp" - version = "0.1.0" - status = Development - tier = Ayo - domain = Database - protocols = [MCP, REST] - hash = "" - notes = "MongoDB database cartridge with BSON document handling, aggregation pipelines, and wire protocol integration" -@end - - -@cartridge(id="neon-mcp"): - name = "neon-mcp" - version = "0.1.0" - status = Development - tier = Ayo - domain = Database - protocols = [MCP, REST] - hash = "" - notes = "Neon serverless Postgres MCP cartridge — projects, branches, endpoints, queries" -@end - - -@cartridge(id="turso-mcp"): - name = "turso-mcp" - version = "0.1.0" - status = Development - tier = Ayo - domain = Database - protocols = [MCP, REST] - hash = "" - notes = "Turso libSQL MCP cartridge — databases, groups, replicas, queries" -@end - - -@cartridge(id="supabase-mcp"): - name = "supabase-mcp" - version = "0.1.0" - status = Development - tier = Ayo - domain = Database - protocols = [MCP, REST] - hash = "" - notes = "Supabase MCP cartridge — PostgREST, Auth, Storage, Functions" -@end - - -@cartridge(id="fly-mcp"): - name = "fly-mcp" - version = "0.1.0" - status = Development - tier = Ayo - domain = Cloud - protocols = [MCP, REST] - hash = "" - notes = "Fly.io Machines API v1 cartridge -- apps, machines, volumes, secrets, regions, IPs" -@end - - -@cartridge(id="railway-mcp"): - name = "railway-mcp" - version = "0.1.0" - status = Development - tier = Ayo - domain = Cloud - protocols = [MCP, REST] - hash = "" - notes = "railway-mcp cartridge" -@end - - -@cartridge(id="render-mcp"): - name = "render-mcp" - version = "0.1.0" - status = Development - tier = Ayo - domain = Cloud - protocols = [MCP, REST] - hash = "" - notes = "Render REST API v1 cartridge -- services, deploys, env groups, custom domains, jobs, bandwidth" -@end - - -@cartridge(id="aws-mcp"): - name = "aws-mcp" - version = "0.2.0" - status = Development - tier = Ayo - domain = Cloud - protocols = [MCP, REST] - hash = "" - notes = "AWS cloud cartridge — Signature V4 auth, multi-service routing (S3/EC2/Lambda/SQS/DynamoDB) with rate-limit back-pressure" -@end - - -@cartridge(id="gcp-mcp"): - name = "gcp-mcp" - version = "0.2.0" - status = Development - tier = Ayo - domain = Cloud - protocols = [MCP, REST] - hash = "" - notes = "GCP cloud cartridge — service account/OAuth2 auth, multi-service routing (Compute/Storage/Functions/PubSub/BigQuery/IAM) with quota tracking" -@end - - -@cartridge(id="hetzner-mcp"): - name = "hetzner-mcp" - version = "0.2.0" - status = Development - tier = Ayo - domain = Cloud - protocols = [MCP, REST] - hash = "" - notes = "Hetzner Cloud cartridge — Bearer token auth, server/volume/firewall/network management with per-second rate limiting" -@end - - -@cartridge(id="digitalocean-mcp"): - name = "digitalocean-mcp" - version = "0.2.0" - status = Development - tier = Ayo - domain = Cloud - protocols = [MCP, REST] - hash = "" - notes = "DigitalOcean cloud infrastructure MCP cartridge — droplets, volumes, domains, SSH keys, snapshots, databases" -@end - - -@cartridge(id="linode-mcp"): - name = "linode-mcp" - version = "0.2.0" - status = Development - tier = Ayo - domain = Cloud - protocols = [MCP, REST] - hash = "" - notes = "Linode/Akamai cloud infrastructure MCP cartridge — instances, volumes, domains, NodeBalancers, StackScripts, images" -@end - - -@cartridge(id="docker-hub-mcp"): - name = "docker-hub-mcp" - version = "0.2.0" - status = Development - tier = Ayo - domain = Container - protocols = [MCP, REST] - hash = "" - notes = "Docker Hub container registry MCP cartridge — images, tags, namespaces, manifests, repositories, stars" -@end diff --git a/.machine_readable/servers/order-ticket.a2ml b/.machine_readable/servers/order-ticket.a2ml deleted file mode 100644 index 5b4534e0..00000000 --- a/.machine_readable/servers/order-ticket.a2ml +++ /dev/null @@ -1,111 +0,0 @@ -; SPDX-License-Identifier: MPL-2.0 -; Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -; -; Order Ticket Protocol Specification -; -; The order-ticket protocol defines how AI agents request specific -; cartridges to be mounted for a session. The flow is: -; -; 1. AI reads the Teranga menu (menu.a2ml) -; 2. AI writes an order ticket (this format) -; 3. BoJ validates the order against the catalogue -; 4. BoJ mounts requested cartridges via Zig FFI -; 5. zig adapter exposes mounted cartridges as REST+gRPC+GraphQL -; 6. AI receives confirmation with endpoints -; -; The metaphor: AI is the Maitre D', presenting the menu to the user, -; taking their order, and having the kitchen (Idris2+Zig) prepare it. - -(order-ticket-spec - (version "1.0.0") - (last-updated "2026-03-02") - - ; --- Order Format --- - ; - ; An order ticket is a structured request. Example: - ; - ; (order - ; (timestamp 1740916800) - ; (requested-by "claude-code-v4.6") - ; (session-id "abc123") - ; (cartridges - ; ("database-mcp" (protocols (MCP LSP))) - ; ("nesy-mcp" (protocols (MCP NeSy))) - ; ("fleet-mcp" (protocols (MCP Fleet)))) - ; (preferred-node "node-eu-west-01") ; optional - ; (fallback local) ; local | any | none - ; ) - - (fields - (required - (timestamp "Unix timestamp of order creation") - (requested-by "Identifier of the AI agent placing the order") - (session-id "Unique session identifier for tracking") - (cartridges "List of (cartridge-name (protocols ...)) pairs")) - (optional - (preferred-node "Node ID from the Umoja network to route to") - (fallback "What to do if preferred node unavailable: local | any | none"))) - - ; --- Validation Rules --- - ; - ; The BoJ server validates orders before mounting: - ; 1. Each requested cartridge must exist in the catalogue - ; 2. Each cartridge must have status = Ready (IsUnbreakable proof) - ; 3. Requested protocols must be supported by the cartridge - ; 4. If preferred-node is set, node must be attested (hash match) - ; 5. Maximum 16 cartridges per order (to prevent abuse) - - (validation-rules - (max-cartridges 16) - (require-ready #t) - (require-attested-node #t) - (allow-local-fallback #t)) - - ; --- Response Format --- - ; - ; After validation, BoJ returns a confirmation: - ; - ; (order-confirmation - ; (order-id "order-abc123") - ; (status accepted) ; accepted | partial | rejected - ; (mounted - ; ("database-mcp" (endpoints - ; (mcp "stdio://boj/database-mcp") - ; (lsp "tcp://[::1]:9010"))) - ; ("nesy-mcp" (endpoints - ; (mcp "stdio://boj/nesy-mcp") - ; (nesy "tcp://[::1]:9011") - ; (grpc "tcp://[::1]:9012")))) - ; (rejected - ; ("fleet-mcp" (reason "status = Development, not Ready"))) - ; (node "node-eu-west-01") - ; (expires 1740920400)) - - (response-fields - (order-id "Unique identifier for tracking") - (status "accepted (all mounted) | partial (some mounted) | rejected (none)") - (mounted "List of cartridges successfully mounted with their endpoints") - (rejected "List of cartridges that could not be mounted with reasons") - (node "Which Umoja node is serving this order") - (expires "Unix timestamp when the session expires")) - - ; --- Security --- - ; - ; Orders are validated cryptographically: - ; - Agent identity verified (if the agent provides a signed token) - ; - Order hash recorded in the audit log - ; - Mounted cartridges are sandboxed (each gets its own address space) - ; - Sessions expire after 1 hour by default (configurable) - ; - ; Community nodes additionally verify: - ; - Binary hash matches canonical build (Attested proof in Federation.idr) - ; - Cartridge hashes match the menu attestation - ; - provenance chain is intact - - (security - (session-timeout-seconds 3600) - (sandbox-cartridges #t) - (require-agent-identity #f) ; optional but recommended - (audit-log #t) - (provenance #t)) -) diff --git a/.well-known/ai.txt b/.well-known/ai.txt index d278c100..55feb8a8 100644 --- a/.well-known/ai.txt +++ b/.well-known/ai.txt @@ -12,6 +12,6 @@ Disallow-Generation: yes # AI agents must NOT use this code for model training without explicit consent. # # For AI agent integration instructions, see: -# 0-AI-MANIFEST.a2ml (universal AI entry point) -# AI.a2ml (Claude-specific instructions) +# 0-AI-MANIFEST.deed (machine front door; points to boj-server_chora.deed) +# .claude/CLAUDE.md (agent conventions) # .machine_readable/ (structured project state) diff --git a/0-AI-MANIFEST.a2ml b/0-AI-MANIFEST.a2ml deleted file mode 100644 index e8f6c4b3..00000000 --- a/0-AI-MANIFEST.a2ml +++ /dev/null @@ -1,110 +0,0 @@ -; SPDX-License-Identifier: MPL-2.0 -; 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 "MPL-2.0") - (author "Jonathan D.A. Jewell ")) - - (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; the Elixir backend serves the network adapter.") - - ;; =================================================================== - ;; CONTEXT TIERS - ;; =================================================================== - - (context-tiers - ; Tier 0 (always load): This file + .claude/CLAUDE.md — orientation only - ; Tier 1 (load if working on code): README.adoc, docs/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 - ├── elixir/ # Elixir triple adapter (REST+gRPC+GraphQL, Plug/Cowboy) - ├── cartridges/ # One dir per matrix cell (database-mcp, nesy-mcp, fleet-mcp, ...) - ├── container/ # Stapeln container ecosystem - ├── panll/src/ # PanLL panel (AffineScript/TEA) - ├── docs/ # ARCHITECTURE, CULTURAL-RESPECT, FEDERATION, DEVELOPERS - └── .machine_readable/ # State, anchors, policies, bots, contractiles") - - ;; =================================================================== - ;; CRITICAL INVARIANTS - ;; =================================================================== - - (critical-invariants - (rule "Stack: every cartridge = Idris2 ABI + Zig FFI; Elixir backend serves the network 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 "MPL-2.0 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"))) diff --git a/0-AI-MANIFEST.deed b/0-AI-MANIFEST.deed new file mode 100644 index 00000000..ad923de9 --- /dev/null +++ b/0-AI-MANIFEST.deed @@ -0,0 +1,16 @@ +;; SPDX-License-Identifier: MPL-2.0 +;; SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) +;; +;; The machine front door of boj-server: pointer-only (A7 ruling Q15). It names +;; where to read and carries no facts of its own. Repository facts are in +;; boj-server_chora.deed; agent conventions are in .claude/CLAUDE.md. It +;; replaces 0-AI-MANIFEST.a2ml, retired 2026-11-14 (docs/history/A2ML-REMOVED.adoc). +(repo-deed + :schema-version "1.0.0" + :canonical-name "boj-server" + :repo-uuid #u8"gv-clade-index:github.com/hyperpolymath/boj-server" + :beholding-chora #u8"chora:estate/github.com/hyperpolymath" + (front-doors + :machine "boj-server_chora.deed" + :human "README.adoc" + :agent ".claude/CLAUDE.md")) diff --git a/Justfile b/Justfile index b98680d8..40aac823 100644 --- a/Justfile +++ b/Justfile @@ -49,7 +49,7 @@ info: @echo "Version: {{version}}" @echo "RSR Tier: {{tier}}" @echo "Recipes: $(just --summary | wc -w)" - @[ -f ".machine_readable/STATE.a2ml" ] && grep -oP 'phase\s*=\s*"\K[^"]+' .machine_readable/STATE.a2ml | head -1 | xargs -I{} echo "Phase: {}" || true + @[ -f "boj-server_chora.deed" ] && grep -oP '^\s*:phase \K[a-z-]+' boj-server_chora.deed | head -1 | xargs -I{} echo "Phase: {}" || true # ═══════════════════════════════════════════════════════════════════════════════ # INIT — Bootstrap a new project from this template @@ -223,10 +223,6 @@ init: fi done - # Also replace [YOUR-REPO-NAME] and [YOUR-NAME/ORG] in AI manifest - sed -i "s|\[YOUR-REPO-NAME\]|${PROJECT_NAME}|g" 0-AI-MANIFEST.a2ml 2>/dev/null || true - sed -i "s|\[YOUR-NAME/ORG\]|${OWNER}|g" 0-AI-MANIFEST.a2ml 2>/dev/null || true - echo "" echo "── Validation ───────────────────────────────────" @@ -459,7 +455,7 @@ matrix: echo " Core catalogue: ffi/zig/src/catalogue.zig" echo " Dynamic loader: ffi/zig/src/loader.zig" echo " REST server: elixir/ (Plug/Cowboy)" - echo " Menu: .machine_readable/servers/menu.a2ml" + echo " Menu: GET /menu (built from each cartridge.json; elixir/lib/boj_rest/router.ex)" echo "" # ═══════════════════════════════════════════════════════════════════════════════ @@ -928,25 +924,27 @@ validate-rsr: for f in .editorconfig .gitignore Justfile README.adoc LICENSE; do [ -f "$f" ] || MISSING="$MISSING $f" done - for f in .machine_readable/STATE.a2ml .machine_readable/META.a2ml .machine_readable/ECOSYSTEM.a2ml .machine_readable/anchors/ANCHOR.a2ml .machine_readable/policies/MAINTENANCE-AXES.a2ml .machine_readable/policies/MAINTENANCE-CHECKLIST.a2ml .machine_readable/policies/SOFTWARE-DEVELOPMENT-APPROACH.a2ml; do + # Repo facts are deeds since 2026-11-14 (docs/history/A2ML-REMOVED.adoc): + # the chora deed carries (status) (meta) (anchor); 0-AI-MANIFEST.deed is + # the pointer-only front door. + for f in boj-server_chora.deed 0-AI-MANIFEST.deed; do [ -f "$f" ] || MISSING="$MISSING $f" done - for f in docs/maintenance/MAINTENANCE-CHECKLIST.md docs/practice/SOFTWARE-DEVELOPMENT-APPROACH.adoc; do + for f in docs/maintenance/MAINTENANCE-CHECKLIST.adoc docs/practice/SOFTWARE-DEVELOPMENT-APPROACH.adoc; do [ -f "$f" ] || MISSING="$MISSING $f" done - if [ -f ".machine_readable/META.a2ml" ]; then - grep -q 'axis-1 = "must > intend > like"' .machine_readable/META.a2ml || MISSING="$MISSING META.a2ml:axis-1" - grep -q 'axis-2 = "corrective > adaptive > perfective"' .machine_readable/META.a2ml || MISSING="$MISSING META.a2ml:axis-2" - grep -q 'axis-3 = "systems > compliance > effects"' .machine_readable/META.a2ml || MISSING="$MISSING META.a2ml:axis-3" - grep -q 'scoping-first = true' .machine_readable/META.a2ml || MISSING="$MISSING META.a2ml:scoping-first" - grep -q 'idris-unsound-scan = "believe_me/assert_total"' .machine_readable/META.a2ml || MISSING="$MISSING META.a2ml:idris-unsound-scan" - grep -q 'audit-focus = "systems in place, documentation explains actual state, safety/security accounted for, observed effects reviewed"' .machine_readable/META.a2ml || MISSING="$MISSING META.a2ml:audit-focus" - grep -q 'compliance-focus = "seams/compromises/exception register, bounded exceptions, anti-drift checks"' .machine_readable/META.a2ml || MISSING="$MISSING META.a2ml:compliance-focus" - grep -q 'effects-evidence = "benchmark execution/results and maintainer status dialogue/review"' .machine_readable/META.a2ml || MISSING="$MISSING META.a2ml:effects-evidence" - grep -q 'compliance-tooling = "panic-attack"' .machine_readable/policies/MAINTENANCE-AXES.a2ml || MISSING="$MISSING MAINTENANCE-AXES.a2ml:compliance-tooling" - grep -q 'effects-tooling = "ecological checking with sustainabot guidance"' .machine_readable/policies/MAINTENANCE-AXES.a2ml || MISSING="$MISSING MAINTENANCE-AXES.a2ml:effects-tooling" - grep -q 'source-human = "docs/maintenance/MAINTENANCE-CHECKLIST.md"' .machine_readable/policies/MAINTENANCE-CHECKLIST.a2ml || MISSING="$MISSING MAINTENANCE-CHECKLIST.a2ml:source-human" - grep -q 'source-human = "docs/practice/SOFTWARE-DEVELOPMENT-APPROACH.adoc"' .machine_readable/policies/SOFTWARE-DEVELOPMENT-APPROACH.a2ml || MISSING="$MISSING SOFTWARE-DEVELOPMENT-APPROACH.a2ml:source-human" + DEED=boj-server_chora.deed + if [ -f "$DEED" ]; then + grep -qE '^\s*\(status$' "$DEED" || MISSING="$MISSING $DEED:(status)" + grep -qE '^\s*\(anchor$' "$DEED" || MISSING="$MISSING $DEED:(anchor)" + grep -q ':axis-1 "must > intend > like"' "$DEED" || MISSING="$MISSING $DEED:meta:axis-1" + grep -q ':axis-2 "corrective > adaptive > perfective"' "$DEED" || MISSING="$MISSING $DEED:meta:axis-2" + grep -q ':axis-3 "systems > compliance > effects"' "$DEED" || MISSING="$MISSING $DEED:meta:axis-3" + grep -q ':scoping-first #t' "$DEED" || MISSING="$MISSING $DEED:meta:scoping-first" + grep -q ':idris-unsound-scan "believe_me/assert_total"' "$DEED" || MISSING="$MISSING $DEED:meta:idris-unsound-scan" + grep -q ':audit-focus "systems in place, documentation explains actual state, safety/security accounted for, observed effects reviewed"' "$DEED" || MISSING="$MISSING $DEED:meta:audit-focus" + grep -q ':compliance-focus "seams/compromises/exception register, bounded exceptions, anti-drift checks"' "$DEED" || MISSING="$MISSING $DEED:meta:compliance-focus" + grep -q ':effects-evidence "benchmark execution/results and maintainer status dialogue/review"' "$DEED" || MISSING="$MISSING $DEED:meta:effects-evidence" fi if [ -n "$MISSING" ]; then echo "MISSING:$MISSING" @@ -954,14 +952,14 @@ validate-rsr: fi echo "RSR compliance: PASS" -# Validate STATE.a2ml syntax +# Check the lifecycle state: the (status) clause of the chora deed validate-state: - @if [ -f ".machine_readable/STATE.a2ml" ]; then \ - grep -q '^\[metadata\]' .machine_readable/STATE.a2ml && \ - grep -q 'project\s*=' .machine_readable/STATE.a2ml && \ - echo "STATE.a2ml: valid" || echo "STATE.a2ml: INVALID (missing required sections)"; \ + @if [ -f "boj-server_chora.deed" ]; then \ + grep -qE '^\s*\(status$' boj-server_chora.deed && \ + grep -qE '^\s*:phase [a-z-]+$' boj-server_chora.deed && \ + echo "boj-server_chora.deed (status): valid" || echo "boj-server_chora.deed (status): INVALID (no (status) clause with a :phase)"; \ else \ - echo "No .machine_readable/STATE.a2ml found"; \ + echo "No boj-server_chora.deed found"; \ fi # Validate AI installation guide completeness (finishbot pre-release check) @@ -1036,16 +1034,15 @@ validate: validate-rsr validate-state validate-ai-install # STATE MANAGEMENT # ═══════════════════════════════════════════════════════════════════════════════ -# Update STATE.a2ml timestamp +# No state timestamp to touch: STATE.a2ml was retired 2026-11-14. The lifecycle +# claim is the (status) clause of boj-server_chora.deed, and the journal is +# docs/status/ROADMAP.adoc (docs/history/A2ML-REMOVED.adoc). state-touch: - @if [ -f ".machine_readable/STATE.a2ml" ]; then \ - sed -i 's/last-updated = "[^"]*"/last-updated = "'"$(date +%Y-%m-%d)"'"/' .machine_readable/STATE.a2ml && \ - echo "STATE.a2ml timestamp updated"; \ - fi + @echo "state-touch: nothing to stamp (state is the (status) clause of boj-server_chora.deed)" -# Show current phase from STATE.a2ml +# Show current phase from the chora deed's (status) clause state-phase: - @grep -oP 'phase\s*=\s*"\K[^"]+' .machine_readable/STATE.a2ml 2>/dev/null | head -1 || echo "unknown" + @grep -oP '^\s*:phase \K[a-z-]+' boj-server_chora.deed 2>/dev/null | head -1 || echo "unknown" # ═══════════════════════════════════════════════════════════════════════════════ # GUIX & GUIX @@ -1155,15 +1152,6 @@ todos: edit: ${EDITOR:-code} . -# Synchronize A2ML metadata to SCM (Shadow Sync) -sync-metadata: - #!/usr/bin/env bash - echo "Synchronizing metadata (A2ML -> SCM)..." - if [ -f .machine_readable/STATE.a2ml ]; then - # boj-server uses a slightly different A2ML structure, keeping it simple for now - echo "✓ Metadata synchronized" - fi - # Run panic-attacker pre-commit scan assail: @command -v panic-attack >/dev/null 2>&1 && panic-attack assail . || echo "panic-attack not found — install from https://github.com/hyperpolymath/panic-attacker" @@ -1483,7 +1471,7 @@ help-me: echo " docs/AI_INSTALLATION_GUIDE.adoc AI-assisted setup guide" echo " docs/architecture/README.adoc Architecture overview" echo " docs/quickstarts/USER.adoc Quick start for users" - echo " .machine_readable/STATE.a2ml Current project state" + echo " boj-server_chora.deed Repo facts: identity, status, meta, anchor" # Run mandatory pre-merge verification gate (conflicts, apps, Hypatia, K9/DEED, CI/lockfile, tests) diff --git a/boj-server_chora.deed b/boj-server_chora.deed index 9dccf680..4bf71ce8 100644 --- a/boj-server_chora.deed +++ b/boj-server_chora.deed @@ -1,14 +1,36 @@ ;; SPDX-License-Identifier: MPL-2.0 ;; SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) ;; -;; Clauses translated field for field from the legacy descriptiles under the -;; mapping specs in 1-formats/deed/mappings/: -;; CLADE.a2ml -> (identity) (clade) (forges) (lineage) (status) -;; per clade-to-repo-deed.adoc (ruled 2026-10-27, standards#1356); -;; AGENTIC.a2ml / NEUROSYM.a2ml -> (agentic) (neurosym) -;; per agentic-neurosym-playbook-to-repo-deed.adoc. -;; Untabled sections in META.a2ml, ECOSYSTEM.a2ml, PLAYBOOK.a2ml and STATE.a2ml -;; stay untranslated pending kyX / state-v1-decision.adoc (D308, D313). +;; The repo deed of boj-server (one deed per repo, standards#837). +;; +;; Every descriptive clause below is translated field for field from a retired +;; A2ML file under the mapping spec that governs its family, in standards +;; 1-formats/deed/mappings/ (the only authority a family translation may cite). +;; A field a table does not list does not translate: it was dropped, not +;; re-homed. docs/history/A2ML-REMOVED.adoc records each removed file, its git +;; blob id and what was dropped from it (owner approval 2026-11-14, after +;; hyperpolymath/hypatia#1113). +;; +;; CLADE.a2ml -> (identity) (clade) (forges) (lineage) (status) +;; clade-to-repo-deed.adoc (ruled 2026-10-27, +;; standards#1356). :repo-uuid is the ADR-008 profile C +;; UUIDv8 of the birth path (spec section 5, P-1), not +;; the v5 that CLADE.a2ml held. +;; META.a2ml -> (meta) meta-ecosystem-to-repo-deed.adoc +;; AGENTIC.a2ml -> (agentic) agentic-neurosym-playbook-to-repo-deed.adoc +;; NEUROSYM.a2ml -> (neurosym) agentic-neurosym-playbook-to-repo-deed.adoc +;; PLAYBOOK.a2ml -> (playbook) agentic-neurosym-playbook-to-repo-deed.adoc +;; ANCHOR.a2ml -> (anchor) A7 section 6.4 (anchor.abnf v2.0.0) +;; STATE.a2ml -> nothing new. state-v1-decision.adoc option B (ruled +;; 2026-11-10): its status "active" is the (status) +;; clause's :phase already, it named no maturity, and the +;; journal is archived by reference, not translated. +;; ECOSYSTEM.a2ml -> nothing. Its sections ([project], [position-in- +;; ecosystem]) are not the rows the table lists, its name +;; is not the canonical name (P-6), and every related- +;; project relationship is outside the closed set. Its +;; [publishing.readme] block stays in the legacy file, +;; which readme-derive.yml still reads (A7 section 10). (repo-deed :schema-version "1.0.0" :canonical-name "boj-server" @@ -45,6 +67,10 @@ :mcp-bridge "mcp-bridge/" :contracts ".machine_readable/svc/self-validating/" :enforcement ".github/workflows/") + ; The clade spec's table lists the fields below and no others ("Fields not + ; listed do not exist in the deed era for this family"). The three + ; :evidence-source, :interaction-source and :evidence-status fields that + ; stood here were outside it, and the first named STATE.a2ml, now retired. (status :phase active :since "2026-03-16" @@ -55,10 +81,59 @@ :successors () :ended "" (history - (entry :phase active :since "2026-03-16" :note "Active MCP server host; cartridge corpus split to hyperpolymath/boj-server-cartridges")) - :evidence-source ".machine_readable/6a2/STATE.a2ml" - :interaction-source "boj-server_chora.deed (agentic)" - :evidence-status "Lifecycle fields above are the CLADE registry surface. Legacy .a2ml records are frozen under D308 and must not be extended.") + (entry :phase active :since "2026-03-16" :note "Active MCP server host; cartridge corpus split to hyperpolymath/boj-server-cartridges"))) + ; META.a2ml: the rows the table lists. Not translated: [project-info] + ; license (a licence carrier; the spec's open question 2 is unruled, and + ; licence facts are the owner's to place), [design-rationale] (populated, + ; so it fails closed pending table rows) and the source's comments. + (meta + :version "0.3.0" + :last-updated "2026-04-25" + :type service + :languages (idris2 zig elixir javascript scheme nickel) + :author "Jonathan D.A. Jewell (hyperpolymath)" + :build-tool just + :container-runtime podman + :ci-platform github-actions + :package-manager guix + :scoping-first #t + :execution-order "axis-1 > axis-2 > axis-3" + :axis-1 "must > intend > like" + :axis-2 "corrective > adaptive > perfective" + :axis-3 "systems > compliance > effects" + (scoping + :sources "README, roadmap, status docs, maintenance checklist, CI/security docs" + :marker-scan "TODO/FIXME/XXX/HACK/STUB/PARTIAL" + :idris-unsound-scan "believe_me/assert_total") + :corrective-first #t + :adaptive-second #t + :adaptive-focus "scope-change reconciliation, stale-reference removal, obsolete-work culling" + :perfective-third #t + :perfective-source "axis-1 honest state after corrective/adaptive updates" + (axis-3 + :audit-focus "systems in place, documentation explains actual state, safety/security accounted for, observed effects reviewed" + :compliance-focus "seams/compromises/exception register, bounded exceptions, anti-drift checks" + :drift-risk-example "single exception broadening into policy violation (e.g. AffineScript->TypeScript spread)" + :effects-evidence "benchmark execution/results and maintainer status dialogue/review") + (adr :id "ADR-001" :title "Three-layer stack: Idris2 ABI + Zig FFI + Zig Adapter (zig retired 2026-04-10)" :status accepted :date "2026-03-02") + (adr :id "ADR-002" :title "2D matrix: protocol types (cols) x capability domains (rows)" :status accepted :date "2026-03-02") + (adr :id "ADR-003" :title "Cartridge metaphor — swappable, verified capability modules" :status accepted :date "2026-03-02") + (adr :id "ADR-004" :title "IsUnbreakable proof type — only Ready cartridges can be mounted" :status accepted :date "2026-03-02") + (adr :id "ADR-005" :title "Umoja federation — gossip protocol, IPv6, hash attestation" :status accepted :date "2026-03-02") + (adr :id "ADR-006" :title "Teranga menu — three-tier A2ML (Core/Shield/Ayo)" :status accepted :date "2026-03-02") + (adr :id "ADR-007" :title "Order-ticket protocol — AI reads menu, writes order, BoJ mounts cartridges" :status accepted :date "2026-03-02") + (adr :id "ADR-008" :title "Zero believe_me policy — all Idris2 code must be total and sound" :status accepted :date "2026-03-02") + (adr :id "ADR-009" :title "Align BoJ with unified-zig-api stack (future work)" :status accepted :date "2026-04-17") + (adr :id "ADR-010" :title "Elixir REST server (Plug/Cowboy) replaces zig adapter; dual dispatch: boj-invoke CLI for FFI cartridges, JsWorkerPool for JS cartridges" :status accepted :date "2026-04-20") + (adr :id "ADR-011" :title "Persistent Deno worker pool (JsWorkerPool) over fork-per-call for JS dispatch — consistent-hash routing, pre-warmed workers" :status accepted :date "2026-04-25") + (adr :id "ADR-012" :title "http-capability-gateway sidecar in catalog mode (BOJ_CARTRIDGES_ROOT) replaces static gateway-policy.yaml" :status accepted :date "2026-04-25") + (adr :id "ADR-013" :title "Seed node deployment on fly.io — lean build (boj-invoke only, no cartridge .so); seed nodes serve JS path for all cartridges" :status accepted :date "2026-04-25") + (adr :id "ADR-014" :title "X-Trust-Level header enforcement for HTTP invoke — loopback bypass, keyed cartridges require authenticated/internal trust from external callers" :status accepted :date "2026-04-25")) + ; AGENTIC.a2ml: [metadata], [agent-permissions] and the five + ; [maintenance-integrity] axioms. The source has no @profile line, so there + ; is no (profile). Not translated: [agent-constraints] (comment-carried and + ; divergent from template canon, so it fails closed under D4-1) and + ; [automation-hooks] (each hook named a retired .a2ml file). (agentic :version "0.2.0" :last-updated "2026-04-25" @@ -74,6 +149,8 @@ :allow-silent-skip #f :require-rerun-after-fix #t :release-claim-requires-hard-pass #t)) + ; NEUROSYM.a2ml: [metadata] and [hypatia-config]. [symbolic-rules] and + ; [neural-config] held only comments, so they are dropped. (neurosym :version "0.2.0" :last-updated "2026-04-25" @@ -81,4 +158,42 @@ :scan-enabled #t :scan-depth standard :report-format "json")) + ; PLAYBOOK.a2ml: [metadata] and the five operational sections kept as + ; positions (the family-1 slot doctrine). The content of [deployment] and + ; the runbook sections ([local-dev-deployment], [container-deployment], + ; [fly-io-*], [ci-required-gates]) has no table rows, so it did not + ; translate. The CI rule it carried is in .claude/CLAUDE.md and + ; docs/AI-CONVENTIONS.adoc. + (playbook + :version "0.2.1" + :last-updated "2026-06-13" + (deployment) + (incident-response) + (release-process) + (docs-format) + (maintenance-operations)) + ; ANCHOR.a2ml under A7 6.4, written as /2. Its version is (metadata + ; :version); authority, golden path, semantic-authority, implementation- + ; policy and satellite-policy go field for field. Not translated (no row in + ; 6.4): [metadata] last-updated, [anchor] repo and purpose, [identity] + ; and [semantic-authority-files]. The implementation-policy lists are + ; informative and verbatim; the language policy itself is a contractile. + (anchor + :schema "hyperpolymath.anchor/2" + :authority "upstream-canonical" + (metadata :version "1.0.0") + (semantic-authority + :policy "canonical" + :owns ("Project semantics and specification" "Invariant definitions and contractiles" "Reference implementation behavior")) + (implementation-policy + :allowed ("Idris2" "Zig" "Elixir" "AffineScript" "JavaScript (Deno)" "Scheme" "Shell" "Just" "AsciiDoc" "Markdown") + :forbidden ("Node.js" "npm" "TypeScript" "Python" "Go")) + (golden-path + :smoke-test-command ("just test" "just quality") + :success-criteria ("Core tests pass" "Quality gates pass" "No unresolved critical security findings")) + (satellite-policy + :must-pin-upstream #t + :must-declare-authority #t + :must-have-anchor #t + :must-have-golden-path #t)) ) diff --git a/container/0-AI-MANIFEST.a2ml b/container/0-AI-MANIFEST.a2ml deleted file mode 100644 index ccb5bc51..00000000 --- a/container/0-AI-MANIFEST.a2ml +++ /dev/null @@ -1,143 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "container-templates" -version: "1.0.0" -context: - - "https://a2ml.org/ns/v2" - - "https://stapeln.dev/ns/v1" - ---- -### [AI_MANIFEST] -description: | - Container templates for the stapeln container ecosystem. This directory - provides Podman-Chainguard-stapeln templates that are customised via - `just container-init` or `just init` during project bootstrap. - - All files use {{PLACEHOLDER}} tokens that are substituted with project- - specific values during initialisation. - -purpose: | - Provide a complete, security-first container deployment story for any - RSR-compliant repository. The templates cover the full lifecycle: - build, sign, verify, deploy, monitor, and govern. - -canonical_locations: - compose: "container/compose.toml" - containerfile: "container/Containerfile" - manifest: "container/manifest.toml" - gatekeeper: "container/.gatekeeper.yaml" - build_pipeline: "container/ct-build.sh" - entrypoint: "container/entrypoint.sh" - monitoring: "container/vordr.toml" - deployment: "container/deploy.k9.ncl" - example: "container/compose.example.toml" - ---- -### [FILE_RELATIONSHIPS] -files: - - name: "compose.toml" - role: "Orchestration" - description: | - selur-compose stack definition. Declares services, volumes, networks, - and health checks. References the Containerfile for image builds and - .gatekeeper.yaml for svalinn policy. - depends_on: ["Containerfile", ".gatekeeper.yaml"] - - - name: "Containerfile" - role: "Image Build" - description: | - Multi-stage OCI container build. Stage 1 compiles the application on - wolfi-base; Stage 2 copies the binary into a minimal runtime image. - Copies entrypoint.sh, .gatekeeper.yaml, and manifest.toml into the - final image. - depends_on: ["entrypoint.sh", ".gatekeeper.yaml", "manifest.toml"] - - - name: "manifest.toml" - role: "Bundle Metadata" - description: | - Cerro-torre .ctp bundle manifest. Describes provenance, dependencies, - attestations, and runtime security profile. Used by `ct pack` and - `ct verify`. - depends_on: [] - - - name: ".gatekeeper.yaml" - role: "Gateway Policy" - description: | - Svalinn edge gateway policy. Controls authentication, rate limiting, - container trust, request validation, CORS, and audit logging. - depends_on: [] - - - name: "ct-build.sh" - role: "Build Pipeline" - description: | - Shell script implementing the 5-stage pipeline: build (Podman), - pack (cerro-torre .ctp), sign (Ed25519), verify, push (optional). - Degrades gracefully when cerro-torre tools are not installed. - depends_on: ["Containerfile", "manifest.toml"] - - - name: "entrypoint.sh" - role: "Container Entrypoint" - description: | - Startup script with signal handling (SIGTERM, SIGINT), logging, and - exec into the main application process. - depends_on: [] - - - name: "vordr.toml" - role: "Runtime Monitoring" - description: | - Vordr monitoring configuration. Health endpoint probing, crash - detection, resource thresholds, and structured log output. - depends_on: [] - - - name: "deploy.k9.ncl" - role: "Deployment Component" - description: | - k9-svc deployment specification at Hunt trust level. Full pedigree - (L1-L5), environment configs, container config, and rolling - deployment strategy. - depends_on: ["compose.toml", "ct-build.sh"] - - - name: "compose.example.toml" - role: "Example" - description: | - Fully-commented multi-service example (Rust API + Elixir worker + - svalinn gateway). Copy to compose.toml and customise. - depends_on: [] - ---- -### [STAPELN_ECOSYSTEM] -overview: | - The stapeln container ecosystem comprises six tools: - - selur — Container orchestration with zero-copy IPC. Reads compose.toml. - cerro-torre — Verified container packaging (.ctp bundles), Ed25519 signing. - svalinn — Policy-driven edge gateway (auth, rate limits, CORS, trust). - vordr — Runtime monitoring (health, crashes, resources, logs). - rokur — Secrets management (runtime injection, no baked secrets). - k9-svc — Nickel deployment components (Kennel/Yard/Hunt trust levels). - -invariants: - - "Base images MUST be cgr.dev/chainguard/wolfi-base or cgr.dev/chainguard/static" - - "Container runtime is Podman — never Docker" - - "Containerfile — never Dockerfile" - - "All images run as non-root (appuser or project-specific user)" - - ".ctp bundles are signed with Ed25519 via cerro-torre" - - "Health endpoints (/health, /ready) must always be public (no auth)" - ---- -### [USAGE] -initialisation: | - Run `just container-init` to substitute all {{PLACEHOLDER}} tokens with - project-specific values. This is also run as part of `just init`. - -development: | - 1. `just container-build` — Build the container image - 2. `just container-verify` — Verify compose configuration - 3. `just container-up` — Start the stack locally - 4. `just container-down` — Stop the stack - -production: | - 1. `just container-sign` — Build, sign, verify .ctp bundle - 2. `just container-push` — Push signed bundle to registry - 3. `selur-compose up` — Deploy on target host diff --git a/container/README.adoc b/container/README.adoc index 72a78d28..4505c87f 100644 --- a/container/README.adoc +++ b/container/README.adoc @@ -64,9 +64,6 @@ All files use `{{PLACEHOLDER}}` tokens that are replaced by `just container-init (L1--L5), environment configs (dev/staging/prod), container configuration, and rolling deployment strategy. -| `0-AI-MANIFEST.a2ml` -| AI-readable manifest describing the container directory, file - interconnections, and the stapeln ecosystem. |=== == The stapeln Ecosystem diff --git a/contractile.just b/contractile.just index 62c4a18f..2fd4fbf9 100644 --- a/contractile.just +++ b/contractile.just @@ -2,6 +2,11 @@ # Source directory: .machine_readable/contractiles # Re-generate with: contractile gen-just --dir .machine_readable/contractiles # +# The `# Source:` files named below were legacy .a2ml contractiles, retired +# 2026-11-14 with no mapping spec to translate them (docs/history/A2ML-REMOVED.adoc). +# The recipes stand as generated until the edicts (file.deed, A7 8.1) exist; +# do not regenerate from the retired files. +# # SPDX-License-Identifier: MPL-2.0 # === DUST (Recovery & Rollback) === diff --git a/docs/AI-CONVENTIONS.adoc b/docs/AI-CONVENTIONS.adoc index 4517b305..00f302f6 100644 --- a/docs/AI-CONVENTIONS.adoc +++ b/docs/AI-CONVENTIONS.adoc @@ -10,13 +10,14 @@ Per-tool config files (.cursorrules, .clinerules, etc.) reference this document. == Session Startup -. Read `0-AI-MANIFEST.a2ml` FIRST (mandatory gatekeeper). -. Read `.machine_readable/STATE.a2ml` for current status and blockers. -. Read `.machine_readable/anchors/ANCHOR.a2ml` for canonical authority boundaries. -. Read `.machine_readable/policies/MAINTENANCE-AXES.a2ml` for maintenance/audit sequencing. -. Read `.machine_readable/policies/MAINTENANCE-CHECKLIST.a2ml` for baseline controls. -. Read `.machine_readable/policies/SOFTWARE-DEVELOPMENT-APPROACH.a2ml` for execution order. -. Read `.machine_readable/AGENTIC.a2ml` for agent constraints. +. Read `0-AI-MANIFEST.deed` FIRST (the pointer-only machine front door). +. Read `boj-server_chora.deed`: lifecycle `(status)`, `(meta)` (ADRs and the + maintenance axes), `(agentic)` (agent permissions and integrity axioms) and + `(anchor)` (canonical authority boundaries and the golden path). +. Read `docs/status/ROADMAP.adoc` for current status and blockers. +. Read `docs/maintenance/MAINTENANCE-CHECKLIST.adoc` and + `docs/practice/SOFTWARE-DEVELOPMENT-APPROACH.adoc` for maintenance sequencing + and execution order. == License @@ -34,10 +35,11 @@ Per-tool config files (.cursorrules, .clinerules, etc.) reference this document. == State Files -State/metadata files, anchors, and policies (.a2ml) belong in `.machine_readable/` ONLY. -NEVER create STATE.a2ml, META.a2ml, ECOSYSTEM.a2ml, AGENTIC.a2ml, -NEUROSYM.a2ml, PLAYBOOK.a2ml, ANCHOR.a2ml, MAINTENANCE-AXES.a2ml, -MAINTENANCE-CHECKLIST.a2ml, or SOFTWARE-DEVELOPMENT-APPROACH.a2ml in the repository root. +A2ML is retired. Repo state and metadata are clauses of `boj-server_chora.deed`, +checked with standards' `deed_lint.js`. NEVER create a `.a2ml` file (STATE, META, +ECOSYSTEM, AGENTIC, NEUROSYM, PLAYBOOK, ANCHOR, policies or any other), anywhere. +`docs/history/A2ML-REMOVED.adoc` records the files retired on 2026-11-14 and the +four kept for a live reader. == Banned Patterns @@ -141,10 +143,9 @@ the link:wikis/CI-and-Required-Checks[CI & Required Checks] wiki page. == References -* `0-AI-MANIFEST.a2ml` -- universal AI entry point -* `.machine_readable/AGENTIC.a2ml` -- agent permissions and constraints -* `.machine_readable/STATE.a2ml` -- current project state -* `.machine_readable/anchors/ANCHOR.a2ml` -- canonical authority and policy boundary -* `.machine_readable/policies/MAINTENANCE-AXES.a2ml` -- canonical axis sequencing and audit requirements -* `.machine_readable/policies/MAINTENANCE-CHECKLIST.a2ml` -- baseline maintenance checklist policy -* `.machine_readable/policies/SOFTWARE-DEVELOPMENT-APPROACH.a2ml` -- axis execution approach policy +* `0-AI-MANIFEST.deed` -- machine front door (pointer-only) +* `boj-server_chora.deed` -- repo facts: `(status)`, `(meta)`, `(agentic)`, `(neurosym)`, `(playbook)`, `(anchor)` +* `docs/status/ROADMAP.adoc` -- current project state +* `docs/maintenance/MAINTENANCE-CHECKLIST.adoc` -- baseline maintenance checklist +* `docs/practice/SOFTWARE-DEVELOPMENT-APPROACH.adoc` -- axis execution approach +* `docs/history/A2ML-REMOVED.adoc` -- ledger of the retired A2ML files diff --git a/docs/README.adoc b/docs/README.adoc index cdb10c09..4a5f2cde 100644 --- a/docs/README.adoc +++ b/docs/README.adoc @@ -202,8 +202,10 @@ toc::[] * link:../TEST-NEEDS.md[`../TEST-NEEDS.md`] — test-coverage tracker (stays at root pending refactor of 5 cross-references) * link:../CHANGELOG.md[`../CHANGELOG.md`] — release history -* `../.machine_readable/6a2/` — retired A2ML state files (D308), kept - read-only until kyX converts them into the repo's chora deed. Not current. +* `../boj-server_chora.deed` — the repo deed: identity, lifecycle status, + ADRs, agent permissions, anchor. The A2ML files it replaced were retired on + 2026-11-14; link:history/A2ML-REMOVED.adoc[`history/A2ML-REMOVED.adoc`] + records where each went and the four kept for a live reader. * link:../GEMINI.md[`../GEMINI.md`] — Gemini CLI integration context (load-bearing; referenced by `gemini-extension.json` as `contextFileName`) diff --git a/docs/RSR_OUTLINE.adoc b/docs/RSR_OUTLINE.adoc index fe4cdb9b..dd838097 100644 --- a/docs/RSR_OUTLINE.adoc +++ b/docs/RSR_OUTLINE.adoc @@ -68,8 +68,8 @@ Every cartridge follows the ABI/FFI universal standard: [source] ---- boj-server/ -├── 0-AI-MANIFEST.a2ml # Universal AI agent entry point -├── AI.a2ml # Claude-specific instructions +├── 0-AI-MANIFEST.deed # Machine front door (pointer-only) +├── boj-server_chora.deed # Repo facts: identity, status, meta, anchor ├── README.adoc # Project overview ├── TOPOLOGY.md # Architecture diagram + completion dashboard ├── READINESS.md # Component Readiness Grades (CRG) @@ -114,18 +114,6 @@ boj-server/ │ ├── DEVELOPERS.md # Contributing cartridges │ └── QUICKSTART.md # Getting started guide ├── .machine_readable/ # ALL machine-readable content -│ ├── STATE.a2ml # Project state, progress, blockers -│ ├── META.a2ml # Architecture decisions, governance -│ ├── ECOSYSTEM.a2ml # Ecosystem position, relationships -│ ├── AGENTIC.a2ml # AI agent interaction patterns -│ ├── NEUROSYM.a2ml # Neurosymbolic integration config -│ ├── PLAYBOOK.a2ml # Operational runbook -│ ├── servers/ -│ │ ├── menu.a2ml # Live Teranga menu -│ │ └── order-ticket.scm # Order protocol specification -│ ├── anchors/ANCHOR.a2ml -│ ├── policies/ # Maintenance axes, checklist, SDA -│ ├── bot_directives/ # Per-bot rules │ └── contractiles/ # Policy enforcement (k9, dust, lust, must, trust) ├── .well-known/ # RFC metadata (security.txt, ai.txt, humans.txt) ├── .github/workflows/ # 17 mandatory + BoJ-specific @@ -141,7 +129,7 @@ boj-server/ * `Justfile` * `README.adoc` * `LICENSE` (MPL-2.0) -* `.machine_readable/STATE.a2ml` +* `boj-server_chora.deed` * `.well-known/security.txt` * `.well-known/ai.txt` * `.well-known/humans.txt` @@ -152,12 +140,12 @@ boj-server/ * **ABI**: Idris2 (dependent types, formal verification) * **FFI**: Zig (zero-cost C ABI, cross-compilation) * **Adapter**: zig (triple API, Phase 3) -* **Infrastructure**: Just, Guile Scheme (`.a2ml` files), Nickel (k9), Shell +* **Infrastructure**: Just, deed (`boj-server_chora.deed`), Nickel (k9), Shell === Prohibited (enforced by CI) * TypeScript/JavaScript (use AffineScript) -* npm, Bun, pnpm, yarn (use Deno) +* Node.js and yarn (use Bun; the JS runtime order is Bun > Deno > pnpm > npm) * Python (use Julia/Rust) * Go (use Rust/Zig) * `Dockerfile` (use `Containerfile`) @@ -187,7 +175,7 @@ All present in `.github/workflows/`: * **proven-servers**: Imports MCP type skeletons and connector interfaces * **polystack**: BoJ supersedes polystack's 13 components -* **PanLL**: Primary consumer (reads menu.a2ml for capability discovery) +* **PanLL**: Primary consumer (capability discovery) * **hypatia**: Neurosymbolic CI scanning * **gitbot-fleet**: 6-bot release gate policy * **stapeln**: Container supply chain for node hosting diff --git a/docs/TOPOLOGY-GUIDE.adoc b/docs/TOPOLOGY-GUIDE.adoc index 62529112..28f8e550 100644 --- a/docs/TOPOLOGY-GUIDE.adoc +++ b/docs/TOPOLOGY-GUIDE.adoc @@ -143,12 +143,12 @@ Always 10 characters wide. Use full blocks only (no half-blocks). TOPOLOGY.md complements but does not replace: -- **STATE.a2ml** — machine-readable state (tasks, blockers, next actions) -- **ECOSYSTEM.a2ml** — position in the wider project ecosystem -- **META.a2ml** — architecture decisions and design rationale -- **0-AI-MANIFEST.a2ml** — AI agent entry point and invariants +- **boj-server_chora.deed** — machine-readable repo facts: lifecycle + `(status)`, `(meta)` architecture decisions, `(anchor)` semantic boundary +- **0-AI-MANIFEST.deed** — AI agent front door (pointer-only) +- **docs/status/ROADMAP.adoc** — current state, blockers and next actions -TOPOLOGY.md is the _visual summary_ for humans; the a2ml files are the +TOPOLOGY.md is the _visual summary_ for humans; the deeds are the _structured data_ for tooling. Both should agree. == Copyright diff --git a/docs/accessibility/README.adoc b/docs/accessibility/README.adoc index 8b3cf192..f4d1fced 100644 --- a/docs/accessibility/README.adoc +++ b/docs/accessibility/README.adoc @@ -249,7 +249,7 @@ We welcome contributions to improve accessibility. See our link:../CONTRIBUTING. == Related Documents * link:../status/ROADMAP.adoc[Project Roadmap] — Accessibility milestones -* link:../../.machine_readable/contractiles/adjust/Adjustfile.a2ml[Adjustfile] — Accessibility contract +* link:../../.machine_readable/contractiles/adjust/adjust.ncl[adjust.ncl] — Accessibility contract runner (the legacy `Adjustfile.a2ml` was retired 2026-11-14; see link:../history/A2ML-REMOVED.adoc[A2ML-REMOVED]) * link:https://www.w3.org/WAI/standards-guidelines/wcag/[WCAG Guidelines] — Official standards * link:https://www.section508.gov/[Section 508] — U.S. federal requirements diff --git a/docs/architecture/README.adoc b/docs/architecture/README.adoc index 076d64f3..0214c4ee 100644 --- a/docs/architecture/README.adoc +++ b/docs/architecture/README.adoc @@ -288,8 +288,8 @@ All 115 cartridges have the scaffold. Status (re-measured 2026-04-30): == The Teranga Menu -The menu (`.machine_readable/servers/menu.a2ml`) is the public catalogue of available -capabilities. Three sections: +The menu (`GET /menu`, built by `BojRest.Router` from each cartridge's `cartridge.json`) +is the public catalogue of available capabilities. Three sections: * *Teranga (Core)*: Cartridges maintained by the project * *Shield*: Privacy and security cartridges (SDP, DoQ/DoH, oDNS) @@ -300,7 +300,7 @@ and having the kitchen prepare it. == The Order-Ticket Protocol -. AI reads the Teranga menu (`menu.a2ml`) +. AI reads the Teranga menu (`GET /menu`) . AI writes an order ticket (`order-ticket.scm`) . BoJ validates the order against the catalogue (`IsUnbreakable` check) . BoJ routes invoke calls via `BojRest.Router`: diff --git a/docs/developer/README.adoc b/docs/developer/README.adoc index bcd78376..c5fdd702 100644 --- a/docs/developer/README.adoc +++ b/docs/developer/README.adoc @@ -56,7 +56,7 @@ Your adapter must: === 6. Register in the menu -Add your cartridge to `.machine_readable/servers/menu.a2ml` under the Ayo section. Set status to `Development` initially. +The menu (`GET /menu`) is built from each cartridge's `cartridge.json`: set `"tier": "Ayo"` there, and set status to `Development` initially. === 7. Pass the IsUnbreakable proof diff --git a/docs/developer/llm-warmup-dev.adoc b/docs/developer/llm-warmup-dev.adoc index 0de05833..73fe2633 100644 --- a/docs/developer/llm-warmup-dev.adoc +++ b/docs/developer/llm-warmup-dev.adoc @@ -112,18 +112,15 @@ tools/ Cartridge tooling (provisioner, configurator, harnes panll/src/ PanLL panel (AffineScript/TEA) -.machine_readable/ All machine-readable content - STATE.a2ml Project state - META.a2ml Architecture decisions - ECOSYSTEM.a2ml Ecosystem position - AGENTIC.a2ml AI agent patterns - NEUROSYM.a2ml Neurosymbolic config - PLAYBOOK.a2ml Operational runbook - servers/menu.a2ml Teranga menu (cartridge catalogue) - anchors/ANCHOR.a2ml Semantic boundary - policies/ Governance files - bot_directives/ Per-bot rules - contractiles/ Policy enforcement (k9, dust, lust, must, trust) +boj-server_chora.deed Repo facts: identity, (status), (meta) ADRs, (agentic), + (neurosym), (playbook), (anchor) semantic boundary +0-AI-MANIFEST.deed Machine front door (pointer-only) + +.machine_readable/ Other machine-readable content + contractiles/ Policy runners (adjust, bust, dust, intend, must, trust) + svc/self-validating/ K9 contracts +# The A2ML files that lived here were retired 2026-11-14: +# docs/history/A2ML-REMOVED.adoc. The live cartridge catalogue is GET /menu. ---- == Build System @@ -287,7 +284,7 @@ See: `src/abi/Federation.idr`, `docs/FEDERATION.adoc` . Hash attestation for community nodes . MPL-2.0 on all code . Cultural terms are permanent and sacred -. A2ML files ONLY in .machine_readable/ +. No `.a2ml` files: A2ML is retired; repo facts are deeds (`boj-server_chora.deed`) . Chainguard base images, Containerfile, Podman . zig is BANNED (migrated to Zig FFI + Deno/JS, 0 `.v` files as of 2026-04-12) diff --git a/docs/examples/extension.a2ml b/docs/examples/extension.a2ml deleted file mode 100644 index b0ee5eb6..00000000 --- a/docs/examples/extension.a2ml +++ /dev/null @@ -1,32 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# extension.a2ml — Example BoJ extension descriptor -# -# Copy this file, fill in the fields, and submit to a BoJ node. -# See docs/EXTENSIBILITY.adoc for the full guide. - -[extension] -name = "database-mcp-pg" # Cartridge name (unique across the catalogue) -version = "0.1.0" # Semantic version -domain = "database" # Must match a CapabilityDomain row -backend = "postgresql" # Your specialisation (the third axis) -tier = "ayo" # Community extensions are always Ayo tier -protocols = ["mcp", "rest"] # Which protocol columns this fills - -[metadata] -author = "Your Name " -description = "PostgreSQL-native database cartridge for BoJ" -homepage = "" # Optional: URL to source repo -license = "MPL-2.0" -hash = "" # SHA-256 of the compiled .so — filled at build time - -[capabilities] -tools = [ - "pg_query", # List the tools your cartridge provides - "pg_schema", - "pg_migrate", -] - -# Optional: declare resource requirements for coprocessor dispatch -[resources] -cpu-only = true # Does not need GPU/accelerator -memory-mb = 64 # Approximate memory footprint diff --git a/docs/history/A2ML-REMOVED.adoc b/docs/history/A2ML-REMOVED.adoc new file mode 100644 index 00000000..e0c75145 --- /dev/null +++ b/docs/history/A2ML-REMOVED.adoc @@ -0,0 +1,448 @@ +// SPDX-License-Identifier: CC-BY-SA-4.0 +// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) += The A2ML files removed from boj-server on 2026-11-14 + +The owner approved on 2026-11-14 moving boj-server off A2ML, as +hyperpolymath/hypatia#1113 did for hypatia. Every `.a2ml` file in boj-server is +translated into deed form where a mapping spec says it translates, every reader +in this repository is moved off it, and the file is deleted. The mapping specs +are in standards `1-formats/deed/mappings/`; a field a spec does not list does +not translate and was dropped, not re-homed. Files with no mapping spec were +deleted when nothing reads them (A7 section 11, ruling Q7). + +This record lists each removed file, what it was, and where its content went. +The contents are not copied here. Git history keeps them. To read one, use its +blob id, or read its path at the last commit that held it: + +[source,bash] +---- +git cat-file -p +git show ad5bcdb6370124980e0fd94e4205f1e6def9a52e: +---- + +Size is in bytes. The sha256 is of the file as it was tracked. + +The deed carriers are `boj-server_chora.deed` (the one repo deed) and +`0-AI-MANIFEST.deed` (the pointer-only front door). Both pass +`deed_lint.js`; the chora deed also passes `deed_lint.js --anchor`. + +== Removed + +[cols="4,1,3,3,4,5",options="header"] +|=== +| Path | Size | sha256 | Git blob id | What it was | Where it went + +| `.machine_readable/CLADE.a2ml` +| 1559 +| `1b3aff992a73b9f312c28eed996106e406f45dc97c94fce0930975d56fd84dca` +| `5db3e8157c0680bd464824fa01c68b99ad18c7e5` +| Clade declaration (gv-clade-index registry, now chora-registry): identity, clade, forges, lineage, status with one history entry. +| Already translated into `(identity) (clade) (forges) (lineage) (status)` per `clade-to-repo-deed.adoc`; the legacy file is deleted. Its v5 `uuid` is not carried: the deed's `:repo-uuid` is the profile C UUIDv8 of the birth path (P-1). Its `[lineage] parent` text is the registry's description, not a parent, and its `[clade] rationale` was empty; see "Open points". + +| `.machine_readable/6a2/META.a2ml` +| 5763 +| `b48668d4d387158678fde26a7c7145c28c905f1c9e46bdc3b916da2a8f2ee587` +| `f205beed7bf0e3369c89593501eb66003e53f79f` +| META descriptile: version, project info, ADR-001 to ADR-014, development practices, maintenance axes, scoping, axis-2 and axis-3 rules, design rationale. +| `(meta)` per `meta-ecosystem-to-repo-deed.adoc`: version, last-updated, type, languages, author, build-tool, container-runtime, ci-platform, package-manager, the maintenance axes, `(scoping)`, the axis-2 rules, `(axis-3)` and 14 `(adr)` clauses (id, title, status, date). Not translated: `[project-info] license` (a licence carrier; the spec's open question 2 is unruled and licence facts are the owner's to place) and `[design-rationale]` (populated, so it fails closed pending table rows). + +| `.machine_readable/6a2/AGENTIC.a2ml` +| 1833 +| `2329e46235c6b57fbeb42886ec9667892af3474dd4380b19bed8c22a60a62c20` +| `11ee7acefee4e3b4f189b29b2f7d4567d590c7a6` +| AGENTIC descriptile: permissions, comment-carried agent constraints, maintenance-integrity axioms, comment-carried automation hooks. +| Already translated into `(agentic)` per `agentic-neurosym-playbook-to-repo-deed.adoc`: version, last-updated, permissions, the five integrity axioms. Not translated: `[agent-constraints]` (comment-carried and divergent from template canon, so it fails closed under D4-1; it held the fly.io build cautions) and `[automation-hooks]` (each hook named a retired `.a2ml` file). + +| `.machine_readable/6a2/NEUROSYM.a2ml` +| 749 +| `180fe890c8a4bd0f5a9dec9d067bf2963a57bcea89a09dce70c19efcf28ca7cf` +| `b1948824fe067bab48dc7adb4568326c63919d35` +| NEUROSYM descriptile: Hypatia scan config; commented-out symbolic rules and neural config. +| Already translated into `(neurosym (hypatia …))`. The comment-only sections are dropped. + +| `.machine_readable/6a2/PLAYBOOK.a2ml` +| 4908 +| `1520b2585930a98987115ef6c44b9feb46f17f27e97a789239abb62b187525ec` +| `6fc257177e8594cf8e14723c03bf202f7841ad04` +| PLAYBOOK descriptile: deployment, local-dev, container and fly.io seed deployment commands, fly.io notes and domains, incident response, release process, maintenance operations, the CI required-gates rule. +| `(playbook)` per `agentic-neurosym-playbook-to-repo-deed.adoc`: version, last-updated and the five operational sections kept as positions. Their content has no table rows and did not translate. The required-gates rule is also stated in `.claude/CLAUDE.md`, `docs/AI-CONVENTIONS.adoc` and `docs/wikis/CI-and-Required-Checks.adoc`. + +| `.machine_readable/6a2/STATE.a2ml` +| 38011 +| `5ed5250228cde45fa8f97dd8cb07a3ceb4c82979c61044d42ed5c9f4a0e728d3` +| `b3d1c23e3cc89c1d3827a81cd6d1a9156d07d173` +| STATE descriptile v1: status, CRG grade C, completion 65%, stack, milestones (phases 0 to 10), quality counts, open gaps, next actions, blockers, the session history journal, architecture and ecosystem summaries. +| Option B of `state-v1-decision.adoc`: its `status = "active"` is the `(status)` clause's `:phase active` already; it named no maturity, so there is no `(maturity)`; the rest is journal, archived here by reference and not translated. Current status lives in `docs/status/ROADMAP.adoc`. + +| `.machine_readable/6a2/anchor/ANCHOR.a2ml` +| 2072 +| `b4ded2635e3f8053413ee369296d26f1049b537f1fcfd0b4415482c2b6ff462e` +| `9b033d6ab4c3bea6fdef69a8a9b5be6eafcd5662` +| Anchor (`hyperpolymath.anchor/1`): authority, purpose, identity, semantic authority, implementation policy, golden path, satellite policy, semantic-authority files. +| The `(anchor)` clause of `boj-server_chora.deed`, written as `hyperpolymath.anchor/2`, under A7 section 6.4: version to `(metadata :version)`; authority, `(semantic-authority)`, `(implementation-policy)`, `(golden-path)` and `(satellite-policy)` field for field. Not translated (no 6.4 row): `[metadata] last-updated`, `[anchor] repo` and `purpose`, `[identity]` and `[semantic-authority-files]` (whose paths do not exist in this repo). + +| `0-AI-MANIFEST.a2ml` +| 781 +| `c9e945d66d069efbdee9d9d3c3de451f1f52e924da1fccae131c900fbfe69420` +| `6bf1f8c7f3805520515a5106f68b8cc8d53ad993` +| AI manifest (S-expression shape): identity, purpose, context tiers, canonical locations, structure, critical invariants, session lifecycle, format meta. +| Replaced by the pointer-only `0-AI-MANIFEST.deed` (A7 ruling Q15). Its sections are not the table of `ai-manifest-decision.adoc`, so nothing was translated. Its canonical locations named files now removed. + +| `.machine_readable/6a2/0-AI-MANIFEST.a2ml` +| 781 +| `c9e945d66d069efbdee9d9d3c3de451f1f52e924da1fccae131c900fbfe69420` +| `6bf1f8c7f3805520515a5106f68b8cc8d53ad993` +| Directory manifest for `6a2/`: the six files that must exist there and a lock protocol for concurrent writers. +| Deleted: no mapping spec, no reader. `.machine_readable/6a2/README.adoc` now says what remains. + +| `.machine_readable/6a2/anchor/0-AI-MANIFEST.a2ml` +| 548 +| `fb06417a3bd6d266398a3c7c20288b87a6623df1ff18f7eeb98ef22c37378c48` +| `0dd6825b17a70c589c0916a48c321f0fecb635a9` +| Directory manifest for `6a2/anchor/`. +| Deleted: no mapping spec, no reader. The directory's README went with it. + +| `.machine_readable/0.1-AI-MANIFEST.a2ml` +| 658 +| `0823ff4f0119047b8c2cfbaa4cabbc19c7166adfd687e62313d5cb2d9d1dd2fa` +| `9d2bc7a077aa84426cacd49d072e14cf7f945301` +| Level-1 directory manifest for `.machine_readable/`: canonical locations of the A2ML descriptiles; "metadata MUST follow a2ml format". +| Deleted: no mapping spec, no reader. + +| `.github/0.1-AI-MANIFEST.a2ml` +| 33 +| `4a01e142d7aa5bd591588351050775e02a3421160d6ea2e9ba1fc97dcc40b748` +| `85b2f0f0a097ea65882ef51128b002576e372198` +| One-line placeholder heading. +| Deleted: no content, no reader. + +| `.machine_readable/configs/0.2-AI-MANIFEST.a2ml` +| 191 +| `43e5323c8c189297afebd91ba719e4652139caa511b4dd4037f20d957e98ec53` +| `6e41e6c25b483cee8c48acf26fb48332fb367dc1` +| Level-2 directory manifest for `configs/`. +| Deleted: no mapping spec, no reader. + +| `.machine_readable/scripts/0.2-AI-MANIFEST.a2ml` +| 398 +| `df879a53ce1dbc169a160164a1f161e97dba17e83e60808886abff74b871c54b` +| `615df84f01893de2968f783c8017f61be7f592d9` +| Level-2 directory manifest for `scripts/`. +| Deleted: no mapping spec, no reader. + +| `.machine_readable/scripts/forge/0.3-AI-MANIFEST.a2ml` +| 206 +| `6bd8128d0a4eed6ee42f7355c1fdd687573657cfdd54c8950c8bfb084671f35b` +| `4bbd6cf394f6417ee141b7f4a65e2e5a2b031a22` +| Level-3 directory manifest for `scripts/forge/`. +| Deleted: no mapping spec, no reader. + +| `.machine_readable/scripts/lifecycle/0.3-AI-MANIFEST.a2ml` +| 214 +| `376064428be7f0f23ef5a2d34591422a3165b36c3bab6fa855356f5df6f3d5c0` +| `3182d1754dfcaf846d6561b73f431d57e7f7d36d` +| Level-3 directory manifest for `scripts/lifecycle/`. +| Deleted: no mapping spec, no reader. + +| `.machine_readable/scripts/verification/0.3-AI-MANIFEST.a2ml` +| 220 +| `3c9c71c5c55c35e577b7ed53b07220f1ec8e5fc6691b9214a13a5c60f9e78052` +| `460e0694090ab32ff28c1a30e31439aa9a490927` +| Level-3 directory manifest for `scripts/verification/`. +| Deleted: no mapping spec, no reader. + +| `verification/0.1-AI-MANIFEST.a2ml` +| 740 +| `dcfc7a5a3cf7480ce21a0502a3ba0c699bd5f577eb0e059df39470ad31b61f1f` +| `3435bdb41bc22273454fc25416ff43f0fe1687f7` +| Level-1 directory manifest for `verification/`: sub-directories and two invariants. +| Deleted: no mapping spec, no reader. Each sub-directory keeps its `README.adoc`. + +| `verification/benchmarks/0.2-AI-MANIFEST.a2ml` +| 170 +| `cce3a2380d24b123bfa544e3fd1804ccc65a09787983a0f6e7136fc2eefc0d55` +| `d922a4c74ecb92d4cf23333a2e3354088ba07324` +| Level-2 directory manifest. +| Deleted: no mapping spec, no reader. + +| `verification/coverage/0.2-AI-MANIFEST.a2ml` +| 286 +| `f246a8fc101ffb74858c936b5856043430b7f79b3fb00a8b4d53de451a692485` +| `32b819e4e0b9737e50c7bb0bd5c94415752633b0` +| Level-2 directory manifest. +| Deleted: no mapping spec, no reader. + +| `verification/fuzzing/0.2-AI-MANIFEST.a2ml` +| 194 +| `d13f11a5e4b89c462c62316170cd38479df9fc9bcf91a6eb253a5d8c7fb5f7fd` +| `5178d400e913379938d4a170dabbbf4f3f582a1e` +| Level-2 directory manifest. +| Deleted: no mapping spec, no reader. + +| `verification/proofs/0.2-AI-MANIFEST.a2ml` +| 193 +| `1ca920ad7ee6fd38761c0c4b9c783e8855d66719997c4e8c363de935556355b7` +| `135e181bdb33ad26c55732e36f4a1731de53f47d` +| Level-2 directory manifest. +| Deleted: no mapping spec, no reader. + +| `verification/safety_case/0.2-AI-MANIFEST.a2ml` +| 292 +| `05535208c8fc81dfaa4ac54dd394aafa70d2cbff1f1a9c65a1a661f971e2c53e` +| `d461915b8a1a93db9749878b4833c2908e28364b` +| Level-2 directory manifest. +| Deleted: no mapping spec, no reader. + +| `verification/simulations/0.2-AI-MANIFEST.a2ml` +| 202 +| `121289312bd69584a180208a51c6d3d8b9ed1347d6257a06461b52810acfd357` +| `f890ecace2b8d193f19902872e8a8b629b02a339` +| Level-2 directory manifest. +| Deleted: no mapping spec, no reader. + +| `verification/tests/0.2-AI-MANIFEST.a2ml` +| 31 +| `0f89582da96de1f765583999e8f8020e7ce2f96ba3a66feba6d55190670f48a6` +| `0008fcfaf28d6f8cf4c65c0f0ca5e2542f166a09` +| One-line placeholder heading. +| Deleted: no content, no reader. + +| `verification/traceability/0.2-AI-MANIFEST.a2ml` +| 294 +| `9634abe63221a8c456d10749ee2dd8d559e8e813f3b9aeed34076be683700763` +| `966776651b42a3fdea4191028eb00770b9f5caf3` +| Level-2 directory manifest. +| Deleted: no mapping spec, no reader. + +| `container/0-AI-MANIFEST.a2ml` +| 5227 +| `45b20fa0d1f8db8e250407ef80454e21cff9f1f4aa53d4859dfa346a4e13eef0` +| `ccb5bc51d49dc343c3e96e924ca8b5e198193219` +| Directory manifest for `container/`: purpose, canonical locations of the container templates. +| Deleted: no mapping spec, no reader. Its row in `container/README.adoc` is removed. + +| `.machine_readable/ENSAID_CONFIG.a2ml` +| 5539 +| `0e14bdc701573c93154600126249e0ab5dfa676d9470870185b0e5538504cbc9` +| `b3863199b6d280d7f40ca79fcba013ed273ae506` +| eNSAID environment config for PanLL: workspace mode, protection, execution, preferences; panels, workflows, clades and portfolios held only commented examples. +| Deleted: no mapping spec; nothing in this repository reads it, and the estate copies are template boilerplate. + +| `.machine_readable/dev-toolchain.a2ml` +| 2512 +| `0908d9e5180886e96f7c796df004c155d6f52b448483e3611704fe04690f38e4` +| `df06945dbf2352a7d5b2c98f59ccfa9667228e61` +| Local dev-loop toolchain paths (rust-analyzer, cargo, zig, julia, idris2) on the owner's machine, and the owner's standing authorization (2026-05-18) to use the boj dev-loop capabilities on demand. +| Deleted: no mapping spec, no reader (it says bsp-mcp and dap-mcp "should read" it; neither does). The authorization note is preserved here by reference. + +| `.machine_readable/agent_instructions/methodology.a2ml` +| 4662 +| `eabce56e69c9abda4461ab16800c32ff6204893a38029e979b4df486987a0207` +| `06221affb49529bb171f5175701256cb7d68f013` +| Agent methodology: mode, priority weights, budgets, fallback files. +| Deleted: template methodology with no mapping spec and no machine reader. The directory's README went with it. + +| `.machine_readable/agent_instructions/coverage.a2ml` +| 2233 +| `ce9e1e2124e3a7d7dc86e3704d0bb68cf81eae1185fe6e6ddcf98c505ff1975d` +| `69796642033856ce09e8282f9dc2479500e07747` +| Agent session-coverage tracker (template). +| Deleted: no mapping spec, no reader. + +| `.machine_readable/agent_instructions/debt.a2ml` +| 1879 +| `ae4680c353b887ddc636d5e0002dd79c94e917c69a33cb24d0a58e53e2178e9f` +| `c0238c5dfa488ecb12ab9e8f45d9fefac2b71f0e` +| Agent meander-debt list (template). +| Deleted: no mapping spec, no reader. + +| `.machine_readable/contractiles/adjust/Adjustfile.a2ml` +| 2959 +| `78bb5b021255eb633d53d9bdfa00d0796695867b62bac734659a0f36a0803fbd` +| `dcdc660f66ca7425668b0f5c911d498a1721fe90` +| Adjust contractile: WCAG 2.2 AA accessibility invariants. +| Deleted: no mapping spec (A7 Q7). `adjust.ncl` now names `Adjustfile.deed` (A7 8.1), not yet written. + +| `.machine_readable/contractiles/bust/Bustfile.a2ml` +| 1578 +| `d1500f38c4a3bfdd84249fea9f0b5d9724251a2ed98067f0a0b47a22872277ff` +| `62af44e6900ff194d5bae54db61f1328b1b55cd7` +| Bust contractile: meta-repo rollback scenarios and escalation ladder (template residue). +| Deleted: no mapping spec. `bust.ncl` now names `Bustfile.deed`, not yet written. + +| `.machine_readable/contractiles/dust/Dustfile.a2ml` +| 428 +| `97be661ba2ed968063f8a8dc93bd06d4a3d7f1a9c2a6108c279ffc33cbea59a5` +| `8c61f268ea08d84b68be9ab1dd31950c6eb716c9` +| Dust contractile: one source-rollback path. +| Deleted: no mapping spec. `dust.ncl` now names `Dustfile.deed`; `contractile.just` keeps its generated recipes. + +| `.machine_readable/contractiles/intend/Intentfile.a2ml` +| 2627 +| `c3327b7a86eb1245eb6cd4b3d6df76d2c424fcd600351dba317e220c0df807f6` +| `fc1e73744cd7688776b5956018b3660b49424243` +| Intent contractile: purpose, anti-purpose, architectural invariants. +| Deleted: no mapping spec. `intend.ncl` now names `Intentfile.deed`, not yet written. + +| `.machine_readable/contractiles/must/Mustfile.a2ml` +| 1523 +| `847f9e7f4ae667b1282b2e373aec6ab5e36edb33df3fdac8b44d0a5ee51d7965` +| `b16f5e0a33fd78f0403d82f3ac0ad7472bc62d43` +| Must contractile: physical-state checks (licence, README, SECURITY, Justfile, package.json, banned files, env files, SPDX, mcp-bridge). +| Deleted: no mapping spec. `must.ncl` now names `Mustfile.deed`; `contractile.just` keeps its generated must recipes. + +| `.machine_readable/contractiles/trust/Trustfile.a2ml` +| 43450 +| `abdb3ecb8fae889a5ae4a9e84ffe5dc6d76c55acbe35a7ca47b8c16106671498` +| `4a684faaf9b80241083987d6ba03ce3d43548b51` +| Trust contractile: threat model, DNS, email, TLS, Cloudflare edge, headers, container and dependency supply chain, gateway, proofs, verification ladder, signature block. +| Deleted: no mapping spec, no machine reader. `trust.ncl` now names `Trustfile.deed`, not yet written. Runbook steps that flip a Trustfile status (`docs/integration/hcg-tier2-rollout-runbook.adoc`) have no target until it exists. + +| `.machine_readable/integrations/feedback-o-tron.a2ml` +| 621 +| `4ddac358aa8295640c42cc1685b192677450d9012ce66033a135f69f02566c15` +| `6841c69b604f21c71f32aaf8b36af5801e74b2e0` +| Integration note: feedback-o-tron bug-reporter intake. +| Deleted: no mapping spec, no reader. + +| `.machine_readable/integrations/proven.a2ml` +| 612 +| `11fabb802ac4a0285caa64c4000436c3e1b386b7a6190d735e10be0fb910dbd9` +| `9af33ffdc7e9faced46b474f2a07df389c9e1631` +| Integration note: proven safety-library adoption guidance. +| Deleted: no mapping spec, no reader. + +| `.machine_readable/integrations/verisimdb.a2ml` +| 387 +| `48f716912dbe895d0f4f59a767c22cea517fcb9bc3637b1540558cd3f647cc51` +| `164c5229a7e2a507cb9f123ccd681159a3376005` +| Integration note: VeriSimDB data feed config. +| Deleted: no mapping spec, no reader. + +| `.machine_readable/integrations/vexometer.a2ml` +| 444 +| `3f85155335da36a216049bc4434f976d19580b6bcd49c020117a5c133e3b9145` +| `238b3d2cdd3a9c59f5e21dcdadba8aaf81d24214` +| Integration note: vexometer measurement config. +| Deleted: no mapping spec, no reader. + +| `.machine_readable/policies/MAINTENANCE-AXES.a2ml` +| 1795 +| `dcf30e7273a9767b4a85ef89de87e1b3cc1c17ad0332f4e12910e5b9d7252702` +| `2428ef74183597a28ef2b97863e3d73f5acedb71` +| Maintenance governance model: entry points, axes, scoping, axis-2 and axis-3 rules, tooling. +| Deleted: no mapping spec. Its only reader, the `validate-rsr` recipe, now checks the `(meta)` axes in the chora deed. Its tooling lines (panic-attack, sustainabot) did not translate. + +| `.machine_readable/policies/MAINTENANCE-CHECKLIST.a2ml` +| 3567 +| `24a58123c8c31fdd02fdc2bee7dea7616fa0ea11df052e73b668bce4160bc0cb` +| `0e065e94fd1165ac1726df58c3b8d6b98dbd77c7` +| Cross-repo maintenance baseline: must/should/could lists. +| Deleted: no mapping spec. The human checklist is `docs/maintenance/MAINTENANCE-CHECKLIST.adoc`; `validate-rsr` checks that file instead. + +| `.machine_readable/policies/SOFTWARE-DEVELOPMENT-APPROACH.a2ml` +| 1582 +| `b8840c589be930c7c6a4384485c84afbf0da19d5eb2790cf98a8a6d2b28c8f8f` +| `093573a07ef2c3cf189dd37cabfb1b40159e0f9b` +| Machine copy of the software development approach (axes, cleanup, collaboration). +| Deleted: no mapping spec. The human document is `docs/practice/SOFTWARE-DEVELOPMENT-APPROACH.adoc`. + +| `.machine_readable/servers/menu.a2ml` +| 21992 +| `d6677554f859f612cd64ac35dbc6b13e5a887d2cdb8ef1bc250e201492778a8a` +| `10602cc985fb727315fa73b852339fd353e7e355` +| The Teranga menu catalogue: the capability matrix, 45 cartridge entries in three tiers, community nodes and an attestation placeholder. +| Deleted: no mapping spec, no reader in this repository or found by an estate code search. The live menu is `GET /menu`, built from each `cartridge.json`; the docs that told contributors to edit this file now say so. + +| `.machine_readable/servers/order-ticket.a2ml` +| 4024 +| `675c0e7ea0e6ecc81f0cd7e27490b17b36aa373adcd98dd75f0ed47cee2e7cc7` +| `5b4534e0e3edde9bfc410896554cbfe0e9df43e7` +| Order-ticket protocol specification (format, fields, validation flow). +| Deleted: no mapping spec, no reader. The endpoint stays specified as `/order-ticket` in `docs/specification/openapi.yaml`. + +| `docs/examples/extension.a2ml` +| 1240 +| `b0906a7d02b498dc74b6b9b2e19755f7d4d93e6a97c6df1917ef8817d3c92bb6` +| `b0ee5eb675de798ac802ef0309de8f4c3b665dfc` +| Example extension descriptor in A2ML. +| Deleted: no reader, and it recommended A2ML. `docs/EXTENSIBILITY.adoc` §1 gives the descriptor as a cartridge manifest. + +|=== + +== Retained, with the reason + +Four `.a2ml` files stay, each because a live reader still needs exactly that +input and has no deed form to read yet. None may gain a fact; content may only +be deleted from them. + +[cols="3,1,3,3,5",options="header"] +|=== +| Path | Size | sha256 | Git blob id | Why it stays + +| `.machine_readable/6a2/ECOSYSTEM.a2ml` +| 735 (was 5066) +| `015ea9e740037a84d65f17dd41bdf96e2e886692d273d65355badce2a9782a96` (was `bbf95d4c7164ff725bc326a05223af15846fdd1dcfecc3a39790b55000d030d8`) +| `475736051b755e5dc6a2e1e5d9b2fb41d7ccc014` (was `a9d253082d43f8830c5463f41597c9da50fe0372`) +| `.github/workflows/readme-derive.yml`, inlined from standards' +`readme-derive-reusable.yml`, reads its `[publishing.readme]` block to derive +`README.md` for Glama, and has no deed reader yet (A7 section 10: the +replacement is `ECOSYSTEM.deed` read with `deed_lint.js --ast-json`). Deleting +the file would silently turn the derivation and its freshness check off. Every +other section was deleted, since none translates under +`meta-ecosystem-to-repo-deed.adoc`: its `[project] name` is not the canonical +name (P-6), its sections are not the table's rows, and all nine +related-project relationships (dependency, supersedes, primary-consumer, +integration, sibling-standard, origin) are outside the closed set. The deleted +sections are `[metadata]`, `[project]`, `[position-in-ecosystem]`, +`[related-projects]`, `[integration-points]` and `[distribution-model]` (the +four fly.io seed nodes and the DNS status). It goes when the reusable reads +`ECOSYSTEM.deed`. + +| `audits/assail-classifications.a2ml` +| 44450 +| `869fca77110152a0801cebe0687764dac7169f9765fe3ceb6a63d907cfd08d16` +| `191279d7b61da9d54c910240b53debd45797a139` +| panic-attack's classifications registry: it flips audited findings to +suppressed. panic-attack's main branch reads +`audits/assail-classifications_praxis.deed` first since 2026-11-14, but no +released binary does, and panicbot and local runs read only this name. +Deleting it would unsuppress the audited findings. It goes when the deed +reader ships and the registry is written as that praxis deed. + +| `.boj/project-memories.a2ml` +| 4749 (was 4848) +| `54574c577980394826b9d3dd776a7660e5ec0751fbcc5139824eab172dbc6df9` (was `2dc552adf90d7958ad4ccf5ff531e361e883ab14ed1498c25b18e8fb1ffdc0d8`) +| `45c045aaa7a879faaa845efc4e66b85a1f09adf5` (was `63e457ad40043135e31034ff397fe692811b2e73`) +| The standing worker briefing. The owner's coord-tui hook +(`~/.config/coord-tui/coord-hooks.sh`, outside this repository) prepends it to +a worker's system prompt when it exists at this path (recorded in the retired +STATE journal, 2026-04-27). Deleting it would silently drop the briefing. +Its on-start step 3 ("Read the plan": `cat .machine_readable/6a2/STATE.a2ml`) +was deleted, since that file is gone. It goes when that hook reads another +form. + +| `panll/src/Boj.a2ml` +| 2996 +| `6489ba99ecc58b994b6ac5487c85f6fd1b8fe7bbc3ebbbb8d7b94f16b1646774` +| `a644193551bced4b7fa0be7505b7c95b2c289e96` +| The BoJ clade definition for PanLL's panel registry. PanLL's CladeLoader +reads clade definitions as `.a2ml` (its own `panel-clades/clades/*/*.a2ml`), +and this file's header names it as that loader's input. It could not be +verified from this session whether PanLL loads this copy, so it stays until +PanLL's loader reads a deed form. +|=== + +== Open points for the owner + +. `[clade] rationale` was empty in `CLADE.a2ml`, and the registry row has no + rationale, but the chora deed's `(clade :rationale)` holds a sentence. Its + source is not recorded. It is left as it was. +. META's `license` was not translated: the meta spec's open question 2 (is + `(meta :license)` the one machine-checked licence surface?) is unruled. +. The `(anchor (implementation-policy))` lists are translated verbatim from + ANCHOR.a2ml. They predate later rulings (they list "JavaScript (Deno)" and + forbid npm, which is now tier 4 and permitted as a last resort). The lists are + informative only; correcting them is a content decision. +. No `file.deed` edict exists yet, so the six contractile runners name + files that are not written, and each still sets `report_format = "a2ml"`. diff --git a/docs/maintenance/MAINTENANCE-CHECKLIST.adoc b/docs/maintenance/MAINTENANCE-CHECKLIST.adoc index f390f041..eb1fddae 100644 --- a/docs/maintenance/MAINTENANCE-CHECKLIST.adoc +++ b/docs/maintenance/MAINTENANCE-CHECKLIST.adoc @@ -5,8 +5,8 @@ Use this as a repeatable maintenance runbook for any repo. Companion policy: * `+docs/practice/SOFTWARE-DEVELOPMENT-APPROACH.adoc+` (human-readable) -* `+.machine_readable/policies/SOFTWARE-DEVELOPMENT-APPROACH.a2ml+` -(machine-readable) +* the `+(meta …)+` clause of `+boj-server_chora.deed+` (machine-readable +maintenance axes) === Canonical Repo Baseline (Final) @@ -113,8 +113,8 @@ compatibility) ** `+.github/CODEOWNERS+` * [ ] Keep machine-readable canonical structure under `+.machine_readable/+`: -** state/meta/ecosystem files (`+*.a2ml+` or repo standard) -** `+anchors/ANCHOR.a2ml+` +** repo facts in the root chora deed (`+_chora.deed+`: `+(status)+`, +`+(meta)+`, `+(anchor)+`), never `+*.a2ml+` (A2ML is retired) ** `+contractiles/+` (`+must+`, `+trust+`, `+lust+`, and related) ** `+ai/+` for AI guidance files ** `+bot_directives/+` for bot control files diff --git a/docs/practice/TESTS-AND-BENCHES.adoc b/docs/practice/TESTS-AND-BENCHES.adoc index eb0ff5e7..634fb51a 100644 --- a/docs/practice/TESTS-AND-BENCHES.adoc +++ b/docs/practice/TESTS-AND-BENCHES.adoc @@ -120,5 +120,5 @@ cd elixir && mix test * link:../TEST-NEEDS.md[TEST-NEEDS.md] — Detailed requirement tracking. * READINESS.md — CRG Grade evidence. -* `.machine_readable/6a2/STATE.a2ml` — retired A2ML (D308), pending kyX → chora -deed; not a current source of stats. +* `STATE.a2ml` was retired on 2026-11-14 (`docs/history/A2ML-REMOVED.adoc`); +it is not a source of stats. diff --git a/docs/quickstarts/BUILD-FROM-SOURCE.adoc b/docs/quickstarts/BUILD-FROM-SOURCE.adoc index bd26d04f..b128a193 100644 --- a/docs/quickstarts/BUILD-FROM-SOURCE.adoc +++ b/docs/quickstarts/BUILD-FROM-SOURCE.adoc @@ -172,7 +172,7 @@ See `container/` for: == Extending -See `docs/EXTENSIBILITY.adoc` and `docs/examples/extension.a2ml` for how to +See `docs/EXTENSIBILITY.adoc` for how to create backend-specific cartridge extensions without modifying core code. == Submitting feedback diff --git a/docs/quickstarts/USER.adoc b/docs/quickstarts/USER.adoc index 49d654ec..485429c0 100644 --- a/docs/quickstarts/USER.adoc +++ b/docs/quickstarts/USER.adoc @@ -225,4 +225,4 @@ The four canonical seed nodes are declared in `container/seed-nodes.toml`. - `docs/FEDERATION.adoc` -- Distributed hosting model - `docs/developer/README.adoc` -- Contributing cartridges - `docs/CULTURAL-RESPECT.adoc` -- Teranga/Umoja/Ayo terminology -- `0-AI-MANIFEST.a2ml` -- Machine-readable project manifest +- `boj-server_chora.deed` -- Machine-readable repo facts (`0-AI-MANIFEST.deed` points to it) diff --git a/docs/wikis/CI-and-Required-Checks.adoc b/docs/wikis/CI-and-Required-Checks.adoc index 70e7c794..b84b118b 100644 --- a/docs/wikis/CI-and-Required-Checks.adoc +++ b/docs/wikis/CI-and-Required-Checks.adoc @@ -123,6 +123,6 @@ actually *reported* -- a `skipped` conclusion counts as success. A gate stuck at * Conventions (authoritative): `docs/AI-CONVENTIONS.adoc` §"CI / Required Status Checks" * AI-agent instructions: `.claude/CLAUDE.md` §"CI / Required Status Checks" -* Operational runbook: this page and `docs/AI-CONVENTIONS.adoc`. The old `6a2/PLAYBOOK.a2ml` entry is retired A2ML (D308), pending kyX → chora deed. +* Operational runbook: this page and `docs/AI-CONVENTIONS.adoc`. The old `6a2/PLAYBOOK.a2ml` entry was retired on 2026-11-14 (`docs/history/A2ML-REMOVED.adoc`); its runbook content had no deed row. * Reference workflows: every required gate in `.github/workflows/` * History: PR #216 (boj-server), PR #45 (boj-server-cartridges) diff --git a/docs/wikis/Developer-Guide.adoc b/docs/wikis/Developer-Guide.adoc index 14b64aea..e131d7ce 100644 --- a/docs/wikis/Developer-Guide.adoc +++ b/docs/wikis/Developer-Guide.adoc @@ -186,7 +186,7 @@ Ensure your cartridge: === 6. Register in the menu -Add your cartridge to `.machine_readable/servers/menu.a2ml` under the *Ayo* section (community tier). Set status to `Development` initially. +The menu (`GET /menu`) is built from each cartridge's `cartridge.json`: set `"tier": "Ayo"` there (community tier), and set status to `Development` initially. === 7. Pass the IsUnbreakable proof @@ -205,7 +205,8 @@ The third axis allows community extensions to specialise a cartridge for a speci === Write an extension descriptor -Create a `.a2ml` file: +Write the descriptor as a cartridge manifest (currently `cartridge.json`); see +link:../EXTENSIBILITY.adoc[EXTENSIBILITY] §1 for the format. The fields are: [source,toml] ---- diff --git a/docs/wikis/FAQ.adoc b/docs/wikis/FAQ.adoc index 23ddd3bb..f363e0e0 100644 --- a/docs/wikis/FAQ.adoc +++ b/docs/wikis/FAQ.adoc @@ -122,7 +122,7 @@ If your tool isn't covered by an existing cartridge, you can create a *community == What is the Teranga menu? -The Teranga menu is the public catalogue of available capabilities, stored at `.machine_readable/servers/menu.a2ml`. It has three tiers: +The Teranga menu is the public catalogue of available capabilities, served at `GET /menu` and built from the `tier` each cartridge declares in its `cartridge.json`. It has three tiers: [cols="1,1,1,1",options="header"] |=== diff --git a/site/.well-known/ai.txt b/site/.well-known/ai.txt index d278c100..55feb8a8 100644 --- a/site/.well-known/ai.txt +++ b/site/.well-known/ai.txt @@ -12,6 +12,6 @@ Disallow-Generation: yes # AI agents must NOT use this code for model training without explicit consent. # # For AI agent integration instructions, see: -# 0-AI-MANIFEST.a2ml (universal AI entry point) -# AI.a2ml (Claude-specific instructions) +# 0-AI-MANIFEST.deed (machine front door; points to boj-server_chora.deed) +# .claude/CLAUDE.md (agent conventions) # .machine_readable/ (structured project state) diff --git a/verification/0.1-AI-MANIFEST.a2ml b/verification/0.1-AI-MANIFEST.a2ml deleted file mode 100644 index 3435bdb4..00000000 --- a/verification/0.1-AI-MANIFEST.a2ml +++ /dev/null @@ -1,27 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "verification-pillar" -level: 1 -parent: "../0-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Primary verification pillar. Contains evidence for correctness, - performance, formal proofs, randomized testing, and aerospace-grade - high-assurance metrics (MC/DC coverage, traceability, safety cases). - -canonical_locations: - tests: "tests/" - benchmarks: "benchmarks/" - proofs: "proofs/" - fuzzing: "fuzzing/" - simulations: "simulations/" - coverage: "coverage/" - traceability: "traceability/" - safety_case: "safety_case/" - -invariants: - - "Evidence MUST be reproducible and documented" - - "High-assurance deployments MUST satisfy traceability and safety_case requirements" diff --git a/verification/benchmarks/0.2-AI-MANIFEST.a2ml b/verification/benchmarks/0.2-AI-MANIFEST.a2ml deleted file mode 100644 index d922a4c7..00000000 --- a/verification/benchmarks/0.2-AI-MANIFEST.a2ml +++ /dev/null @@ -1,11 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "benches-pillar" -level: 2 -parent: "../0.1-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Benches pillar. diff --git a/verification/coverage/0.2-AI-MANIFEST.a2ml b/verification/coverage/0.2-AI-MANIFEST.a2ml deleted file mode 100644 index 32b819e4..00000000 --- a/verification/coverage/0.2-AI-MANIFEST.a2ml +++ /dev/null @@ -1,12 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "verification-unit-coverage" -level: 2 -parent: "../0.1-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - High-assurance verification unit for coverage. - Critical for safety-of-life and aerospace-grade deployment standards. diff --git a/verification/fuzzing/0.2-AI-MANIFEST.a2ml b/verification/fuzzing/0.2-AI-MANIFEST.a2ml deleted file mode 100644 index 5178d400..00000000 --- a/verification/fuzzing/0.2-AI-MANIFEST.a2ml +++ /dev/null @@ -1,11 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "fuzzing-unit" -level: 2 -parent: "../0.1-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Fuzzing unit for high-rigor verification. diff --git a/verification/proofs/0.2-AI-MANIFEST.a2ml b/verification/proofs/0.2-AI-MANIFEST.a2ml deleted file mode 100644 index 135e181b..00000000 --- a/verification/proofs/0.2-AI-MANIFEST.a2ml +++ /dev/null @@ -1,11 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "verification-unit-proofs" -level: 2 -parent: "../0.1-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Sub-unit focusing on proofs. diff --git a/verification/safety_case/0.2-AI-MANIFEST.a2ml b/verification/safety_case/0.2-AI-MANIFEST.a2ml deleted file mode 100644 index d461915b..00000000 --- a/verification/safety_case/0.2-AI-MANIFEST.a2ml +++ /dev/null @@ -1,12 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "verification-unit-safety_case" -level: 2 -parent: "../0.1-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - High-assurance verification unit for safety case. - Critical for safety-of-life and aerospace-grade deployment standards. diff --git a/verification/simulations/0.2-AI-MANIFEST.a2ml b/verification/simulations/0.2-AI-MANIFEST.a2ml deleted file mode 100644 index f890ecac..00000000 --- a/verification/simulations/0.2-AI-MANIFEST.a2ml +++ /dev/null @@ -1,11 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "simulations-unit" -level: 2 -parent: "../0.1-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Simulations unit for high-rigor verification. diff --git a/verification/tests/0.2-AI-MANIFEST.a2ml b/verification/tests/0.2-AI-MANIFEST.a2ml deleted file mode 100644 index 0008fcfa..00000000 --- a/verification/tests/0.2-AI-MANIFEST.a2ml +++ /dev/null @@ -1 +0,0 @@ -# AI Manifest - Level 1: tests diff --git a/verification/traceability/0.2-AI-MANIFEST.a2ml b/verification/traceability/0.2-AI-MANIFEST.a2ml deleted file mode 100644 index 96677665..00000000 --- a/verification/traceability/0.2-AI-MANIFEST.a2ml +++ /dev/null @@ -1,12 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "verification-unit-traceability" -level: 2 -parent: "../0.1-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - High-assurance verification unit for traceability. - Critical for safety-of-life and aerospace-grade deployment standards.