// SPDX-License-Identifier: MPL-2.0
= PanLL eNSAID — The Human-Things Interface
:toc: preamble
:toc-title: Contents
:icons: font
:doctype: article

image:https://img.shields.io/badge/OpenSSF-BestPractices-green[link="https://www.bestpractices.dev/projects/XXXX"]

Four kinds of pane, contribute to a neurosymbolic development environment designed as a cognitive-relief layer: reducing friction, maintaining context, and making hard work less punishing. Built on AffineScript, Rust, and Bun.

== Overview

PanLL (pronounced "panel") is an Environment for NeSy-Agentic Integrated Development (eNSAID). It is a Human-Things Interface (HTI) built to support a tighter, calmer co-orbit between a human operator and a neurosymbolic machine.()()()

PanLL is the eNSAID in the broader vision: not a complete cure for cognitive overload, not the total ambient environment, but a practical support layer—the friction reducer, the context keeper, the anti-inertia mechanism. It does not solve every underlying problem; it reduces pain, drag, and strain so movement becomes possible again.

Its purpose is straightforward: reduce the amount of unnecessary thinking required to make progress.

== The four-pane parallel layout

[cols="1,2,2", options="header"]
|===
| Pane | Role | Analogy

| Pane-A (Ambient)()
| Persistent context and environmental support. Maintains continuity, absorbs state, reduces active cognitive management.
| The background

| Pane-L (Symbolic)()
| Strict logic, types, and constraints. The contractual layer governing inference and action. Powered by Typell.
| The law

| Pane-N (Neural)()
| Streaming inference manifold. Agent's internal monologue, reasoning traces, OODA-style movement.
| The mind

| Pane-W (World)()
| Central shared canvas. The task barycentre where results, actions, artefacts, and state become visible.
| The workbench
|===

== Core systems

These are not decorative features. They exist to reduce avoidable breakage, ambiguity, and strain:

Anti-Crash Library::
Logical circuit breaker preventing unvalidated neural output from reaching the task barycentre (Pane-W).

Vexometer::
Real-time friction and cognitive-load monitoring with anti-inflammatory UI adjustments. Measures what hurts; adjusts to reduce it.

Contractiles::
Adaptive state contracts between operator and machine. Negotiated boundaries for autonomy and intervention.

Feedback-O-Tron::
Community-driven performance reporting and constraint suggestions.

== What is standard and what is ours

[cols="1,2,2", options="header"]
|===
| Concept | Status | Home

| The Elm Architecture (TEA) in AffineScript (canonical)
| Standard (Elm/TEA pattern)
| Frontend architecture

| Rust + WebKitGTK backend
| Standard (Tauri-adjacent pattern)
| Gossamer backend

| Bun build orchestration
| Standard
| Build pipeline

| BEAM supervision for backend connections
| Standard (Elixir/OTP)
| beam/panll_beam

| Four-pane cognitive layout (A/L/N/W)
| Novel UI architecture
| Core design

| Vexometer (friction monitoring + adaptive UI)
| Novel mechanism
| Vexometer module

| Anti-Crash Library (neural output gating)
| Novel mechanism
| AntiCrash module

| Contractiles (adaptive state contracts)
| Novel concept
| Contractiles module

| eNSAID framing (cognitive-relief metaphor)
| Novel vocabulary
| Design philosophy
|===

== Design principles

• Minimise explicit prompting.
• Reduce unnecessary interruption.
• Preserve reversibility (easy undo, refinement, recovery).
• Maintain context so the user does not have to keep re-establishing it.
• Help without constantly demanding attention.
• Make progress easier under real cognitive conditions, not ideal ones.

== Technical stack

[cols="1,2,2", options="header"]
|===
| Layer | Choice | Rationale

| Frontend
| AffineScript + TEA
| Sound type system. Exhaustive pattern matching. No any escape hatch. The compiler catches state bugs that TypeScript structurally cannot.

| Backend
| Rust + Gossamer (WebKitGTK)
| 5 MB binary vs 100+ MB Electron. No GC pauses during real-time panel updates. Cross-platform filesystem watching via notify.

| Runtime
| Bun
| No node_modules. URL imports. Secure-by-default permissions. AffineScript/Tailwind run through npm: specifiers; no package.json.

| Testing
| Bun.test (97 JS) + cargo test (12 Rust)
| Built into the runtime. No extra framework.

| Styling
| Tailwind CSS 4.x
| Utility-first, purged in production. Consistent panel styling without specificity wars.

| Middlewarere
| Elixir/BEAM
| Supervision model fits multi-panel environment where connections fail independently.

| Verification
| Idris 2 ABI (planned) + Echidna
| High-assurance interface verification for Pane-L. Powered by Typell.

| Data Processing
| Julia
| Numeric analysis, calibration, batch processing without Python runtime limitations.
|===

== Known scope boundaries

[CAUTION]

Typell integration is planned, not yet wired. Pane-L (Symbolic) is designed to consume the Typell verification kernel via JSON-RPC. The current Pane-L implementation uses local type-checking. The full Idris 2 ABI + Echidna verification pipeline is a future milestone.

[CAUTION]

BEAM API is scaffolded. The Elixir/BEAM middleware supports HTTP, GraphQL, and gRPC endpoints, but these are currently health-check and status endpoints. Full protocol verification through BEAM is deferred.

[CAUTION**

"Cognitive relief" is a design intent, not a measured guarantee. We provide the mechanisms (Vexometer, Anti-Crash, Contractiles) to monitor and reduce friction. Whether these achieve cognitive relief for a given user and task is an empirical question, not a theorem.re

== BuildBu

[source,bash]

Compile AffineScript

bun task res:buildbures

Run tests (97 JS + 12 Rust)

bun task test

Development mode (Tailwind + static server + Gossamer)

bun task dev

Full production buildbu

bun task buildbu

== Documentation

• link:EXPLAINME.adoc[EXPLAINME] — claim-by-claim receipts and known gapsre
• link:Glossary.adoc[Glossary] — terminology referencere
• docs/design/eNSAID-specification.adoc — core cognitive governance model
• docs/design/decisions/ — ADR-style design decisions (DD-001 to DD-018)
• docs/architecture/TOPOLOGY.md — system architecture map and completion dashboard
• link:https://github.com/hyperpolymath/typell[Typell] — verification kernel powering Pane-L

== License

SPDX-License-Identifier: MPL-2.0 — see link:LICENSE[LICENSE].

Prose documentation is licensed under CC-BY-SA-4.0; see LICENSE-docs.