Historical migration guide

This page collects material from the project's pre-standardization trial build — an older README, docs/CONFIGURATION_STANDARD.md, and a demonstration recording — and states plainly which parts describe something the current main branch does not do. None of this is a criticism of that earlier work; it's what LPV1-01 calls treating an old repository/build as "migration input, not permission to preserve multiple authoritative cores."

The old three-layer configuration scheme

Note: this page is itself a stand-in for LPV1-01 and LPV1-10's migration requirements — normative rules about how migration must behave — applied to this specific history.

docs/CONFIGURATION_STANDARD.md (still in the repository, superseded) describes:

Polycallfile           writable project topology: server LANG PORT:PORT, network start, ...
Polycallrc              global read-only runtime defaults
Polycallrc.<language>   per-language read-only overrides
.polycallrc             legacy fallback

with commands config load, config show <language>, config rc show/validate/migrate, and a network start directive that executes as part of loading.

None of this exists in the current CLI or parser. The current Polycallfile is a single file using the schema-1 grammar in the Polycallfile reference — declarative sections and typed key/value assignments only, no directive that "executes" anything, and no Polycallrc/language-override/.polycallrc layering. The current config command has exactly three subcommands: validate, show, migrate (see CLI reference) — there is no config load or config rc *. CFG-016 explicitly requires that old network start commands become declarative listener/service definitions, not executable statements, precisely because of this history.

The demonstration recording

An earlier project demo covered, among other things: a config.polycall file with server node 8080:8084 / server python 3001:8084 mappings, an interactive REPL ("trial version... only in development"), a raw HTTP book-service example, and described planned "zero-trust" and edge-caching features. Normalizing a few names that came through unclear in that recording: OBINexus, Nnamdi Michael Okpala, LibPolycall, Polycallfile, OpenSSL, bindings, foreign function interface.

What of this maps to the current implementation, and what doesn't:

  • The implicit REPL described as launching on invalid arguments or missing configuration is gone by design — L05 in the consolidation decisions and CLI-018 both forbid it. polycall with bad arguments now prints a usage error and a nonzero exit code, never a shell.
  • Multiple config files / port-pair mappings — superseded by the single-Polycallfile schema above.
  • OpenSSL as a required dependency — not true of the current build; see Getting started.
  • The book-service HTTP demo — see the next section; it does not currently exist as a LibPolycall-routed example.
  • "Zero-trust," "system consciousness" telemetry, cryptographically-seeded GUIDs, IaaS platform claims — these were marketing language in the original top-level README, describing intended direction, not a description of shipped behavior. The actual, narrower security and telemetry mechanisms that exist today are described in LPV1-08 and LPV1-09's summaries. Treat "zero-trust" specifically as aspirational language, not evidence that transport encryption or per-service identity isolation is implemented — mode mtls is explicitly refused rather than silently provided (see Polycallfile reference).

The book-service demo

The old demo's book service exposed raw HTTP POST/GET /books on a fixed port, exercised in this repository today only by examples/business-logic/test_client_api.{py,js,go,lua} — each of which is a plain HTTP client (http.client, net/http, ...) hitting localhost:8084 directly, with no Polycallfile, no runtime, and no service/method declaration anywhere in the request path.

This is not currently a LibPolycall example. A successful HTTP request against that port would prove only that some HTTP server answered it — not that LibPolycall's runtime, dispatcher, or authentication routed anything, because nothing in the current runtime exposes an HTTP bridge or a books service. Rebuilding this as a real, current tutorial would mean declaring a service.books in a Polycallfile, writing a provider that registers books.create/books.list over the actual wire protocol (the same pattern as examples/python-math/), and — if an HTTP-facing surface is wanted — building and documenting an explicit HTTP-to-wire-protocol bridge, none of which exists today. Until that's built, treat the old book-service demo as historical illustration of the idea of polymorphic dispatch, not as something to reproduce as-is.

The removed binding command

An earlier revision of the current CLI had binding list / binding check subcommands reporting a static "experimental" state for each language name. It was removed in this session: the runtime has no actual concept of "binding support state" to report — [service.ID].language is an informational schema field (see Polycallfile reference), not something the runtime tracks build/package readiness for. If you have a script or habit that calls polycall binding ..., it will now fail with "unknown command"; see Language integration for the actual, current per-language support state instead.

bindings/ directory and zig-polycall

Referenced in the original README's "Unified Codebase" notes. main has no bindings/ directory today. If you're carrying scripts, CI steps, or documentation links that assume one exists, they need updating — Language integration is the current source of truth for what's actually shippable per language.