Architecture

Repository architecture

A summary of the repo layout. The canonical text lives in TOPOLOGY.md — this page repeats it with extra cross-links into the wiki and ecosystem.

Purpose

Custom Julia package registry aggregating all hyperpolymath Julia packages. Provides a unified package index, dependency resolution, and installation entry point for post-disciplinary research, formal verification, and verified-computing libraries.

Module map

julia-professional-registry/
├── Registry.toml             # the canonical index — source of truth for clients
├── A/  B/  C/  ...           # per-letter package directories (Julia registry convention)
│   └── <Package>/
│       └── <Version>/
│           ├── Package.toml
│           ├── Versions.toml
│           ├── Deps.toml
│           ├── Compat.toml
│           └── WeakCompat.toml
├── tests/                    # Idris2 contract tests (CRG Grade C)
├── julia-professional-registry-tests.ipkg
├── .github/
│   ├── workflows/            # CI: governance + hypatia-scan + codeql + scorecard +
│   │                         #     mirror + secret-scanner + boj-build + casket-pages
│   ├── ISSUE_TEMPLATE/
│   ├── CODEOWNERS
│   ├── FUNDING.yml
│   ├── copilot-instructions.md
│   └── pull_request_template.md
├── .machine_readable/        # AI-agent metadata, dual-track convention
│   ├── 6a2/                  # canonical: STATE / META / ECOSYSTEM
│   ├── integrations/         # per-system integration descriptors
│   ├── agent_instructions/   # agent-facing methodology and debt
│   ├── anchors/              # immutable reference points
│   ├── contractiles/         # contractile policy files (INTENT / MUST / TRUST / ADJUST)
│   ├── CLADE.a2ml            # repo classification (the "clade")
│   └── ...
├── 0-AI-MANIFEST.a2ml        # AI agent entry point — read this first
├── README.adoc
├── EXPLAINME.adoc            # "show me the receipts" — annotated tour
├── TOPOLOGY.md               # this file's source
├── TEST-NEEDS.md
├── ROADMAP.adoc
├── GOVERNANCE.adoc
├── MAINTAINERS.adoc
├── CONTRIBUTING.md
├── CODE_OF_CONDUCT.md
├── SECURITY.md
├── CHANGELOG.md
├── LICENSE
├── LICENSES/                 # REUSE-compliant license texts
├── NOTICE
├── flake.nix                 # Nix dev shell (legacy — Guix is canonical)
├── guix.scm                  # Guix dev shell (canonical per standards#101)
├── Justfile                  # build/test/lint task runner
└── stapeln.toml              # stapeln dependency manifest

Component roles

Registry.toml

The flat index that Julia's Pkg machinery reads when you call Pkg.Registry.add. Adding a package requires editing this file; not editing it on a registration PR is a common mistake.

Per-letter directories

Julia registry convention — packages are bucketed by their first letter to keep any single directory's child count manageable. Inside each <Letter>/<Package>/<Version>/ directory, the four-to-five canonical TOML files describe what version exists, what it depends on, and what versions of those deps are compatible.

tests/ + the ipkg

The CRG Grade C test suite is Idris2-based — it parses Registry.toml and the per-package metadata, then asserts properties (no duplicate UUIDs, every entry resolves to a per-letter directory, compat ranges are well-formed, etc.). See Testing.

Workflows

Workflow	Role
governance.yml	Calls standards/governance-reusable: SPDX, license, RSR, banned-language checks
hypatia-scan.yml	Calls standards/hypatia-scan-reusable: full CI/CD intelligence scan
codeql.yml	CodeQL static analysis, matrix scoped to language: actions (the repo's only analysable surface)
scorecard.yml	OpenSSF Scorecard via standards reusable
secret-scanner.yml	Secret-scanning via standards reusable
mirror.yml	Multi-forge mirroring via standards reusable
boj-build.yml	Triggers boj-server (Casket / ssg-mcp) build
casket-pages.yml	Builds the Casket-rendered docs site

All wrapper workflows are SHA-pinned to a specific standards commit; the floating @main pattern is forbidden.

.machine_readable/

The dual-track convention: human-readable docs at the root, machine-readable metadata in .machine_readable/. AI agents (Claude Code, Copilot, Hypatia) read 0-AI-MANIFEST.a2ml first, then drill into the canonical 6a2/ subdirectory.

The integrations files describe how this repo connects to other estate components: verisimdb (canonical flat-file store), proven (proof infrastructure), vexometer (verification meter), feedback-o-tron (outcome tracking).

What this repo is not

• Not a fork of JuliaRegistries/General — see Roadmap § Non-goals.
• Not a host of package source code — packages live in their own repos; this is an index.
• Not a CI surface for the registered packages themselves — each package runs its own CI in its own repo.