Skip to content

Commit 797b907

Browse files
hyperpolymathhyperpolymath
authored
Create EXPLAINME-new.adoc (#101)
<!-- SPDX-License-Identifier: CC-BY-SA-4.0 Copyright (c) Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk> --> ## Summary <!-- What does this PR do, and why? --> Closes # ## Type of change - [ ] 🐛 Bug fix (non-breaking change that fixes an issue) - [ ] ✨ New feature (non-breaking change that adds functionality) - [ ] 💥 Breaking change (would change existing behaviour) - [ ] 🕳️ Soundness fix (fixes a checker/proof false-negative) - [ ] 📖 Documentation - [ ] 🧹 Refactor / tech debt (behaviour-preserving) - [ ] ⚡ Performance - [ ] 🔧 Build / CI / tooling ## How has this been verified? <!-- Establish ground truth: which tool did you RUN, and what did it report? Don't cite a status doc — cite the command and its output. --> ## Checklist - [ ] My commits are **signed** (`git commit -S`). - [ ] I ran the project's own checks/tests locally and they pass. - [ ] New files carry the correct `SPDX-License-Identifier` (code/config `MPL-2.0`, prose `CC-BY-SA-4.0`); I did not relicense existing files. - [ ] Docs are updated, and no public claim now overstates what the code does. - [ ] I have not introduced a soundness hole (or I have flagged where I might have). ## Notes for reviewers <!-- Anything that needs special attention, follow-up, or context. --> ---- ## Summary by Gitar - **Documentation:** - Added `EXPLAINME-new.adoc` mapping README claims to implementations and caveats <sub>This will update automatically on new commits.</sub> Signed-off-by: Jonathan D.A. Jewell <6759885+hyperpolymath@users.noreply.github.com>
1 parent d3086ff commit 797b907

1 file changed

Lines changed: 151 additions & 0 deletions

File tree

‎EXPLAINME-new.adoc‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
// SPDX-License-Identifier: MPL-2.0
2+
= PanLL eNSAID — EXPLAINME
3+
:toc: preamble
4+
:toc-title: Contents
5+
:icons: font
6+
:doctype: article
7+
8+
This file backs every factual claim in link:README.adoc[README.adoc] with code paths and honest caveats. Read it if you are doing due diligence on whether the story matches the code.
9+
10+
== Claim-to-implementation map
11+
12+
=== PanLL is a cognitive-relief layer (eNSAID)
13+
14+
[quote, README.adoc]
15+
____
16+
A practical cognitive-relief layer: reducing friction, maintaining context, and making hard work less punishing.
17+
____
18+
19+
How this is implemented::
20+
The four-pane layout (A/L/N/W) separates ambient context, symbolic constraints, neural reasoning, and active work—reducing context-switching by design. The `Vexometer` monitors interaction friction and adjusts UI density. The `AntiCrash` library gates unvalidated neural output, preventing cascading confusion. `Contractiles` negotiate operator/machine autonomy boundaries.
21+
22+
Caveat::
23+
**"Cognitive relief" is a design intent, not a measured psychological guarantee.** The mechanisms (Vexometer, AntiCrash, Contractiles) provide the *infrastructure* for friction reduction. Whether they achieve cognitive relief for a specific user, task, or neurosymbolic agent is an empirical question. We do not have controlled user studies; we have architectural decisions aligned with cognitive-ergonomic principles.
24+
25+
=== ReScript + TEA provides a sound type system with no any escape hatch
26+
27+
[quote, README.adoc]
28+
____
29+
Actually type-safe — no any escape hatch, exhaustive pattern matching on every variant, and the compiler catches state bugs that TypeScript structurally cannot.
30+
____
31+
32+
How this is implemented::
33+
The frontend is written in ReScript using The Elm Architecture (TEA). ReScript's type system is sound by default; it lacks TypeScript's `any` type and structural unsoundness. Every UI variant is matched exhaustively. Build produces 0 warnings (`deno task res:build` in 180ms). Source: `link:src/[]` (ReScript modules).
34+
35+
Caveat::
36+
Soundness is relative to ReScript's type system. It guarantees the UI state machine cannot enter an ill-typed state, but it does not prove the *business logic* of the neurosymbolic interaction correct. That is Typell's job (planned).
37+
38+
=== 5 MB binary vs 100+ MB Electron; no GC pauses
39+
40+
[quote, README.adoc]
41+
____5 MB binary vs 100+ MB Electron. No garbage collector pauses during real-time panel updates.____
42+
43+
How this is implemented::
44+
The backend is Rust (`link:src-tauri/[]` or equivalent Rust backend) using Gossamer (WebKitGTK) for the webview shell. Rust's ownership model eliminates GC. Gossamer compiles to a ~5 MB binary. Filesystem watching uses the `notify` crate.
45+
46+
Caveat::
47+
The 5 MB figure is the Rust binary; the full installation includes WebKitGTK dependencies (provided by the host OS or container). Linux is the primary target; macOS and Windows require WebKitGTK availability. Gossamer is actively maintained but less battle-tested than Electron.
48+
49+
=== 109 tests passing (97 JS + 12 Rust)
50+
51+
[quote, README.adoc]
52+
____109 tests passing (97 JS via Deno.test + 12 Rust via cargo test)____
53+
54+
How this is implemented::
55+
`deno task test` runs the Deno test suite (97 tests covering UI components, state management, event-chain import, Anti-Crash gating, Vexometer polling). `cargo test` runs the Rust suite (12 tests covering backend commands, filesystem watching, identity state capture). CI enforces both.
56+
57+
Caveat::
58+
These are integration and unit tests, not formal proofs. They verify component behavior, not system-wide soundness. The Typell integration (when wired) will add formal verification for Pane-L constraints.
59+
60+
=== Deno build with no package.json
61+
62+
[quote, README.adoc]
63+
____No node_modules black hole — URL imports, built-in TypeScript support for glue code, secure-by-default permissions model.____
64+
65+
How this is implemented::
66+
`link:deno.json[]` configures the build. ReScript and Tailwind run through `npm:` specifiers without a `package.json` or direct `npm` CLI invocation. All imports are URL-based or managed specifiers.
67+
68+
Caveat::
69+
The `npm:` specifier mechanism *does* hit the npm registry for ReScript and Tailwind packages. The "no node_modules" claim means no local `node_modules` directory is materialised in the repo; Deno manages the cache internally.
70+
71+
=== Event-chain import from panic-attack
72+
73+
[quote, README.adoc]
74+
____PanLL can ingest PanLL event-chain JSON exported by panic-attack and surface it in Pane-W for MVP timeline review.____
75+
76+
How this is implemented::
77+
Pane-W includes an Event Chain panel with "Import JSON" (paste) and "Load File" (filesystem) handlers. The imported JSON is parsed, validated, and surfaced as a timeline. Persistence via localStorage.
78+
79+
Caveat::
80+
The import validates JSON structure, not the semantic truth of the event chain. Maliciously crafted event chains will render but may not represent actual security events.
81+
82+
== Dogfooded Across The Account
83+
84+
[cols="1,2,2", options="header"]
85+
|===
86+
| Technology / Pattern | Used here | Also used in
87+
88+
| ReScript + TEA
89+
| Frontend architecture
90+
| link:https://github.com/hyperpolymath/kategoria[Kategoria] (Route α tooling, planned)
91+
92+
| Rust + Gossamer
93+
| Backend
94+
| link:https://github.com/hyperpolymath/typell[Typell] (kernel)
95+
96+
| Deno build orchestration
97+
| Build/test pipeline
98+
| Estate-wide standard
99+
100+
| Elixir/BEAM middleware
101+
| `beam/panll_beam`
102+
| link:https://github.com/hyperpolymath/standards[Standards] (BEAM API pattern)
103+
|===
104+
105+
== Known gaps
106+
107+
[CAUTION]
108+
====
109+
**Typell is not wired.** Pane-L currently uses local type checking. The Typell JSON-RPC integration for dependent, linear, and session type verification is designed but not implemented.
110+
====
111+
112+
[CAUTION]
113+
====
114+
**BEAM API is scaffolded.** HTTP, GraphQL, and gRPC endpoints exist for health checks and status. Full query validation through BEAM is deferred.
115+
====
116+
117+
[CAUTION]
118+
====
119+
**No formal cognitive-ergonomic validation.** The Vexometer measures interaction friction (timing, error rates, undo frequency). It does not measure cognitive load directly (no EEG, no eye tracking). The mapping from Vexometer readings to "cognitive relief" is a hypothesis, not a validated model.
120+
====
121+
122+
[CAUTION]
123+
====
124+
**v0.2.0, not v1.0.0.** PanLL is a connected workbench, not a production release. APIs, panel layouts, and state contracts may change.
125+
====
126+
127+
== Evidence Index
128+
129+
[cols="2,3", options="header"]
130+
|===
131+
| Path | Proves / Implements
132+
133+
| `src/` (ReScript)
134+
| 4-pane UI, TEA architecture, Anti-Crash, Vexometer, Contractiles
135+
136+
| `src-tauri/` or Rust backend
137+
| Gossamer webview, 270 migrated commands, filesystem watching
138+
139+
| `beam/panll_beam/`
140+
| BEAM middleware scaffold (HTTP/GraphQL/gRPC)
141+
142+
| `deno.json`
143+
| Build orchestration (no `package.json`)
144+
145+
| `docs/architecture/TOPOLOGY.md`
146+
| System architecture map and completion dashboard
147+
148+
| `docs/design/decisions/`
149+
| DD-001 to DD-018 (architectural decisions)
150+
|===
151+
abc def ghi jkl mno pqr stu

0 commit comments

Comments
 (0)