Explicit logic declarations for program verification and optimization.

Topo extracts the logical requirements of a program — what's public, what must run before what, what can run in parallel — from implicit code patterns into explicit .topo declarations. These declarations are contracts: the toolchain verifies code compliance and uses them to enable aggressive optimizations.

namespace engine {
  public:
    void render(int handle);

    fn render {
      stage<1> loadShaders();
      stage<1> prepareBuffers();
      stage<2> drawFrame();
    }

  protected:
    void loadShaders();
    void prepareBuffers();
    void drawFrame() const;

    external void writeLog(int code);
}

• Undeclared behavior is forbidden. Non-external functions cannot reach system capabilities (file I/O, network, processes). Violations are compile-time errors, not warnings.
• Declarations enable optimization. Explicit stage ordering, parallelism, and visibility give the compiler information beyond what traditional analysis can derive.
• Review focuses on declarations. A 1000-line PR might have 3 unsafe points marked external — reviewers check those, not the entire diff.

Topo ships as 13 independent repositories grouped by responsibility.

• topo-core — declaration language core (Lexer / Parser / Sema / Analysis / Check / Transform / Transpile / Build / Platform). Zero LLVM dependency; the root of every downstream package.
• topo-lang — language plugin framework (Registry, EmitterFactory, BuildDriverFactory, InitTemplateProvider, CheckRunnerBase).

• topo-llvm — LLVM backend: 17 IR passes, C-ABI runtime, JIT engine, bundled llvm-dev.
• topo-jvm — JVM backend: ASM bytecode transformer (15 passes), Gradle integration.
• topo-v8 — V8-family backend (TypeScript today, JavaScript later); currently a forwarding layer over tsserver.

• topo-lang-cpp — C++
• topo-lang-rust — Rust
• topo-lang-java — Java
• topo-lang-python — Python
• topo-lang-typescript — TypeScript

• topo-lsp — LSP server, routes per [build].language to each host bridge.
• topo-tpm — Topo package manager (.topo declaration packages, MVP).
• topo-cli — top-level CLIs: topo-check, topo-build, topo-init, topo-transpile, topo-profile.

• topo-meta — agent workspace bundling all 13 repos for cross-project development. Not a production dependency.

Each language SDK is a standalone repo — install only what you use.

# Example: C++ project
git clone https://github.com/topo-lang/topo-lang-cpp /tmp/topo-lang-cpp
cmake -S /tmp/topo-lang-cpp -B /tmp/topo-lang-cpp/build
cmake --build /tmp/topo-lang-cpp/build
cmake --install /tmp/topo-lang-cpp/build --prefix ~/.local

# Then in your project's CMakeLists.txt:
find_package(topo-lang-cpp CONFIG REQUIRED)
target_link_libraries(my_target PRIVATE topo::lang-cpp::TopoCppAnalysis)

Cross-repo dependencies are declared via find_package(<repo> CONFIG REQUIRED); targets use the topo::<sub>::<target> namespace (e.g. topo::core::TopoPlatform, topo::llvm::topo-arena).

For full-stack development (working across multiple sub-repos at once), clone the agent workspace meta-repo:

git clone https://github.com/topo-lang/topo-meta
cd topo-meta
bash topo-llvm/scripts/setup-llvm.sh    # one-time LLVM toolchain
cmake --preset default
cmake --build build
scripts/test.sh

• Org-wide defaults for code of conduct, contributing, and security policy cascade to every Topo repository. Each sub-repo may override with its own.
• File issues / PRs against the specific sub-repo your change touches (see the repo list above).
• For cross-cutting RFCs, open a discussion at the org level.

Each Topo repository is MIT licensed — see the LICENSE file in each repo. The project has been developed with extensive AI assistance; see each repo's AI-DECLARATION.md for provenance details.