PolyAPI prototype

PolyAPI is a typed API language and compiler for generating semantically equivalent service implementations in multiple programming languages. The core repository contains the language frontend, canonical security-aware IR, target factory, generators, proxy, configuration model, and normative specifications. Deployable applications and their generated artifacts live under examples/.

flowchart LR
    S[".poly source"] --> T["Tree-sitter frontend"]
    T --> IR["polyapi.ir/v2 or v3"]
    IR --> G["Go target"]
    IR --> P["Python target"]
    IR --> R["Rust target profile"]
    IR --> J["Java target profile"]
    IR --> D["Postgres migration"]

Loading

Go, Python, Rust, Java, Postgres, and bundle generators are implemented. The v3 password-session profile requires the complete five-target compatibility set and rejects emission if its compiler-owned operation graph or security contract is changed.

Core development

Install the committed Tree-sitter tooling and run core tests:

npm ci
make test

Compiler commands require explicit inputs and output locations so running the CLI cannot accidentally write application artifacts into the repository root:

go run ./cmd/polyapi lower \
  -spec examples/quote/quote.poly

go run ./cmd/polyapi compile \
  -spec examples/quote/quote.poly \
  -targets go,python,postgres,bundle \
  -out /tmp/polyapi-generated

go run ./cmd/polyapi validate-ir \
  -ir examples/quote/quote.ir.json

Examples

Examples are isolated applications with their own specification, checked IR, generated artifacts, host wiring, Dockerfile, Compose stack, dependencies, scripts, and README.

• Quote service — Go/Python UDS routing with immutable idempotent Postgres persistence.
• Authentication service — embedded Go/Python/Rust/ Java UDS routing with Argon2id bearer sessions, users, organizations, least-privilege Postgres functions, and adversarial security tests.
• Example directory contract — required layout for new example specifications.

Convenience targets are namespaced by example:

make quote-generate
make quote-test
make quote-e2e
make quote-run
make auth-generate
make auth-test
make auth-security
make auth-e2e
make auth-run

Specifications

• Language specification
• Canonical IR specification
• Backend execution profile
• Postgres persistence profile
• Password-session authentication profile
• Executable grammar and Tree-sitter grammar
• Strict IR JSON Schemas: v2 and v3 auth

Core layout

Path	Purpose
cmd/polyapi	Compiler command with explicit source/output flags.
internal/frontend	Tree-sitter CST decoding, typed AST, diagnostics, and lowering.
internal/ir	Canonical IR validation and security-flow verification.
internal/compiler	Backend factory and Go, Python, Rust, Java, Postgres, and bundle generators.
internal/config	Typed runtime configuration and environment parsing.
internal/router	UDS reverse proxy, health quarantine, and bounded telemetry.
internal/spec	Temporary bootstrap emitter model.
grammar and tree-sitter-polyapi	Normative and executable grammars.
docs and schema	Versioned language, IR, backend, persistence, and JSON contracts.
examples	Fully isolated application specifications and deployments.

The frontend uses the committed Tree-sitter ABI 15 parser through its Go binding. Tree-sitter and CGo are compiler build-time dependencies; generated Go hosts can still be built with CGO_ENABLED=0.