Pollux Polyglot JS

About

Pollux Polyglot JS provides official high-performance TypeScript and JavaScript bindings for Pollux Core and the Pollux FFI Native Bridge (pollux-abi/1).

Modern applications running under Bun, Deno, or Node.js frequently execute external modules, user scripts, or agentic routines that require tight, verifiable containment. Standard runtime sandboxing models vary wildly across engines and lack cross-language conformance.

Pollux Polyglot JS binds your JavaScript runtime directly to the native Pollux evaluation engine, evaluating every sensitive system call (filesystem, network, processes, secrets) against a declarative capability manifest with zero execution variance.

Philosophy

"Capabilities precede execution; evaluation must remain deterministic across every runtime."

This is a Sxnnyside Project project, part of the Sxnnyside Project's Pollux Ecosystem.

Features

• Tri-Runtime Native Architecture: Direct JIT FFI for Bun (bun:ffi), typed symbol bindings for Deno (Deno.dlopen), and low-overhead compatibility for Node.js (koffi).
• Strictly Typed Wire Protocol: 100% TypeScript coverage conforming to Pollux ABI specification (pollux-abi/1) and RFC-001 wire protocol.
• Deterministic Evaluation: Guaranteed byte-for-byte identical evaluation traces and decisions across all supported runtimes.
• Resource Management Lifecycle: Native handles protected against use-after-free and memory leaks with full Symbol.dispose (using) support.
• Type-Safe Operation Builders: Pre-built helpers for filesystem (fileRead, fileWrite), network (netConnect), process control (procSpawn), secrets, and environment isolation.

Installation

Prerequisites

• Bun (>= 1.2.0), Deno (>= 2.0.0), or Node.js (>= 20.0.0)
• libpollux_ffi dynamic library (compiled from pollux-polyglot-native-bridge or set via POLLUX_FFI_PATH)

From Source

git clone https://github.com/sxnnyside-project/pollux-polyglot-js.git
cd pollux-polyglot-js

just install
just check

Usage

import {
  PolluxEngine,
  fileRead,
  fileWrite,
} from "@sxnnyside/pollux-polyglot-js";

const manifestYaml = `
version: 1
filesystem:
  read:
    - ./data
`;

// Initialize the engine (automatically selects Bun, Deno, or Node driver)
const engine = await PolluxEngine.load(manifestYaml);

// Evaluate allowed read operation
const readResult = engine.evaluate(fileRead("./data/input.json"));
console.log(readResult.allowed); // true
console.log(readResult.outcome); // "allow"

// Evaluate unauthorized write operation
const writeResult = engine.evaluate(fileWrite("./data/input.json"));
console.log(writeResult.allowed); // false
console.log(writeResult.outcome); // "deny"

// Clean up native memory
engine.destroy();

Architecture

pollux-polyglot-js/
├── src/
│   ├── ffi/          # Runtime-specific FFI drivers (Bun, Deno, Node)
│   ├── engine.ts     # PolluxEngine stateful container & lifecycle
│   ├── operation.ts  # Strongly typed wire operation builders
│   ├── loader.ts     # Multi-path native library resolver
│   └── types.ts      # ABI wire protocol and capability types
└── tests/            # Multi-runtime conformance and integration tests

For a detailed breakdown of the task runner and contribution guidelines, see CLAUDE.md.

Contributing

Contributions are accepted. See CONTRIBUTING.md for guidelines.

Before contributing, read the Code of Conduct.

License

This project is licensed under the MIT License — see the LICENSE file for details.