LibPolycall

LibPolycall

LibPolycall is a small native runtime and CLI for polymorphic function calls: one caller (an application, or the polycall CLI) invokes a named service and method with typed arguments and gets back a typed result or a structured error, regardless of which language actually implements that method.

caller  --(service, method, typed args)-->  runtime  --(wire protocol)-->  provider
caller  <--(typed result / structured error)-- runtime <----------------------┘

A concrete example, verified end to end in this repository: a Python process implements

def add(a: int, b: int) -> int:
    return a + b

registers it as math.add with the runtime, and the polycall CLI — written in C, with no addition logic of its own — sends add(2, 3) through the runtime and receives 5 back. See Your first Python call for the full, reproducible walkthrough.

Why "polyglot"

Two services declared in the same Polycallfile can be implemented in different languages without the caller knowing or caring which. The runtime does not translate between language type systems implicitly — every method has a declared, typed signature (i64, string, bool, ...), and arguments are checked against it before a provider ever sees them. "Polyglot" describes the deployment (many languages can participate), not automatic type coercion between them.

What actually exists today

This documentation distinguishes three things throughout, because they are not the same:

Verified

Exercised in this repository this session, or backed by a checked-in, reproducible test. Safe to build on.

Proposed standard / partial

Written into the LPV1 standards as a target, or implemented for only part of its stated scope. Read the requirement text before depending on it.

Historical / unsupported

Described in older project material (a README, a demo transcript, an early trial build) but not present in the current implementation. See the historical migration guide.

As of this writing, concretely:

Area Status
config validate, config show, doctor check, version show Verified
Python provider over the real wire protocol (add(a, b)) Verified
C provider via the public polycall_provider_* API Verified
runtime start/stop lifecycle, including graceful shutdown Verified (a Linux-only shutdown hang was found and fixed this session)
runtime status/reload, service list/inspect, telemetry snapshot Registered, but honestly report unavailable — Phase F's management protocol isn't built yet
config migrate Registered, reports unsupported — no historical-format reader yet
Node, Lua, Go, Java, COBOL bindings Declared as valid service.*.language values in the schema; no working example or SDK ships for them yet
Zero-trust security architecture, "system consciousness" telemetry, IaaS platform claims from early project material Not implemented; see the migration guide

Where to go next