Nextgen Languages Evangeliser

image:[TPCF: Perimeter 3,link=docs/TPCF.md] image:[Learn — to love it!]

Learn — to love it! — Duolingo / Rosetta Stone for programming languages. A language-comprehension and transfer engine that classifies cross-language correspondences so what you learned in one language carries to the next — without shame.

Note	The canonical design is docs/theory/CORRESPONDENCE-MODEL.adoc. This README mirrors it. The repo began as ReScript Evangeliser; ReScript is now a legacy host (being migrated) and a legacy target. See ROADMAP.adoc for the re-point.

What is This?

Nextgen Languages Evangeliser is Duolingo / Rosetta Stone for programming languages — a language-comprehension and transfer engine. It works one layer above text editing, on syntactic and semantic intention, so the effort you spent learning language A transfers when you move to B (JS → TypeScript, Ruby, Prolog, C, or exotic targets like QPL, Arrow, JTV).

Transfer learning across languages is the product. The engine computes and classifies cross-language correspondences and surfaces what carries cleanly, what is a trap, and what has no analog at all.

We never shame developers. Your JavaScript is good — the engine tells you which of your existing intuitions transfer, and warns you before one bites.

What it is NOT

• Not "the next best IDE." It does not compete on contrast, project widgets, pop-up notepads, shortcuts, or attention/memory/workflow ergonomics. That is PanLL (PanLL + eNSAID = the contact between human, tool, task, and environment). This engine feeds PanLL; it is not PanLL.

• Not a linter. It is not about colouring scopes or spotting a missing ; / extra ). The differentiator is an engine that computes and classifies cross-language equivalence, not one that looks it up.

• Not a universal translator. A verified any-language→any-language compiler with full Curry–Howard fidelity would be nice; it is not the goal.

• Not a shame-the-JavaScript pattern matcher.

The Model: Concept / Form / Transition

Concept	The invariant / equivalence-class — the recurring trope ("bind a name to a value", "iterate a collection", "fail recoverably").
Form	A representative of a Concept in one language (let in ReScript, = in Erlang, def in Python). A Concept has many Forms.
Transition	A directed correspondence Form(A) → Form(B): the Echo-refined map plus its residue — what is lost, added, or inverted in crossing.

A lesson is a Concept shown through the learner’s known Form, the target Form, and the Transition between — narrated without shame: "you already know this; here’s the catch".

The six CorrespondenceKinds

Classification is not a boolean "relates"; it is a graded CorrespondenceKind, realised as grades of the Echo fibre. Each maps to a pedagogy:

Kind	Signature	Pedagogy
Cognate / true friend	Intention + behaviour coincide; residue ≈ ∅. e.g. def → define.	Transfer directly.
False friend / homonym	Surface matches, semantics diverge. e.g. BASIC = (assignment) vs. Erlang = (single-assignment bind/unify).	Flag the trap.
Antonym / inverted	Related but opposite. e.g. 0- vs. 1-indexing; truthiness; stack-growth direction.	Remap the intuition.
Alien realization	Same intention, foreign mechanism, large residue. e.g. subtraction in JTV (reversible/add-only) is add run backwards.	Bridge with effort.
Novel / no anchor	Forward fibre empty. e.g. static types coming from assembly + JS; ownership/borrowing; Prolog cut.	Teach de novo.
Vanished	Backward fibre empty. e.g. return in ReScript; null in a null-free language.	Un-learn / re-route.

Classification runs per stratum — surface → structure → semantic intention → abstraction/trope → cross-language invariant. A correspondence can hold at one stratum and break at another, and that divergence is itself the most valuable signal (it is the false-friend signature).

The formal carrier (honest)

• Carrier = Dyadic Relation (proven-tests-and-benches Dyadic.idr): { relates; reflexive; symmetric; transitive }. Equivalence = refl ∧ sym ∧ trans.

• Crossings are lossy-with-residue = Echo fibre (hyperpolymath/echo-types, Agda): Echo f y := Σ (x : A), f x ≡ y. The residue is precisely what is lost or added going A→B.

• invariant-path is the governance front-end: it anchors each equivalence claim to two code locations plus a witness, human-in-the-loop.

Note	"Knot theory" is an aspirational lens for intuition, not a literal computation. "Invariant" here means a preserved quantity that certifies "same idea" — no knot-invariant is computed, and we do not claim Curry–Howard fidelity.

Engine vs. Cartridge

We build	the general engine + the interface + the classification vocabulary (CorrespondenceKind) + the residue/fibre model + a reference language pack.
The community builds	the per-language modules as cartridges (estate standards/cartridges/) — which Forms instantiate which Concepts, and for each Transition the kind + residue + an optional witness.

The engine is language-agnostic. The nextgen-language collection is merely the substrate we dogfood.

Interface: levels of objects, not chrome

The "levels of objects" are rendered as overlay view-layers — switchable, non-destructive, each conforming to the estate overlay-protocol (additive, idempotent, Idris2-ABI proved):

• focus — show only what’s needed now

• glyph — Makaton-style symbols (accessible, low cognitive load)

• blockly / flowchart — structure as blocks

• raw code — the text itself

• side-by-side — multi-language diff with step-sync

The primary surface is a browser multi-pane workspace; a CLI/TUI is the offline fallback. Accessibility is first-class: Hyperpolymath Accessibility Standard, Level A minimum → AA (keyboard-only, ≥4.5:1 contrast, colourblind-safe palettes, ARIA/screen-reader, reduced-motion, plain-language mode).

Downstream: feeding PanLL

The engine emits; it does not own the IDE. Analyses become octads written to VeriSimDB (:8097) plus Groove signals; PanLL panels subscribe and re-render. Ergonomics are read from .machine_readable/ENSAID_CONFIG.a2ml. View-layers conform to the overlay-protocol.

Worked examples

Example	Kind	Note
def → define	cognate	"just a rename" — a hypothesis to verify, not assume
BASIC = vs. Erlang =	false friend / homonym	surface-corresponds ∧ semantics-diverge
0- vs. 1-indexing	antonym	residue = the flip
JTV reversible/add-only (subtraction = reversed add)	alien realization	JTV is a security-focused, reversible, total, effect/info-flow/capability-typed language
static types (coming from assembly + JS)	novel / no anchor	nothing to transfer from
return in ReScript	vanished	a concept the learner relied on is gone

Quick Start

Prerequisites

• Deno (latest stable)

• ReScript 12.2+ (current/legacy host; the host is being ported to AffineScript — see ROADMAP.adoc)

Note	AffineScript / Idris2 / Zig may be absent in some environments. Material is authored now and verified in CI — we do not claim local green builds we cannot run.

Installation

# Clone the repository
git clone https://github.com/hyperpolymath/nextgen-languages-evangeliser.git
cd nextgen-languages-evangeliser

# Install dependencies
just install

# Build host sources
just build

Usage

# Scan a source file (offline CLI fallback)
deno run --allow-read bin/evangeliser.js scan <file>

# List available correspondences / patterns
deno run --allow-read bin/evangeliser.js patterns

# Show the glyph legend
deno run --allow-read bin/evangeliser.js legend

# Display statistics
deno run --allow-read bin/evangeliser.js stats

Development

just test      # Run tests
just watch     # Watch mode
just fmt       # Format code
just ci        # Full CI simulation

Targets

The engine is language-agnostic; targets are the languages a learner moves to. AffineScript is a first-class teaching target and the future host, but the frame is no longer "evangelise AffineScript specifically" — it is "teach any language by transfer, with AffineScript among the first-class targets."

Target	Status	Why interesting for transfer
AffineScript	First-class; future host	Affine/linear use-once, borrow checking, QTT — dense with novel/no-anchor correspondences; emits typed-wasm → WebAssembly
ReScript	Legacy target + legacy host	Sound inference, Option/Result, pattern matching; source of the vanished return example
TypeScript, Ruby, Prolog, C, JTV, …	Reference / planned	Cartridge-authored; JTV is the canonical alien-realization + novel worked example

Technology Stack

• ReScript 12.2 — current/legacy host (being migrated; banned in new code per estate policy: .res → .affine)

• AffineScript — future host (Zig FFI + Idris2 ABI seams); OCaml 5.1+ toolchain; emits typed-wasm IR → WebAssembly

• Deno — runtime and package management

• Zig — FFI layer (canonical per manifest); Idris2 — ABI / proofs

Language Policy

Per Hyperpolymath Standard:

Allowed	Banned
AffineScript (future host), ReScript (legacy)	TypeScript
Deno	Node.js/npm/bun
justfile	Makefile
Zig (FFI), Idris2 (ABI/proofs)	V (outside V ecosystem)

ReScript is banned in new code; existing .res migrates to .affine. See CLAUDE.md and .claude/CLAUDE.md for the full policy.

Project Structure

nextgen-languages-evangeliser/
+-- src/                    # Host source (ReScript today; AffineScript target)
|   +-- Types.res           # Core type model
|   +-- Glyphs.res          # Makaton-inspired glyph view-layer
|   +-- Narrative.res       # Shame-free narrative (per CorrespondenceKind)
|   +-- Patterns.res        # Correspondence / pattern catalogue
|   +-- Scanner.res(i)      # Detection engine + interface
|   +-- Analyser.res(i)     # Classification + aggregation + interface
|   +-- Output.res          # focus/glyph/blockly/raw/side-by-side view-layers
|   +-- Cli.res             # CLI entry point (offline fallback)
+-- gui/                    # Browser multi-pane workspace (primary surface)
+-- test/                   # Test suites
+-- bin/evangeliser.js      # Deno CLI shim
+-- docs/                   # Documentation
|   +-- theory/CORRESPONDENCE-MODEL.adoc  # Canonical design spec
+-- rescript.json           # Host (ReScript) configuration
+-- deno.json               # Deno configuration
+-- Justfile                # Task orchestration
+-- Mustfile.epx            # Deployment contract
+-- config.ncl              # Nickel configuration
+-- CLAUDE.md               # AI context

Philosophy: no shame, transfer-first

We never shame developers. The six kinds map to: transfer cognates, warn on false friends, remap antonyms, bridge the alien, teach the novel, re-route the vanished. The narrative voice stays celebrate / minimise / better / safety / example.

Example narrative (a false friend):

You already know this! You’ve used = for assignment for years — that intuition is real.

Here’s the catch: in Erlang = doesn’t assign, it binds-once and unifies. Re-= with a different value fails a match rather than overwriting.

Re-route: read X = 5 as "assert X equals 5 (binding it if unbound)", not "store 5 in X".

RSR Compliance

This project follows the Rhodium Standard Repository (RSR) framework:

• Type Safety: ReScript 12.2 host today; AffineScript (affine/linear types, borrow checking) as the host target. Correspondence carrier is Idris2/Agda-grounded (Dyadic + Echo).

• Offline First: CLI/TUI fallback; zero network dependency to scan

• Complete Documentation: see docs/ and the design spec

• Security First: see SECURITY.md

• Open Governance: TPCF Perimeter 3 (Community Sandbox)

• Licensed: MPL-2.0

• Build Reproducibility: Deno + Justfile

See RSR_COMPLIANCE.md for full details.

Documentation

• CORRESPONDENCE-MODEL.adoc - Canonical design spec

• CONTRIBUTING.md - How to contribute (incl. cartridge authoring)

• CODE_OF_CONDUCT.md - Community guidelines

• SECURITY.md - Security policies

• CHANGELOG.md - Version history

• RSR_COMPLIANCE.md - RSR framework compliance

• TPCF.md - Contribution framework

• ROADMAP.adoc - Re-point sequence & milestones

Contributing

We welcome contributions! See CONTRIBUTING.md for:

• Code of Conduct

• Development setup

• Cartridge authoring guide (per-language correspondence modules)

• Testing requirements

• Pull request process

This is a TPCF Perimeter 3 project - all contributions are welcome!

License

This project is licensed under the Palimpsest License (MPL-2.0).

See LICENSE for the full license text.

Roadmap

• ✓ Correspondence-model spec merged (Concept/Form/Transition + six CorrespondenceKinds)

• ✓ Standards / repo hygiene merged

• [-] Identity re-point + abstraction-model pivot (classify, not translate)

• ❏ Browser multi-pane GUI (overlay view-layers)

• ❏ AffineScript host port (Zig FFI + Idris2 ABI)

• ❏ Cartridge contract + 2nd language pack

• ❏ Proofs/benches + PanLL octad emission

See ROADMAP.adoc for detailed milestones.

Citations

If you use this project in academic research, please cite:

@software{nextgen_languages_evangeliser_2026,
  title = {Nextgen Languages Evangeliser: Cross-Language Correspondence Classification for Transfer Learning},
  author = {Jonathan D.A. Jewell},
  year = {2026},
  url = {https://github.com/hyperpolymath/nextgen-languages-evangeliser},
  note = {Duolingo/Rosetta Stone for programming languages; successor to rescript-evangeliser; RSR Bronze-compliant, TPCF Perimeter 3}
}

Community

• GitHub: Issues and Discussions

• AffineScript: hyperpolymath/affinescript

• ReScript Forum: forum.rescript-lang.org

Acknowledgments

• Dyadic / Echo: proven-tests-and-benches and hyperpolymath/echo-types for the formal carrier (relation + loss-with-residue)

• PanLL / eNSAID: the downstream contact layer this engine feeds

• Makaton: inspiration for the glyph view-layer

• Deno Team: for the excellent runtime

• Contributors: see humans.txt

Status

• Version: 0.6.0-alpha (re-pointed from rescript-evangeliser 0.5.x)

• RSR Level: Bronze

• Design: correspondence-model spec merged; hygiene merged; abstraction-model pivot next

• Toolchain: AffineScript/Idris2/Zig deferred — authored now, verified in CI

• Last Updated: 2026-06-18

---

Made with care for developers learning a new language.

Remember: Learn — to love it!