LibPolyCall V1.0.0

Archieved Repo

LibPolyCall v1.0.0 configuration uses Polycallfile for writable project topology, Polycallrc for global read-only runtime defaults, and Polycallrc.<language> for language overrides. See docs/CONFIGURATION_STANDARD.md for load order, validation, migration, and CLI commands.

From the Desk of Nnamdi Michael Okpala, Founder — OBINexusComputing

---

Founder	LibPolyCall Version Favicon

"The future isn't coming—it's here. And it speaks every language."

For too long, we've accepted the fragmentation of our digital ecosystem. Python talks to Python. Node.js whispers to JavaScript. Java shouts in its own dialect. Meanwhile, developers waste countless hours building bridges between languages, creating duplicate APIs, and maintaining separate implementations for what should be unified solutions.

This ends now.

The Program-First Revolution

LibPolyCall represents a fundamental shift from "binding-first" to "program-first" architecture. While others build language-specific solutions, we've created something unprecedented: a single protocol that makes language barriers obsolete.

Think about it: Why should your brilliant algorithm be imprisoned in one language? Why should your API exist in five different implementations? Why should your microservices struggle to communicate because they weren't born speaking the same dialect?

The answer is simple: They shouldn't.

Zero-Trust, Maximum Trust

In a world where security breaches make headlines daily, LibPolyCall implements zero-trust architecture at its core. Every component, every connection, every data exchange is validated, encrypted, and monitored. We don't just connect systems—we create secure, intelligent networks that think before they trust.

Our cryptographically-seeded GUID system doesn't just track state; it creates perfect reproducibility. Every bug becomes a learning opportunity. Every interaction becomes intelligence. Every problem becomes solvable.

The Telemetry Advantage

Traditional systems are blind. They process requests without understanding context, handle errors without learning from them, and scale without intelligence.

LibPolyCall sees everything:

• Silent protocol observation captures every interaction
• Real-time analytics reveal patterns others miss
• State machine mapping creates complete user journey intelligence
• Bug replication makes impossible problems possible to solve

This isn't just monitoring—this is system consciousness.

---

Getting Started

Prerequisites

• GCC 9+ or Clang 11+ (C11 support required)
• GNU Make 4+
• POSIX threads (-lpthread)
• Optional: OpenSSL (USE_OPENSSL=1)

Build

# Default build (static lib + shared lib + CLI binary)
make

# Debug build (symbols + DEBUG macro)
make debug

# Optimised release build
make release

# Fully static binary (Linux / MinGW only)
make static

# Rebuild from scratch
make rebuild

The CLI binary is emitted under build/bin and object files are emitted under build/obj.

Install / Uninstall (Unix-like systems only)

sudo make install         # installs to /usr/local by default
sudo make install PREFIX=/opt/polycall   # custom prefix
sudo make uninstall

Clean

make clean        # remove build artefacts
make distclean    # clean + uninstall

All Makefile Targets

Target	Description
all	Build everything (default)
debug	Build with -g -DDEBUG
release	Build with -O2 -DNDEBUG
static	Static executable (Linux / MinGW)
rebuild	Clean then build all
install	Install headers, libs, CLI
uninstall	Remove installed files
distclean	clean + uninstall
help	Print this table

Options: pass USE_OPENSSL=1 to link libssl/libcrypto.

---

CLI Commands

The polycall binary exposes the following commands.

Global flags

polycall --help                            # print usage
polycall --repl                            # interactive REPL (global scope)
polycall --daemon --config Polycallfile    # foreground daemon supervisor

The interactive REPL supports an in-memory PolyCall session, hexadecimal terminal colors, and Tab completion. See docs/POLYCALL_READ_EVAULTE_PRINT_LOOP.md.

Any sub-command also accepts --repl to drop into a scoped REPL after execution:

polycall micro isolate create myapp --repl

Configuration

polycall config load [language]                      # load & validate hierarchy, show load order
polycall config validate [path]                      # validate single file or full hierarchy
polycall config show [language]                      # print merged config to stdout
polycall config rc show <language>                   # print language override file
polycall config rc validate <language>               # validate language override file
polycall config migrate <source> <Polycallrc.lang>   # migrate legacy .polycallrc

Microservices

polycall micro isolate create NAME [--memory SIZE]   # create isolation cell
polycall micro isolate list                          # list active isolation cells

NAME is any identifier; --memory SIZE accepts bytes optionally suffixed with k, m, or g (e.g. --memory 64m).

Edge routing

polycall edge route nearest TARGET --from SOURCE [--strategy astar]

Routes from SOURCE to TARGET using A* on the configured edge graph and prints the path and total cost.

FFI

polycall ffi call TARGET:SYMBOL [--topology local|p2p|network] [--data VALUE]

TARGET is the runtime identifier (e.g. pypolycall, node, java). SYMBOL is the exported function name. Language is inferred from TARGET.

Telemetry

polycall telemetry show                  # list captured events with sequence numbers
polycall telemetry snapshot [--cuid]     # snapshot current event buffer; print CUID if requested

CUID

polycall cuid verify SNAPSHOT_ID         # verify a CUID against the in-process snapshot

Note: a telemetry snapshot --cuid must have been taken in the same process (or REPL session) before cuid verify can succeed.

---

Static Analysis & Memory Safety

Run the linter against the C sources (requires cpplint):

pip install cpplint
cpplint --filter=-legal/copyright,-build/include_subdir,-build/header_guard \
  --extensions=c,h \
  src/core/*.c src/cli/*.c src/main.c

For deeper memory and thread safety analysis (requires cppcheck):

cppcheck --enable=all --std=c11 \
  -I include -I include/core \
  --suppress=missingIncludeSystem \
  src/

For clang-tidy (requires LLVM):

clang-tidy src/core/*.c src/cli/*.c -- \
  -std=c11 -I include -I include/core

Known Antipatterns (v1.0.0 audit)

The following issues were identified by static analysis on 2026-06-24 and are tracked for remediation:

Severity	File	Issue
Resolved	src/cli/polycall_cli.c	REPL tokenization uses a local reentrant splitter so Windows and Unix builds do not depend on strtok_r()
High	src/core/network.c:50,179	socket_fd > 0 incorrectly rejects fd 0 (stdin); use >= 0
High	src/core/polycall_micro.c:104	polycall_micro_cleanup iterates 0..count while destroy_service decrements count, causing early loop exit and leaked services
High	src/core/polycall_micro.c:343	polycall_micro_collect_garbage calls destroy_service during iteration, invalidating the loop invariant
Medium	src/core/polycall_protocol.c:13	protocol_error_buffer is a static global — not safe under concurrent protocol contexts
Medium	src/core/network.c	errno used (via select error path) but <errno.h> not explicitly included
Resolved	src/core/polycall_ffi.c	Payload size formatting uses a platform-specific macro so Windows builds do not warn on %zu support
Medium	src/core/polycall_config.c	unsigned long used for port values; prefer uint32_t for portability
Low	src/core/polycall_adapter.c	Mixed CRLF/LF line endings; normalise to LF
Low	network.c, polycall_parser.c, polycall_state_machine.c, polycall_tokenizer.c	Missing trailing newline at end of file
Low	src/cli/polycall_cli.c:128,459–485	unsigned long / unsigned long long casts; prefer fixed-width uint64_t

---

Configuration File Reference

LibPolyCall uses a three-layer configuration hierarchy:

File	Layer	Purpose
Polycallfile	Project (writable)	Servers, network topology, workspace paths
Polycallrc	Runtime (read-only defaults)	Port, log level, timeouts
Polycallrc.<language>	Language override	Per-language server type and workspace

Legacy .polycallrc is detected and warned about; migrate with:

polycall config migrate .polycallrc Polycallrc.<language>

---

Version History

v1.0.0 (current)

• Three-layer config hierarchy (Polycallfile / Polycallrc / Polycallrc.<language>)
• Zero-trust protocol with cryptographically-seeded CUID
• Telemetry engine with snapshot and event replay
• Micro-service isolation with memory and CPU limits
• Edge node registration and connection management
• Cross-language FFI: C, Python, Node.js, Java, Go, Rust, COBOL

v1.0.0 — Unified Architecture (2024-09-10)

• COBOL binding: enterprise mainframe integration via cbl-polycall
• Unified codebase: merged polycall repository into libpolycall
• Expanded documentation: legal framework and DOP architecture docs

Migration notes: original polycall v1 preserved in polycall-v1/; all bindings now under bindings/. See MIGRATION_REPORT.md for details.

---

LibPolyCall as Infrastructure as a Service (IaaS)

LibPolyCall is the polymorphic binding layer that powers the OBINexus Web IaaS platform. It provides:

• One API definition → multiple language implementations
• Unified debugging → faster problem resolution
• Centralised telemetry → intelligent scaling decisions
• Program-first design → technology-agnostic solutions

---

"In a world of language silos, be the universal protocol. In an age of security breaches, be the zero-trust solution. In an era of blind systems, be the intelligent observer. The future isn't coming—it's here, and it's written in C."

Repository: obinexus/libpolycall

Nnamdi Michael Okpala — Founder & Chief Architect, OBINexusComputing